free-coding-models 0.2.17 → 0.3.0

package/bin/free-coding-models.js

@@ -98,6 +98,7 @@ import { loadConfig, saveConfig, getApiKey, getProxySettings, resolveApiKeys, ad
 import { buildMergedModels } from '../src/model-merger.js'
 import { ProxyServer } from '../src/proxy-server.js'
 import { loadOpenCodeConfig, saveOpenCodeConfig, syncToOpenCode, restoreOpenCodeBackup, cleanupOpenCodeProxyConfig } from '../src/opencode-sync.js'
+import { syncProxyToTool, cleanupToolConfig, PROXY_SYNCABLE_TOOLS } from '../src/proxy-sync.js'
 import { usageForRow as _usageForRow } from '../src/usage-reader.js'
 import { loadRecentLogs } from '../src/log-reader.js'
 import { buildProviderModelTokenKey, loadTokenUsageByProviderModel } from '../src/token-usage-reader.js'
@@ -108,7 +109,7 @@ import { TIER_COLOR } from '../src/tier-colors.js'
 import { resolveCloudflareUrl, buildPingRequest, ping, extractQuotaPercent, getProviderQuotaPercentCached, usagePlaceholderForProvider } from '../src/ping.js'
 import { runFiableMode, filterByTierOrExit, fetchOpenRouterFreeModels } from '../src/analysis.js'
 import { PROVIDER_METADATA, ENV_VAR_NAMES, isWindows, isMac } from '../src/provider-metadata.js'
-import { parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelemetryConfig, getTelemetryDistinctId, getTelemetrySystem, getTelemetryTerminal, isTelemetryEnabled, sendUsageTelemetry, sendFeatureRequest, sendBugReport } from '../src/telemetry.js'
+import { parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelemetryConfig, getTelemetryDistinctId, getTelemetrySystem, getTelemetryTerminal, isTelemetryEnabled, sendUsageTelemetry, sendBugReport } from '../src/telemetry.js'
 import { ensureFavoritesConfig, toFavoriteKey, syncFavoriteFlags, toggleFavoriteModel } from '../src/favorites.js'
 import { checkForUpdateDetailed, checkForUpdate, runUpdate, promptUpdateNotification } from '../src/updater.js'
 import { promptApiKey } from '../src/setup.js'
@@ -140,7 +141,7 @@ const readline = require('readline')
 const pkg = require('../package.json')
 const LOCAL_VERSION = pkg.version
 
-// 📖 sendFeatureRequest, sendBugReport → imported from ../src/telemetry.js
+// 📖 sendBugReport → imported from ../src/telemetry.js
 
 // 📖 parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelemetryConfig → imported from ../src/telemetry.js
 
@@ -199,6 +200,80 @@ async function main() {
     process.exit(0)
   }
 
+  // 📖 CLI subcommand: free-coding-models daemon <action>
+  const daemonSubcmd = process.argv[2] === 'daemon' ? (process.argv[3] || 'status') : null
+  if (daemonSubcmd) {
+    const dm = await import('../src/daemon-manager.js')
+    if (daemonSubcmd === 'status') {
+      const s = await dm.getDaemonStatus()
+      console.log()
+      if (s.status === 'running') {
+        console.log(chalk.greenBright(`  📡 FCM Proxy V2: Running`))
+        console.log(chalk.dim(`  PID: ${s.info.pid}  •  Port: ${s.info.port}  •  Accounts: ${s.info.accountCount}  •  Version: ${s.info.version}`))
+        console.log(chalk.dim(`  Started: ${s.info.startedAt}`))
+      } else if (s.status === 'stopped') {
+        console.log(chalk.yellow(`  📡 FCM Proxy V2: Stopped (service installed but not running)`))
+      } else if (s.status === 'stale') {
+        console.log(chalk.red(`  📡 FCM Proxy V2: Stale (crashed — PID ${s.info?.pid} no longer alive)`))
+      } else if (s.status === 'unhealthy') {
+        console.log(chalk.red(`  📡 FCM Proxy V2: Unhealthy (PID alive but health check failed)`))
+      } else {
+        console.log(chalk.dim(`  📡 FCM Proxy V2: Not installed`))
+        console.log(chalk.dim(`  Install via: free-coding-models daemon install`))
+      }
+      console.log()
+      process.exit(0)
+    }
+    if (daemonSubcmd === 'install') {
+      const result = dm.installDaemon()
+      console.log()
+      if (result.success) {
+        console.log(chalk.greenBright('  ✅ FCM Proxy V2 background service installed and started!'))
+        console.log(chalk.dim('  The proxy will now run automatically at login.'))
+      } else {
+        console.log(chalk.red(`  ❌ Install failed: ${result.error}`))
+      }
+      console.log()
+      process.exit(result.success ? 0 : 1)
+    }
+    if (daemonSubcmd === 'uninstall') {
+      const result = dm.uninstallDaemon()
+      console.log()
+      if (result.success) {
+        console.log(chalk.greenBright('  ✅ FCM Proxy V2 background service uninstalled.'))
+      } else {
+        console.log(chalk.red(`  ❌ Uninstall failed: ${result.error}`))
+      }
+      console.log()
+      process.exit(result.success ? 0 : 1)
+    }
+    if (daemonSubcmd === 'restart') {
+      const result = dm.restartDaemon()
+      console.log()
+      if (result.success) {
+        console.log(chalk.greenBright('  ✅ FCM Proxy V2 service restarted.'))
+      } else {
+        console.log(chalk.red(`  ❌ Restart failed: ${result.error}`))
+      }
+      console.log()
+      process.exit(result.success ? 0 : 1)
+    }
+    if (daemonSubcmd === 'logs') {
+      const logPath = dm.getDaemonLogPath()
+      console.log(chalk.dim(`  Log file: ${logPath}`))
+      try {
+        const { execSync } = await import('child_process')
+        execSync(`tail -50 "${logPath}"`, { stdio: 'inherit' })
+      } catch {
+        console.log(chalk.dim('  (no logs yet)'))
+      }
+      process.exit(0)
+    }
+    console.log(chalk.red(`  Unknown command: ${daemonSubcmd}`))
+    console.log(chalk.dim('  Usage: free-coding-models daemon [status|install|uninstall|restart|logs]'))
+    process.exit(1)
+  }
+
   // 📖 If --profile <name> was passed, load that profile into the live config
   let startupProfileSettings = null
   if (cliArgs.profileName) {
@@ -382,6 +457,7 @@ async function main() {
     terminalCols: process.stdout.columns || 80, // 📖 Current terminal width
     widthWarningStartedAt: (process.stdout.columns || 80) < 166 ? now : null, // 📖 Start the narrow-terminal countdown immediately when booting in a small viewport.
     widthWarningDismissed: false, // 📖 Esc hides the narrow-terminal warning early for the current narrow-width session.
+    widthWarningShowCount: 0, // 📖 Counter for how many times the narrow-terminal warning has been shown (max 2 per session).
     // 📖 Settings screen state (P key opens it)
     settingsOpen: false,          // 📖 Whether settings overlay is active
     settingsCursor: 0,            // 📖 Which provider row is selected in settings
@@ -396,6 +472,13 @@ async function main() {
     settingsUpdateError: null,    // 📖 Last update-check error message for maintenance row
     settingsProxyPortEditMode: false, // 📖 Whether Settings is editing the preferred proxy port field.
     settingsProxyPortBuffer: '',  // 📖 Inline input buffer for the preferred proxy port (0 = auto).
+    daemonStatus: 'not-installed', // 📖 Background daemon status: 'running'|'stopped'|'stale'|'unhealthy'|'not-installed'
+    daemonInfo: null,             // 📖 daemon.json contents when daemon is running
+    // 📖 Proxy & Daemon overlay state (opened from Settings)
+    proxyDaemonOpen: false,       // 📖 Whether the dedicated Proxy & Daemon overlay is active
+    proxyDaemonCursor: 0,         // 📖 Selected row in the proxy/daemon overlay
+    proxyDaemonScrollOffset: 0,   // 📖 Vertical scroll offset for the proxy/daemon overlay
+    proxyDaemonMessage: null,     // 📖 Feedback message { type: 'success'|'warning'|'error', msg: string, ts: number }
     config,                       // 📖 Live reference to the config object (updated on save)
     visibleSorted: [],            // 📖 Cached visible+sorted models — shared between render loop and key handlers
     helpVisible: false,           // 📖 Whether the help overlay (K key) is active
@@ -429,14 +512,9 @@ async function main() {
     activeProfile: getActiveProfileName(config), // 📖 Currently loaded profile name (or null)
     profileSaveMode: false,       // 📖 Whether the inline "Save profile" name input is active
     profileSaveBuffer: '',        // 📖 Typed characters for the profile name being saved
-    // 📖 Feature Request state (J key opens it)
-    featureRequestOpen: false,    // 📖 Whether the feature request overlay is active
-    featureRequestBuffer: '',     // 📖 Typed characters for the feature request message
-    featureRequestStatus: 'idle', // 📖 'idle'|'sending'|'success'|'error' — webhook send status
-    featureRequestError: null,    // 📖 Last webhook error message
-    // 📖 Bug Report state (I key opens it)
-    bugReportOpen: false,         // 📖 Whether the bug report overlay is active
-    bugReportBuffer: '',          // 📖 Typed characters for the bug report message
+    // 📖 Feedback state (J/I keys open it)
+    feedbackOpen: false,          // 📖 Whether the feedback overlay is active
+    bugReportBuffer: '',          // 📖 Typed characters for the feedback message
     bugReportStatus: 'idle',      // 📖 'idle'|'sending'|'success'|'error' — webhook send status
     bugReportError: null,         // 📖 Last webhook error message
     // 📖 OpenCode sync status (S key in settings)
@@ -468,6 +546,7 @@ async function main() {
       if (prevCols >= 166 || state.widthWarningDismissed) {
         state.widthWarningStartedAt = Date.now()
         state.widthWarningDismissed = false
+        state.widthWarningShowCount++ // 📖 Increment counter when showing the warning again
       } else if (!state.widthWarningStartedAt) {
         state.widthWarningStartedAt = Date.now()
       }
@@ -726,7 +805,7 @@ async function main() {
     ENV_VAR_NAMES,
     ensureProxyRunning,
     syncToOpenCode,
-    cleanupOpenCodeProxyConfig,
+    cleanupToolConfig,
     restoreOpenCodeBackup,
     checkForUpdateDetailed,
     runUpdate,
@@ -740,7 +819,6 @@ async function main() {
     getToolModeOrder,
     startRecommendAnalysis: overlays.startRecommendAnalysis,
     stopRecommendAnalysis: overlays.stopRecommendAnalysis,
-    sendFeatureRequest,
     sendBugReport,
     stopUi,
     ping,
@@ -788,27 +866,27 @@ async function main() {
     refreshAutoPingMode()
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.featureRequestOpen && !state.bugReportOpen && !state.changelogOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen && !state.proxyDaemonOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
     const content = state.settingsOpen
       ? overlays.renderSettings()
+      : state.proxyDaemonOpen
+        ? overlays.renderProxyDaemon()
       : state.installEndpointsOpen
         ? overlays.renderInstallEndpoints()
       : state.recommendOpen
         ? overlays.renderRecommend()
-        : state.featureRequestOpen
-          ? overlays.renderFeatureRequest()
-          : state.bugReportOpen
-            ? overlays.renderBugReport()
-              : state.helpVisible
+        : state.feedbackOpen
+          ? overlays.renderFeedback()
+            : state.helpVisible
                 ? overlays.renderHelp()
               : state.logVisible
                 ? overlays.renderLog()
               : state.changelogOpen
                 ? overlays.renderChangelog()
-                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion)
+                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion)
     process.stdout.write(ALT_HOME + content)
   }, Math.round(1000 / FPS))
 
@@ -816,7 +894,7 @@ async function main() {
   const initialVisible = state.results.filter(r => !r.hidden)
   state.visibleSorted = sortResultsWithPinnedFavorites(initialVisible, state.sortColumn, state.sortDirection)
 
-  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion))
+  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.widthWarningShowCount, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true, state.isOutdated, state.latestVersion))
 
   // 📖 If --recommend was passed, auto-open the Smart Recommend overlay on start
   if (cliArgs.recommendMode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.2.17",
+  "version": "0.3.0",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",
@@ -36,7 +36,8 @@
   "type": "module",
   "main": "bin/free-coding-models.js",
   "bin": {
-    "free-coding-models": "./bin/free-coding-models.js"
+    "free-coding-models": "./bin/free-coding-models.js",
+    "fcm-proxy-daemon": "./bin/fcm-proxy-daemon.js"
   },
   "files": [
     "bin/",

package/src/account-manager.js

@@ -39,6 +39,12 @@ const UNKNOWN_COOLDOWN_BASE_MS = 15 * 60 * 1000 // 15m initial cooldown
 const UNKNOWN_COOLDOWN_MAX_MS = 6 * 60 * 60 * 1000 // 6h max cooldown
 const KNOWN_FALLBACK_COOLDOWN_MS = 5 * 60 * 1000 // 5m fallback for known providers
 
+// 📖 Generic consecutive-failure cooldown constants.
+// When an account accumulates FAILURE_COOLDOWN_THRESHOLD consecutive non-429 failures,
+// it enters a graduated cooldown (30s → 60s → 120s) so the proxy routes around it.
+const FAILURE_COOLDOWN_THRESHOLD = 3
+const FAILURE_COOLDOWN_STEPS_MS = [30_000, 60_000, 120_000]
+
 // ─── Internal: per-account health state ──────────────────────────────────────
 
 class AccountHealth {
@@ -85,6 +91,15 @@ class AccountHealth {
       cooldownUntilMs: 0,
       probeInFlight: false,
     }
+
+    /**
+     * 📖 Generic consecutive-failure tracking for non-429 errors.
+     * When consecutiveFailures >= FAILURE_COOLDOWN_THRESHOLD, the account enters
+     * a graduated cooldown to avoid wasting requests on a failing endpoint.
+     */
+    this.consecutiveFailures = 0
+    this.failureCooldownUntilMs = 0
+    this.failureCooldownLevel = 0
   }
 
   /**
@@ -265,6 +280,9 @@ export class AccountManager {
     const retryAfterTs = this._retryAfterMap.get(acct.id)
     if (retryAfterTs && Date.now() < retryAfterTs) return false
 
+    // 📖 Generic failure cooldown — blocks account after consecutive non-429 failures
+    if (health.failureCooldownUntilMs > 0 && Date.now() < health.failureCooldownUntilMs) return false
+
     // Only exclude when quota is known to be nearly exhausted.
     // When quotaSignal is 'unknown' (null quotaPercent), we remain available.
     if (health.quotaSignal === 'known' && health.quotaPercent !== null && health.quotaPercent <= 5) return false
@@ -455,6 +473,17 @@ export class AccountManager {
     if (classifiedError?.retryAfterSec) {
       this._retryAfterMap.set(accountId, Date.now() + classifiedError.retryAfterSec * 1000)
     }
+
+    // 📖 Generic consecutive-failure cooldown: when an account hits FAILURE_COOLDOWN_THRESHOLD
+    // consecutive non-429 failures, put it in graduated cooldown (30s → 60s → 120s)
+    // so the proxy routes around it instead of wasting requests.
+    health.consecutiveFailures++
+    if (health.consecutiveFailures >= FAILURE_COOLDOWN_THRESHOLD) {
+      const stepIdx = Math.min(health.failureCooldownLevel, FAILURE_COOLDOWN_STEPS_MS.length - 1)
+      health.failureCooldownUntilMs = Date.now() + FAILURE_COOLDOWN_STEPS_MS[stepIdx]
+      health.failureCooldownLevel++
+      health.consecutiveFailures = 0
+    }
   }
 
   /**
@@ -532,6 +561,11 @@ export class AccountManager {
 
     // Clear retry-after from the retryAfterMap (no longer cooling down)
     this._retryAfterMap.delete(accountId)
+
+    // 📖 Reset generic failure cooldown state on success
+    health.consecutiveFailures = 0
+    health.failureCooldownUntilMs = 0
+    health.failureCooldownLevel = 0
   }
 
   /**

package/src/anthropic-translator.js

@@ -0,0 +1,370 @@
+/**
+ * @file src/anthropic-translator.js
+ * @description Bidirectional wire format translation between Anthropic Messages API
+ * and OpenAI Chat Completions API.
+ *
+ * 📖 This is the key module that enables Claude Code to work natively through the
+ *    FCM proxy without needing the external "free-claude-code" Python proxy.
+ *    Claude Code sends requests in Anthropic format (POST /v1/messages) and this
+ *    module translates them to OpenAI format for the upstream providers, then
+ *    translates the responses back.
+ *
+ * 📖 Supports both JSON and SSE streaming modes.
+ *
+ * @functions
+ *   → translateAnthropicToOpenAI(body) — Convert Anthropic Messages request → OpenAI chat completions
+ *   → translateOpenAIToAnthropic(openaiResponse, requestModel) — Convert OpenAI JSON response → Anthropic
+ *   → createAnthropicSSETransformer(requestModel) — Create a Transform stream for SSE translation
+ *
+ * @exports translateAnthropicToOpenAI, translateOpenAIToAnthropic, createAnthropicSSETransformer
+ * @see src/proxy-server.js — routes /v1/messages through this translator
+ */
+
+import { Transform } from 'node:stream'
+import { randomUUID } from 'node:crypto'
+
+/**
+ * 📖 Translate an Anthropic Messages API request body to OpenAI Chat Completions format.
+ *
+ * Anthropic format:
+ *   { model, messages: [{role, content}], system, max_tokens, stream, temperature, top_p, stop_sequences }
+ *
+ * OpenAI format:
+ *   { model, messages: [{role, content}], max_tokens, stream, temperature, top_p, stop }
+ *
+ * @param {object} body — Anthropic request body
+ * @returns {object} — OpenAI-compatible request body
+ */
+export function translateAnthropicToOpenAI(body) {
+  // 📖 Guard against null/undefined/non-object input
+  if (!body || typeof body !== 'object') return { model: '', messages: [], stream: false }
+  if (!Array.isArray(body.messages)) body = { ...body, messages: [] }
+
+  const openaiMessages = []
+
+  // 📖 Anthropic "system" field → OpenAI system message
+  if (body.system) {
+    if (typeof body.system === 'string') {
+      openaiMessages.push({ role: 'system', content: body.system })
+    } else if (Array.isArray(body.system)) {
+      // 📖 Anthropic supports system as array of content blocks
+      const text = body.system
+        .filter(b => b.type === 'text')
+        .map(b => b.text)
+        .join('\n\n')
+      if (text) openaiMessages.push({ role: 'system', content: text })
+    }
+  }
+
+  // 📖 Convert Anthropic messages to OpenAI format
+  if (Array.isArray(body.messages)) {
+    for (const msg of body.messages) {
+      const role = msg.role === 'assistant' ? 'assistant' : 'user'
+
+      if (typeof msg.content === 'string') {
+        openaiMessages.push({ role, content: msg.content })
+      } else if (Array.isArray(msg.content)) {
+        // 📖 Anthropic content blocks: [{type: "text", text: "..."}, {type: "tool_result", ...}]
+        const textParts = msg.content
+          .filter(b => b.type === 'text')
+          .map(b => b.text)
+        const toolResults = msg.content.filter(b => b.type === 'tool_result')
+        const toolUses = msg.content.filter(b => b.type === 'tool_use')
+
+        // 📖 Tool use blocks (assistant) → OpenAI tool_calls
+        if (toolUses.length > 0 && role === 'assistant') {
+          const toolCalls = toolUses.map(tu => ({
+            id: tu.id || randomUUID(),
+            type: 'function',
+            function: {
+              name: tu.name,
+              arguments: typeof tu.input === 'string' ? tu.input : JSON.stringify(tu.input || {}),
+            }
+          }))
+          openaiMessages.push({
+            role: 'assistant',
+            content: textParts.join('\n') || null,
+            tool_calls: toolCalls,
+          })
+        }
+        // 📖 Tool result blocks (user) → OpenAI tool messages
+        else if (toolResults.length > 0) {
+          // 📖 First push any text parts as user message
+          if (textParts.length > 0) {
+            openaiMessages.push({ role: 'user', content: textParts.join('\n') })
+          }
+          for (const tr of toolResults) {
+            const content = typeof tr.content === 'string'
+              ? tr.content
+              : Array.isArray(tr.content)
+                ? tr.content.filter(b => b.type === 'text').map(b => b.text).join('\n')
+                : JSON.stringify(tr.content || '')
+            openaiMessages.push({
+              role: 'tool',
+              tool_call_id: tr.tool_use_id || tr.id || '',
+              content,
+            })
+          }
+        }
+        // 📖 Plain text content blocks → join into single message
+        else if (textParts.length > 0) {
+          openaiMessages.push({ role, content: textParts.join('\n') })
+        }
+      }
+    }
+  }
+
+  const result = {
+    model: body.model,
+    messages: openaiMessages,
+    stream: body.stream === true,
+  }
+
+  // 📖 Map Anthropic parameters to OpenAI equivalents
+  if (body.max_tokens != null) result.max_tokens = body.max_tokens
+  if (body.temperature != null) result.temperature = body.temperature
+  if (body.top_p != null) result.top_p = body.top_p
+  if (Array.isArray(body.stop_sequences) && body.stop_sequences.length > 0) {
+    result.stop = body.stop_sequences
+  }
+
+  // 📖 Map Anthropic tools to OpenAI function tools
+  if (Array.isArray(body.tools) && body.tools.length > 0) {
+    result.tools = body.tools.map(tool => ({
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description || '',
+        parameters: tool.input_schema || {},
+      }
+    }))
+  }
+
+  return result
+}
+
+/**
+ * 📖 Translate an OpenAI Chat Completions JSON response to Anthropic Messages format.
+ *
+ * @param {object} openaiResponse — parsed OpenAI response
+ * @param {string} requestModel — model name from the original request
+ * @returns {object} — Anthropic Messages response
+ */
+export function translateOpenAIToAnthropic(openaiResponse, requestModel) {
+  const choice = openaiResponse.choices?.[0]
+  const message = choice?.message || {}
+  const content = []
+
+  // 📖 Text content → Anthropic text block
+  if (message.content) {
+    content.push({ type: 'text', text: message.content })
+  }
+
+  // 📖 Tool calls → Anthropic tool_use blocks
+  if (Array.isArray(message.tool_calls)) {
+    for (const tc of message.tool_calls) {
+      let input = {}
+      try { input = JSON.parse(tc.function?.arguments || '{}') } catch { /* ignore */ }
+      content.push({
+        type: 'tool_use',
+        id: tc.id || randomUUID(),
+        name: tc.function?.name || '',
+        input,
+      })
+    }
+  }
+
+  // 📖 Fallback: Anthropic requires at least one content block — provide empty text if none
+  if (content.length === 0) {
+    content.push({ type: 'text', text: '' })
+  }
+
+  // 📖 Map OpenAI finish_reason → Anthropic stop_reason
+  let stopReason = 'end_turn'
+  if (choice?.finish_reason === 'stop') stopReason = 'end_turn'
+  else if (choice?.finish_reason === 'length') stopReason = 'max_tokens'
+  else if (choice?.finish_reason === 'tool_calls') stopReason = 'tool_use'
+
+  return {
+    id: openaiResponse.id || `msg_${randomUUID().replace(/-/g, '')}`,
+    type: 'message',
+    role: 'assistant',
+    content,
+    model: requestModel || openaiResponse.model || '',
+    stop_reason: stopReason,
+    stop_sequence: null,
+    usage: {
+      input_tokens: openaiResponse.usage?.prompt_tokens || 0,
+      output_tokens: openaiResponse.usage?.completion_tokens || 0,
+    },
+  }
+}
+
+/**
+ * 📖 Create a Transform stream that converts OpenAI SSE chunks to Anthropic SSE format.
+ *
+ * OpenAI SSE:
+ *   data: {"choices":[{"delta":{"content":"Hello"}}]}
+ *
+ * Anthropic SSE:
+ *   event: message_start
+ *   data: {"type":"message_start","message":{...}}
+ *
+ *   event: content_block_start
+ *   data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+ *
+ *   event: content_block_delta
+ *   data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
+ *
+ *   event: message_stop
+ *   data: {"type":"message_stop"}
+ *
+ * @param {string} requestModel — model from original request
+ * @returns {{ transform: Transform, getUsage: () => object }}
+ */
+// 📖 Max SSE buffer size to prevent memory exhaustion from malformed streams (1 MB)
+const MAX_SSE_BUFFER = 1 * 1024 * 1024
+
+export function createAnthropicSSETransformer(requestModel) {
+  let headerSent = false
+  // 📖 Track block indices for proper content_block_start/stop/delta indexing.
+  // nextBlockIndex increments for each new content block (text or tool_use).
+  // currentBlockIndex tracks the index of the most recently opened block.
+  let nextBlockIndex = 0
+  let currentBlockIndex = -1
+  let inputTokens = 0
+  let outputTokens = 0
+  let buffer = ''
+
+  const transform = new Transform({
+    transform(chunk, encoding, callback) {
+      buffer += chunk.toString()
+      // 📖 Guard against unbounded buffer growth from malformed SSE streams
+      if (buffer.length > MAX_SSE_BUFFER) {
+        buffer = ''
+        return callback(new Error('SSE buffer overflow'))
+      }
+      const lines = buffer.split('\n')
+      // 📖 Keep the last incomplete line in the buffer
+      buffer = lines.pop() || ''
+
+      for (const line of lines) {
+        if (!line.startsWith('data: ')) continue
+        const payload = line.slice(6).trim()
+        if (payload === '[DONE]') {
+          // 📖 End of stream — close any open block, then send message_delta + message_stop
+          if (currentBlockIndex >= 0) {
+            this.push(`event: content_block_stop\ndata: ${JSON.stringify({ type: 'content_block_stop', index: currentBlockIndex })}\n\n`)
+            currentBlockIndex = -1
+          }
+          this.push(`event: message_delta\ndata: ${JSON.stringify({
+            type: 'message_delta',
+            delta: { stop_reason: 'end_turn', stop_sequence: null },
+            usage: { output_tokens: outputTokens },
+          })}\n\n`)
+          this.push(`event: message_stop\ndata: ${JSON.stringify({ type: 'message_stop' })}\n\n`)
+          continue
+        }
+
+        let parsed
+        try { parsed = JSON.parse(payload) } catch { continue }
+
+        // 📖 Send message_start header on first chunk
+        if (!headerSent) {
+          headerSent = true
+          this.push(`event: message_start\ndata: ${JSON.stringify({
+            type: 'message_start',
+            message: {
+              id: parsed.id || `msg_${randomUUID().replace(/-/g, '')}`,
+              type: 'message',
+              role: 'assistant',
+              content: [],
+              model: requestModel || parsed.model || '',
+              stop_reason: null,
+              stop_sequence: null,
+              usage: { input_tokens: inputTokens, output_tokens: 0 },
+            },
+          })}\n\n`)
+        }
+
+        const choice = parsed.choices?.[0]
+        if (!choice) continue
+        const delta = choice.delta || {}
+
+        // 📖 Track usage if present
+        if (parsed.usage) {
+          inputTokens = parsed.usage.prompt_tokens || inputTokens
+          outputTokens = parsed.usage.completion_tokens || outputTokens
+        }
+
+        // 📖 Text delta
+        if (delta.content) {
+          if (currentBlockIndex < 0 || nextBlockIndex === 0) {
+            // 📖 Open first text block
+            currentBlockIndex = nextBlockIndex++
+            this.push(`event: content_block_start\ndata: ${JSON.stringify({
+              type: 'content_block_start',
+              index: currentBlockIndex,
+              content_block: { type: 'text', text: '' },
+            })}\n\n`)
+          }
+          this.push(`event: content_block_delta\ndata: ${JSON.stringify({
+            type: 'content_block_delta',
+            index: currentBlockIndex,
+            delta: { type: 'text_delta', text: delta.content },
+          })}\n\n`)
+        }
+
+        // 📖 Tool call deltas (if model supports tool use)
+        if (Array.isArray(delta.tool_calls)) {
+          for (const tc of delta.tool_calls) {
+            if (tc.function?.name) {
+              // 📖 New tool call — close previous block if open, then start new one
+              if (currentBlockIndex >= 0) {
+                this.push(`event: content_block_stop\ndata: ${JSON.stringify({ type: 'content_block_stop', index: currentBlockIndex })}\n\n`)
+              }
+              currentBlockIndex = nextBlockIndex++
+              this.push(`event: content_block_start\ndata: ${JSON.stringify({
+                type: 'content_block_start',
+                index: currentBlockIndex,
+                content_block: {
+                  type: 'tool_use',
+                  id: tc.id || randomUUID(),
+                  name: tc.function.name,
+                  input: {},
+                },
+              })}\n\n`)
+            }
+            if (tc.function?.arguments) {
+              this.push(`event: content_block_delta\ndata: ${JSON.stringify({
+                type: 'content_block_delta',
+                index: currentBlockIndex >= 0 ? currentBlockIndex : 0,
+                delta: { type: 'input_json_delta', partial_json: tc.function.arguments },
+              })}\n\n`)
+            }
+          }
+        }
+
+        // 📖 Handle finish_reason for tool_calls — close ALL open blocks
+        if (choice.finish_reason === 'tool_calls' && currentBlockIndex >= 0) {
+          this.push(`event: content_block_stop\ndata: ${JSON.stringify({ type: 'content_block_stop', index: currentBlockIndex })}\n\n`)
+          currentBlockIndex = -1
+        }
+      }
+      callback()
+    },
+
+    flush(callback) {
+      // 📖 Process any remaining buffer
+      if (buffer.trim()) {
+        // ignore incomplete data
+      }
+      callback()
+    },
+  })
+
+  return {
+    transform,
+    getUsage: () => ({ input_tokens: inputTokens, output_tokens: outputTokens }),
+  }
+}