ldrouter 1.11.17 → 1.12.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.12.0] - 2026-09-05
+
+### Added
+
+- **Request-lifecycle debug logging** (`docs/13-LOGGING.md`): full observability of every request as it passes through the gateway, emitted to stdout/stderr so `docker logs` collects it.
+  - Per-request ID (reuses `x-request-id` or generates one) tagged on every line — `docker logs ldrouter 2>&1 | grep req_xxx` reconstructs the whole lifecycle.
+  - `[INCOMING]` → `[BODY SUMMARY]` → `[MESSAGES]` → `[TOOLS]` → `[MODEL RESOLVE]` → `[CAPABILITIES REQUIRED]` → `[CAPABILITY REJECT]` → `[ATTEMPT]` → `[UPSTREAM REQUEST]` → `[UPSTREAM RESPONSE]` → `[STREAM START/END/ERROR]` → `[DONE]`.
+  - Per-candidate rejection reasons for the `No combo member satisfies...` error (why each member was filtered: `member_disabled`, `model_not_found`, `upstream_unavailable`, `circuit_open`, `tools`, `reasoning`, `streaming`, etc.).
+  - Nested `error.cause` / undici stack capture for `UPSTREAM FETCH ERROR` (no more bare `fetch failed`).
+  - Stream counters (chunks/bytes/first-chunk-ms) and client-disconnect detection.
+  - `[CONFIG]` line at startup printing body limit + active debug flags.
+  - Replaced `uncaughtException`/`unhandledRejection` no-op `{}` handlers with full message/stack/cause logging.
+- **Debug env flags**: `DEBUG_HTTP`, `DEBUG_HTTP_BODY`, `DEBUG_UPSTREAM`, `DEBUG_STREAM`, plus `LOG_LEVEL` alias for `LATEDEV_LOG_LEVEL` (all default off; enable for one-shot reproduction).
+- **Secret redaction**: all debug output routes through the existing `redact.ts` — provider keys are fingerprinted, never logged; `Authorization`/`x-api-key`/cookies always masked.
+
 ## [1.11.16] - 2026-09-04
 
 ### Fixed

package/dist/server/app.js

@@ -21,6 +21,7 @@ import { registerGatewayRoutes } from './routes/gateway.js';
 import { registerHealthRoutes } from './routes/health.js';
 import { registerAdminIpGate } from './security/admin-ip-gate.js';
 import { metricsRegistry } from './metrics/registry.js';
+import { fatal, lifecycle, formatError, getDebugFlags, errorLine } from './logging/debug.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export async function buildApp(opts = {}) {
     const cfg = loadConfig();
@@ -63,11 +64,21 @@ export async function buildApp(opts = {}) {
             name: normalized instanceof Error ? normalized.name : undefined,
             message: errMsg,
             stack: normalized instanceof Error ? normalized.stack : undefined,
+            cause: normalized instanceof Error ? normalized.cause : undefined,
         };
         if (status >= 500)
             log.error({ requestId, url: req.url, err: errDetail }, 'request error');
         else
             log.warn({ requestId, url: req.url, err: { type: (g?.type ?? 'error'), message: errMsg } }, 'request rejected');
+        // docs/13 §19: server-side stack with request context (never to client).
+        if (status >= 500) {
+            errorLine(requestId, 'SERVER ERROR', [
+                `route=${req.routeOptions?.url ?? req.url}`,
+                `method=${req.method}`,
+                `statusCode=${status}`,
+                ...formatError(normalized),
+            ]);
+        }
         const accept = (req.headers['accept'] ?? '').toString();
         const isAnthropic = accept.includes('application/vnd.anthropic') || req.url.includes('/v1/messages');
         if (g) {
@@ -82,9 +93,21 @@ 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);
+    // docs/13 §20: print effective config so operators know body limits and
+    // which debug flags are active for the running process.
+    const dbg = getDebugFlags();
+    lifecycle('-', 'CONFIG', [
+        `host=${cfg.host}`,
+        `port=${cfg.port}`,
+        `dataDir=${cfg.dataDir}`,
+        `logLevel=${cfg.logLevel}`,
+        `trustProxyHops=${cfg.trustProxyHops}`,
+        `bodyLimit=${64 * 1024 * 1024} bytes`,
+        `debugHttp=${dbg.http}`,
+        `debugHttpBody=${dbg.httpBody}`,
+        `debugUpstream=${dbg.upstream}`,
+        `debugStream=${dbg.stream}`,
+    ]);
     // 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);
@@ -112,15 +135,17 @@ export async function buildApp(opts = {}) {
         reply.code(404).send(toOpenAIError(err, req.id));
     });
     // Process-level crash prevention
-    process.on('uncaughtException', () => {
+    process.on('uncaughtException', (err) => {
+        fatal('FATAL', ['uncaughtException', ...formatError(err)]);
         const log = getLogger();
-        log.error({ err: {} }, 'uncaught exception');
+        log.error({ err: { name: err.name, message: err.message, stack: err.stack } }, 'uncaught exception');
         // Don't exit immediately - let Fastify error handler process
         setTimeout(() => process.exit(1), 1000);
     });
-    process.on('unhandledRejection', (_reason) => {
+    process.on('unhandledRejection', (reason) => {
+        fatal('FATAL', ['unhandledRejection', ...formatError(reason)]);
         const log = getLogger();
-        log.error({ reason: '' }, 'unhandled rejection');
+        log.error({ err: { reason: String(reason) } }, 'unhandled rejection');
     });
     // On startup: ensure settings row + detect master key status
     app.addHook('onReady', async () => {

package/dist/server/config/index.js

@@ -11,6 +11,8 @@ const EnvSchema = z.object({
     LATEDEV_MASTER_KEY: z.string().optional(),
     LATEDEV_TRUST_PROXY: z.coerce.number().int().min(0).max(8).default(0),
     LATEDEV_LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).default('info'),
+    // Alias used by docs/13 debug tooling: LOG_LEVEL=debug enables lifecycle lines.
+    LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).optional(),
     LATEDEV_DB_URL: z.string().optional(),
     NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),
 });
@@ -54,7 +56,7 @@ export function loadConfig(env = process.env, argv = process.argv) {
         dbFile,
         masterKey: parsed.LATEDEV_MASTER_KEY ?? readMasterKeyFile(dataDir),
         trustProxyHops: parsed.LATEDEV_TRUST_PROXY,
-        logLevel: parsed.LATEDEV_LOG_LEVEL,
+        logLevel: parsed.LOG_LEVEL ?? parsed.LATEDEV_LOG_LEVEL,
         env: parsed.NODE_ENV,
         isContainer,
         appVersion: getAppVersion(),

package/dist/server/gateway/runner.js

@@ -18,6 +18,7 @@ import { getSettings } from '../db/repositories/settings.js';
 import { buildCacheKey, lookupCache, storeCache, cacheAllowed } from '../caching/store.js';
 import { metrics } from '../metrics/registry.js';
 import { emitRequestLogged, emitRequestStarted } from './events.js';
+import { debugHttp, debugBody, debugUpstream, debugStream, errorLine, formatError, getDebugFlags, truncate } from '../logging/debug.js';
 export class GatewayRunner {
     async execute(req, ctx) {
         const start = Date.now();
@@ -31,6 +32,17 @@ export class GatewayRunner {
         let comboPlan = null;
         if (resolved.kind === 'combo')
             comboPlan = loadCombo(resolved.comboId);
+        // docs/13 §9: full resolution chain requested -> alias -> combo/model
+        if (getDebugFlags().http) {
+            const lines = [`requested=${req.canonical.model}`, `type=${resolved.kind}`];
+            if (target.kind === 'alias')
+                lines.push(`viaAlias=${target.alias}`);
+            if (resolved.kind === 'model')
+                lines.push(`providerModelId=${resolved.modelId}`, `publicModelId=${resolved.publicModelId}`);
+            if (resolved.kind === 'combo')
+                lines.push(`comboId=${resolved.comboId}`, `comboPublicId=${resolved.publicModelId}`);
+            debugHttp(ctx.requestId, 'MODEL RESOLVE', lines);
+        }
         // --- ACL check ---
         if (ctx.key) {
             if (resolved.kind === 'model') {
@@ -74,20 +86,52 @@ export class GatewayRunner {
         try {
             // --- Capability requirements ---
             const required = deriveRequiredCapabilities(req.canonical);
+            debugHttp(ctx.requestId, 'CAPABILITIES REQUIRED', [
+                `tools=${required.tools}`,
+                `stream=${required.streaming}`,
+                `vision=${required.imageInput}`,
+                `reasoning=${required.reasoning}`,
+                `json=${required.structuredOutput}`,
+                `structuredOutput=${required.structuredOutput}`,
+                `parallelToolCalls=undefined(derived-from-request-not-gated)`,
+                `audioInput=${required.audioInput}`,
+            ]);
             // --- Determine candidates ---
             let candidates = [];
             let selectionReasons = [];
             if (resolved.kind === 'model') {
-                candidates = await this.loadModelCandidate(resolved.modelId, required);
+                candidates = await this.loadModelCandidate(resolved.modelId, required, ctx.requestId);
                 selectionReasons.push('direct_model');
+                if (candidates.length === 0) {
+                    debugHttp(ctx.requestId, 'CAPABILITY REJECT', [
+                        `model=${resolved.publicModelId}`,
+                        `reason=direct_model_unavailable_or_capability_mismatch`,
+                        '(direct model candidates rejected: not found / provider disabled / model disabled / upstream unavailable / circuit open / capability mismatch)',
+                    ]);
+                }
             }
             else if (comboPlan) {
                 const all = await this.loadAllModels();
-                const filtered = selectCandidates(comboPlan, all, required);
+                const rejected = [];
+                const filtered = selectCandidates(comboPlan, all, required, (c, reason) => {
+                    rejected.push({ publicModelId: c.publicModelId, reason });
+                    debugHttp(ctx.requestId, 'CAPABILITY REJECT', [`model=${c.publicModelId}`, `reason=${reason}`]);
+                });
+                // docs/13 §10: always report why EACH member was filtered out
+                debugHttp(ctx.requestId, 'CANDIDATE FILTER', [
+                    `comboMembers=${comboPlan.members.length}`,
+                    `afterFilter=${filtered.length}`,
+                    `rejectedCount=${rejected.length}`,
+                    ...rejected.map((r) => `rejected: ${r.publicModelId} reason=${r.reason}`),
+                ]);
                 if (filtered.length === 0) {
                     throw new GatewayError('capability_not_supported', 'No combo member satisfies the request capabilities or availability', { status: 400 });
                 }
                 candidates = orderCandidates(comboPlan, filtered);
+                debugHttp(ctx.requestId, 'CANDIDATES ORDERED', [
+                    `mode=${comboPlan.mode}`,
+                    ...candidates.map((c, i) => `candidate[${i}]: providerModelId=${c.modelId} publicModelId=${c.publicModelId}`),
+                ]);
                 selectionReasons.push('combo');
             }
             if (candidates.length === 0) {
@@ -137,11 +181,13 @@ export class GatewayRunner {
                 finalModelId = candidate.modelId;
                 const provider = getDb().select().from(schema.providers).where(eq(schema.providers.id, candidate.providerId)).get();
                 if (!provider || !provider.enabled) {
+                    debugHttp(ctx.requestId, 'ATTEMPT SKIP', [`attempt=${i + 1} model=${candidate.publicModelId} reason=skipped_disabled_provider`]);
                     attempts.push(this.failedAttempt(i + 1, candidate, provider?.name ?? '', 'skipped_disabled_provider', null, null, 0, null, null));
                     continue;
                 }
                 const eff = getEffectiveState(provider.id, provider.cbCooldownSeconds);
                 if (eff === 'open' && !halfOpenProbeAllowed(provider.id)) {
+                    debugHttp(ctx.requestId, 'ATTEMPT SKIP', [`attempt=${i + 1} model=${candidate.publicModelId} provider=${provider.name} reason=circuit_open`]);
                     attempts.push(this.failedAttempt(i + 1, candidate, provider.name, 'circuit_open', null, null, 0, null, null));
                     if (comboPlan && shouldFallback(comboPlan, { type: 'connection_error' })) {
                         metrics.fallbackCount.inc();
@@ -152,6 +198,19 @@ export class GatewayRunner {
                 }
                 const cfg = providerToUpstreamConfig(provider);
                 const attemptStart = Date.now();
+                // docs/13 §11–§12: provider/account + upstream request summary
+                const upstreamModel = candidate.publicModelId.split('/').slice(1).join('/');
+                debugHttp(ctx.requestId, 'ATTEMPT', [
+                    `attempt=${i + 1}/${maxAttempts}`,
+                    `provider=${provider.name}`,
+                    `providerId=${provider.id}`,
+                    `model=${candidate.publicModelId}`,
+                    `upstreamModel=${upstreamModel}`,
+                    `upstreamType=${cfg.type}`,
+                    `baseUrl=${cfg.baseUrl}`,
+                    `stream=${req.canonical.stream}`,
+                    `providerKeyFingerprint=${apiKeyFingerprint(cfg.apiKey)}`,
+                ]);
                 const attempt = {
                     attemptNumber: i + 1,
                     providerId: provider.id,
@@ -206,6 +265,14 @@ export class GatewayRunner {
                 }
                 catch (e) {
                     const err = e instanceof GatewayError ? e : new GatewayError('upstream_error', e.message, { cause: e });
+                    debugUpstream(ctx.requestId, 'ATTEMPT ERROR', [
+                        `attempt=${i + 1}`,
+                        `provider=${provider.name}`,
+                        `model=${candidate.publicModelId}`,
+                        `type=${err.type}`,
+                        `status=${err.status}`,
+                        `willFallback=${comboPlan ? shouldFallback(comboPlan, { type: classifyFailure(err), status: err.status }) : false}`,
+                    ]);
                     const shouldRetry = comboPlan ? shouldFallback(comboPlan, { type: classifyFailure(err), status: err.status }) : false;
                     attempt.statusCode = err.status;
                     attempt.success = false;
@@ -288,14 +355,26 @@ export class GatewayRunner {
             metrics.activeRequests.dec();
         }
     }
-    async loadModelCandidate(modelId, required) {
+    async loadModelCandidate(modelId, required, requestId) {
         const db = getDb();
+        const reject = (reason) => {
+            if (requestId)
+                debugHttp(requestId, 'CAPABILITY REJECT', [`modelId=${modelId}`, `reason=${reason}`]);
+        };
         const m = db.select().from(schema.models).where(eq(schema.models.id, modelId)).get();
-        if (!m)
+        if (!m) {
+            reject('model_not_found');
             return [];
+        }
         const p = db.select().from(schema.providers).where(eq(schema.providers.id, m.providerId)).get();
-        if (!p || !p.enabled)
+        if (!p) {
+            reject('provider_not_found');
             return [];
+        }
+        if (!p.enabled) {
+            reject('provider_disabled');
+            return [];
+        }
         const caps = safeJson(m.capabilitiesJson);
         const candidate = {
             modelId: m.id,
@@ -306,12 +385,30 @@ export class GatewayRunner {
             circuitOpen: isOpen(m.providerId),
             capabilities: caps,
         };
-        if (!m.enabled || !m.upstreamAvailable)
+        if (!m.enabled) {
+            reject('model_disabled');
             return [];
-        if (candidate.circuitOpen)
+        }
+        if (!m.upstreamAvailable) {
+            reject('upstream_unavailable');
+            return [];
+        }
+        if (candidate.circuitOpen) {
+            reject('circuit_open');
             return [];
-        if (!modelMeets(caps, required))
+        }
+        if (!modelMeets(caps, required)) {
+            reject('capability_mismatch');
             return [];
+        }
+        debugHttp(requestId ?? '-', 'CAPABILITY CANDIDATE', [
+            `model=${m.publicModelId}`,
+            `caps.tools=${caps.tools}`,
+            `caps.streaming=${caps.streaming}`,
+            `caps.reasoning=${caps.reasoning}`,
+            `caps.image_input=${caps.image_input}`,
+            `caps.structured_output=${caps.structured_output}`,
+        ]);
         return [candidate];
     }
     async loadAllModels() {
@@ -333,18 +430,20 @@ export class GatewayRunner {
         if (req.canonical.stream) {
             return this.runStreamingAttempt(req, ctx, candidate, cfg, onStreamStart, onFirstToken);
         }
-        return this.runNonStreamingAttempt(req, candidate, cfg);
+        return this.runNonStreamingAttempt(req, candidate, cfg, ctx);
     }
-    async runNonStreamingAttempt(req, candidate, cfg) {
+    async runNonStreamingAttempt(req, candidate, cfg, ctx) {
         const upstreamModel = candidate.publicModelId.split('/').slice(1).join('/');
         let call;
         if (cfg.type === 'openai') {
             const payload = canonicalToOpenAIRequest(req.canonical, upstreamModel);
-            call = await callUpstreamNonStreaming(cfg, upstreamUrl(cfg, '/v1/chat/completions'), payload);
+            logUpstreamRequest(ctx.requestId, cfg, upstreamUrl(cfg, '/v1/chat/completions'), payload, req.canonical.stream);
+            call = await callUpstreamNonStreaming(cfg, upstreamUrl(cfg, '/v1/chat/completions'), payload, ctx.requestId);
         }
         else {
             const payload = canonicalToAnthropicRequest(req.canonical, upstreamModel);
-            call = await callUpstreamNonStreaming(cfg, upstreamUrl(cfg, '/v1/messages'), payload);
+            logUpstreamRequest(ctx.requestId, cfg, upstreamUrl(cfg, '/v1/messages'), payload, req.canonical.stream);
+            call = await callUpstreamNonStreaming(cfg, upstreamUrl(cfg, '/v1/messages'), payload, ctx.requestId);
         }
         if (!call.ok) {
             if (call.status === 429)
@@ -402,7 +501,39 @@ export class GatewayRunner {
         const toolBuf = [];
         let finishReason = null;
         const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 };
+        // docs/13 §15–§16: stream counters + client disconnect tracking
+        let chunkCount = 0;
+        let bytesReceived = 0;
+        let firstChunkTime = null;
+        let lastChunkTime = null;
+        const loggedFirstChunks = [];
+        let clientDisconnected = false;
+        // Guard: the admin test-stream endpoint passes a minimal `fakeRaw` that has
+        // writeHead/write/end but no `.on` — skip disconnect tracking in that case.
+        if (typeof pipe.on === 'function') {
+            pipe.on('close', () => {
+                // Distinguish client disconnect from normal end: 'close' fires on the raw
+                // socket when the client (or upstream) side goes away.
+                if (!pipe.writableEnded) {
+                    clientDisconnected = true;
+                    debugStream(ctx.requestId, 'CLIENT DISCONNECT', [
+                        `afterMs=${Date.now() - streamStartTs}`,
+                        `streaming=${streamStarted}`,
+                        `chunksSoFar=${chunkCount}`,
+                    ]);
+                }
+            });
+        }
         const chunkHandler = (chunk, isFirst) => {
+            chunkCount++;
+            bytesReceived += chunk.data.length;
+            lastChunkTime = Date.now();
+            if (isFirst)
+                firstChunkTime = Date.now() - streamStartTs;
+            if (loggedFirstChunks.length < 3) {
+                loggedFirstChunks.push(chunk.data);
+                debugStream(ctx.requestId, `STREAM FIRST CHUNK ${loggedFirstChunks.length}`, [truncate(chunk.data, 2000)]);
+            }
             try {
                 const obj = JSON.parse(chunk.data);
                 if (cfg.type === 'openai') {
@@ -473,12 +604,23 @@ export class GatewayRunner {
         try {
             const url = cfg.type === 'openai' ? upstreamUrl(cfg, '/v1/chat/completions') : upstreamUrl(cfg, '/v1/messages');
             const payload = cfg.type === 'openai' ? canonicalToOpenAIRequest(req.canonical, upstreamModel) : canonicalToAnthropicRequest(req.canonical, upstreamModel);
-            const meta = await callUpstreamStreaming(cfg, url, payload, chunkHandler);
+            logUpstreamRequest(ctx.requestId, cfg, url, payload, true);
+            debugStream(ctx.requestId, 'STREAM START', [`upstreamConnected=true`]);
+            const meta = await callUpstreamStreaming(cfg, url, payload, chunkHandler, ctx.requestId);
             // Upstream completed cleanly: ensure head + terminator are written.
             if (!headWritten)
                 writeHead();
             pipe.write('data: [DONE]\n\n');
             pipe.end();
+            debugStream(ctx.requestId, 'STREAM END', [
+                `chunks=${chunkCount}`,
+                `bytes=${bytesReceived}`,
+                `firstChunkMs=${firstChunkTime ?? 'null'}`,
+                `lastChunkMs=${lastChunkTime ? lastChunkTime - streamStartTs : 'null'}`,
+                `durationMs=${Date.now() - streamStartTs}`,
+                `finishedNormally=true`,
+                `clientDisconnected=${clientDisconnected}`,
+            ]);
             if (!usage.total)
                 usage.total = usage.input + usage.output;
             return {
@@ -497,8 +639,20 @@ export class GatewayRunner {
                     writeHead();
                 pipe.end();
                 const err = e instanceof GatewayError ? e : new GatewayError('upstream_error', e.message);
+                errorLine(ctx.requestId, 'STREAM ERROR', [
+                    `chunksBeforeError=${chunkCount}`,
+                    `bytesBeforeError=${bytesReceived}`,
+                    `clientDisconnected=${clientDisconnected}`,
+                    ...formatErrorPublic(e),
+                ]);
                 throw err;
             }
+            errorLine(ctx.requestId, 'STREAM ERROR (before first chunk)', [
+                `chunksBeforeError=${chunkCount}`,
+                `bytesBeforeError=${bytesReceived}`,
+                `clientDisconnected=${clientDisconnected}`,
+                ...formatErrorPublic(e),
+            ]);
             throw e;
         }
     }
@@ -732,6 +886,36 @@ function hasTools(req) {
 function estimateTokens(s) {
     return Math.ceil(s.length / 4);
 }
+// docs/13 §11: safe provider key fingerprint — never the key itself.
+function apiKeyFingerprint(key) {
+    let h = 5381;
+    for (let i = 0; i < key.length; i++) {
+        h = ((h << 5) + h + key.charCodeAt(i)) >>> 0;
+    }
+    return `fp_${h.toString(16).padStart(8, '0')}…${key.slice(-4).replace(/./g, '*')}${key.length}ch`;
+}
+// docs/13 §12: upstream request summary + optional full body
+function logUpstreamRequest(requestId, cfg, url, payload, stream) {
+    const json = JSON.stringify(payload ?? {});
+    debugUpstream(requestId, 'UPSTREAM REQUEST', [
+        `method=POST`,
+        `url=${url}`,
+        `type=${cfg.type}`,
+        `stream=${stream}`,
+        `contentLength=${json.length}`,
+        `customHeaders=${JSON.stringify(Object.keys(cfg.customHeaders ?? {}))}`,
+    ]);
+    if (getDebugFlags().httpBody) {
+        const LIMIT = 512 * 1024;
+        debugBody(requestId, 'UPSTREAM BODY', [
+            json.length > LIMIT ? `${json.slice(0, LIMIT)}…(+${json.length - LIMIT} chars, truncated)` : json,
+        ]);
+    }
+}
+/** Public alias so error formatting from debug.ts is available in this module. */
+function formatErrorPublic(e) {
+    return formatError(e);
+}
 /**
  * Safely parse capabilities JSON. Returns minimal default if parsing fails.
  * CRITICAL: Must return a complete default object with all capability fields,

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/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

package/dist/server/upstream/client.js

@@ -2,6 +2,7 @@
 import { decryptSecret, decryptCustomHeaders } from '../auth/crypto.js';
 import { GatewayError } from '../errors.js';
 import { buildHeaders, stripSlash } from '../providers/index.js';
+import { debugUpstream, errorLine, formatError, truncate } from '../logging/debug.js';
 export function providerToUpstreamConfig(p) {
     let apiKey;
     let customHeaders;
@@ -34,7 +35,7 @@ export function providerToUpstreamConfig(p) {
         totalTimeoutMs: p.totalTimeoutMs,
     };
 }
-export async function callUpstreamNonStreaming(cfg, url, payload) {
+export async function callUpstreamNonStreaming(cfg, url, payload, requestId = '-') {
     const ctl = new AbortController();
     const timer = setTimeout(() => ctl.abort(), cfg.totalTimeoutMs);
     const start = Date.now();
@@ -47,6 +48,7 @@ export async function callUpstreamNonStreaming(cfg, url, payload) {
         });
         const text = await res.text();
         const ttft = Date.now() - start;
+        logUpstreamResponse(requestId, res.status, res.statusText, res.headers, ttft, text);
         return {
             status: res.status,
             ok: res.ok,
@@ -58,6 +60,7 @@ export async function callUpstreamNonStreaming(cfg, url, payload) {
     }
     catch (e) {
         const err = e;
+        errorLine(requestId, 'UPSTREAM FETCH ERROR', [`url=${url}`, `afterMs=${Date.now() - start}`, ...formatError(e)]);
         if (err.name === 'AbortError') {
             throw new GatewayError('timeout_error', 'Upstream request timed out', { status: 504, cause: e });
         }
@@ -73,11 +76,28 @@ export function extractUpstreamRequestId(headers) {
     }
     return headers['x-request-id'] ?? headers['request-id'] ?? headers['x-amzn-requestid'] ?? null;
 }
+/** docs/13 §14: upstream response summary (sanitized headers) + error body for non-2xx. */
+function logUpstreamResponse(requestId, status, statusText, headers, durationMs, body) {
+    const h = (name) => headers.get(name) ?? undefined;
+    debugUpstream(requestId, 'UPSTREAM RESPONSE', [
+        `status=${status}`,
+        `statusText=${statusText}`,
+        `content-type=${h('content-type') ?? 'undefined'}`,
+        `content-length=${h('content-length') ?? 'undefined'}`,
+        `transfer-encoding=${h('transfer-encoding') ?? 'undefined'}`,
+        `server=${h('server') ?? 'undefined'}`,
+        `durationToHeadersMs=${durationMs}`,
+        `upstreamRequestId=${extractUpstreamRequestId(headers) ?? 'null'}`,
+    ]);
+    if (status < 200 || status >= 300) {
+        errorLine(requestId, 'UPSTREAM ERROR BODY', [truncate(body, 4000)]);
+    }
+}
 /**
  * Call upstream with SSE streaming. Invokes onChunk for each SSE event.
  * Returns a promise resolving when the stream completes or rejects on failure.
  */
-export async function callUpstreamStreaming(cfg, url, payload, onChunk) {
+export async function callUpstreamStreaming(cfg, url, payload, onChunk, requestId = '-') {
     const ctl = new AbortController();
     const totalTimer = setTimeout(() => ctl.abort(), cfg.totalTimeoutMs);
     const start = Date.now();
@@ -98,8 +118,10 @@ export async function callUpstreamStreaming(cfg, url, payload, onChunk) {
         });
         if (!res.ok || !res.body) {
             const text = await res.text();
+            logUpstreamResponse(requestId, res.status, res.statusText, res.headers, Date.now() - start, text);
             throw new UpstreamHttpError(res.status, text, extractUpstreamRequestId(res.headers));
         }
+        logUpstreamResponse(requestId, res.status, res.statusText, res.headers, Date.now() - start, '');
         // First-token watchdog
         firstTokenTimer = setTimeout(() => ctl.abort(), cfg.firstTokenTimeoutMs);
         resetIdle();
@@ -161,6 +183,12 @@ export async function callUpstreamStreaming(cfg, url, payload, onChunk) {
             throw new GatewayError('upstream_error', `Upstream HTTP ${e.status}: ${e.bodyExcerpt}`, { status: 502, cause: e });
         }
         const err = e;
+        errorLine(requestId, 'UPSTREAM FETCH ERROR', [
+            `url=${url}`,
+            `afterMs=${Date.now() - start}`,
+            `ttftKnown=${ttft !== null}`,
+            ...formatError(e),
+        ]);
         if (err.name === 'AbortError') {
             if (ttft === null && firstTokenTimer) {
                 throw new GatewayError('timeout_error', 'Upstream first token timeout', { status: 504, cause: e });

package/package.json

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