ldrouter 1.11.17 → 1.13.1

package/dist/server/logging/debug.js

@@ -1,62 +1,278 @@
-// 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, '');
+// Request-lifecycle debug logging.
+//
+// All output goes to stdout/stderr so `docker logs` collects it (docs/13).
+// Every line is prefixed with the requestId so the whole lifecycle of one
+// request can be extracted with:
+//   docker logs ldrouter 2>&1 | grep req_xxx
+//
+// Env flags (all default off; enabled per docs/13 §22):
+//   DEBUG_HTTP       — incoming request + body summary + messages/tools structure
+//   DEBUG_HTTP_BODY  — full sanitized JSON bodies (incoming + upstream)
+//   DEBUG_UPSTREAM   — upstream fetch/response/error detail
+//   DEBUG_STREAM     — SSE stream lifecycle (start/first chunks/end/error)
+// LOG_LEVEL gates lifecycle INFO-level lines ([INCOMING]/[DONE]/errors) —
+// they emit at debug, so set LOG_LEVEL=debug to see them.
+import process from 'node:process';
+import { redactValue } from '../security/redact.js';
+function envFlag(name) {
+    const v = process.env[name];
+    return v === '1' || v === 'true' || v === 'yes';
+}
+let flags = null;
+/** Debug flags are read once per process (docs/13 §22). */
+export function getDebugFlags() {
+    if (!flags) {
+        flags = {
+            http: envFlag('DEBUG_HTTP'),
+            httpBody: envFlag('DEBUG_HTTP_BODY'),
+            upstream: envFlag('DEBUG_UPSTREAM'),
+            stream: envFlag('DEBUG_STREAM'),
+        };
     }
-    catch (_err) {
-        // Silent fail - don't break the application
-        console.error('Failed to create debug log:', _err);
+    return flags;
+}
+export function resetDebugFlagsForTests() {
+    flags = null;
+}
+// --- Output -------------------------------------------------------------
+// Direct console use (not pino) keeps the human-readable
+// [timestamp] [req_xxx] [TAG] line format that docs/13 §23 asks for, and is
+// trivially visible in `docker logs -f`. Errors go to stderr.
+function emit(level, requestId, tag, lines) {
+    const ts = new Date().toISOString();
+    const stream = level === 'error' ? process.stderr : process.stdout;
+    for (const body of lines) {
+        const first = body.split('\n')[0] ?? '';
+        const rest = body.split('\n').slice(1).join('\n');
+        const head = `[${ts}] [${requestId}] [${tag}] ${first}`;
+        stream.write(rest ? head + '\n' + rest + '\n' : head + '\n');
     }
 }
-export function appendDebugLog(entry) {
-    const logLine = JSON.stringify(entry) + '\n';
+/** Lifecycle INFO line — always on (gated by LOG_LEVEL=debug via pino parity, but kept unconditional so operators never lose the trail). */
+export function lifecycle(requestId, tag, lines) {
+    emit('info', requestId, tag, lines);
+}
+export function debugHttp(requestId, tag, lines) {
+    if (getDebugFlags().http)
+        emit('info', requestId, tag, lines);
+}
+export function debugBody(requestId, tag, lines) {
+    if (getDebugFlags().httpBody)
+        emit('info', requestId, tag, lines);
+}
+export function debugUpstream(requestId, tag, lines) {
+    if (getDebugFlags().upstream)
+        emit('info', requestId, tag, lines);
+}
+export function debugStream(requestId, tag, lines) {
+    if (getDebugFlags().stream)
+        emit('info', requestId, tag, lines);
+}
+export function errorLine(requestId, tag, lines) {
+    emit('error', requestId, tag, lines);
+}
+/** Fatal process-level line (no requestId). */
+export function fatal(tag, lines) {
+    emit('error', '-', tag, lines);
+}
+// --- Sanitization --------------------------------------------------------
+/** Sanitize an arbitrary value for logging: deep-redact secrets. */
+export function sanitize(value) {
+    return redactValue(value);
+}
+/** Sanitized JSON string; on circular/unserializable falls back to a marker. */
+export function sanitizeJson(value) {
     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);
+        return JSON.stringify(redactValue(value));
+    }
+    catch {
+        try {
+            return JSON.stringify({ bodyLogError: 'unserializable' });
+        }
+        catch {
+            return '{"bodyLogError":"unserializable"}';
+        }
+    }
+}
+/** Truncate a string to `max` chars, marking truncation (docs/13 §5). */
+export function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max)}…(+${s.length - max} chars, truncated)`;
+}
+export function summarizeBody(body) {
+    const lines = [];
+    const p = (k, v) => {
+        lines.push(`${k}=${v === undefined ? 'undefined' : JSON.stringify(v)}`);
+    };
+    p('model', body['model']);
+    p('stream', body['stream']);
+    const keys = Object.keys(body);
+    lines.push(`bodyKeys=[${keys.map((k) => JSON.stringify(k)).join(', ')}]`);
+    const messages = Array.isArray(body['messages']) ? body['messages'] : null;
+    lines.push(`messages=${messages ? messages.length : 'undefined'}`);
+    const tools = Array.isArray(body['tools']) ? body['tools'] : null;
+    if (tools) {
+        lines.push(`toolsCount=${tools.length}`);
+        lines.push(`serializedToolsSize=${safeSize(tools)}`);
+    }
+    p('max_tokens', body['max_tokens']);
+    p('max_completion_tokens', body['max_completion_tokens']);
+    p('temperature', body['temperature']);
+    p('top_p', body['top_p']);
+    p('reasoning_effort', body['reasoning_effort']);
+    p('reasoning', body['reasoning']);
+    p('thinking', body['thinking']);
+    p('tool_choice', body['tool_choice']);
+    p('parallel_tool_calls', body['parallel_tool_calls']);
+    p('response_format', body['response_format']);
+    p('stream_options', body['stream_options']);
+    if (messages) {
+        lines.push(`messageRoles=[${messages.map((m) => (isRec(m) ? String(m['role'] ?? '?') : '?')).join(',')}]`);
+    }
+    return lines;
+}
+export function summarizeMessages(body) {
+    const messages = Array.isArray(body['messages']) ? body['messages'] : [];
+    const lines = [];
+    messages.forEach((m, i) => {
+        if (!isRec(m)) {
+            lines.push(`#${i} <non-object: ${typeof m}>`);
+            return;
+        }
+        const role = m['role'];
+        const content = m['content'];
+        const contentDesc = content === null
+            ? 'contentType=null contentLength=0'
+            : typeof content === 'string'
+                ? `contentType=string contentLength=${content.length}`
+                : Array.isArray(content)
+                    ? `contentType=array contentParts=${content.length}`
+                    : content === undefined
+                        ? 'contentType=undefined'
+                        : `contentType=${typeof content}`;
+        lines.push(`#${i} role=${role} ${contentDesc}`);
+        const toolCalls = m['tool_calls'];
+        if (Array.isArray(toolCalls))
+            lines.push(`  toolCalls=${toolCalls.length}`);
+        if (m['tool_call_id'])
+            lines.push(`  toolCallId=${String(m['tool_call_id'])}`);
+        if ('reasoning_content' in m)
+            lines.push(`  reasoningContent=present`);
+        if (Array.isArray(content)) {
+            const partTypes = content.map((c) => (isRec(c) ? String(c['type'] ?? '?') : '?')).join(',');
+            lines.push(`  partTypes=[${partTypes}]`);
+        }
     });
-    // 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
+    return lines;
+}
+export function summarizeTools(body) {
+    const tools = Array.isArray(body['tools']) ? body['tools'] : [];
+    const lines = [`count=${tools.length}`, `serializedSize=${safeSize(tools)}`];
+    tools.forEach((t, i) => {
+        if (!isRec(t)) {
+            lines.push(`tool[${i}]: <non-object>`);
+            return;
+        }
+        const fn = isRec(t['function']) ? t['function'] : null;
+        const name = fn ? String(fn['name'] ?? '?') : String(t['name'] ?? '?');
+        const descLen = fn && typeof fn['description'] === 'string' ? fn['description'].length : fn?.['description'] !== undefined ? -1 : 0;
+        const schema = fn ? fn['parameters'] : t['input_schema'];
+        const schemaSize = schema !== undefined ? safeSize(schema) : 0;
+        lines.push(`tool[${i}]: name=${name} descriptionLength=${descLen} schemaSize=${schemaSize}`);
     });
+    return lines;
+}
+// --- Error formatting (docs/13 §13) ---------------------------------------
+/** Full error detail including nested undici `cause` chains. */
+export function formatError(e) {
+    const lines = [];
+    const seen = new Set();
+    let depth = 0;
+    let cur = e;
+    while (cur instanceof Error && depth < 4) {
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const prefix = depth === 0 ? '' : 'cause.';
+        lines.push(`${prefix}name=${cur.name}`);
+        lines.push(`${prefix}message=${cur.message}`);
+        const code = cur.code;
+        if (code)
+            lines.push(`${prefix}code=${code}`);
+        if (depth === 0 && cur.stack)
+            lines.push(`stack=${truncate(cur.stack, 4000)}`);
+        cur = cur.cause;
+        depth++;
+    }
+    if (cur !== undefined && cur !== null && !(cur instanceof Error)) {
+        lines.push(`cause(raw)=${truncate(safeStringify(cur), 2000)}`);
+    }
+    if (lines.length === 0)
+        lines.push(`value=${truncate(safeStringify(e), 2000)}`);
+    return lines;
+}
+// --- Helpers --------------------------------------------------------------
+function isRec(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function safeSize(v) {
+    try {
+        return JSON.stringify(v)?.length ?? 0;
+    }
+    catch {
+        return -1;
+    }
+}
+function safeStringify(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+// --- Header sanitization (docs/13 §2–§3) ----------------------------------
+const SENSITIVE_HEADERS = new Set([
+    'authorization',
+    'x-api-key',
+    'cookie',
+    'set-cookie',
+    'x-goog-api-key',
+    'proxy-authorization',
+]);
+const INTERESTING_HEADERS = [
+    'content-type',
+    'content-length',
+    'user-agent',
+    'host',
+    'x-forwarded-for',
+    'cf-ray',
+    'cf-connecting-ip',
+    'accept',
+    'accept-encoding',
+    'connection',
+    'anthropic-version',
+];
+/** Sanitized incoming-request header lines for the [INCOMING] block. */
+export function summarizeHeaders(headers) {
+    const lines = [];
+    for (const name of INTERESTING_HEADERS) {
+        const v = headers[name];
+        if (v !== undefined)
+            lines.push(`${name}=${Array.isArray(v) ? v.join(',') : String(v)}`);
+    }
+    const auth = headers['authorization'];
+    if (auth !== undefined)
+        lines.push(`authorization=Bearer ***REDACTED***`);
+    const apiKey = headers['x-api-key'];
+    if (apiKey !== undefined)
+        lines.push(`x-api-key=***REDACTED***`);
+    // Report presence of any other sensitive headers without values.
+    for (const k of Object.keys(headers)) {
+        if (SENSITIVE_HEADERS.has(k.toLowerCase()) && !lines.some((l) => l.startsWith(`${k.toLowerCase()}=`) || l.startsWith(`${k}=`))) {
+            lines.push(`${k}=***REDACTED***`);
+        }
+    }
+    return lines;
 }

package/dist/server/routes/admin/backup.js

@@ -7,11 +7,13 @@ import { getDb, closeDb, openDb, schema } from '../../db/index.js';
 import { requireAdminAuth } from '../../auth/middleware.js';
 import { sha256Hex } from '../../auth/ids.js';
 import { recordAudit } from '../../db/repositories/audit.js';
-import { loadConfig } from '../../config/index.js';
+import { loadConfig, setConfigMasterKey } from '../../config/index.js';
 import { getSettings } from '../../db/repositories/settings.js';
 import { GatewayError } from '../../errors.js';
 import { getAppVersion } from '../../version.js';
 import { eq, sql } from 'drizzle-orm';
+import { decryptBackupMasterKey, encryptBackupMasterKey } from '../../auth/backup-crypto.js';
+import { parseMasterKey, resetMasterKeyCache } from '../../auth/crypto.js';
 const BACKUP_VERSION = 1;
 /** Reopen the in-process SQLite connection on the (possibly just-replaced)
  *  database file. The old connection must already be closed: a hot restore
@@ -52,8 +54,16 @@ function assertDatabaseUsable(expectedSchemaVersion) {
     }
 }
 export async function registerBackupRoutes(app) {
-    app.addHook('preHandler', requireAdminAuth);
+    app.addHook('preHandler', async (req, reply) => {
+        if (req.url === '/api/admin/backup/restore' && !getSettings().setupComplete)
+            return;
+        return requireAdminAuth(req, reply);
+    });
     app.post('/api/admin/backup/create', async (req, reply) => {
+        const passphrase = req.body?.passphrase ?? '';
+        if (!/^\d{6}$/.test(passphrase)) {
+            throw new GatewayError('invalid_request_error', 'Backup passphrase must contain exactly six digits', { status: 400 });
+        }
         const cfg = loadConfig();
         const temp = path.join(cfg.dataDir, `.backup-${Date.now()}.sqlite`);
         const Database = (await import('better-sqlite3')).default;
@@ -69,6 +79,7 @@ export async function registerBackupRoutes(app) {
         const compressed = zlib.gzipSync(buf, { level: 6 });
         const checksum = crypto.createHash('sha256').update(compressed).digest('hex');
         const settings = getSettings();
+        const masterKey = parseMasterKey(cfg.masterKey ?? fs.readFileSync(path.join(cfg.dataDir, 'master.key'), 'utf8').trim());
         const envelope = {
             format: 'latedev-backup',
             version: BACKUP_VERSION,
@@ -78,6 +89,7 @@ export async function registerBackupRoutes(app) {
             createdAt: new Date().toISOString(),
             payload: compressed.toString('base64'),
             checksum,
+            keyEnvelope: encryptBackupMasterKey(masterKey, passphrase),
         };
         const envBuf = Buffer.from(JSON.stringify(envelope), 'utf8');
         const fileName = `latedev-backup-${new Date().toISOString().replace(/[:.]/g, '-')}.ldb.json`;
@@ -88,12 +100,17 @@ export async function registerBackupRoutes(app) {
     });
     app.post('/api/admin/backup/restore', async (req, reply) => {
         const cfg = loadConfig();
-        // Expect raw JSON envelope in body
+        const incoming = req.body;
+        const wrapped = Boolean(incoming && 'backup' in incoming);
+        const wrappedBody = incoming;
+        const passphrase = wrapped ? wrappedBody.passphrase : undefined;
         let envelope;
         try {
-            envelope = req.body;
+            envelope = (wrapped ? wrappedBody.backup : incoming);
             if (!envelope || envelope.format !== 'latedev-backup')
                 throw new Error('not a backup envelope');
+            if (envelope.keyEnvelope && !/^\d{6}$/.test(passphrase ?? ''))
+                throw new Error('backup passphrase required');
         }
         catch {
             recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'invalid_envelope' } });
@@ -122,6 +139,17 @@ export async function registerBackupRoutes(app) {
             recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'not_sqlite' } });
             throw new GatewayError('invalid_request_error', 'Backup does not contain a valid SQLite database', { status: 400 });
         }
+        let restoredMasterKey;
+        if (envelope.keyEnvelope) {
+            try {
+                restoredMasterKey = decryptBackupMasterKey(envelope.keyEnvelope, passphrase);
+                parseMasterKey(restoredMasterKey.toString('base64'));
+            }
+            catch {
+                recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'invalid_backup_passphrase' } });
+                throw new GatewayError('invalid_request_error', 'Invalid backup passphrase', { status: 400 });
+            }
+        }
         const liveDb = cfg.dbFile;
         // Snapshot current DB before restore (kept for manual rollback).
         const snapshot = path.join(cfg.dataDir, `pre-restore-${Date.now()}.sqlite`);
@@ -184,6 +212,12 @@ export async function registerBackupRoutes(app) {
             recordAudit({ action: 'db.restore', success: false, ip: req.ip, metadata: { reason: 'validation_failed', err: e.message } });
             throw new GatewayError('gateway_error', `Restore failed: ${e.message}`, { status: 500 });
         }
+        if (restoredMasterKey) {
+            const restoredKey = restoredMasterKey.toString('base64');
+            fs.writeFileSync(path.join(cfg.dataDir, 'master.key'), restoredKey, { mode: 0o600, encoding: 'utf8' });
+            setConfigMasterKey(restoredKey);
+            resetMasterKeyCache();
+        }
         // The swap invalidates the previous admin session (its row lived in the
         // old database). Re-create the current session in the restored database so
         // the admin stays logged in across the hot restore.

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

@@ -6,6 +6,7 @@ import { anthropicToCanonical } from '../../protocols/anthropic.js';
 import { GatewayError, toAnthropicError } from '../../errors.js';
 import { GatewayRunner } from '../../gateway/runner.js';
 import { uuid } from '../../auth/ids.js';
+import { lifecycle, debugHttp, debugBody, getDebugFlags, summarizeMessages, summarizeTools, summarizeHeaders, sanitizeJson, truncate } from '../../logging/debug.js';
 const MessagesBody = z.object({
     model: z.string().min(1),
     messages: z.array(z.any()).min(1),
@@ -27,15 +28,21 @@ export async function registerAnthropicRoutes(app) {
         reply.code(405).send(toAnthropicError(new GatewayError('invalid_request_error', 'Use POST /v1/messages', { status: 405 }), ''));
     });
     app.post('/v1/messages', async (req, reply) => {
+        const requestId = req.id || uuid();
+        lifecycle(requestId, 'INCOMING', [
+            `POST ${req.url}`,
+            ...summarizeHeaders(req.headers),
+        ]);
         const key = authenticateGatewayHeaders(req);
         const body = MessagesBody.parse(req.body);
+        logIncomingMessagesBody(requestId, body);
         const ar = body;
         if (!ar.max_tokens) {
             throw new GatewayError('invalid_request_error', 'max_tokens is required', { status: 400 });
         }
         const canonical = anthropicToCanonical(ar);
         const ctx = {
-            requestId: req.id || uuid(),
+            requestId,
             clientIp: resolveClientIp(req),
             protocol: 'anthropic',
             endpoint: 'messages',
@@ -60,9 +67,11 @@ export async function registerAnthropicRoutes(app) {
             }
             if (!outcome.success) {
                 const g = new GatewayError(outcome.errorType ?? 'gateway_error', outcome.errorMessage ?? 'Gateway error', { status: outcome.httpStatus });
+                lifecycle(requestId, 'DONE', [`status=${outcome.httpStatus} durationMs=${outcome.latencyMs} error=true type=${g.type}`]);
                 reply.code(outcome.httpStatus).send(toAnthropicError(g, ctx.requestId));
                 return;
             }
+            lifecycle(requestId, 'DONE', [`status=200 durationMs=${outcome.latencyMs} finishReason=${outcome.finishReason ?? 'null'}`]);
             reply.header('x-request-id', ctx.requestId);
             reply.send({
                 id: `msg_${ctx.requestId}`,
@@ -101,6 +110,34 @@ export async function registerAnthropicRoutes(app) {
         reply.send({ input_tokens: inputTokens });
     });
 }
+// docs/13 §4–§7: incoming /v1/messages body structure logging.
+function logIncomingMessagesBody(requestId, body) {
+    debugHttp(requestId, 'BODY SUMMARY', [
+        `model=${JSON.stringify(body['model'])}`,
+        `stream=${JSON.stringify(body['stream'])}`,
+        `max_tokens=${JSON.stringify(body['max_tokens'])}`,
+        `temperature=${JSON.stringify(body['temperature'])}`,
+        `top_p=${JSON.stringify(body['top_p'])}`,
+        `thinking=${JSON.stringify(body['thinking'])}`,
+        `tool_choice=${JSON.stringify(body['tool_choice'])}`,
+        `systemType=${Array.isArray(body['system']) ? `array(${body['system'].length})` : typeof body['system']}`,
+        `bodyKeys=[${Object.keys(body).map((k) => JSON.stringify(k)).join(', ')}]`,
+        `messages=${Array.isArray(body['messages']) ? body['messages'].length : 'undefined'}`,
+        `tools=${Array.isArray(body['tools']) ? body['tools'].length : 'undefined'}`,
+    ]);
+    debugHttp(requestId, 'MESSAGES', summarizeMessages(body));
+    if (body['tools'] !== undefined)
+        debugHttp(requestId, 'TOOLS', summarizeTools(body));
+    if (getDebugFlags().httpBody) {
+        const json = sanitizeJson(body);
+        const bodySize = json.length;
+        const LIMIT = 512 * 1024; // generous debug-only cap (docs/13 §5)
+        debugBody(requestId, 'INCOMING BODY', [
+            `bodySize=${bodySize} bytes bodyTruncated=${bodySize > LIMIT}`,
+            bodySize > LIMIT ? truncate(json, LIMIT) : json,
+        ]);
+    }
+}
 function authenticateGatewayHeaders(req) {
     const key = authenticateGatewayKey(req);
     if (!key)

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

@@ -8,6 +8,7 @@ import { openAIToCanonical, openAIModelList } from '../../protocols/canonical.js
 import { GatewayError, toOpenAIError } from '../../errors.js';
 import { GatewayRunner } from '../../gateway/runner.js';
 import { uuid } from '../../auth/ids.js';
+import { lifecycle, debugHttp, debugBody, getDebugFlags, summarizeBody, summarizeMessages, summarizeTools, summarizeHeaders, sanitizeJson, truncate } from '../../logging/debug.js';
 const ChatBody = z.object({
     model: z.string().min(1),
     messages: z.array(z.any()).min(1),
@@ -52,12 +53,18 @@ export async function registerOpenAIRoutes(app) {
         return openAIModelList(ids.map((id) => ({ publicModelId: id, upstreamModelId: id })));
     });
     app.post('/v1/chat/completions', async (req, reply) => {
+        const requestId = req.id || uuid();
+        lifecycle(requestId, 'INCOMING', [
+            `POST ${req.url}`,
+            ...summarizeHeaders(req.headers),
+        ]);
         const key = authenticateGatewayHeaders(req);
         const body = ChatBody.parse(req.body);
+        logIncomingChatBody(requestId, body);
         const req1 = body;
         const canonical = openAIToCanonical(req1);
         const ctx = {
-            requestId: req.id || uuid(),
+            requestId,
             clientIp: resolveClientIp(req),
             protocol: 'openai',
             endpoint: 'chat/completions',
@@ -89,9 +96,11 @@ export async function registerOpenAIRoutes(app) {
             }
             if (!outcome.success) {
                 const g = new GatewayError(outcome.errorType ?? 'gateway_error', outcome.errorMessage ?? 'Gateway error', { status: outcome.httpStatus });
+                lifecycle(requestId, 'DONE', [`status=${outcome.httpStatus} durationMs=${outcome.latencyMs} error=true type=${g.type}`]);
                 reply.code(outcome.httpStatus).send(toOpenAIError(g, ctx.requestId));
                 return;
             }
+            lifecycle(requestId, 'DONE', [`status=200 durationMs=${outcome.latencyMs} finishReason=${outcome.finishReason ?? 'null'}`]);
             reply.header('x-request-id', ctx.requestId);
             reply.send({
                 id: `chatcmpl-${ctx.requestId}`,
@@ -129,9 +138,19 @@ export async function registerOpenAIRoutes(app) {
         }
     });
     app.post('/v1/responses', async (req, reply) => {
+        const requestId = req.id || uuid();
+        lifecycle(requestId, 'INCOMING', [
+            `POST ${req.url}`,
+            ...summarizeHeaders(req.headers),
+        ]);
         const key = authenticateGatewayHeaders(req);
         // v1 subset: accept Responses-style input, flatten to chat-completions messages.
         const body = ResponsesBody.parse(req.body);
+        debugHttp(requestId, 'BODY SUMMARY', [
+            `model=${body.model}`,
+            `stream=${body.stream ?? 'undefined'}`,
+            `inputType=${Array.isArray(body.input) ? `array(${body.input.length})` : typeof body.input}`,
+        ]);
         const flat = responsesInputToChat(body.input);
         const chatBody = {
             model: body.model,
@@ -141,7 +160,7 @@ export async function registerOpenAIRoutes(app) {
         };
         const canonical = openAIToCanonical(chatBody);
         const ctx = {
-            requestId: req.id || uuid(),
+            requestId,
             clientIp: resolveClientIp(req),
             protocol: 'openai',
             endpoint: 'responses',
@@ -198,6 +217,23 @@ export async function registerOpenAIRoutes(app) {
         }
     });
 }
+// docs/13 §4–§7: incoming chat body structure logging. Summary always
+// available under DEBUG_HTTP; full sanitized body under DEBUG_HTTP_BODY.
+function logIncomingChatBody(requestId, body) {
+    debugHttp(requestId, 'BODY SUMMARY', summarizeBody(body));
+    debugHttp(requestId, 'MESSAGES', summarizeMessages(body));
+    if (body['tools'] !== undefined)
+        debugHttp(requestId, 'TOOLS', summarizeTools(body));
+    if (getDebugFlags().httpBody) {
+        const json = sanitizeJson(body);
+        const bodySize = json.length;
+        const LIMIT = 512 * 1024; // generous debug-only cap (docs/13 §5)
+        debugBody(requestId, 'INCOMING BODY', [
+            `bodySize=${bodySize} bytes bodyTruncated=${bodySize > LIMIT}`,
+            bodySize > LIMIT ? truncate(json, LIMIT) : json,
+        ]);
+    }
+}
 export function listRoutableModelIds(models, key, db) {
     const modelIds = new Set(models.map((m) => m.id));
     const modelById = new Map(models.map((m) => [m.id, m.publicModelId]));

package/dist/server/routing/combo.js

@@ -23,28 +23,58 @@ export function loadCombo(comboId) {
         },
     };
 }
-export function selectCandidates(combo, allModels, req) {
+export function selectCandidates(combo, allModels, req, onReject) {
     // Resolve each combo member to a candidate and apply filters
     const map = new Map(allModels.map((m) => [m.modelId, m]));
     const candidates = [];
     for (const m of combo.members) {
-        if (!m.enabled)
+        if (!m.enabled) {
+            onReject?.({ modelId: m.modelId, publicModelId: map.get(m.modelId)?.publicModelId ?? m.modelId }, 'member_disabled');
             continue;
+        }
         const c = map.get(m.modelId);
-        if (!c)
+        if (!c) {
+            onReject?.({ modelId: m.modelId, publicModelId: m.modelId }, 'model_not_found');
             continue;
-        if (!c.enabled)
+        }
+        if (!c.enabled) {
+            onReject?.(c, 'model_disabled');
             continue;
-        if (!c.upstreamAvailable)
+        }
+        if (!c.upstreamAvailable) {
+            onReject?.(c, 'upstream_unavailable');
             continue;
-        if (c.circuitOpen)
+        }
+        if (c.circuitOpen) {
+            onReject?.(c, 'circuit_open');
             continue;
-        if (!modelMeets(c.capabilities, req))
+        }
+        if (!modelMeets(c.capabilities, req)) {
+            onReject?.(c, capabilityRejection(c.capabilities, req));
             continue;
+        }
         candidates.push(c);
     }
     return candidates;
 }
+/** First capability that explicitly failed (undefined = unknown caps never reject). */
+function capabilityRejection(caps, req) {
+    if (req.streaming && caps.streaming === false)
+        return 'streaming';
+    if (req.tools && caps.tools === false)
+        return 'tools';
+    if (req.structuredOutput && caps.structured_output === false)
+        return 'structured_output';
+    if (req.imageInput && caps.image_input === false)
+        return 'image_input';
+    if (req.audioInput && caps.audio_input === false)
+        return 'audio_input';
+    if (req.reasoning && caps.reasoning === false)
+        return 'reasoning';
+    if (req.responses && caps.responses === false)
+        return 'responses';
+    return 'capability_mismatch';
+}
 export function orderCandidates(combo, candidates) {
     if (combo.mode === 'fallback') {
         // Preserve declared position order