lynkr 9.14.1 → 9.14.3

package/scripts/seed-capabilities.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * Seed per-family capability profiles from online benchmark data.
+ *
+ * Reads (all optional, all fail-soft): SWE-Bench Verified leaderboard,
+ * data/capability-benchmarks/*.json drop-ins, models.dev boolean flags.
+ * Maps scores to families, normalizes to 0-1 caps, and writes
+ * data/capability-seeds.snapshot.json for the shortfall resolver.
+ * Shipped seeds (config/model-capability-seeds.json) are only ever changed
+ * by human review of the printed diff — this script never touches them.
+ *
+ * Request-path routing never calls this (zero latency impact) and never
+ * needs it: unknown families fall back to heuristic → tier caps.
+ *
+ * Usage:
+ *   node scripts/seed-capabilities.js [--refresh] [--model provider:model]
+ *     [--dry-run] [--check] [--stale-days 90]
+ *
+ *   --refresh   fetch remote sources (default: cache-only)
+ *   --model     limit to one family (e.g. --model z.ai:glm-5.2)
+ *   --dry-run   print diff, write nothing
+ *   --check     exit 2 if shipped seeds are older than --stale-days (CI)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { fetchSweBench } = require('../src/routing/capability-seeds/swebench');
+const { fetchModelsDevFlags, NO_TOOLCALL_TOOL_USE_CAP } = require('../src/routing/capability-seeds/models-dev');
+const { loadBenchmarksDir } = require('../src/routing/capability-seeds/benchmarks-dir');
+const { mapEntryToFamily, scoresToCaps, normalizeFamily } = require('../src/routing/capability-seeds/normalize');
+const { SHIPPED_PATH, SNAPSHOT_PATH } = require('../src/routing/capability-seeds/registry');
+
+const STALE_DAYS_DEFAULT = 90;
+
+function _parseArgs(argv) {
+  const out = { refresh: false, model: null, dryRun: false, check: false, staleDays: STALE_DAYS_DEFAULT };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--refresh') out.refresh = true;
+    else if (argv[i] === '--dry-run') out.dryRun = true;
+    else if (argv[i] === '--check') out.check = true;
+    else if (argv[i] === '--model') out.model = String(argv[++i] || '');
+    else if (argv[i] === '--stale-days') out.staleDays = Number(argv[++i]) || STALE_DAYS_DEFAULT;
+  }
+  return out;
+}
+
+function _readJson(p) {
+  try {
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Drop-in source name → normalized score slot.
+function _slotFor(source) {
+  const s = String(source || '').toLowerCase();
+  if (s.includes('terminal')) return 'terminal';
+  if (s.includes('livecode') || s.includes('bigcode')) return 'livecode';
+  if (s.includes('arena')) return 'arena';
+  if (s.includes('swe')) return 'swe';
+  return null;
+}
+
+async function main() {
+  const args = _parseArgs(process.argv.slice(2));
+
+  if (args.check) {
+    const shipped = _readJson(SHIPPED_PATH);
+    const updatedAt = shipped?.updatedAt ? new Date(shipped.updatedAt).getTime() : NaN;
+    const ageDays = Number.isFinite(updatedAt) ? (Date.now() - updatedAt) / 86400000 : Infinity;
+    if (!(ageDays <= args.staleDays)) {
+      console.error(`STALE: shipped seeds updatedAt=${shipped?.updatedAt ?? 'missing'} (> ${args.staleDays}d). Run --refresh and review the diff.`);
+      process.exit(2);
+    }
+    console.log(`OK: shipped seeds fresh (${shipped.updatedAt}, ${ageDays.toFixed(0)}d old).`);
+    return;
+  }
+
+  const shipped = _readJson(SHIPPED_PATH);
+  const shippedSeeds = shipped?.seeds && typeof shipped.seeds === 'object' ? shipped.seeds : {};
+  const knownFamilies = Object.keys(shippedSeeds).filter((k) => !k.endsWith('*'));
+  const wildcardFamilies = Object.keys(shippedSeeds).filter((k) => k.endsWith('*'));
+
+  let onlyFamily = null;
+  if (args.model) {
+    const [provider, ...rest] = args.model.split(':');
+    const { family } = normalizeFamily(provider, rest.join(':') || provider);
+    onlyFamily = family;
+    console.log(`Limiting to family: ${onlyFamily}`);
+  }
+
+  // 1. Gather score entries per source.
+  const scored = {}; // family -> { swe, terminal, livecode, arena }
+  const unmapped = [];
+  const scaffolded = [];
+  const candidates = [];
+  const statuses = [];
+  const addScore = (family, slot, fraction, source) => {
+    if (onlyFamily && family !== onlyFamily) return;
+    scored[family] = scored[family] || {};
+    // Keep the max when several entries map to one family.
+    if (scored[family][slot] === undefined || fraction > scored[family][slot]) {
+      scored[family][slot] = fraction;
+      scored[family][`${slot}:source`] = source;
+    }
+  };
+  // Bare-model scores only: a "+" joins scaffold + model ("live-swe-agent +
+  // claude 4.5 opus") and measures the harness, not the weights. Those go to
+  // a separate review list and never seed caps.
+  const triage = (name, score, slot, source) => {
+    if (String(name).includes('+')) {
+      scaffolded.push({ source, name, score });
+      return;
+    }
+    const m = mapEntryToFamily(name, knownFamilies);
+    if (m.family) {
+      addScore(m.family, slot, score, source);
+      return;
+    }
+    const w = mapEntryToFamily(name, wildcardFamilies);
+    if (w.family) {
+      candidates.push({ entry: name, score, slot, prefix: w.family.replace(/\*$/, '') });
+      return;
+    }
+    unmapped.push({ source, name, score });
+  };
+
+  const swe = await fetchSweBench({ refresh: args.refresh });
+  statuses.push(`swebench[${swe.board || '?'}]: ${swe.status}${swe.cached ? ' (cache)' : ''}${swe.reason ? ` — ${swe.reason}` : ''}`);
+  for (const e of swe.entries || []) {
+    triage(e.name, e.resolved / 100, 'swe', `swebench-verified@${e.resolved}%`);
+  }
+
+  const dir = loadBenchmarksDir();
+  for (const f of dir.files || []) {
+    const slot = _slotFor(f.source);
+    statuses.push(`${f.source}: ${f.status}${f.reason ? ` — ${f.reason}` : ''}${f.status === 'ok' && !slot ? ' (unknown slot — skipped)' : ''}`);
+    if (f.status !== 'ok' || !slot) continue;
+    for (const e of f.entries || []) {
+      const fraction = f.scale === 'fraction' ? e.score : e.score / 100;
+      triage(e.name, fraction, slot, `${f.source}@${e.score}`);
+    }
+  }
+
+  const md = await fetchModelsDevFlags({ refresh: args.refresh });
+  statuses.push(`models.dev: ${md.status}${md.cached ? ' (cache)' : ''}${md.reason ? ` — ${md.reason}` : ''}`);
+
+  // 2. Normalize to caps.
+  const proposed = {};
+  for (const [family, slots] of Object.entries(scored)) {
+    const scores = {};
+    for (const k of ['swe', 'terminal', 'livecode', 'arena']) {
+      if (Number.isFinite(slots[k])) scores[k] = slots[k];
+    }
+    const caps = scoresToCaps(scores);
+    if (!caps) continue;
+    const sources = Object.keys(scores).map((k) => slots[`${k}:source`]).filter(Boolean);
+    const flag = md.flags?.[family];
+    if (flag && flag.toolCall === false && caps.tool_use > NO_TOOLCALL_TOOL_USE_CAP) {
+      caps.tool_use = NO_TOOLCALL_TOOL_USE_CAP;
+      sources.push('models.dev:no-tool_call-cap');
+    }
+    proposed[family] = { caps, sources, fetchedAt: new Date().toISOString().slice(0, 10) };
+  }
+
+  // 3. Diff vs snapshot + shipped.
+  const snapshot = _readJson(SNAPSHOT_PATH);
+  const prevSeeds = snapshot?.seeds && typeof snapshot.seeds === 'object' ? snapshot.seeds : {};
+  const moves = [];
+  for (const [family, entry] of Object.entries(proposed)) {
+    const prev = prevSeeds[family];
+    const shippedCaps = shippedSeeds[family]?.caps;
+    const sameAs = (a, b) => a && b && ['reasoning', 'codegen', 'debugging', 'tool_use'].every((h) => a[h] === b[h]);
+    if (!prev && !shippedCaps) moves.push({ family, type: 'added', caps: entry.caps });
+    else if (!sameAs(prev?.caps, entry.caps)) moves.push({ family, type: 'changed', from: prev?.caps ?? null, to: entry.caps });
+  }
+
+  console.log('Sources:');
+  for (const s of statuses) console.log(`  - ${s}`);
+  console.log(`Families scored: ${Object.keys(proposed).length}, changed vs snapshot: ${moves.length}`);
+  for (const m of moves.slice(0, 30)) {
+    console.log(`  ${m.type} ${m.family}: ${JSON.stringify(m.from ?? null)} → ${JSON.stringify(m.to ?? m.caps)}`);
+  }
+  if (moves.length > 30) console.log(`  … and ${moves.length - 30} more`);
+  const topUnmapped = unmapped.sort((a, b) => b.score - a.score).slice(0, 10);
+  if (topUnmapped.length > 0) {
+    console.log('Unmapped (no family match — review, add alias/seed if real):');
+    for (const u of topUnmapped) console.log(`  - [${u.source}] ${u.name} (${u.score})`);
+  }
+  const topCandidates = candidates.sort((a, b) => b.score - a.score).slice(0, 15);
+  if (topCandidates.length > 0) {
+    console.log('Candidate new seeds (matched a shipped wildcard — add an exact entry to graduate):');
+    for (const c of topCandidates) {
+      console.log(`  - "${c.entry}" (${c.slot} ${c.score}) → under prefix "${c.prefix}"`);
+    }
+  }
+  const topScaffolded = scaffolded.sort((a, b) => b.score - a.score).slice(0, 5);
+  if (topScaffolded.length > 0) {
+    console.log('Scaffolded entries (harness+model composites — never seeded, shown for context):');
+    for (const u of topScaffolded) console.log(`  - [${u.source}] ${u.name} (${u.score})`);
+  }
+
+  if (args.dryRun) {
+    console.log('dry-run: wrote nothing.');
+    return;
+  }
+  const next = {
+    version: 1,
+    fetchedAt: new Date().toISOString(),
+    seeds: { ...prevSeeds },
+  };
+  for (const [family, entry] of Object.entries(proposed)) next.seeds[family] = entry;
+  try {
+    fs.mkdirSync(path.dirname(SNAPSHOT_PATH), { recursive: true });
+    fs.writeFileSync(SNAPSHOT_PATH, `${JSON.stringify(next, null, 2)}\n`);
+    console.log(`Wrote ${SNAPSHOT_PATH} (${Object.keys(next.seeds).length} families).`);
+    console.log('Review the diff above; to promote entries to shipped seeds, copy them into config/model-capability-seeds.json and bump updatedAt.');
+  } catch (err) {
+    console.error(`Write failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`seed-capabilities failed: ${err?.message || err}`);
+  process.exit(1);
+});

package/src/api/claude-desktop-gateway.js

@@ -0,0 +1,123 @@
+/**
+ * Claude Desktop third-party gateway support.
+ *
+ * Claude Desktop has a native "3p" deployment mode in which it sends its
+ * normal Anthropic Messages API traffic to a local gateway URL instead of
+ * api.anthropic.com (this is the route Ollama's `ollama launch
+ * claude-desktop` integration uses). Lynkr already speaks the Messages API
+ * on /v1/messages, so the only missing surface is model discovery: Desktop
+ * lists the gateway's models and maps them into its model picker using two
+ * non-standard fields observed in Ollama's gateway implementation
+ * (internal/proxy/claude_desktop.go): `anthropic_family_tier` and
+ * `is_family_default`.
+ *
+ * This router serves that list, derived from Lynkr's TIER_* config so the
+ * Desktop model picker doubles as a tier selector:
+ *
+ *   SIMPLE    -> haiku family (default)
+ *   MEDIUM    -> sonnet family
+ *   COMPLEX   -> sonnet family (default)
+ *   REASONING -> opus family (default)
+ *
+ * The selected id PINS routing: src/api/router.js resolves the request's
+ * `model` field against ../routing/model-slots.js and, when it matches one
+ * of these ids (anything but "Lynkr Auto" / claude-fable-5), skips content
+ * scoring entirely and forces that tier. Only "Lynkr Auto" and unrecognized
+ * ids fall through to Lynkr's normal per-message scoring, same as Claude
+ * Code traffic gets.
+ *
+ * Gating: GET /v1/models is already served in OpenAI format by
+ * openai-router.js (mounted after this router). We only intercept callers
+ * that identify as Anthropic API clients via the `anthropic-version` header
+ * (Claude Desktop always sends it) or an explicit ?format=anthropic. Set
+ * CLAUDE_DESKTOP_GATEWAY=0 to disable the intercept entirely.
+ *
+ * Profile installation lives in scripts/claude-desktop.js.
+ */
+
+const express = require("express");
+const config = require("../config");
+const logger = require("../logger");
+const { MODEL_SLOTS } = require("../routing/model-slots");
+
+const router = express.Router();
+
+// Fixed timestamp: Anthropic's list endpoint dates models by release, not by
+// request time, and a stable value keeps repeated calls cache-friendly.
+const CREATED_AT = "2026-01-01T00:00:00Z";
+
+const DEFAULT_MAX_TOKENS = 32768;
+
+// MODEL_SLOTS lives in ../routing/model-slots.js — shared with router.js,
+// which resolves an incoming request's `model` field back to a tier so an
+// explicit pick in Desktop's dropdown pins routing instead of only being
+// advisory (see the model-id-pin block in router.js).
+
+function gatewayEnabled() {
+  return process.env.CLAUDE_DESKTOP_GATEWAY !== "0";
+}
+
+function maxTokens() {
+  const raw = Number(process.env.CLAUDE_DESKTOP_GATEWAY_MAX_TOKENS);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_MAX_TOKENS;
+}
+
+/**
+ * Build the Anthropic-shaped model list from configured tiers. Tiers that
+ * are unset in .env are skipped; if that leaves a family with no default,
+ * the first surviving entry of that family is promoted so Desktop always
+ * has a selectable default per family.
+ */
+function buildGatewayModels() {
+  const entries = [];
+  for (const slot of MODEL_SLOTS) {
+    let label = slot.label;
+    if (!label) {
+      const configured = config.modelTiers?.[slot.tier];
+      if (!configured) continue; // tier unset in .env — skip this slot
+      const [provider, ...modelParts] = configured.split(":");
+      const model = modelParts.join(":") || provider;
+      label = `Lynkr ${slot.tier} (${model})`;
+    }
+    entries.push({
+      type: "model",
+      id: slot.id,
+      display_name: label,
+      created_at: slot.createdAt || CREATED_AT,
+      max_tokens: maxTokens(),
+      anthropic_family_tier: slot.family,
+      is_family_default: slot.isDefault,
+    });
+  }
+  return entries;
+}
+
+router.get("/models", (req, res, next) => {
+  const wantsAnthropic =
+    req.headers["anthropic-version"] || req.query.format === "anthropic";
+  if (!gatewayEnabled() || !wantsAnthropic) return next();
+
+  try {
+    const data = buildGatewayModels();
+    if (data.length === 0) return next(); // no tiers configured — fall through
+    logger.debug(
+      { modelCount: data.length, ua: req.headers["user-agent"] },
+      "[ClaudeDesktopGateway] Listed tier models (Anthropic format)"
+    );
+    res.json({
+      data,
+      first_id: data[0].id,
+      last_id: data[data.length - 1].id,
+      has_more: false,
+    });
+  } catch (error) {
+    logger.error(
+      { error: error.message },
+      "[ClaudeDesktopGateway] Failed to list models"
+    );
+    next(); // fall through to the OpenAI-format handler rather than 500
+  }
+});
+
+module.exports = router;
+module.exports._buildGatewayModels = buildGatewayModels; // test hook

package/src/api/health.js

@@ -4,7 +4,6 @@ try {
 } catch {
   Database = null;
 }
-const { invokeModel } = require("../clients/databricks");
 const logger = require("../logger");
 const config = require("../config");
 const { getHeadroomManager } = require("../headroom");

package/src/api/mcp-broker.js

@@ -0,0 +1,149 @@
+/**
+ * MCP broker (ROUTING-NOTES Track B / §1 gap: Lynkr was MCP-client-only).
+ *
+ * Exposes Lynkr's configured MCP servers to OTHER clients over HTTP, so one
+ * Lynkr install can act as the single MCP access point for a team/toolchain
+ * instead of every client wiring up (and holding credentials for) every
+ * server separately. The credential-injection property falls out of the
+ * existing registry design: downstream server env/credentials live in
+ * Lynkr's MCP config and never leave this process — callers see only tool
+ * names and results.
+ *
+ * Surface (all JSON):
+ *   GET  /v1/mcp/servers      configured servers (id + tool count)
+ *   GET  /v1/mcp/tools        aggregated tools/list across servers,
+ *                             namespaced "<server>:<tool>"
+ *   POST /v1/mcp/tools/call   { server, tool, arguments } → tool result
+ *
+ * Security: OFF by default. Enabling requires BOTH
+ *   LYNKR_MCP_BROKER_ENABLED=true
+ *   LYNKR_MCP_BROKER_TOKEN=<secret>       (Bearer-checked on every call)
+ * Enabled-without-token fails CLOSED (503 + loud log) — an exposed tool
+ * surface must never be reachable unauthenticated (§4.4 rule: a live
+ * caller's input is never silently trusted). Optional allowlist:
+ *   LYNKR_MCP_BROKER_SERVERS=id1,id2      (default: all configured)
+ *
+ * @module api/mcp-broker
+ */
+
+const express = require('express');
+const crypto = require('crypto');
+const logger = require('../logger');
+const mcp = require('../mcp');
+
+const router = express.Router();
+
+const CALL_TIMEOUT_MS = Number.parseInt(process.env.LYNKR_MCP_BROKER_CALL_TIMEOUT_MS, 10) || 60_000;
+
+function _enabled() {
+  return process.env.LYNKR_MCP_BROKER_ENABLED === 'true';
+}
+
+function _allowedServers() {
+  const raw = process.env.LYNKR_MCP_BROKER_SERVERS;
+  if (!raw) return null; // null = all configured servers
+  return new Set(raw.split(',').map((s) => s.trim()).filter(Boolean));
+}
+
+function _timingSafeEqual(a, b) {
+  const ha = crypto.createHash('sha256').update(String(a)).digest();
+  const hb = crypto.createHash('sha256').update(String(b)).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+
+function brokerAuth(req, res, next) {
+  if (!_enabled()) {
+    return res.status(404).json({ error: { type: 'not_found', message: 'MCP broker is not enabled' } });
+  }
+  const token = process.env.LYNKR_MCP_BROKER_TOKEN;
+  if (!token) {
+    // Fail closed: enabled-but-tokenless must never serve.
+    logger.error('[McpBroker] LYNKR_MCP_BROKER_ENABLED=true but LYNKR_MCP_BROKER_TOKEN is unset — refusing to serve. Set a token to activate the broker.');
+    return res.status(503).json({
+      error: { type: 'broker_misconfigured', message: 'MCP broker enabled without LYNKR_MCP_BROKER_TOKEN; refusing to serve unauthenticated' },
+    });
+  }
+  const auth = req.headers.authorization || '';
+  const presented = auth.startsWith('Bearer ') ? auth.slice(7) : null;
+  if (!presented || !_timingSafeEqual(presented, token)) {
+    return res.status(401).json({ error: { type: 'unauthorized', message: 'Invalid or missing bearer token' } });
+  }
+  next();
+}
+
+function _visibleServers() {
+  const allow = _allowedServers();
+  return mcp.listServers().filter((s) => !allow || allow.has(s.id));
+}
+
+async function _clientFor(serverId) {
+  const allow = _allowedServers();
+  if (allow && !allow.has(serverId)) {
+    const err = new Error(`server "${serverId}" is not allowlisted for the broker`);
+    err.status = 403;
+    throw err;
+  }
+  const server = mcp.getServer(serverId);
+  if (!server) {
+    const err = new Error(`unknown MCP server "${serverId}"`);
+    err.status = 404;
+    throw err;
+  }
+  return mcp.ensureClient(serverId);
+}
+
+router.get('/v1/mcp/servers', brokerAuth, async (_req, res) => {
+  const servers = _visibleServers().map((s) => ({
+    id: s.id,
+    description: s.description ?? null,
+  }));
+  res.json({ servers });
+});
+
+router.get('/v1/mcp/tools', brokerAuth, async (_req, res) => {
+  const results = [];
+  const errors = {};
+  await Promise.all(_visibleServers().map(async (server) => {
+    try {
+      const client = await mcp.ensureClient(server.id);
+      const listed = await client.request('tools/list', {});
+      for (const tool of listed?.tools ?? []) {
+        results.push({
+          name: `${server.id}:${tool.name}`,
+          server: server.id,
+          tool: tool.name,
+          description: tool.description ?? null,
+          input_schema: tool.inputSchema ?? tool.input_schema ?? null,
+        });
+      }
+    } catch (err) {
+      // Per-server failure is reported, not hidden — a dead server must not
+      // silently vanish from the tool list (§4.3: no invisible degradation).
+      errors[server.id] = err.message;
+    }
+  }));
+  res.json({ tools: results, ...(Object.keys(errors).length ? { server_errors: errors } : {}) });
+});
+
+router.post('/v1/mcp/tools/call', brokerAuth, async (req, res) => {
+  const { server, tool, arguments: args } = req.body || {};
+  if (!server || !tool) {
+    return res.status(400).json({ error: { type: 'invalid_request', message: 'body must include { server, tool, arguments? }' } });
+  }
+  try {
+    const client = await _clientFor(server);
+    const result = await Promise.race([
+      client.request('tools/call', { name: tool, arguments: args ?? {} }),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(Object.assign(new Error('tool call timed out'), { status: 504 })), CALL_TIMEOUT_MS).unref?.()
+      ),
+    ]);
+    res.json({ server, tool, result });
+  } catch (err) {
+    const status = err.status ?? 502;
+    logger.warn({ server, tool, error: err.message }, '[McpBroker] tool call failed');
+    res.status(status).json({ error: { type: 'tool_call_failed', message: err.message, server, tool } });
+  }
+});
+
+module.exports = router;

package/src/api/middleware/budget-enforcer.js

@@ -21,18 +21,88 @@ function _readContext(req) {
   };
 }
 
+// Default expected-output tokens when the caller didn't set max_tokens —
+// same shape as LiteLLM's TPM floor: the estimate is soft admission control,
+// trued up by the post-response recordSpend(), not a hard ceiling.
+const DEFAULT_OUTPUT_TOKENS_ESTIMATE = 1024;
+
+// Cached blended per-1k price across the configured tier models. Routing
+// hasn't picked a model yet at middleware time, so the estimate prices at
+// the average of what this install could plausibly serve. Refreshed every
+// 60s (tier config can hot-reload).
+let _priceCache = { at: 0, inputPer1k: 0, outputPer1k: 0 };
+const PRICE_CACHE_TTL_MS = 60_000;
+
+function _blendedTierPricing() {
+  const now = Date.now();
+  if (now - _priceCache.at < PRICE_CACHE_TTL_MS) return _priceCache;
+  try {
+    const { getModelTierSelector } = require('../../routing/model-tiers');
+    const { getModelRegistrySync } = require('../../routing/model-registry');
+    const registry = getModelRegistrySync && getModelRegistrySync();
+    const models = getModelTierSelector().getAllConfiguredModels();
+    let inputSum = 0;
+    let outputSum = 0;
+    let priced = 0;
+    for (const m of models) {
+      const cost = registry?.getCost?.(m.model);
+      if (!cost || cost.unknown) continue;
+      inputSum += cost.input ?? 0;
+      outputSum += cost.output ?? 0;
+      priced += 1;
+    }
+    _priceCache = {
+      at: now,
+      inputPer1k: priced > 0 ? inputSum / priced : 0,
+      outputPer1k: priced > 0 ? outputSum / priced : 0,
+    };
+  } catch {
+    _priceCache = { at: now, inputPer1k: 0, outputPer1k: 0 };
+  }
+  return _priceCache;
+}
+
+/**
+ * Pre-flight cost estimate for a request that hasn't been routed yet:
+ * estimated input tokens (4-chars≈1-token over system+tools+messages) plus
+ * expected output (caller's max_tokens, else a floor), priced at the blended
+ * average of the configured tier models. Falls back to a $0.01 nominal gate
+ * when nothing is priceable — never LESS strict than the old behavior.
+ *
+ * @param {object} body — request payload
+ * @returns {number} estimated USD cost
+ */
+function estimateRequestCost(body) {
+  try {
+    const { countPayloadTokens } = require('../../utils/tokens');
+    const inputTokens = countPayloadTokens(body || {}).total || 0;
+    const outputTokens = Math.min(
+      typeof body?.max_tokens === 'number' && body.max_tokens > 0
+        ? body.max_tokens
+        : DEFAULT_OUTPUT_TOKENS_ESTIMATE,
+      32_000,
+    );
+    const price = _blendedTierPricing();
+    const est = (inputTokens / 1000) * price.inputPer1k
+      + (outputTokens / 1000) * price.outputPer1k;
+    // Floor at the old nominal $0.01 so free/unpriced configs still gate
+    // exhausted accounts exactly as before.
+    return Math.max(0.01, est);
+  } catch {
+    return 0.01;
+  }
+}
+
 /**
- * Express middleware. Estimates request cost via cost-optimizer and rejects
- * if the budget is already exceeded. Records spend after the response.
+ * Express middleware. Estimates request cost from the payload's token count
+ * and blended tier pricing, and rejects if the budget would be exceeded.
+ * Actual spend is recorded post-response (estimate → true-up pattern).
  */
 function budgetEnforcer(req, res, next) {
   if (process.env.LYNKR_BUDGET_ENFORCER === 'false') return next();
   const context = _readContext(req);
-  // Cheap pre-check at $0; we use the request to record actual spend.
-  // The actual ceiling check happens with an estimated $0.01 "minimum" so
-  // exhausted accounts get rejected before we even route.
   const budget = getHierarchicalBudget();
-  const check = budget.check(context, 0.01);
+  const check = budget.check(context, estimateRequestCost(req.body));
   if (!check.ok) {
     logger.warn({ exceeded: check.exceeded }, '[BudgetEnforcer] Budget exceeded');
     return res.status(429).json({
@@ -57,4 +127,4 @@ function recordSpend(context, amount) {
   getHierarchicalBudget().record(context, amount);
 }
 
-module.exports = { budgetEnforcer, recordSpend };
+module.exports = { budgetEnforcer, recordSpend, estimateRequestCost };

package/src/api/middleware/budget.js

@@ -30,6 +30,36 @@ function budgetMiddleware(req, res, next) {
     });
   }
 
+  // Token-aware (TPM) rate limiting — off unless LYNKR_TPM_LIMIT is set.
+  // Pre-flight gates on the window's actual consumption plus this request's
+  // cheap estimate; the true-up lands in the res 'finish' handler below.
+  try {
+    const { countPayloadTokens } = require('../../utils/tokens');
+    const estInput = countPayloadTokens(req.body || {}).total || 0;
+    const estOutput = typeof req.body?.max_tokens === 'number' && req.body.max_tokens > 0
+      ? req.body.max_tokens
+      : 1024;
+    const tokenCheck = budgetManager.checkTokenRate(userId, estInput + estOutput);
+    if (!tokenCheck.allowed) {
+      logger.warn({
+        userId,
+        limit: tokenCheck.limit,
+        current: tokenCheck.current,
+        estimated: tokenCheck.estimated,
+      }, 'Token rate limit (TPM) exceeded');
+      return res.status(429).json({
+        error: 'rate_limit_exceeded',
+        message: `Token rate limit exceeded: ${tokenCheck.limit} tokens per minute`,
+        limit: tokenCheck.limit,
+        current: tokenCheck.current,
+        resetInMs: tokenCheck.resetInMs,
+        retryAfter: Math.ceil(tokenCheck.resetInMs / 1000),
+      });
+    }
+  } catch (err) {
+    logger.debug({ err: err.message }, 'TPM check failed — allowing request');
+  }
+
   // Check budget
   const budgetCheck = budgetManager.checkBudget(userId);
   if (!budgetCheck.allowed) {
@@ -68,14 +98,18 @@ function budgetMiddleware(req, res, next) {
     try {
       const usage = res.locals.usage;
       if (!usage) return;
+      const tokensInput = usage.prompt_tokens || usage.input_tokens || 0;
+      const tokensOutput = usage.completion_tokens || usage.output_tokens || 0;
       budgetManager.recordUsage(userId, req.session?.id || null, {
-        tokensInput: usage.prompt_tokens || usage.input_tokens || 0,
-        tokensOutput: usage.completion_tokens || usage.output_tokens || 0,
+        tokensInput,
+        tokensOutput,
         costUsd: usage.cost_usd || 0,
         model: usage.model || null,
         endpoint: req.path,
         latencyMs: Date.now() - req.budgetInfo.startTime,
       });
+      // TPM true-up with actual consumption (no-op unless LYNKR_TPM_LIMIT set).
+      budgetManager.recordTokenUsage(userId, tokensInput + tokensOutput);
     } catch (err) {
       logger.warn({ err: err.message }, 'Failed to record usage after response');
     }