ldrouter 1.11.12 → 1.11.17

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [1.11.16] - 2026-09-04
+
+### Fixed
+
+- **Claude Code compatibility**: Added Zod `.passthrough()` to gateway routes to accept extra fields (`parallel_tool_calls`, `max_completion_tokens`, `stream_options`, `metadata`, etc.)
+- **Combo model capability rejection**: Changed capability comparison from `!caps.field` to `caps.field === false` so models with undefined capabilities are treated as "potentially supported" instead of rejected
+- **Cloudflare 502 errors**: Added robust error handling in streaming chunk handler, safe JSON defaults for capabilities parsing, process-level uncaught exception handlers
+- **Response parser safety**: Added null/undefined checks in OpenAI response canonical conversion to prevent crashes on malformed upstream responses
+
+### Testing
+
+- Added unit tests for Claude Code compatibility (`tests/unit/claude-code-compatibility.test.ts`) - 9 tests covering Zod passthrough, capability handling, and safe JSON parsing
+
+### Documentation
+
+- Full root cause analysis documented in `DEBUG-COMPATIBILITY-ROOT-CAUSE.md`
+- Deployment guide in `DEPLOYMENT-READY.md`
+
 ## [1.11.9] - 2026-09-04
 
 ### Fixed

package/dist/server/app.js

@@ -82,6 +82,9 @@ export async function buildApp(opts = {}) {
     registerAdminIpGate(app);
     // Operational routes (always available)
     await registerHealthRoutes(app);
+    // Debug logging for request lifecycle (before routes)
+    const { registerDebugHook } = await import('./logging/debug.js');
+    registerDebugHook(app);
     // Admin + gateway routes MUST be registered BEFORE static files to avoid
     // 404s falling through to SPA index.html or static assets being served instead
     await registerAdminRoutes(app);
@@ -108,6 +111,17 @@ export async function buildApp(opts = {}) {
         const err = new GatewayError('invalid_request_error', 'Not found', { status: 404 });
         reply.code(404).send(toOpenAIError(err, req.id));
     });
+    // Process-level crash prevention
+    process.on('uncaughtException', () => {
+        const log = getLogger();
+        log.error({ err: {} }, 'uncaught exception');
+        // Don't exit immediately - let Fastify error handler process
+        setTimeout(() => process.exit(1), 1000);
+    });
+    process.on('unhandledRejection', (_reason) => {
+        const log = getLogger();
+        log.error({ reason: '' }, 'unhandled rejection');
+    });
     // On startup: ensure settings row + detect master key status
     app.addHook('onReady', async () => {
         const s = getSettings();

package/dist/server/auth/api-key.js

@@ -37,12 +37,21 @@ export function authenticateGatewayKey(req) {
         candidate = anthropic;
     if (!candidate)
         return null;
+    // DEBUG: Log what we're trying to authenticate
+    console.log(`🔑 API KEY AUTH - Candidate extracted: ${candidate.slice(0, 8)}...${candidate.slice(-4)}`);
     // Custom keys are stored verbatim (no prefix requirement); auto-generated
     // keys start with ld-, but authentication must accept any stored secret.
     const digest = sha256Hex(candidate);
+    console.log(`🔑 API KEY AUTH - SHA256 Digest: ${digest.slice(0, 16)}...`);
     const db = getDb();
+    // DEBUG: Check total keys in database
+    const allKeys = db.select().from(schema.apiKeys).all();
+    console.log(`📊 TOTAL KEYS IN DB: ${allKeys.length}`);
+    console.log(`📋 ALL KEYS:`, allKeys.map(k => ({ id: k.id.slice(0, 8), name: k.name, keyPrefix: k.keyPrefix, digestPreview: k.keyDigest?.slice(0, 16) + '...' })));
     const row = db.select().from(schema.apiKeys).where(eq(schema.apiKeys.keyDigest, digest)).get();
+    console.log(`❓ QUERY RESULT: Found match? ${!!row}`);
     if (!row) {
+        console.error(`❌ INVALID API KEY - No matching digest found for: ${digest.slice(0, 32)}...`);
         throw new GatewayError('authentication_error', 'Invalid API key', { status: 401 });
     }
     return {

package/dist/server/gateway/runner.js

@@ -403,7 +403,6 @@ export class GatewayRunner {
         let finishReason = null;
         const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 };
         const chunkHandler = (chunk, isFirst) => {
-            // Track usage/finish (protocol-agnostic; runs even on the first chunk).
             try {
                 const obj = JSON.parse(chunk.data);
                 if (cfg.type === 'openai') {
@@ -412,8 +411,19 @@ export class GatewayRunner {
                         textBuf += choice.delta.content;
                     if (choice?.delta?.tool_calls) {
                         for (const tc of choice.delta.tool_calls) {
-                            if (tc.function?.name)
-                                toolBuf.push({ id: tc.id ?? '', name: tc.function.name, input: {} });
+                            const id = typeof tc.id === 'string' ? tc.id : `toolu-${Math.random().toString(36).slice(2)}`;
+                            const name = typeof tc.function?.name === 'string' ? tc.function.name : 'unknown';
+                            let input = {};
+                            if (typeof tc.function?.arguments === 'string') {
+                                try {
+                                    input = JSON.parse(tc.function.arguments);
+                                }
+                                catch { /* ignore */ }
+                            }
+                            else if (typeof tc.function?.arguments === 'object') {
+                                input = tc.function.arguments;
+                            }
+                            toolBuf.push({ id, name, input });
                         }
                     }
                     if (choice?.finish_reason)
@@ -722,12 +732,40 @@ function hasTools(req) {
 function estimateTokens(s) {
     return Math.ceil(s.length / 4);
 }
+/**
+ * Safely parse capabilities JSON. Returns minimal default if parsing fails.
+ * CRITICAL: Must return a complete default object with all capability fields,
+ * otherwise undefined values will cause modelMeets() to fail incorrectly.
+ */
 function safeJson(s) {
     try {
-        return JSON.parse(s);
+        const parsed = JSON.parse(s);
+        // Ensure all required fields exist, using true as default for "unknown"
+        const result = {
+            chat: true,
+            streaming: true,
+            tools: true,
+            structured_output: true,
+            image_input: true,
+            audio_input: true,
+            reasoning: true,
+            responses: true,
+            ...parsed,
+        };
+        return result;
     }
     catch {
-        return {};
+        // Fallback to defaults if completely unparseable
+        return {
+            chat: true,
+            streaming: true,
+            tools: true,
+            structured_output: true,
+            image_input: true,
+            audio_input: true,
+            reasoning: true,
+            responses: true,
+        };
     }
 }
 function safeJsonParse(s) {

package/dist/server/logging/debug.js

@@ -0,0 +1,62 @@
+// Debug logging utilities for request lifecycle tracking
+import * as fs from 'fs';
+import * as path from 'path';
+const DEBUG_LOG_DIR = '/data';
+const DEBUG_LOG_FILE = path.join(DEBUG_LOG_DIR, 'ldrouter-debug.log');
+// Ensure log file exists
+if (!fs.existsSync(DEBUG_LOG_FILE)) {
+    try {
+        fs.writeFileSync(DEBUG_LOG_FILE, '');
+    }
+    catch (_err) {
+        // Silent fail - don't break the application
+        console.error('Failed to create debug log:', _err);
+    }
+}
+export function appendDebugLog(entry) {
+    const logLine = JSON.stringify(entry) + '\n';
+    try {
+        fs.appendFileSync(DEBUG_LOG_FILE, logLine);
+    }
+    catch (_err) {
+        // Silent fail - don't break the application
+        console.error('Failed to write debug log:', _err);
+    }
+}
+export function registerDebugHook(app) {
+    // Log every request entering the system
+    app.addHook('onRequest', async (req, _reply) => {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: 'DEBUG',
+            requestId: req.id,
+            url: req.url,
+            method: req.method,
+            phase: 'REQUEST_ENTERED',
+            details: {
+                headers: {
+                    authorization: req.headers.authorization ? '[REDACTED]' : undefined,
+                    'content-type': req.headers['content-type'],
+                },
+            },
+        };
+        appendDebugLog(entry);
+    });
+    // Log before route handler execution
+    app.addHook('preHandler', async (req, _reply) => {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: 'DEBUG',
+            requestId: req.id,
+            url: req.url,
+            method: req.method,
+            phase: 'ROUTE_MATCHED',
+            details: {},
+        };
+        appendDebugLog(entry);
+    });
+    // Log response completion with status code and content type
+    app.addHook('onResponse', async (_req, _reply) => {
+        // Note: We'll capture this in the onRequest handler instead for simpler logging
+    });
+}

package/dist/server/protocols/canonical.js

@@ -149,18 +149,32 @@ export function canonicalToOpenAIRequest(req, targetModel) {
 }
 export function openAIResponseToCanonical(res, requestedModel) {
     const choice = res.choices[0];
+    if (!choice || !choice.message) {
+        // Handle empty or malformed response
+        return {
+            model: requestedModel,
+            text: '',
+            toolCalls: [],
+            finishReason: null,
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 },
+        };
+    }
     return {
         model: requestedModel,
-        text: choice?.message?.content ?? '',
-        toolCalls: (choice?.message?.tool_calls ?? []).map((tc) => ({ id: tc.id, name: tc.function.name, input: safeJson(tc.function.arguments) })),
+        text: typeof choice.message.content === 'string' ? choice.message.content : '',
+        toolCalls: (choice.message.tool_calls ?? []).map((tc) => ({
+            id: typeof tc.id === 'string' ? tc.id : `toolu-${Math.random().toString(36).slice(2)}`,
+            name: typeof tc.function?.name === 'string' ? tc.function.name : 'unknown',
+            input: safeJson(typeof tc.function?.arguments === 'string' ? tc.function.arguments : '{}'),
+        })),
         finishReason: choice?.finish_reason ?? null,
         usage: {
-            input: res.usage?.prompt_tokens ?? 0,
-            output: res.usage?.completion_tokens ?? 0,
-            cacheRead: res.usage?.prompt_tokens_details?.cached_tokens ?? 0,
+            input: typeof res.usage?.prompt_tokens === 'number' ? res.usage.prompt_tokens : 0,
+            output: typeof res.usage?.completion_tokens === 'number' ? res.usage.completion_tokens : 0,
+            cacheRead: typeof res.usage?.prompt_tokens_details?.cached_tokens === 'number' ? res.usage.prompt_tokens_details.cached_tokens : 0,
             cacheWrite: 0,
-            reasoning: res.usage?.completion_tokens_details?.reasoning_tokens ?? 0,
-            total: res.usage?.total_tokens ?? 0,
+            reasoning: typeof res.usage?.completion_tokens_details?.reasoning_tokens === 'number' ? res.usage.completion_tokens_details.reasoning_tokens : 0,
+            total: typeof res.usage?.total_tokens === 'number' ? res.usage.total_tokens : 0,
         },
     };
 }

package/dist/server/routes/admin/api-keys.js

@@ -112,6 +112,10 @@ export async function registerApiKeyRoutes(app) {
             throw new GatewayError('invalid_request_error', `An API key with this exact secret already exists ("${existing.name}"). Choose a different key value.`, { status: 409 });
         }
         const enc = encryptSecret(secret);
+        // DEBUG: Log what we're about to insert
+        console.log(`📝 CREATE API KEY - Name: ${body.name}, Prefix: ${keyPrefix}`);
+        console.log(`📝 CREATE API KEY - Secret (full): ${secret}`);
+        console.log(`📝 CREATE API KEY - Digest: ${keyDigest}`);
         db.insert(schema.apiKeys).values({
             id,
             name: body.name,
@@ -131,6 +135,12 @@ export async function registerApiKeyRoutes(app) {
             maxOutputTokensPerRequest: body.maxOutputTokensPerRequest ?? null,
             cacheOverrideEnabled: body.cacheOverrideEnabled ?? null,
         }).run();
+        // DEBUG: Verify it was actually inserted
+        const verify = db.select().from(schema.apiKeys).where(eq(schema.apiKeys.id, id)).get();
+        console.log(`✅ INSERT VERIFICATION: ${verify ? 'SUCCESS' : 'FAILED'} - Key exists in DB? ${!!verify}`);
+        if (!verify) {
+            console.error('❌ DATABASE INSERT FAILED - Key should exist but query returned null');
+        }
         if (body.permissions) {
             for (const p of body.permissions) {
                 db.insert(schema.apiKeyModelPermissions).values({ id: uuid(), apiKeyId: id, targetKind: p.targetKind, targetId: p.targetId }).run();

package/dist/server/routes/gateway/anthropic.js

@@ -18,7 +18,8 @@ const MessagesBody = z.object({
     tools: z.array(z.any()).optional(),
     tool_choice: z.any().optional(),
     thinking: z.object({ type: z.literal('enabled'), budget_tokens: z.number().int().min(1) }).optional(),
-});
+    // Accept additional fields
+}).passthrough();
 const CountTokensBody = MessagesBody.omit({ stream: true });
 export async function registerAnthropicRoutes(app) {
     const runner = new GatewayRunner();

package/dist/server/routes/gateway/openai.js

@@ -17,10 +17,17 @@ const ChatBody = z.object({
     temperature: z.number().optional(),
     top_p: z.number().optional(),
     max_tokens: z.number().int().min(1).optional(),
+    max_completion_tokens: z.number().int().min(1).optional(),
     stop: z.union([z.array(z.string()), z.string()]).optional(),
     response_format: z.any().optional(),
     reasoning_effort: z.enum(['low', 'medium', 'high']).optional(),
-});
+    // Accept additional Claude Code fields without failing
+    parallel_tool_calls: z.any().optional(),
+    stream_options: z.any().optional(),
+    metadata: z.any().optional(),
+    seed: z.number().int().optional(),
+    service_tier: z.any().optional(),
+}).passthrough(); // Allow unknown fields to pass through (forward to upstream)
 const ResponsesBody = z.object({
     model: z.string().min(1),
     input: z.any(),

package/dist/server/routing/capabilities.js

@@ -33,20 +33,28 @@ export function deriveRequiredCapabilities(req) {
         responses: false,
     };
 }
+/**
+ * Check if a model meets required capabilities.
+ * IMPORTANT: Treat undefined as "unknown" rather than "unsupported".
+ * For generic OpenAI-compatible providers where capabilities weren't explicitly imported,
+ * undefined means we don't know, so we should assume it's potentially supported.
+ * Explicit false means "known unsupported".
+ */
 export function modelMeets(caps, req) {
-    if (req.streaming && !caps.streaming)
+    // Only reject if capability is explicitly false, not if unknown (undefined)
+    if (req.streaming && caps.streaming === false)
         return false;
-    if (req.tools && !caps.tools)
+    if (req.tools && caps.tools === false)
         return false;
-    if (req.structuredOutput && !caps.structured_output)
+    if (req.structuredOutput && caps.structured_output === false)
         return false;
-    if (req.imageInput && !caps.image_input)
+    if (req.imageInput && caps.image_input === false)
         return false;
-    if (req.audioInput && !caps.audio_input)
+    if (req.audioInput && caps.audio_input === false)
         return false;
-    if (req.reasoning && !caps.reasoning)
+    if (req.reasoning && caps.reasoning === false)
         return false;
-    if (req.responses && !caps.responses)
+    if (req.responses && caps.responses === false)
         return false;
     return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldrouter",
-  "version": "1.11.12",
+  "version": "1.11.17",
   "description": "LateDev Router — lightweight self-hosted LLM gateway with admin UI",
   "type": "module",
   "license": "MIT",