@jsonstudio/llms 0.6.473 → 0.6.567

package/dist/conversion/shared/responses-output-builder.js

@@ -177,47 +177,6 @@ function normalizeUsage(usageRaw) {
     }
     return usageRaw;
 }
-function extractApplyPatchArguments(rawArgs) {
-    // Upstream Responses providers may wrap apply_patch arguments in a JSON object
-    // (e.g. { patch: '*** Begin Patch...', input: '...' }). For Codex, the tool
-    // expects a FREEFORM patch string obeying the unified diff grammar. Here we
-    // best-effort extract such a patch string when available.
-    const tryExtractFromObject = (obj) => {
-        if (!obj || typeof obj !== 'object' || Array.isArray(obj))
-            return null;
-        const record = obj;
-        const candidates = ['patch', 'input'];
-        for (const key of candidates) {
-            const value = record[key];
-            if (typeof value !== 'string')
-                continue;
-            const trimmed = value.trimStart();
-            if (trimmed.startsWith('*** Begin Patch')) {
-                return trimmed;
-            }
-        }
-        return null;
-    };
-    if (typeof rawArgs === 'string') {
-        const trimmed = rawArgs.trimStart();
-        if (trimmed.startsWith('*** Begin Patch')) {
-            return trimmed;
-        }
-        try {
-            const parsed = JSON.parse(rawArgs);
-            const fromObject = tryExtractFromObject(parsed);
-            if (fromObject) {
-                return fromObject;
-            }
-        }
-        catch {
-            // non-JSON string that is not a patch header; leave to caller
-        }
-        return null;
-    }
-    const fromObject = tryExtractFromObject(rawArgs);
-    return fromObject;
-}
 function buildFunctionCallOutput(call, allocateOutputId, sanitizeFunctionName, baseCount, offset) {
     try {
         const fn = call?.function || {};
@@ -228,37 +187,16 @@ function buildFunctionCallOutput(call, allocateOutputId, sanitizeFunctionName, b
         if (!sanitized || sanitized.toLowerCase() === 'tool')
             return null;
         const rawArgs = fn?.arguments ?? call.arguments ?? {};
-        let argsStr;
-        if (sanitized === 'apply_patch') {
-            const patch = extractApplyPatchArguments(rawArgs);
-            if (patch != null) {
-                argsStr = patch;
-            }
-            else if (typeof rawArgs === 'string') {
-                argsStr = rawArgs;
-            }
-            else {
+        const argsStr = typeof rawArgs === 'string'
+            ? rawArgs
+            : (() => {
                 try {
-                    argsStr = JSON.stringify(rawArgs ?? {});
+                    return JSON.stringify(rawArgs ?? {});
                 }
                 catch {
-                    argsStr = '{}';
+                    return '{}';
                 }
-            }
-        }
-        else {
-            argsStr =
-                typeof rawArgs === 'string'
-                    ? rawArgs
-                    : (() => {
-                        try {
-                            return JSON.stringify(rawArgs ?? {});
-                        }
-                        catch {
-                            return '{}';
-                        }
-                    })();
-        }
+            })();
         const originalCallId = typeof call.id === 'string' && call.id.trim().length
             ? String(call.id)
             : (typeof call.call_id === 'string' && call.call_id.trim().length ? String(call.call_id) : undefined);

package/dist/conversion/shared/tool-governor.js

@@ -3,6 +3,7 @@
 // canonicalizer 按需加载（避免在请求侧仅注入时引入不必要的模块）
 // enforceChatBudget: 为避免在请求侧引入多余依赖，这里提供最小实现（保留形状，不裁剪）。
 import { augmentOpenAITools } from '../../guidance/index.js';
+import { validateToolCall } from '../../tools/tool-registry.js';
 function isObject(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
 // Note: tool schema strict augmentation removed per alignment
 function enforceChatBudget(chat, _modelId) { return chat; }
@@ -173,8 +174,7 @@ export function processChatRequestTools(request, opts) {
                     continue;
                 const typeStr = String(t.type || '').toLowerCase();
                 const nameStr = typeof fn.name === 'string' ? String(fn.name).toLowerCase() : '';
-                const shouldPatch = typeStr === 'function' ||
-                    nameStr === 'apply_patch';
+                const shouldPatch = typeStr === 'function' || nameStr === 'apply_patch';
                 if (!shouldPatch)
                     continue;
                 if (!Object.prototype.hasOwnProperty.call(fn, 'parameters')) {
@@ -208,7 +208,8 @@ export function processChatRequestTools(request, opts) {
         catch { /* ignore */ }
         // 4) Enforce payload budget (context bytes) with minimal loss policy
         const modelId = typeof canonical?.model === 'string' ? String(canonical.model) : 'unknown';
-        return enforceChatBudget(canonical, modelId);
+        const budgeted = enforceChatBudget(canonical, modelId);
+        return normalizeApplyPatchToolCallsOnRequest(budgeted);
     }
     catch {
         return out;
@@ -219,6 +220,75 @@ export function processChatRequestTools(request, opts) {
  * - Canonicalize textual tool markup to tool_calls; ensure finish_reason and content=null policy
  */
 import { repairArgumentsToString, parseLenient } from './jsonish.js';
+function normalizeApplyPatchToolCallsOnResponse(chat) {
+    try {
+        const out = JSON.parse(JSON.stringify(chat));
+        const choices = Array.isArray(out?.choices) ? out.choices : [];
+        for (const ch of choices) {
+            const msg = ch && ch.message ? ch.message : undefined;
+            const tcs = Array.isArray(msg?.tool_calls) ? msg.tool_calls : [];
+            if (!tcs.length)
+                continue;
+            for (const tc of tcs) {
+                try {
+                    const fn = tc && tc.function ? tc.function : undefined;
+                    const name = typeof fn?.name === 'string' ? String(fn.name).trim().toLowerCase() : '';
+                    if (name !== 'apply_patch')
+                        continue;
+                    const rawArgs = fn?.arguments;
+                    const argsStr = repairArgumentsToString(rawArgs);
+                    const validation = validateToolCall('apply_patch', argsStr);
+                    if (validation && validation.ok && typeof validation.normalizedArgs === 'string') {
+                        fn.arguments = validation.normalizedArgs;
+                    }
+                }
+                catch {
+                    // best-effort per tool_call
+                }
+            }
+        }
+        return out;
+    }
+    catch {
+        return chat;
+    }
+}
+function normalizeApplyPatchToolCallsOnRequest(request) {
+    try {
+        const out = JSON.parse(JSON.stringify(request));
+        const messages = Array.isArray(out?.messages) ? out.messages : [];
+        for (const msg of messages) {
+            if (!msg || typeof msg !== 'object')
+                continue;
+            if (msg.role !== 'assistant')
+                continue;
+            const tcs = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+            if (!tcs.length)
+                continue;
+            for (const tc of tcs) {
+                try {
+                    const fn = tc && tc.function ? tc.function : undefined;
+                    const name = typeof fn?.name === 'string' ? String(fn.name).trim().toLowerCase() : '';
+                    if (name !== 'apply_patch')
+                        continue;
+                    const rawArgs = fn?.arguments;
+                    const argsStr = repairArgumentsToString(rawArgs);
+                    const validation = validateToolCall('apply_patch', argsStr);
+                    if (validation && validation.ok && typeof validation.normalizedArgs === 'string') {
+                        fn.arguments = validation.normalizedArgs;
+                    }
+                }
+                catch {
+                    // best-effort per tool_call
+                }
+            }
+        }
+        return out;
+    }
+    catch {
+        return request;
+    }
+}
 function enhanceResponseToolArguments(chat) {
     try {
         const enable = String(process?.env?.RCC_TOOL_ENHANCE ?? '1').trim() !== '0';
@@ -336,7 +406,8 @@ export function processChatResponseTools(resp) {
     try {
         const { canonicalizeChatResponseTools } = require('./tool-canonicalizer.js');
         const canon = canonicalizeChatResponseTools(resp);
-        return enhanceResponseToolArguments(canon);
+        const withPatch = normalizeApplyPatchToolCallsOnResponse(canon);
+        return enhanceResponseToolArguments(withPatch);
     }
     catch {
         return resp;

package/dist/conversion/shared/tool-mapping.js

@@ -29,20 +29,26 @@ function ensureApplyPatchSchema(seed) {
     const schema = seed ? { ...seed } : {};
     schema.type = typeof schema.type === 'string' ? schema.type : 'object';
     const properties = isPlainObject(schema.properties) ? { ...schema.properties } : {};
-    properties.input = {
+    delete properties.input;
+    delete properties.patch;
+    properties.patch = {
         type: 'string',
-        description: 'Unified diff patch body between *** Begin Patch/*** End Patch.'
+        description: 'Unified diff patch text. The first line MUST be exactly "*** Begin Patch", followed by one or more file sections starting with ' +
+            '"*** Add File: {path}", "*** Update File: {path}", or "*** Delete File: {path}", using hunks with lines prefixed by " ", "+", or "-". ' +
+            'The last non-empty line MUST be exactly "*** End Patch". Git-style headers like "--- a/file" / "+++ b/file" and merge markers ' +
+            '"<<<<<<<", "=======", ">>>>>>>" are NOT allowed.'
     };
-    if (!properties.patch || typeof properties.patch !== 'object') {
-        properties.patch = {
-            type: 'string',
-            description: 'Alias of input for backwards compatibility.'
+    if (!isPlainObject(properties.paths)) {
+        properties.paths = {
+            type: 'array',
+            description: 'Optional explicit list of relative file paths that the patch touches. Each entry must be a relative workspace path (packages/foo/file.ts).',
+            items: { type: 'string' }
         };
     }
     schema.properties = properties;
     const requiredList = Array.isArray(schema.required) ? schema.required.filter((entry) => typeof entry === 'string') : [];
-    if (!requiredList.includes('input')) {
-        requiredList.push('input');
+    if (!requiredList.includes('patch')) {
+        requiredList.push('patch');
     }
     schema.required = requiredList;
     if (typeof schema.additionalProperties !== 'boolean') {

package/dist/filters/special/request-toolcalls-stringify.js

@@ -27,12 +27,14 @@ export class RequestToolCallsStringifyFilter {
                             const fnName = typeof fn.name === 'string' ? fn.name.trim() : '';
                             // Case 1: non-string arguments → stringify directly
                             if (currentArgs !== undefined && typeof currentArgs !== 'string') {
+                                let argsJson = '{}';
                                 try {
-                                    fn.arguments = JSON.stringify(currentArgs ?? {});
+                                    argsJson = JSON.stringify(currentArgs ?? {});
                                 }
                                 catch {
-                                    fn.arguments = '{}';
+                                    argsJson = '{}';
                                 }
+                                fn.arguments = argsJson;
                                 tc.function = fn;
                                 continue;
                             }
@@ -61,9 +63,6 @@ export class RequestToolCallsStringifyFilter {
                                         if (fnName === 'shell') {
                                             fn.arguments = JSON.stringify({ command: currentArgs });
                                         }
-                                        else if (fnName === 'apply_patch') {
-                                            fn.arguments = JSON.stringify({ patch: currentArgs });
-                                        }
                                         else {
                                             fn.arguments = JSON.stringify({ input: currentArgs });
                                         }
@@ -74,56 +73,7 @@ export class RequestToolCallsStringifyFilter {
                                     tc.function = fn;
                                     continue;
                                 }
-                                // 已经是合法 JSON 的场景下，仅对特定工具做形状修复。
-                                if (parsedOk && fnName === 'apply_patch') {
-                                    try {
-                                        let obj = parsedValue;
-                                        // 1) 若整体是字符串，则视为补丁文本
-                                        if (typeof obj === 'string') {
-                                            obj = { patch: obj };
-                                        }
-                                        if (obj && typeof obj === 'object') {
-                                            const container = obj;
-                                            const rawPatch = container.patch;
-                                            const rawInput = container.input;
-                                            // 2) 若 patch 是形如 JSON 的字符串，尝试解包 {"input": "..."} 或 {"patch": "..."}
-                                            if (typeof rawPatch === 'string') {
-                                                const ptrim = rawPatch.trim();
-                                                if (ptrim.startsWith('{') && ptrim.endsWith('}')) {
-                                                    try {
-                                                        const inner = JSON.parse(ptrim);
-                                                        if (typeof inner.patch === 'string') {
-                                                            container.patch = inner.patch;
-                                                        }
-                                                        else if (typeof inner.input === 'string') {
-                                                            container.patch = inner.input;
-                                                        }
-                                                        else {
-                                                            container.patch = ptrim;
-                                                        }
-                                                    }
-                                                    catch {
-                                                        container.patch = rawPatch;
-                                                    }
-                                                }
-                                            }
-                                            else if (rawPatch === undefined && typeof rawInput === 'string') {
-                                                // 3) 若只有 input 字段，则复制一份到 patch，避免双层包装
-                                                container.patch = rawInput;
-                                            }
-                                            fn.arguments = JSON.stringify(container);
-                                            tc.function = fn;
-                                            continue;
-                                        }
-                                    }
-                                    catch {
-                                        // 回退到原始字符串形状
-                                        fn.arguments = trimmed;
-                                        tc.function = fn;
-                                        continue;
-                                    }
-                                }
-                                // 其它合法 JSON 场景保持原样
+                                // 合法 JSON 场景保持原样
                                 fn.arguments = trimmed;
                                 tc.function = fn;
                             }

package/dist/filters/special/request-tools-normalize.js

@@ -101,25 +101,6 @@ export class RequestOpenAIToolsNormalizeFilter {
                                 };
                             }
                         }
-                        else if (name === 'apply_patch') {
-                            dst.function.parameters = {
-                                type: 'object',
-                                properties: {
-                                    input: {
-                                        type: 'string',
-                                        description: 'Unified diff patch body between *** Begin Patch/*** End Patch.'
-                                    },
-                                    patch: {
-                                        type: 'string',
-                                        description: 'Alias of input for backwards compatibility.'
-                                    }
-                                },
-                                required: ['input'],
-                                additionalProperties: false
-                            };
-                            dst.function.description =
-                                'Use apply_patch to edit files. Provide the diff via the input field (*** Begin Patch ... *** End Patch).';
-                        }
                     }
                     catch { /* ignore */ }
                     finalTools.push(dst);

package/dist/guidance/index.js

@@ -62,9 +62,11 @@ function augmentApplyPatch(fn) {
     const marker = '[Codex ApplyPatch Guidance]';
     const guidance = [
         marker,
-        'Edit files by applying a unified diff patch. Return ONLY the patch text with *** Begin Patch/*** End Patch blocks.',
-        'Paths resolve relative to the active workspace root. Use forward-slash paths (e.g., packages/foo/file.ts) and switch to absolute paths only if you truly need to edit outside the workspace.',
-        '路径一律相对于当前工作区根目录解析；请写 packages/foo/... 这样的相对路径，跨工作区时再使用绝对路径。',
+        'Edit files by applying a unified diff patch. Return ONLY the patch text with *** Begin Patch/*** End Patch blocks and file sections starting with "*** Add/Update/Delete File: {path}".',
+        'Populate the `paths` array with every relative file path touched by this patch (e.g., ["src/foo.ts"]); paths are preferred over any filenames embedded in the patch body.',
+        'Do NOT use git-style headers ("--- a/file", "+++ b/file") or merge markers ("<<<<<<<", "=======", ">>>>>>>"); hunks must use only " ", "+", "-" prefixes.',
+        'Paths resolve relative to the active workspace root. Use forward-slash paths (e.g., packages/foo/file.ts).',
+        '路径一律相对于当前工作区根目录解析；请写 packages/foo/... 这样的相对路径。',
         'Example:',
         '*** Begin Patch',
         '*** Update File: path/to/file.ts',
@@ -75,9 +77,16 @@ function augmentApplyPatch(fn) {
     ].join('\n');
     const params = ensureObjectSchema(fn.parameters);
     const props = params.properties;
-    if (!isObject(props.patch)) {
-        props.patch = { type: 'string', description: 'Unified diff patch text' };
+    if (isObject(props)) {
+        delete props.input;
     }
+    props.patch = { type: 'string', description: 'Unified diff patch text' };
+    props.paths = {
+        type: 'array',
+        description: 'Explicit list of relative file paths affected by this patch (e.g., ["src/foo.ts"]).',
+        items: { type: 'string' }
+    };
+    params.properties = props;
     if (!Array.isArray(params.required)) {
         params.required = [];
     }
@@ -171,9 +180,15 @@ export function augmentAnthropicTools(tools) {
             const n = name.trim();
             try {
                 if (n === 'apply_patch') {
-                    if (!isObject(schema.properties?.patch)) {
-                        schema.properties.patch = { type: 'string', description: 'Unified diff patch text' };
-                    }
+                    const props = ensureObjectSchema(schema.properties);
+                    delete props.input;
+                    props.patch = { type: 'string', description: 'Unified diff patch text' };
+                    props.paths = {
+                        type: 'array',
+                        description: 'Explicit list of relative file paths affected by this patch (e.g., ["src/foo.ts"]).',
+                        items: { type: 'string' }
+                    };
+                    schema.properties = props;
                     if (!Array.isArray(schema.required))
                         schema.required = [];
                     if (!schema.required.includes('patch'))
@@ -183,7 +198,8 @@ export function augmentAnthropicTools(tools) {
                     const marker = '[Codex ApplyPatch Guidance]';
                     const guidance = [
                         marker,
-                        'Use unified diff patch with *** Begin Patch/End Patch. Return only the patch text.',
+                        'Use unified diff patch with *** Begin Patch/End Patch. Return only the patch body.',
+                        'Populate the `paths` array with every relative workspace path touched by this patch.',
                         'All file paths must stay relative to the workspace root; never emit leading \'/\' or drive letters.',
                         '所有文件路径都必须相对当前工作区根目录，禁止输出以 / 或盘符开头的绝对路径。'
                     ].join('\n');

package/dist/router/virtual-router/engine-health.d.ts

@@ -0,0 +1,11 @@
+import { ProviderHealthManager } from './health-manager.js';
+import { ProviderRegistry } from './provider-registry.js';
+import type { ProviderErrorEvent, ProviderFailureEvent, ProviderHealthConfig } from './types.js';
+type DebugLike = {
+    log?: (...args: unknown[]) => void;
+} | Console | undefined;
+export declare function handleProviderFailureImpl(event: ProviderFailureEvent, healthManager: ProviderHealthManager, healthConfig: Required<ProviderHealthConfig>, markProviderCooldown: (providerKey: string, cooldownMs: number | undefined) => void): void;
+export declare function mapProviderErrorImpl(event: ProviderErrorEvent, healthConfig: Required<ProviderHealthConfig>): ProviderFailureEvent | null;
+export declare function applySeriesCooldownImpl(event: ProviderErrorEvent, providerRegistry: ProviderRegistry, healthManager: ProviderHealthManager, markProviderCooldown: (providerKey: string, cooldownMs: number | undefined) => void, debug?: DebugLike): void;
+export declare function deriveReason(code: string, stage: string, statusCode?: number): string;
+export {};

package/dist/router/virtual-router/engine-health.js

@@ -0,0 +1,210 @@
+const SERIES_COOLDOWN_DETAIL_KEY = 'virtualRouterSeriesCooldown';
+export function handleProviderFailureImpl(event, healthManager, healthConfig, markProviderCooldown) {
+    if (!event || !event.providerKey) {
+        return;
+    }
+    if (event.affectsHealth === false) {
+        return;
+    }
+    if (event.fatal) {
+        healthManager.tripProvider(event.providerKey, event.reason, event.cooldownOverrideMs);
+    }
+    else if (event.reason === 'rate_limit' && event.statusCode === 429) {
+        healthManager.cooldownProvider(event.providerKey, event.reason, event.cooldownOverrideMs);
+        const ttl = event.cooldownOverrideMs ?? healthConfig.cooldownMs;
+        markProviderCooldown(event.providerKey, ttl);
+    }
+    else {
+        healthManager.recordFailure(event.providerKey, event.reason);
+    }
+}
+export function mapProviderErrorImpl(event, healthConfig) {
+    if (!event || !event.runtime) {
+        return null;
+    }
+    const runtime = event.runtime;
+    const providerKey = runtime.providerKey ||
+        (runtime.target && typeof runtime.target === 'object'
+            ? runtime.target.providerKey
+            : undefined);
+    if (!providerKey) {
+        return null;
+    }
+    const routeName = runtime.routeName;
+    const statusCode = event.status;
+    const code = event.code?.toUpperCase() ?? 'ERR_UNKNOWN';
+    const stage = event.stage?.toLowerCase() ?? 'unknown';
+    const recoverable = event.recoverable === true;
+    let fatal = !recoverable;
+    let reason = deriveReason(code, stage, statusCode);
+    let cooldownOverrideMs;
+    if (statusCode === 401 || statusCode === 402 || statusCode === 403 || code.includes('AUTH')) {
+        fatal = true;
+        cooldownOverrideMs = Math.max(10 * 60_000, healthConfig.fatalCooldownMs ?? 10 * 60_000);
+        reason = 'auth';
+    }
+    else if (statusCode === 429 && !recoverable) {
+        fatal = true;
+        cooldownOverrideMs = Math.max(10 * 60_000, healthConfig.fatalCooldownMs ?? 10 * 60_000);
+        reason = 'rate_limit';
+    }
+    else if (statusCode && statusCode >= 500) {
+        fatal = true;
+        cooldownOverrideMs = Math.max(5 * 60_000, healthConfig.fatalCooldownMs ?? 5 * 60_000);
+        reason = 'upstream_error';
+    }
+    else if (stage.includes('compat')) {
+        fatal = true;
+        cooldownOverrideMs = Math.max(10 * 60_000, healthConfig.fatalCooldownMs ?? 10 * 60_000);
+        reason = 'compatibility';
+    }
+    return {
+        providerKey,
+        routeName,
+        reason,
+        fatal,
+        statusCode,
+        errorCode: code,
+        retryable: recoverable,
+        affectsHealth: event.affectsHealth !== false,
+        cooldownOverrideMs,
+        metadata: {
+            ...event.runtime,
+            stage,
+            eventCode: code,
+            originalMessage: event.message,
+            statusCode
+        }
+    };
+}
+export function applySeriesCooldownImpl(event, providerRegistry, healthManager, markProviderCooldown, debug) {
+    const seriesDetail = extractSeriesCooldownDetail(event);
+    if (!seriesDetail) {
+        return;
+    }
+    const targetKeys = resolveSeriesCooldownTargets(seriesDetail, event, providerRegistry);
+    if (targetKeys.length === 0) {
+        debug?.log?.('[virtual-router] series cooldown skipped: no targets', {
+            providerId: seriesDetail.providerId,
+            providerKey: seriesDetail.providerKey,
+            series: seriesDetail.series
+        });
+        return;
+    }
+    const affected = [];
+    for (const providerKey of targetKeys) {
+        try {
+            const profile = providerRegistry.get(providerKey);
+            const modelSeries = resolveModelSeries(profile.modelId);
+            if (modelSeries !== seriesDetail.series) {
+                continue;
+            }
+            healthManager.tripProvider(providerKey, 'rate_limit', seriesDetail.cooldownMs);
+            markProviderCooldown(providerKey, seriesDetail.cooldownMs);
+            affected.push(providerKey);
+        }
+        catch {
+            // ignore lookup failures; invalid keys may show up if config drifted
+        }
+    }
+    if (affected.length) {
+        debug?.log?.('[virtual-router] series cooldown', {
+            providerId: seriesDetail.providerId,
+            providerKey: seriesDetail.providerKey,
+            series: seriesDetail.series,
+            cooldownMs: seriesDetail.cooldownMs,
+            affected
+        });
+    }
+}
+function resolveSeriesCooldownTargets(detail, event, providerRegistry) {
+    const candidates = new Set();
+    const push = (key) => {
+        if (typeof key !== 'string') {
+            return;
+        }
+        const trimmed = key.trim();
+        if (!trimmed) {
+            return;
+        }
+        if (providerRegistry.has(trimmed)) {
+            candidates.add(trimmed);
+        }
+    };
+    push(detail.providerKey);
+    const runtimeKey = (event.runtime?.target && typeof event.runtime.target === 'object'
+        ? event.runtime.target.providerKey
+        : undefined) || event.runtime?.providerKey;
+    push(runtimeKey);
+    return Array.from(candidates);
+}
+function extractSeriesCooldownDetail(event) {
+    if (!event || !event.details || typeof event.details !== 'object') {
+        return null;
+    }
+    const raw = event.details[SERIES_COOLDOWN_DETAIL_KEY];
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const record = raw;
+    const providerIdRaw = record.providerId;
+    const seriesRaw = record.series;
+    const providerKeyRaw = record.providerKey;
+    const cooldownRaw = record.cooldownMs;
+    if (typeof providerIdRaw !== 'string' || !providerIdRaw.trim()) {
+        return null;
+    }
+    const normalizedSeries = typeof seriesRaw === 'string' ? seriesRaw.trim().toLowerCase() : '';
+    if (normalizedSeries !== 'gemini-pro' && normalizedSeries !== 'gemini-flash' && normalizedSeries !== 'claude') {
+        return null;
+    }
+    const cooldownMs = typeof cooldownRaw === 'number'
+        ? cooldownRaw
+        : typeof cooldownRaw === 'string'
+            ? Number.parseFloat(cooldownRaw)
+            : Number.NaN;
+    if (!Number.isFinite(cooldownMs) || cooldownMs <= 0) {
+        return null;
+    }
+    return {
+        providerId: providerIdRaw.trim(),
+        ...(typeof providerKeyRaw === 'string' && providerKeyRaw.trim().length
+            ? { providerKey: providerKeyRaw.trim() }
+            : {}),
+        series: normalizedSeries,
+        cooldownMs: Math.round(cooldownMs)
+    };
+}
+export function deriveReason(code, stage, statusCode) {
+    if (code.includes('RATE') || code.includes('429'))
+        return 'rate_limit';
+    if (code.includes('AUTH') || statusCode === 401 || statusCode === 403)
+        return 'auth';
+    if (stage.includes('compat'))
+        return 'compatibility';
+    if (code.includes('SSE'))
+        return 'sse';
+    if (code.includes('TIMEOUT') || statusCode === 408 || statusCode === 504)
+        return 'timeout';
+    if (statusCode && statusCode >= 500)
+        return 'upstream_error';
+    if (statusCode && statusCode >= 400)
+        return 'client_error';
+    return 'unknown';
+}
+function resolveModelSeries(modelId) {
+    if (!modelId) {
+        return 'default';
+    }
+    const lower = modelId.toLowerCase();
+    if (lower.includes('claude') || lower.includes('opus')) {
+        return 'claude';
+    }
+    if (lower.includes('flash')) {
+        return 'gemini-flash';
+    }
+    if (lower.includes('gemini') || lower.includes('pro')) {
+        return 'gemini-pro';
+    }
+    return 'default';
+}

package/dist/router/virtual-router/engine-logging.d.ts

@@ -0,0 +1,19 @@
+import { type ClassificationResult, type RoutingFeatures, type RoutingInstructionMode, type VirtualRouterContextRoutingConfig } from './types.js';
+import { ProviderRegistry } from './provider-registry.js';
+type LoggingDeps = {
+    providerRegistry: ProviderRegistry;
+    contextRouting: VirtualRouterContextRoutingConfig | undefined;
+};
+export declare function formatStickyScope(scope?: string): string | undefined;
+export declare function parseProviderKey(providerKey: string): {
+    providerId: string;
+    keyAlias?: string;
+    modelId?: string;
+} | null;
+export declare function describeTargetProvider(providerKey: string, fallbackModelId?: string): {
+    providerLabel: string;
+    resolvedModel?: string;
+};
+export declare function buildHitReason(routeUsed: string, providerKey: string, classification: ClassificationResult, features: RoutingFeatures, mode: RoutingInstructionMode | undefined, deps: LoggingDeps): string;
+export declare function formatVirtualRouterHit(routeName: string, poolId: string | undefined, providerKey: string, modelId?: string, hitReason?: string, stickyScope?: string): string;
+export {};