ldrouter 1.11.17 → 1.13.1

package/CHANGELOG.md

@@ -4,6 +4,33 @@ 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.13.1] - 2026-09-11
+
+### Fixed
+
+- **Update notification**: force a fresh npm registry check when the admin UI loads, so the update button is not hidden by the 15-minute cache.
+
+## [1.13.0] - 2026-09-11
+
+### Added
+
+- **Passphrase-protected full backups**: backups now include administrator state and a master-key envelope protected by a user-entered six-digit passphrase; `/setup` can import them without recreating the admin account.
+
+## [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/auth/backup-crypto.js

@@ -0,0 +1,31 @@
+import crypto from 'node:crypto';
+function passphraseKey(passphrase, salt) {
+    if (!/^\d{6}$/.test(passphrase))
+        throw new Error('Backup passphrase must contain exactly six digits');
+    return crypto.scryptSync(passphrase, salt, 32, { N: 16_384, r: 8, p: 1 });
+}
+export function encryptBackupMasterKey(masterKey, passphrase) {
+    const salt = crypto.randomBytes(16);
+    const nonce = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', passphraseKey(passphrase, salt), nonce);
+    const ciphertext = Buffer.concat([cipher.update(masterKey), cipher.final()]);
+    return {
+        algorithm: 'scrypt-aes-256-gcm',
+        salt: salt.toString('base64'),
+        nonce: nonce.toString('base64'),
+        ciphertext: ciphertext.toString('base64'),
+        tag: cipher.getAuthTag().toString('base64'),
+    };
+}
+export function decryptBackupMasterKey(envelope, passphrase) {
+    if (envelope.algorithm !== 'scrypt-aes-256-gcm')
+        throw new Error('Unsupported backup key encryption');
+    try {
+        const decipher = crypto.createDecipheriv('aes-256-gcm', passphraseKey(passphrase, Buffer.from(envelope.salt, 'base64')), Buffer.from(envelope.nonce, 'base64'));
+        decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
+        return Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, 'base64')), decipher.final()]);
+    }
+    catch {
+        throw new Error('Invalid backup passphrase');
+    }
+}

package/dist/server/auth/crypto.js

@@ -40,6 +40,9 @@ export function getMasterKey() {
 export function isMasterKeyConfigured() {
     return Boolean(loadConfig().masterKey);
 }
+export function resetMasterKeyCache() {
+    cachedKey = null;
+}
 export function masterKeyVersion() {
     return cachedKeyVersion;
 }

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,