@jsonstudio/llms 0.6.54 → 0.6.97

package/dist/conversion/codecs/responses-openai-codec.js

@@ -1,5 +1,6 @@
 import { buildResponsesPayloadFromChat, runStandardChatRequestFilters } from '../index.js';
-import { captureResponsesContext, buildChatRequestFromResponses } from '../responses/responses-openai-bridge.js';
+import { captureResponsesContext, buildChatRequestFromResponses, buildResponsesRequestFromChat } from '../responses/responses-openai-bridge.js';
+import { captureResponsesRequestContext } from '../shared/responses-conversation-store.js';
 import { FilterEngine, ResponseToolTextCanonicalizeFilter, ResponseToolArgumentsStringifyFilter, ResponseFinishInvariantsFilter } from '../../filters/index.js';
 // Ported from root package (no behavior change). Types relaxed.
 export class ResponsesOpenAIConversionCodec {
@@ -83,6 +84,20 @@ export class ResponsesOpenAIConversionCodec {
             endpoint: context.endpoint ?? dto.metadata?.endpoint
         };
         const filtered = await runStandardChatRequestFilters(chatRequest, profile, ctxForFilters);
+        try {
+            const rebuilt = buildResponsesRequestFromChat(filtered, ctx);
+            const payloadForStore = rebuilt?.request;
+            if (payloadForStore && typeof payloadForStore === 'object') {
+                captureResponsesRequestContext({
+                    requestId: dto.route.requestId,
+                    payload: payloadForStore,
+                    context: ctx
+                });
+            }
+        }
+        catch {
+            // best-effort capture
+        }
         if (filtered && typeof filtered === 'object') {
             const maybe = filtered;
             if (maybe.max_tokens === undefined && typeof maybe.max_output_tokens === 'number') {

package/dist/conversion/hub/pipeline/hub-pipeline.d.ts

@@ -44,6 +44,7 @@ export interface HubPipelineResult {
 export declare class HubPipeline {
     private readonly routerEngine;
     private config;
+    private unsubscribeProviderErrors?;
     constructor(config: HubPipelineConfig);
     updateVirtualRouterConfig(nextConfig: VirtualRouterConfig): void;
     private executeRequestStagePipeline;

package/dist/conversion/hub/pipeline/hub-pipeline.js

@@ -1,5 +1,6 @@
 import { Readable } from 'node:stream';
 import { VirtualRouterEngine } from '../../../router/virtual-router/engine.js';
+import { providerErrorCenter } from '../../../router/virtual-router/error-center.js';
 import { defaultSseCodecRegistry } from '../../../sse/index.js';
 import { ResponsesFormatAdapter } from '../format-adapters/responses-format-adapter.js';
 import { ResponsesSemanticMapper } from '../semantic-mappers/responses-mapper.js';
@@ -22,10 +23,24 @@ import { runReqOutboundStage3Compat } from './stages/req_outbound/req_outbound_s
 export class HubPipeline {
     routerEngine;
     config;
+    unsubscribeProviderErrors;
     constructor(config) {
         this.config = config;
         this.routerEngine = new VirtualRouterEngine();
         this.routerEngine.initialize(config.virtualRouter);
+        try {
+            this.unsubscribeProviderErrors = providerErrorCenter.subscribe((event) => {
+                try {
+                    this.routerEngine.handleProviderError(event);
+                }
+                catch {
+                    // ignore subscriber errors
+                }
+            });
+        }
+        catch {
+            this.unsubscribeProviderErrors = undefined;
+        }
     }
     updateVirtualRouterConfig(nextConfig) {
         if (!nextConfig || typeof nextConfig !== 'object') {
@@ -92,6 +107,10 @@ export class HubPipeline {
             }
         }
         const workingRequest = processedRequest ?? standardizedRequest;
+        const normalizedMeta = normalized.metadata;
+        const responsesResume = normalizedMeta && typeof normalizedMeta.responsesResume === 'object'
+            ? normalizedMeta.responsesResume
+            : undefined;
         const metadataInput = {
             requestId: normalized.id,
             entryEndpoint: normalized.entryEndpoint,
@@ -100,7 +119,8 @@ export class HubPipeline {
             direction: normalized.direction,
             providerProtocol: normalized.providerProtocol,
             routeHint: normalized.routeHint,
-            stage: normalized.stage
+            stage: normalized.stage,
+            responsesResume: responsesResume
         };
         const routing = runReqProcessStage2RouteSelect({
             routerEngine: this.routerEngine,
@@ -109,6 +129,19 @@ export class HubPipeline {
             normalizedMetadata: normalized.metadata,
             stageRecorder: inboundRecorder
         });
+        // Emit virtual router hit log for debugging (orange [virtual-router] ...)
+        try {
+            const routeName = routing.decision?.routeName;
+            const providerKey = routing.target?.providerKey;
+            const modelId = workingRequest.model;
+            const logger = (normalized.metadata && normalized.metadata.logger);
+            if (logger && typeof logger.logVirtualRouterHit === 'function' && routeName && providerKey) {
+                logger.logVirtualRouterHit(routeName, providerKey, typeof modelId === 'string' ? modelId : undefined);
+            }
+        }
+        catch {
+            // logging must not break routing
+        }
         const outboundAdapterContext = this.buildAdapterContext(normalized, routing.target);
         if (routing.target?.compatibilityProfile) {
             outboundAdapterContext.compatibilityProfile = routing.target.compatibilityProfile;

package/dist/conversion/hub/pipeline/stages/req_inbound/req_inbound_stage3_context_capture/index.js

@@ -1,5 +1,4 @@
 import { captureResponsesContext, buildChatRequestFromResponses } from '../../../../../responses/responses-openai-bridge.js';
-import { captureResponsesRequestContext } from '../../../../../shared/responses-conversation-store.js';
 import { recordStage } from '../../../stages/utils.js';
 export async function runReqInboundStage3ContextCapture(options) {
     let context;
@@ -54,16 +53,6 @@ export function captureResponsesContextSnapshot(options) {
     catch {
         // best-effort context capture
     }
-    try {
-        captureResponsesRequestContext({
-            requestId: options.adapterContext.requestId,
-            payload: options.rawRequest,
-            context
-        });
-    }
-    catch {
-        // ignore store capture failures
-    }
     return context;
 }
 function captureChatContextSnapshot(options) {

package/dist/conversion/hub/pipeline/stages/resp_outbound/resp_outbound_stage1_client_remap/index.js

@@ -15,6 +15,7 @@ export function runRespOutboundStage1ClientRemap(options) {
         clientPayload = buildResponsesPayloadFromChat(options.payload, {
             requestId: options.requestId
         });
+        mergeOriginalResponsesPayload(clientPayload, options.adapterContext);
     }
     recordStage(options.stageRecorder, 'resp_outbound_stage1_client_remap', clientPayload);
     return clientPayload;
@@ -41,3 +42,24 @@ function resolveAliasMapFromContext(adapterContext) {
     }
     return Object.keys(map).length ? map : undefined;
 }
+function mergeOriginalResponsesPayload(payload, adapterContext) {
+    if (!adapterContext) {
+        return;
+    }
+    const raw = adapterContext.__raw_responses_payload;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return;
+    }
+    try {
+        if (payload.required_action == null && raw.required_action != null) {
+            payload.required_action = JSON.parse(JSON.stringify(raw.required_action));
+        }
+    }
+    catch {
+        /* ignore clone errors */
+    }
+    const rawStatus = typeof raw.status === 'string' ? raw.status : undefined;
+    if (rawStatus === 'requires_action') {
+        payload.status = 'requires_action';
+    }
+}

package/dist/conversion/hub/process/chat-process.js

@@ -44,7 +44,10 @@ async function applyRequestToolGovernance(request, context) {
         model: request.model,
         profile: providerProtocol,
         stream: inboundStreamIntent,
-        toolFilterHints: metadataToolHints
+        toolFilterHints: metadataToolHints,
+        rawPayload: context.metadata?.__raw_request_body && typeof context.metadata.__raw_request_body === 'object'
+            ? context.metadata.__raw_request_body
+            : undefined
     });
     const governed = normalizeRecord(governedPayload);
     const providerStreamIntent = typeof governed.stream === 'boolean' ? governed.stream : undefined;

package/dist/conversion/hub/response/provider-response.js

@@ -117,6 +117,14 @@ export async function convertProviderResponse(options) {
         catch {
             // ignore conversation capture errors
         }
+        if (formatEnvelope.payload && typeof formatEnvelope.payload === 'object') {
+            try {
+                options.context.__raw_responses_payload = JSON.parse(JSON.stringify(formatEnvelope.payload));
+            }
+            catch {
+                /* best-effort clone */
+            }
+        }
     }
     formatEnvelope.payload = runRespInboundStageCompatResponse({
         payload: formatEnvelope.payload,

package/dist/conversion/responses/responses-openai-bridge.d.ts

@@ -48,6 +48,7 @@ export declare function buildResponsesRequestFromChat(payload: Record<string, un
     bridgeHistory?: BridgeInputBuildResult;
     systemInstruction?: string;
 }): BuildResponsesRequestResult;
+export declare function ensureResponsesApplyPatchArguments(input?: BridgeInputItem[]): void;
 export declare function buildResponsesPayloadFromChat(payload: unknown, context?: ResponsesRequestContext): Record<string, unknown> | unknown;
 export declare function extractRequestIdFromResponse(response: any): string | undefined;
 export { buildChatResponseFromResponses } from '../shared/responses-response-utils.js';

package/dist/conversion/responses/responses-openai-bridge.js

@@ -18,6 +18,7 @@ function isObject(v) {
 // --- Public bridge functions ---
 export function captureResponsesContext(payload, dto) {
     const preservedInput = cloneBridgeEntries(payload.input);
+    ensureResponsesApplyPatchArguments(preservedInput);
     ensureBridgeInstructions(payload);
     const context = {
         requestId: dto?.route?.requestId,
@@ -298,6 +299,76 @@ export function buildResponsesRequestFromChat(payload, ctx, extras) {
     ensureBridgeInstructions(out);
     return { request: out, originalSystemMessages };
 }
+export function ensureResponsesApplyPatchArguments(input) {
+    if (!Array.isArray(input) || !input.length) {
+        return;
+    }
+    for (const entry of input) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const type = typeof entry.type === 'string' ? entry.type.toLowerCase() : '';
+        if (type !== 'function_call')
+            continue;
+        const name = (typeof entry.name === 'string' && entry.name.trim()) ||
+            (entry.function && typeof entry.function === 'object' && typeof entry.function.name === 'string' && entry.function.name.trim()) ||
+            '';
+        if (name !== 'apply_patch')
+            continue;
+        let normalized;
+        try {
+            normalized = normalizeApplyPatchArguments(entry.arguments ?? entry.function?.arguments);
+        }
+        catch {
+            // best-effort: do not fail the whole request due to a malformed historical tool call
+            normalized = undefined;
+        }
+        if (normalized === undefined) {
+            continue;
+        }
+        entry.arguments = normalized;
+        if (entry.function && typeof entry.function === 'object') {
+            entry.function.arguments = normalized;
+        }
+    }
+}
+function normalizeApplyPatchArguments(source) {
+    let parsed;
+    if (typeof source === 'string' && source.trim()) {
+        try {
+            parsed = JSON.parse(source);
+        }
+        catch {
+            parsed = { patch: source };
+        }
+    }
+    else if (source && typeof source === 'object') {
+        parsed = { ...source };
+    }
+    else if (source === undefined) {
+        parsed = {};
+    }
+    else {
+        return typeof source === 'string' ? source : undefined;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return typeof source === 'string' ? source : undefined;
+    }
+    const patchText = typeof parsed.patch === 'string' && parsed.patch.trim().length
+        ? parsed.patch
+        : typeof parsed.input === 'string' && parsed.input.trim().length
+            ? parsed.input
+            : undefined;
+    if (patchText) {
+        parsed.patch = patchText;
+        parsed.input = patchText;
+    }
+    try {
+        return JSON.stringify(parsed);
+    }
+    catch {
+        return typeof source === 'string' ? source : undefined;
+    }
+}
 function readToolCallIdStyleFromContext(ctx) {
     if (!ctx) {
         return undefined;

package/dist/conversion/shared/tool-filter-pipeline.d.ts

@@ -0,0 +1,21 @@
+import { ToolFilterHints } from '../../filters/index.js';
+interface RequestFilterOptions {
+    entryEndpoint?: string;
+    requestId?: string;
+    model?: string;
+    profile?: string;
+    stream?: boolean;
+    toolFilterHints?: ToolFilterHints;
+    /**
+     * Optional raw payload snapshot for local tool governance (e.g. view_image exposure).
+     */
+    rawPayload?: Record<string, unknown>;
+}
+interface ResponseFilterOptions {
+    entryEndpoint?: string;
+    requestId?: string;
+    profile?: string;
+}
+export declare function runChatRequestToolFilters(chatRequest: any, options?: RequestFilterOptions): Promise<any>;
+export declare function runChatResponseToolFilters(chatJson: any, options?: ResponseFilterOptions): Promise<any>;
+export {};

package/dist/conversion/shared/tool-filter-pipeline.js

@@ -1,6 +1,30 @@
 import { FilterEngine } from '../../filters/index.js';
 import { loadFieldMapConfig } from '../../filters/utils/fieldmap-loader.js';
 import { createSnapshotWriter } from './snapshot-utils.js';
+const REQUEST_FILTER_STAGES = [
+    'request_pre',
+    'request_map',
+    'request_post',
+    'request_finalize'
+];
+const RESPONSE_FILTER_STAGES = [
+    'response_pre',
+    'response_map',
+    'response_post',
+    'response_finalize'
+];
+function assertStageCoverage(label, registeredStages, skeletonStages) {
+    const allowed = new Set(skeletonStages);
+    const uncovered = [];
+    for (const stage of registeredStages) {
+        if (!allowed.has(stage)) {
+            uncovered.push(stage);
+        }
+    }
+    if (uncovered.length) {
+        throw new Error(`[tool-filter-pipeline] ${label}: registered filter stage(s) not covered by skeleton: ${uncovered.join(', ')}`);
+    }
+}
 export async function runChatRequestToolFilters(chatRequest, options = {}) {
     const reqCtxBase = {
         requestId: options.requestId ?? `req_${Date.now()}`,
@@ -21,24 +45,30 @@ export async function runChatRequestToolFilters(chatRequest, options = {}) {
             return;
         snapshot(stage, payload);
     };
-    recordStage('req_process_tool_filters_input', chatRequest);
+    const preFiltered = applyLocalToolGovernance(chatRequest, options.rawPayload);
+    recordStage('req_process_tool_filters_input', preFiltered);
     const engine = new FilterEngine();
+    const registeredStages = new Set();
+    const register = (filter) => {
+        registeredStages.add(filter.stage);
+        engine.registerFilter(filter);
+    };
     const profile = (reqCtxBase.profile || '').toLowerCase();
     const endpoint = (reqCtxBase.endpoint || '').toLowerCase();
     const isAnthropic = profile === 'anthropic-messages' || endpoint.includes('/v1/messages');
     if (!isAnthropic) {
         try {
             const { RequestToolListFilter } = await import('../../filters/index.js');
-            engine.registerFilter(new RequestToolListFilter());
+            register(new RequestToolListFilter());
         }
         catch {
             /* optional */
         }
     }
     const { RequestToolCallsStringifyFilter, RequestToolChoicePolicyFilter } = await import('../../filters/index.js');
-    engine.registerFilter(new RequestToolCallsStringifyFilter());
+    register(new RequestToolCallsStringifyFilter());
     if (!isAnthropic) {
-        engine.registerFilter(new RequestToolChoicePolicyFilter());
+        register(new RequestToolChoicePolicyFilter());
     }
     try {
         const cfg = await loadFieldMapConfig('openai-openai.fieldmap.json');
@@ -52,15 +82,96 @@ export async function runChatRequestToolFilters(chatRequest, options = {}) {
         } })());
     }
     catch { /* ignore */ }
-    let staged = await engine.run('request_pre', chatRequest, reqCtxBase);
-    recordStage('req_process_tool_filters_request_pre', staged);
-    staged = await engine.run('request_map', staged, reqCtxBase);
-    recordStage('req_process_tool_filters_request_map', staged);
-    staged = await engine.run('request_post', staged, reqCtxBase);
-    recordStage('req_process_tool_filters_request_post', staged);
+    try {
+        const { RequestOpenAIToolsNormalizeFilter, ToolPostConstraintsFilter } = await import('../../filters/index.js');
+        register(new RequestOpenAIToolsNormalizeFilter());
+        register(new ToolPostConstraintsFilter('request_finalize'));
+    }
+    catch {
+        // optional; keep prior behavior when filter not available
+    }
+    assertStageCoverage('request', registeredStages, REQUEST_FILTER_STAGES);
+    let staged = preFiltered;
+    for (const stage of REQUEST_FILTER_STAGES) {
+        staged = await engine.run(stage, staged, reqCtxBase);
+        recordStage(`req_process_tool_filters_${stage}`, staged);
+    }
     recordStage('req_process_tool_filters_output', staged);
     return staged;
 }
+function applyLocalToolGovernance(chatRequest, rawPayload) {
+    if (!chatRequest || typeof chatRequest !== 'object') {
+        return chatRequest;
+    }
+    const messages = Array.isArray(chatRequest.messages) ? chatRequest.messages : undefined;
+    const tools = Array.isArray(chatRequest.tools) ? chatRequest.tools : undefined;
+    if (!tools || !tools.length) {
+        return chatRequest;
+    }
+    const hasImageHint = detectImageHint(messages, rawPayload);
+    if (hasImageHint) {
+        return chatRequest;
+    }
+    const filteredTools = tools.filter((tool) => {
+        if (!tool || typeof tool !== 'object')
+            return false;
+        const fn = tool.function;
+        if (!fn || typeof fn !== 'object')
+            return true;
+        const name = fn.name;
+        if (typeof name !== 'string')
+            return true;
+        return name.trim() !== 'view_image';
+    });
+    if (filteredTools.length === tools.length) {
+        return chatRequest;
+    }
+    return {
+        ...chatRequest,
+        tools: filteredTools
+    };
+}
+function detectImageHint(messages, rawPayload) {
+    const candidates = [];
+    const collect = (value) => {
+        if (typeof value === 'string' && value) {
+            candidates.push(value);
+        }
+    };
+    if (Array.isArray(messages)) {
+        for (const msg of messages) {
+            if (msg && typeof msg === 'object') {
+                const text = msg.content;
+                if (typeof text === 'string') {
+                    collect(text);
+                }
+                else if (Array.isArray(text)) {
+                    for (const part of text) {
+                        if (part && typeof part === 'object') {
+                            collect(part.text);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (rawPayload && typeof rawPayload === 'object') {
+        collect(rawPayload.content);
+    }
+    if (!candidates.length) {
+        return false;
+    }
+    const patterns = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg'];
+    for (const text of candidates) {
+        const lower = text.toLowerCase();
+        for (const ext of patterns) {
+            if (lower.includes(ext)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 export async function runChatResponseToolFilters(chatJson, options = {}) {
     const resCtxBase = {
         requestId: options.requestId ?? `req_${Date.now()}`,
@@ -81,20 +192,25 @@ export async function runChatResponseToolFilters(chatJson, options = {}) {
     };
     recordStage('resp_process_tool_filters_input', chatJson);
     const engine = new FilterEngine();
+    const registeredStages = new Set();
+    const register = (filter) => {
+        registeredStages.add(filter.stage);
+        engine.registerFilter(filter);
+    };
     const { ResponseToolTextCanonicalizeFilter, ResponseToolArgumentsStringifyFilter, ResponseFinishInvariantsFilter } = await import('../../filters/index.js');
-    engine.registerFilter(new ResponseToolTextCanonicalizeFilter());
+    register(new ResponseToolTextCanonicalizeFilter());
     try {
         const { ResponseToolArgumentsToonDecodeFilter, ResponseToolArgumentsBlacklistFilter, ResponseToolArgumentsSchemaConvergeFilter } = await import('../../filters/index.js');
-        engine.registerFilter(new ResponseToolArgumentsToonDecodeFilter());
+        register(new ResponseToolArgumentsToonDecodeFilter());
         try {
-            engine.registerFilter(new ResponseToolArgumentsSchemaConvergeFilter());
+            register(new ResponseToolArgumentsSchemaConvergeFilter());
         }
         catch { /* optional */ }
-        engine.registerFilter(new ResponseToolArgumentsBlacklistFilter());
+        register(new ResponseToolArgumentsBlacklistFilter());
     }
     catch { /* optional */ }
-    engine.registerFilter(new ResponseToolArgumentsStringifyFilter());
-    engine.registerFilter(new ResponseFinishInvariantsFilter());
+    register(new ResponseToolArgumentsStringifyFilter());
+    register(new ResponseFinishInvariantsFilter());
     try {
         const cfg = await loadFieldMapConfig('openai-openai.fieldmap.json');
         if (cfg)
@@ -107,12 +223,12 @@ export async function runChatResponseToolFilters(chatJson, options = {}) {
         } })());
     }
     catch { /* ignore */ }
-    let staged = await engine.run('response_pre', chatJson, resCtxBase);
-    recordStage('resp_process_tool_filters_response_pre', staged);
-    staged = await engine.run('response_map', staged, resCtxBase);
-    recordStage('resp_process_tool_filters_response_map', staged);
-    staged = await engine.run('response_post', staged, resCtxBase);
-    recordStage('resp_process_tool_filters_response_post', staged);
+    assertStageCoverage('response', registeredStages, RESPONSE_FILTER_STAGES);
+    let staged = chatJson;
+    for (const stage of RESPONSE_FILTER_STAGES) {
+        staged = await engine.run(stage, staged, resCtxBase);
+        recordStage(`resp_process_tool_filters_${stage}`, staged);
+    }
     recordStage('resp_process_tool_filters_output', staged);
     return staged;
 }

package/dist/conversion/shared/tool-governor.d.ts

@@ -0,0 +1,21 @@
+type Unknown = Record<string, unknown>;
+export interface ToolGovernanceOptions {
+    injectGuidance?: boolean;
+    snapshot?: {
+        enabled?: boolean;
+        endpoint?: string;
+        requestId?: string;
+        baseDir?: string;
+    };
+}
+export declare function processChatRequestTools(request: Unknown, opts?: ToolGovernanceOptions): Unknown;
+export declare function processChatResponseTools(resp: Unknown): Unknown;
+export interface GovernContext extends ToolGovernanceOptions {
+    phase: 'request' | 'response';
+    endpoint?: 'chat' | 'responses' | 'messages';
+    stream?: boolean;
+    produceRequiredAction?: boolean;
+    requestId?: string;
+}
+export declare function governTools(payload: Unknown, ctx: GovernContext): Unknown;
+export {};

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

@@ -40,6 +40,114 @@ function tryWriteSnapshot(options, stage, data) {
  * - Inject/Refine system tool guidance (idempotent)
  * - Canonicalize textual tool markup to tool_calls; set content=null when applicable
  */
+const IMAGE_EXT_RE = /\.(png|jpe?g|gif|webp|bmp|svg)(?:[?#].*)?$/i;
+function hasImageReference(messages) {
+    if (!Array.isArray(messages))
+        return false;
+    for (const entry of messages) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const content = entry.content;
+        if (!content)
+            continue;
+        if (Array.isArray(content)) {
+            if (content.some((part) => isImagePart(part)))
+                return true;
+        }
+        else if (isObject(content)) {
+            if (isImagePart(content))
+                return true;
+        }
+        else if (typeof content === 'string') {
+            if (stringHasImageLink(content))
+                return true;
+        }
+    }
+    return false;
+}
+function hasInputImage(entries) {
+    if (!Array.isArray(entries))
+        return false;
+    for (const entry of entries) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const type = String(entry.type || '').toLowerCase();
+        if (type.includes('image'))
+            return true;
+        const content = entry.content;
+        if (!content)
+            continue;
+        if (Array.isArray(content)) {
+            if (content.some((part) => isImagePart(part)))
+                return true;
+        }
+        else if (isObject(content)) {
+            if (isImagePart(content))
+                return true;
+        }
+    }
+    return false;
+}
+function attachmentsHaveImage(payload) {
+    const attachments = payload?.attachments;
+    if (!Array.isArray(attachments))
+        return false;
+    for (const attachment of attachments) {
+        if (!attachment || typeof attachment !== 'object')
+            continue;
+        const mime = typeof attachment.mime === 'string' ? attachment.mime.toLowerCase() : '';
+        if (mime.startsWith('image/'))
+            return true;
+        const name = typeof attachment.name === 'string' ? attachment.name : '';
+        if (IMAGE_EXT_RE.test(name))
+            return true;
+        const url = typeof attachment.url === 'string' ? attachment.url : '';
+        if (stringHasImageLink(url))
+            return true;
+    }
+    return false;
+}
+function stringHasImageLink(value) {
+    if (!value)
+        return false;
+    if (value.includes('cid:'))
+        return true;
+    if (IMAGE_EXT_RE.test(value))
+        return true;
+    const lowered = value.toLowerCase();
+    return lowered.includes('image://');
+}
+function isImagePart(part) {
+    if (!part || typeof part !== 'object')
+        return false;
+    const type = String(part.type || '').toLowerCase();
+    if (type.includes('image'))
+        return true;
+    const imageUrl = part.image_url || part.imageUrl;
+    if (typeof imageUrl === 'string')
+        return true;
+    if (isObject(imageUrl) && typeof imageUrl.url === 'string')
+        return true;
+    const url = part.url;
+    if (typeof url === 'string' && stringHasImageLink(url))
+        return true;
+    return false;
+}
+function shouldExposeViewImage(payload) {
+    if (hasImageReference(payload?.messages))
+        return true;
+    if (hasInputImage(payload?.input))
+        return true;
+    if (attachmentsHaveImage(payload))
+        return true;
+    return false;
+}
+function isViewImageTool(tool) {
+    if (!tool || typeof tool !== 'object')
+        return false;
+    const name = String(tool.name || tool?.function?.name || '').toLowerCase();
+    return name === 'view_image';
+}
 export function processChatRequestTools(request, opts) {
     const options = { ...(opts || {}) };
     if (!isObject(request))
@@ -48,8 +156,15 @@ export function processChatRequestTools(request, opts) {
     // tools 形状最小修复：为缺失 function.parameters 的工具补一个空对象，避免上游
     // Responses/OpenAI 校验 422（外部错误必须暴露，但这里属于规范化入口）。
     try {
-        const tools = Array.isArray(out?.tools) ? out.tools : [];
+        let tools = Array.isArray(out?.tools) ? out.tools : [];
         if (tools.length > 0) {
+            if (!shouldExposeViewImage(out)) {
+                const filtered = tools.filter((tool) => !isViewImageTool(tool));
+                if (filtered.length !== tools.length) {
+                    tools = filtered;
+                    out.tools = tools;
+                }
+            }
             for (const t of tools) {
                 if (!t || typeof t !== 'object')
                     continue;

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

@@ -8,6 +8,56 @@ export function stringifyArgs(args) {
         return String(args);
     }
 }
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function clonePlainObject(value) {
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return { ...value };
+    }
+}
+function asSchema(value) {
+    if (isPlainObject(value)) {
+        return clonePlainObject(value);
+    }
+    return undefined;
+}
+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 = {
+        type: 'string',
+        description: 'Unified diff patch body between *** Begin Patch/*** End Patch.'
+    };
+    if (!properties.patch || typeof properties.patch !== 'object') {
+        properties.patch = {
+            type: 'string',
+            description: 'Alias of input for backwards compatibility.'
+        };
+    }
+    schema.properties = properties;
+    const requiredList = Array.isArray(schema.required) ? schema.required.filter((entry) => typeof entry === 'string') : [];
+    if (!requiredList.includes('input')) {
+        requiredList.push('input');
+    }
+    schema.required = requiredList;
+    if (typeof schema.additionalProperties !== 'boolean') {
+        schema.additionalProperties = false;
+    }
+    return schema;
+}
+function enforceBuiltinToolSchema(name, candidate) {
+    const normalizedName = typeof name === 'string' ? name.trim().toLowerCase() : '';
+    if (normalizedName === 'apply_patch') {
+        const base = asSchema(candidate);
+        return ensureApplyPatchSchema(base);
+    }
+    return asSchema(candidate);
+}
 const DEFAULT_SANITIZER = (value) => {
     if (typeof value === 'string') {
         const trimmed = value.trim();
@@ -66,7 +116,7 @@ export function bridgeToolToChatDefinition(rawTool, options) {
         return null;
     }
     const description = resolveToolDescription(fnNode?.description ?? tool.description);
-    const parameters = resolveToolParameters(fnNode, tool);
+    const parameters = enforceBuiltinToolSchema(name, resolveToolParameters(fnNode, tool));
     const strict = resolveToolStrict(fnNode, tool);
     const rawType = typeof tool.type === 'string' && tool.type.trim().length ? tool.type.trim() : 'function';
     const normalizedType = rawType.toLowerCase() === 'custom' ? 'function' : rawType;
@@ -105,7 +155,7 @@ export function chatToolToBridgeDefinition(rawTool, options) {
         return null;
     }
     const description = resolveToolDescription(fnNode?.description);
-    const parameters = resolveToolParameters(fnNode, undefined);
+    const parameters = enforceBuiltinToolSchema(name, resolveToolParameters(fnNode, undefined));
     const strict = resolveToolStrict(fnNode, undefined);
     const normalizedType = typeof tool.type === 'string' && tool.type.trim().length ? tool.type.trim() : 'function';
     const responseShape = {

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

@@ -73,7 +73,7 @@ export class RequestOpenAIToolsNormalizeFilter {
                             delete dst.function.strict;
                     }
                     catch { /* ignore */ }
-                    // Switch schema for 'shell' at unified shaping point
+                    // Switch schema for specific built-in tools at unified shaping point
                     try {
                         const name = String(dst.function.name || '').toLowerCase();
                         if (name === 'shell') {
@@ -101,6 +101,25 @@ 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

@@ -63,6 +63,8 @@ function augmentApplyPatch(fn) {
     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/... 这样的相对路径，跨工作区时再使用绝对路径。',
         'Example:',
         '*** Begin Patch',
         '*** Update File: path/to/file.ts',
@@ -181,7 +183,9 @@ 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 text.',
+                        'All file paths must stay relative to the workspace root; never emit leading \'/\' or drive letters.',
+                        '所有文件路径都必须相对当前工作区根目录，禁止输出以 / 或盘符开头的绝对路径。'
                     ].join('\n');
                     copy.description = appendOnce(desc, guidance, marker);
                 }
@@ -216,7 +220,7 @@ export function buildSystemToolGuidance() {
     lines.push(bullet('function.arguments must be a single JSON string. / arguments 必须是单个 JSON 字符串。'));
     lines.push(bullet('shell: Place ALL intent into the command argv array only; do not invent extra keys. / shell 所有意图写入 command 数组，不要添加额外键名。'));
     lines.push(bullet('File writes are FORBIDDEN via shell (no redirection, no here-doc, no sed -i, no ed -s, no tee). Use apply_patch ONLY. / 通过 shell 写文件一律禁止（不得使用重定向、heredoc、sed -i、ed -s、tee）；必须使用 apply_patch。'));
-    lines.push(bullet('apply_patch: Provide a unified diff patch with *** Begin Patch/*** End Patch only. / 仅输出统一 diff 补丁。'));
+    lines.push(bullet('apply_patch: Provide a unified diff patch with *** Begin Patch/*** End Patch only, and keep file paths relative to the workspace (no leading / or drive letters). / 仅输出统一 diff 补丁，且文件路径必须是相对路径（禁止以 / 或盘符开头）。'));
     lines.push(bullet('apply_patch example / 示例：\n*** Begin Patch\n*** Update File: path/to/file.ts\n@@\n- old line\n+ new line\n*** End Patch'));
     lines.push(bullet('update_plan: Keep exactly one step in_progress; others pending/completed. / 仅一个 in_progress 步骤。'));
     lines.push(bullet('view_image: Path must be an image file (.png .jpg .jpeg .gif .webp .bmp .svg). / 仅图片路径。'));

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

@@ -0,0 +1,38 @@
+import { type RoutingDecision, type RoutingDiagnostics, type RouterMetadataInput, type VirtualRouterConfig, type TargetMetadata, type ProviderFailureEvent, type ProviderErrorEvent } from './types.js';
+import type { ProcessedRequest, StandardizedRequest } from '../../conversion/hub/types/standardized.js';
+export declare class VirtualRouterEngine {
+    private routing;
+    private readonly providerRegistry;
+    private readonly healthManager;
+    private loadBalancer;
+    private classifier;
+    private routeStats;
+    private readonly debug;
+    private healthConfig;
+    initialize(config: VirtualRouterConfig): void;
+    route(request: StandardizedRequest | ProcessedRequest, metadata: RouterMetadataInput): {
+        target: TargetMetadata;
+        decision: RoutingDecision;
+        diagnostics: RoutingDiagnostics;
+    };
+    handleProviderFailure(event: ProviderFailureEvent): void;
+    handleProviderError(event: ProviderErrorEvent): void;
+    getStatus(): {
+        routes: Record<string, {
+            providers: string[];
+            hits: number;
+            lastUsedProvider?: string;
+        }>;
+        health: import("./types.js").ProviderHealthState[];
+    };
+    private validateConfig;
+    private selectProvider;
+    private incrementRouteStat;
+    private providerHealthConfig;
+    private resolveStickyKey;
+    private mapProviderError;
+    private deriveReason;
+    private buildRouteCandidates;
+    private sortByPriority;
+    private routeWeight;
+}

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

@@ -11,11 +11,14 @@ export class VirtualRouterEngine {
     loadBalancer = new RouteLoadBalancer();
     classifier = new RoutingClassifier({});
     routeStats = new Map();
+    debug = console; // thin hook; host may monkey-patch for colored logging
+    healthConfig = null;
     initialize(config) {
         this.validateConfig(config);
         this.routing = config.routing;
         this.providerRegistry.load(config.providers);
         this.healthManager.configure(config.health);
+        this.healthConfig = config.health ?? null;
         this.healthManager.registerProviders(Object.keys(config.providers));
         this.loadBalancer = new RouteLoadBalancer(config.loadBalancing);
         this.classifier = new RoutingClassifier(config.classifier);
@@ -32,6 +35,7 @@ export class VirtualRouterEngine {
         const target = this.providerRegistry.buildTarget(selection.providerKey);
         this.healthManager.recordSuccess(selection.providerKey);
         this.incrementRouteStat(selection.routeUsed, selection.providerKey);
+        this.debug?.log?.('[virtual-router-hit]', selection.routeUsed, selection.providerKey, target.modelId || '');
         const didFallback = selection.routeUsed !== routeName || classification.fallback;
         return {
             target,
@@ -117,7 +121,7 @@ export class VirtualRouterEngine {
     }
     selectProvider(requestedRoute, metadata, classification) {
         const candidates = this.buildRouteCandidates(requestedRoute, classification.candidates);
-        const stickyKey = metadata.requestId;
+        const stickyKey = this.resolveStickyKey(metadata);
         const attempted = [];
         for (const routeName of candidates) {
             const pool = this.routing[routeName];
@@ -147,7 +151,20 @@ export class VirtualRouterEngine {
         stats.hits += 1;
         stats.lastProvider = providerKey;
     }
+    providerHealthConfig() {
+        return this.healthManager.getConfig();
+    }
+    resolveStickyKey(metadata) {
+        const resume = metadata.responsesResume;
+        if (resume && typeof resume.previousRequestId === 'string' && resume.previousRequestId.trim()) {
+            return resume.previousRequestId.trim();
+        }
+        return metadata.requestId;
+    }
     mapProviderError(event) {
+        // NOTE: mapProviderError is the only place where VirtualRouter translates providerErrorCenter
+        // events into health signals. Classification is intentionally coarse; upstream providers
+        // are expected to set event.recoverable explicitly when they know an error is safe to retry.
         if (!event || !event.runtime) {
             return null;
         }
@@ -162,15 +179,18 @@ export class VirtualRouterEngine {
         const code = event.code?.toUpperCase() ?? 'ERR_UNKNOWN';
         const stage = event.stage?.toLowerCase() ?? 'unknown';
         const recoverable = event.recoverable === true;
+        // 默认策略：只有显式可恢复的错误才视为非致命；其余一律按致命处理
         let fatal = !recoverable;
         let reason = this.deriveReason(code, stage, statusCode);
         let cooldownOverrideMs;
-        if (statusCode === 429 || code.includes('429') || recoverable) {
+        // 400 / 429 作为明确可恢复池：走限流通道，不做长期拉黑
+        if (statusCode === 429 || code.includes('429') || statusCode === 400 || code.includes('400')) {
             fatal = false;
             cooldownOverrideMs = Math.max(30_000, this.providerHealthConfig().cooldownMs);
             reason = 'rate_limit';
+            // 401 / 402 / 500 / 524 以及所有未被标记为可恢复的错误一律视为不可恢复
         }
-        else if (statusCode === 401 || statusCode === 403 || code.includes('AUTH')) {
+        else if (statusCode === 401 || statusCode === 402 || statusCode === 403 || code.includes('AUTH')) {
             fatal = true;
             cooldownOverrideMs = Math.max(10 * 60_000, this.providerHealthConfig().fatalCooldownMs ?? 10 * 60_000);
             reason = 'auth';
@@ -221,9 +241,6 @@ export class VirtualRouterEngine {
             return 'client_error';
         return 'unknown';
     }
-    providerHealthConfig() {
-        return this.healthManager.getConfig();
-    }
     buildRouteCandidates(requestedRoute, classificationCandidates) {
         const normalized = requestedRoute || DEFAULT_ROUTE;
         const baseList = classificationCandidates && classificationCandidates.length

package/dist/router/virtual-router/types.d.ts

@@ -96,6 +96,11 @@ export interface RouterMetadataInput {
     providerProtocol?: string;
     stage?: 'inbound' | 'outbound' | 'response';
     routeHint?: string;
+    responsesResume?: {
+        previousRequestId?: string;
+        restoredFromResponseId?: string;
+        [key: string]: unknown;
+    };
 }
 export interface RoutingFeatures {
     requestId: string;

package/dist/tools/tool-registry.js

@@ -95,11 +95,12 @@ export function validateToolCall(name, argsString) {
     const rawArgs = tryParseJson(typeof argsString === 'string' ? argsString : '{}');
     switch (normalizedName) {
         case 'apply_patch': {
-            const patch = asString(rawArgs.patch);
+            const input = asString(rawArgs.input);
+            const patch = asString(rawArgs.patch) ?? input;
             if (!patch) {
-                return { ok: false, reason: 'missing_patch' };
+                return { ok: false, reason: 'missing_input' };
             }
-            return { ok: true, normalizedArgs: toJson({ patch }) };
+            return { ok: true, normalizedArgs: toJson({ input: patch, patch }) };
         }
         case 'shell': {
             const rawCommand = rawArgs.command;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonstudio/llms",
-  "version": "0.6.054",
+  "version": "0.6.097",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",