@jsonstudio/rcc 0.89.552 → 0.89.611

package/node_modules/@jsonstudio/llms/dist/conversion/hub/pipeline/compat/compat-pipeline-executor.js

@@ -12,6 +12,7 @@ import { applyQwenRequestTransform, applyQwenResponseTransform } from '../../../
 import { extractGlmToolMarkup } from '../../../compat/actions/glm-tool-extraction.js';
 import { applyGlmWebSearchRequestTransform } from '../../../compat/actions/glm-web-search.js';
 import { applyGeminiWebSearchCompat } from '../../../compat/actions/gemini-web-search.js';
+import { applyIflowWebSearchRequestTransform } from '../../../compat/actions/iflow-web-search.js';
 import { applyGlmImageContentTransform } from '../../../compat/actions/glm-image-content.js';
 import { applyGlmVisionPromptTransform } from '../../../compat/actions/glm-vision-prompt.js';
 const RATE_LIMIT_ERROR = 'ERR_COMPAT_RATE_LIMIT_DETECTED';
@@ -171,6 +172,11 @@ function applyMapping(root, mapping, state) {
                 replaceRoot(root, applyGeminiWebSearchCompat(root, state.adapterContext));
             }
             break;
+        case 'iflow_web_search_request':
+            if (state.direction === 'request') {
+                replaceRoot(root, applyIflowWebSearchRequestTransform(root, state.adapterContext));
+            }
+            break;
         case 'glm_image_content':
             if (state.direction === 'request') {
                 replaceRoot(root, applyGlmImageContentTransform(root));

package/node_modules/@jsonstudio/llms/dist/conversion/hub/pipeline/compat/compat-types.d.ts

@@ -106,6 +106,8 @@ export type MappingInstruction = {
     action: 'glm_vision_prompt';
 } | {
     action: 'gemini_web_search_request';
+} | {
+    action: 'iflow_web_search_request';
 };
 export type FilterInstruction = {
     action: 'rate_limit_text';

package/node_modules/@jsonstudio/llms/dist/conversion/hub/pipeline/hub-pipeline.js

@@ -21,6 +21,7 @@ import { runReqProcessStage2RouteSelect } from './stages/req_process/req_process
 import { runReqOutboundStage1SemanticMap } from './stages/req_outbound/req_outbound_stage1_semantic_map/index.js';
 import { runReqOutboundStage2FormatBuild } from './stages/req_outbound/req_outbound_stage2_format_build/index.js';
 import { runReqOutboundStage3Compat } from './stages/req_outbound/req_outbound_stage3_compat/index.js';
+import { extractSessionIdentifiersFromMetadata } from './session-identifiers.js';
 export class HubPipeline {
     routerEngine;
     config;
@@ -123,6 +124,7 @@ export class HubPipeline {
         const stdMetadata = workingRequest?.metadata;
         const serverToolRequired = stdMetadata?.webSearchEnabled === true ||
             stdMetadata?.serverToolRequired === true;
+        const sessionIdentifiers = extractSessionIdentifiersFromMetadata(normalized.metadata);
         const metadataInput = {
             requestId: normalized.id,
             entryEndpoint: normalized.entryEndpoint,
@@ -133,7 +135,9 @@ export class HubPipeline {
             routeHint: normalized.routeHint,
             stage: normalized.stage,
             responsesResume: responsesResume,
-            ...(serverToolRequired ? { serverToolRequired: true } : {})
+            ...(serverToolRequired ? { serverToolRequired: true } : {}),
+            ...(sessionIdentifiers.sessionId ? { sessionId: sessionIdentifiers.sessionId } : {}),
+            ...(sessionIdentifiers.conversationId ? { conversationId: sessionIdentifiers.conversationId } : {})
         };
         const routing = runReqProcessStage2RouteSelect({
             routerEngine: this.routerEngine,

package/node_modules/@jsonstudio/llms/dist/conversion/hub/pipeline/session-identifiers.d.ts

@@ -0,0 +1,9 @@
+export interface SessionIdentifiers {
+    sessionId?: string;
+    conversationId?: string;
+}
+export declare function extractSessionIdentifiersFromMetadata(metadata: Record<string, unknown> | undefined): SessionIdentifiers;
+export declare function coerceClientHeaders(raw: unknown): Record<string, string> | undefined;
+export declare function pickHeader(headers: Record<string, string>, candidates: string[]): string | undefined;
+export declare function findHeaderValue(headers: Record<string, string>, target: string): string | undefined;
+export declare function normalizeHeaderKey(value: string): string;

package/node_modules/@jsonstudio/llms/dist/conversion/hub/pipeline/session-identifiers.js

@@ -0,0 +1,76 @@
+export function extractSessionIdentifiersFromMetadata(metadata) {
+    const directSession = normalizeIdentifier(metadata?.sessionId);
+    const directConversation = normalizeIdentifier(metadata?.conversationId);
+    const headers = coerceClientHeaders(metadata?.clientHeaders);
+    const sessionId = directSession ||
+        (headers ? pickHeader(headers, ['session_id', 'session-id', 'x-session-id', 'anthropic-session-id']) : undefined);
+    const conversationId = directConversation ||
+        (headers
+            ? pickHeader(headers, [
+                'conversation_id',
+                'conversation-id',
+                'x-conversation-id',
+                'anthropic-conversation-id',
+                'openai-conversation-id'
+            ])
+            : undefined);
+    return {
+        ...(sessionId ? { sessionId } : {}),
+        ...(conversationId ? { conversationId } : {})
+    };
+}
+export function coerceClientHeaders(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return undefined;
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === 'string' && value.trim()) {
+            normalized[key] = value;
+        }
+    }
+    return Object.keys(normalized).length ? normalized : undefined;
+}
+export function pickHeader(headers, candidates) {
+    for (const name of candidates) {
+        const value = findHeaderValue(headers, name);
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function findHeaderValue(headers, target) {
+    const lowered = typeof target === 'string' ? target.toLowerCase() : '';
+    if (!lowered) {
+        return undefined;
+    }
+    const normalizedTarget = normalizeHeaderKey(lowered);
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value !== 'string') {
+            continue;
+        }
+        const trimmed = value.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const loweredKey = key.toLowerCase();
+        if (loweredKey === lowered) {
+            return trimmed;
+        }
+        if (normalizeHeaderKey(loweredKey) === normalizedTarget) {
+            return trimmed;
+        }
+    }
+    return undefined;
+}
+export function normalizeHeaderKey(value) {
+    return value.replace(/[\s_-]+/g, '');
+}
+function normalizeIdentifier(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}

package/node_modules/@jsonstudio/llms/dist/conversion/hub/pipeline/stages/resp_inbound/resp_inbound_stage1_sse_decode/index.js

@@ -1,5 +1,17 @@
 import { defaultSseCodecRegistry } from '../../../../../../sse/index.js';
 import { recordStage } from '../../../stages/utils.js';
+import { ProviderProtocolError } from '../../../../../shared/errors.js';
+function resolveProviderType(protocol) {
+    if (protocol === 'openai-chat')
+        return 'openai';
+    if (protocol === 'openai-responses')
+        return 'responses';
+    if (protocol === 'anthropic-messages')
+        return 'anthropic';
+    if (protocol === 'gemini-chat')
+        return 'gemini';
+    return undefined;
+}
 export async function runRespInboundStage1SseDecode(options) {
     const stream = extractSseStream(options.payload);
     if (!stream) {
@@ -15,7 +27,15 @@ export async function runRespInboundStage1SseDecode(options) {
             reason: 'protocol_unsupported',
             protocol: options.providerProtocol
         });
-        throw new Error(`[resp_inbound_stage1_sse_decode] Protocol ${options.providerProtocol} does not support SSE decoding`);
+        throw new ProviderProtocolError(`[resp_inbound_stage1_sse_decode] Protocol ${options.providerProtocol} does not support SSE decoding`, {
+            code: 'SSE_DECODE_ERROR',
+            protocol: options.providerProtocol,
+            providerType: resolveProviderType(options.providerProtocol),
+            details: {
+                phase: 'resp_inbound_stage1_sse_decode',
+                reason: 'protocol_unsupported'
+            }
+        });
     }
     try {
         const codec = defaultSseCodecRegistry.get(options.providerProtocol);
@@ -38,7 +58,16 @@ export async function runRespInboundStage1SseDecode(options) {
             protocol: options.providerProtocol,
             error: message
         });
-        throw new Error(`[resp_inbound_stage1_sse_decode] Failed to decode SSE payload for protocol ${options.providerProtocol}: ${message}`);
+        throw new ProviderProtocolError(`[resp_inbound_stage1_sse_decode] Failed to decode SSE payload for protocol ${options.providerProtocol}: ${message}`, {
+            code: 'SSE_DECODE_ERROR',
+            protocol: options.providerProtocol,
+            providerType: resolveProviderType(options.providerProtocol),
+            details: {
+                phase: 'resp_inbound_stage1_sse_decode',
+                requestId: options.adapterContext.requestId,
+                message
+            }
+        });
     }
 }
 function supportsSseProtocol(protocol) {

package/node_modules/@jsonstudio/llms/dist/conversion/hub/process/chat-process.js

@@ -326,9 +326,9 @@ function maybeInjectWebSearchTool(request, metadata) {
     const injectPolicy = rawConfig.injectPolicy === 'always' || rawConfig.injectPolicy === 'selective'
         ? rawConfig.injectPolicy
         : 'selective';
+    const intent = detectWebSearchIntent(request);
     if (injectPolicy === 'selective') {
-        const hasExplicitIntent = detectWebSearchIntent(request);
-        if (!hasExplicitIntent) {
+        if (!intent.hasIntent) {
             // 当最近一条用户消息没有明显的“联网搜索”关键词时，
             // 如果上一轮 assistant 的工具调用已经属于搜索类（如 web_search），
             // 则仍然视为 web_search 续写场景，强制注入 web_search 工具，
@@ -351,9 +351,35 @@ function maybeInjectWebSearchTool(request, metadata) {
         return typeof fn?.name === 'string' && fn.name.trim() === 'web_search';
     });
     if (hasWebSearch) {
-        return request;
+        const nextMetadata = {
+            ...(request.metadata ?? {}),
+            webSearchEnabled: true
+        };
+        return {
+            ...request,
+            metadata: nextMetadata
+        };
+    }
+    let engines = rawConfig.engines.filter((engine) => typeof engine?.id === 'string' && !!engine.id.trim() && !engine.serverToolsDisabled);
+    // 当用户明确要求「谷歌搜索」时，只暴露 Gemini / Antigravity 类搜索后端：
+    // - providerKey 以 gemini-cli. 或 antigravity. 开头；
+    // - 或 engine id 中包含 "google"（向前兼容配置中用 id 标识 google 引擎的场景）。
+    if (intent.googlePreferred) {
+        const preferred = engines.filter((engine) => {
+            const id = engine.id.trim().toLowerCase();
+            const providerKey = (engine.providerKey || '').toLowerCase();
+            if (providerKey.startsWith('gemini-cli.') || providerKey.startsWith('antigravity.')) {
+                return true;
+            }
+            if (id.includes('google')) {
+                return true;
+            }
+            return false;
+        });
+        if (preferred.length > 0) {
+            engines = preferred;
+        }
     }
-    const engines = rawConfig.engines.filter((engine) => typeof engine?.id === 'string' && !!engine.id.trim() && !engine.serverToolsDisabled);
     if (!engines.length) {
         return request;
     }
@@ -418,7 +444,7 @@ function maybeInjectWebSearchTool(request, metadata) {
 function detectWebSearchIntent(request) {
     const messages = Array.isArray(request.messages) ? request.messages : [];
     if (!messages.length) {
-        return false;
+        return { hasIntent: false, googlePreferred: false };
     }
     // 从末尾向前找到最近一条 user 消息，忽略 tool / assistant 的工具调用轮次，
     // 以便在 Responses / 多轮工具调用场景下仍然根据“最近一条用户输入”判断意图。
@@ -431,7 +457,7 @@ function detectWebSearchIntent(request) {
         }
     }
     if (!lastUser) {
-        return false;
+        return { hasIntent: false, googlePreferred: false };
     }
     // 支持多模态 content：既可能是纯文本字符串，也可能是带 image_url 的分段数组。
     let content = '';
@@ -455,34 +481,72 @@ function detectWebSearchIntent(request) {
         content = texts.join('\n');
     }
     if (!content) {
-        return false;
+        return { hasIntent: false, googlePreferred: false };
+    }
+    // Hard 100% keywords (中文)：明确说明“谷歌搜索 / 谷歌一下 / 百度一下”均视为搜索意图。
+    // 其中“谷歌搜索 / 谷歌一下”会偏向 Google/Gemini 搜索后端。
+    const zh = content;
+    const hasGoogleExplicit = zh.includes('谷歌搜索') ||
+        zh.includes('谷歌一下');
+    const hasBaiduExplicit = zh.includes('百度一下');
+    if (hasGoogleExplicit || hasBaiduExplicit) {
+        // 谷歌 / 百度关键字都会优先尝试走“谷歌搜索”引擎；
+        // 只有在 Virtual Router 未配置任何谷歌相关 engine 时，才回退为普通联网搜索。
+        return {
+            hasIntent: true,
+            googlePreferred: true
+        };
     }
+    // English intent: simple substring match on lowercased text.
     const text = content.toLowerCase();
-    const keywords = [
-        // English
+    // 1) Direct patterns like "web search" / "internet search" / "/search".
+    const englishDirect = [
         'web search',
         'web_search',
         'websearch',
         'internet search',
         'search the web',
-        'online search',
-        'search online',
-        'search on the internet',
-        'search the internet',
         'web-search',
-        'online-search',
         'internet-search',
-        // Chinese
-        '联网搜索',
-        '网络搜索',
-        '上网搜索',
-        '网上搜索',
-        '网上查',
-        '网上查找',
-        '上网查',
-        '上网搜',
-        // Command-style
         '/search'
     ];
-    return keywords.some((keyword) => text.includes(keyword.toLowerCase()));
+    if (englishDirect.some((keyword) => text.includes(keyword))) {
+        return { hasIntent: true, googlePreferred: text.includes('google') };
+    }
+    // 2) Verb + noun combinations, similar to the Chinese rule:
+    //    - verb: search / find / look up / look for / google
+    //    - noun: web / internet / online / news / information / info / report / reports / article / articles
+    const verbTokensEn = ['search', 'find', 'look up', 'look for', 'google'];
+    const nounTokensEn = [
+        'web',
+        'internet',
+        'online',
+        'news',
+        'information',
+        'info',
+        'report',
+        'reports',
+        'article',
+        'articles'
+    ];
+    const hasVerbEn = verbTokensEn.some((token) => text.includes(token));
+    const hasNounEn = nounTokensEn.some((token) => text.includes(token));
+    if (hasVerbEn && hasNounEn) {
+        return { hasIntent: true, googlePreferred: text.includes('google') };
+    }
+    // 中文规则：
+    // 1. 只要文本中包含“上网”，直接命中（例如“帮我上网看看今天的新闻”）。
+    // 2. 否则，如果同时包含「搜索/查找/搜」中的任意一个动词 + 「网络/联网/新闻/信息/报道」中的任意一个名词，也判定为联网搜索意图。
+    const chineseText = content; // 中文大小写不敏感，这里直接用原文。
+    if (chineseText.includes('上网')) {
+        return { hasIntent: true, googlePreferred: false };
+    }
+    const verbTokens = ['搜索', '查找', '搜'];
+    const nounTokens = ['网络', '联网', '新闻', '信息', '报道'];
+    const hasVerb = verbTokens.some((token) => chineseText.includes(token));
+    const hasNoun = nounTokens.some((token) => chineseText.includes(token));
+    if (hasVerb && hasNoun) {
+        return { hasIntent: true, googlePreferred: false };
+    }
+    return { hasIntent: false, googlePreferred: false };
 }

package/node_modules/@jsonstudio/llms/dist/conversion/responses/responses-openai-bridge.js

@@ -3,6 +3,7 @@ import { evaluateResponsesHostPolicy } from './responses-host-policy.js';
 import { convertMessagesToBridgeInput, convertBridgeInputToChatMessages } from '../shared/bridge-message-utils.js';
 import { createToolCallIdTransformer, enforceToolCallIdStyle, resolveToolCallIdStyle, stripInternalToolingMetadata, sanitizeResponsesFunctionName } from '../shared/responses-tool-utils.js';
 import { mapBridgeToolsToChat, mapChatToolsToBridge } from '../shared/tool-mapping.js';
+import { ProviderProtocolError } from '../shared/errors.js';
 // --- Utilities (ported strictly) ---
 import { canonicalizeChatResponseTools } from '../shared/tool-canonicalizer.js';
 import { normalizeMessageReasoningTools } from '../shared/reasoning-tool-normalizer.js';
@@ -95,7 +96,16 @@ export function buildChatRequestFromResponses(payload, context) {
     // 不在 Responses 路径做工具治理；统一在 Chat 后半段处理
     // No system tips for MCP on OpenAI Responses path (avoid leaking tool names)
     if (!messages.length) {
-        throw new Error('Responses payload produced no chat messages');
+        throw new ProviderProtocolError('Responses payload produced no chat messages', {
+            code: 'MALFORMED_REQUEST',
+            protocol: 'openai-responses',
+            providerType: 'responses',
+            details: {
+                context: 'buildChatRequestFromResponses',
+                inputLength: Array.isArray(context.input) ? context.input.length : undefined,
+                requestId: context.requestId
+            }
+        });
     }
     // 如果只有 system 消息且无 user/assistant/tool，后续桥接 action 会从 instructions 注入兜底 user 消息
     const result = { model: payload.model, messages };
@@ -536,15 +546,76 @@ export function buildResponsesPayloadFromChat(payload, context) {
     if (response.object === 'response' && Array.isArray(response.output)) {
         return response;
     }
-    if (!Array.isArray(response.choices) || !response.choices.length) {
-        throw new Error('Responses bridge expects OpenAI Chat completion payload');
+    const hasChoicesArray = Array.isArray(response.choices);
+    const choicesLength = hasChoicesArray ? response.choices.length : 0;
+    // Graceful fallback for provider payloads that do not contain a valid
+    // ChatCompletion-style choices array (e.g. certain compat error envelopes).
+    if (!hasChoicesArray || choicesLength === 0) {
+        const rawStatus = response.status;
+        const statusCode = typeof rawStatus === 'string' && rawStatus.trim().length
+            ? rawStatus.trim()
+            : typeof rawStatus === 'number'
+                ? String(rawStatus)
+                : undefined;
+        const message = typeof response.msg === 'string' && response.msg.trim().length
+            ? response.msg.trim()
+            : typeof response.message === 'string' && response.message.trim().length
+                ? response.message.trim()
+                : 'Upstream returned non-standard Chat completion payload (missing choices).';
+        const out = {
+            id: response.id || `resp-${Date.now()}`,
+            object: 'response',
+            created_at: response.created_at || response.created || Math.floor(Date.now() / 1000),
+            model: response.model,
+            status: 'failed',
+            output: []
+        };
+        if (message) {
+            out.output_text = message;
+            out.error = {
+                type: 'provider_error',
+                code: statusCode,
+                message
+            };
+        }
+        if (context) {
+            for (const k of ['metadata', 'parallel_tool_calls', 'tool_choice', 'include']) {
+                if (context[k] !== undefined)
+                    out[k] = context[k];
+            }
+            if (!shouldStripHostManagedFields(context) && context.store !== undefined) {
+                out.store = context.store;
+            }
+        }
+        if (typeof response.request_id === 'string') {
+            out.request_id = response.request_id;
+        }
+        else if (typeof response.id === 'string') {
+            out.request_id = response.id;
+        }
+        else if (typeof context?.requestId === 'string') {
+            out.request_id = context.requestId;
+        }
+        if (out.metadata) {
+            stripInternalToolingMetadata(out.metadata);
+        }
+        return out;
     }
     const canonical = canonicalizeChatResponseTools(response);
     const choices = Array.isArray(canonical?.choices) ? canonical.choices : [];
     const primaryChoice = choices[0] && typeof choices[0] === 'object' ? choices[0] : undefined;
     const message = primaryChoice && typeof primaryChoice.message === 'object' ? primaryChoice.message : undefined;
     if (!message) {
-        throw new Error('Responses bridge could not locate assistant message in Chat completion');
+        throw new ProviderProtocolError('Responses bridge could not locate assistant message in Chat completion', {
+            code: 'MALFORMED_RESPONSE',
+            protocol: 'openai-chat',
+            providerType: 'openai',
+            details: {
+                context: 'buildResponsesPayloadFromChat',
+                choicesLength: choices.length,
+                requestId: context?.requestId
+            }
+        });
     }
     if (message) {
         try {

package/node_modules/@jsonstudio/llms/dist/conversion/shared/anthropic-message-utils.js

@@ -3,6 +3,7 @@ import { resolveBridgePolicy, resolvePolicyActions } from './bridge-policies.js'
 import { normalizeChatMessageContent } from './chat-output-normalizer.js';
 import { mapBridgeToolsToChat, mapChatToolsToBridge } from './tool-mapping.js';
 import { jsonClone } from '../hub/types/json.js';
+import { ProviderProtocolError } from './errors.js';
 function isObject(v) {
     return !!v && typeof v === 'object' && !Array.isArray(v);
 }
@@ -111,20 +112,39 @@ function extractToolResultSegment(entry) {
     }
     return String(entry);
 }
+function resolveProtocolErrorCode(context) {
+    const ctx = context.toLowerCase();
+    return ctx.includes('tool') ? 'TOOL_PROTOCOL_ERROR' : 'MALFORMED_REQUEST';
+}
 function requireTrimmedString(value, context) {
     if (typeof value !== 'string') {
-        throw new Error(`Anthropic bridge constraint violated: ${context} must be a string`);
+        throw new ProviderProtocolError(`Anthropic bridge constraint violated: ${context} must be a string`, {
+            code: resolveProtocolErrorCode(context),
+            protocol: 'anthropic-messages',
+            providerType: 'anthropic',
+            details: { context, actualType: typeof value }
+        });
     }
     const trimmed = value.trim();
     if (!trimmed.length) {
-        throw new Error(`Anthropic bridge constraint violated: ${context} must not be empty`);
+        throw new ProviderProtocolError(`Anthropic bridge constraint violated: ${context} must not be empty`, {
+            code: resolveProtocolErrorCode(context),
+            protocol: 'anthropic-messages',
+            providerType: 'anthropic',
+            details: { context }
+        });
     }
     return trimmed;
 }
 function requireSystemText(block, context) {
     const text = flattenAnthropicText(block).trim();
     if (!text) {
-        throw new Error(`Anthropic bridge constraint violated: ${context} must contain text`);
+        throw new ProviderProtocolError(`Anthropic bridge constraint violated: ${context} must contain text`, {
+            code: resolveProtocolErrorCode(context),
+            protocol: 'anthropic-messages',
+            providerType: 'anthropic',
+            details: { context }
+        });
     }
     return text;
 }
@@ -710,7 +730,12 @@ export function buildAnthropicRequestFromOpenAIChat(chatReq) {
                 pushSystemBlock(requireSystemText(val, 'top-level system'));
                 return;
             }
-            throw new Error('Anthropic bridge constraint violated: unsupported system payload type');
+            throw new ProviderProtocolError('Anthropic bridge constraint violated: unsupported system payload type', {
+                code: 'MALFORMED_REQUEST',
+                protocol: 'anthropic-messages',
+                providerType: 'anthropic',
+                details: { context: 'top-level system', actualType: typeof val }
+            });
         };
         ingestSystem(sys);
     }
@@ -730,7 +755,12 @@ export function buildAnthropicRequestFromOpenAIChat(chatReq) {
         const text = collectText(contentNode).trim();
         if (role === 'system') {
             if (!text) {
-                throw new Error('Anthropic bridge constraint violated: Chat system message must contain text');
+                throw new ProviderProtocolError('Anthropic bridge constraint violated: Chat system message must contain text', {
+                    code: 'MALFORMED_REQUEST',
+                    protocol: 'anthropic-messages',
+                    providerType: 'anthropic',
+                    details: { context: 'chat.system', original: contentNode }
+                });
             }
             pushSystemBlock(text);
             continue;
@@ -738,7 +768,12 @@ export function buildAnthropicRequestFromOpenAIChat(chatReq) {
         if (role === 'tool') {
             const toolCallId = requireTrimmedString(m.tool_call_id ?? m.call_id ?? m.tool_use_id ?? m.id, 'tool_result.tool_call_id');
             if (!knownToolCallIds.has(toolCallId)) {
-                throw new Error(`Anthropic bridge constraint violated: tool result ${toolCallId} has no matching tool call`);
+                throw new ProviderProtocolError(`Anthropic bridge constraint violated: tool result ${toolCallId} has no matching tool call`, {
+                    code: 'TOOL_PROTOCOL_ERROR',
+                    protocol: 'anthropic-messages',
+                    providerType: 'anthropic',
+                    details: { toolCallId }
+                });
             }
             const block = {
                 type: 'tool_result',

package/node_modules/@jsonstudio/llms/dist/conversion/shared/errors.d.ts

@@ -0,0 +1,20 @@
+export type ProviderProtocolErrorCode = 'TOOL_PROTOCOL_ERROR' | 'SSE_DECODE_ERROR' | 'MALFORMED_RESPONSE' | 'MALFORMED_REQUEST';
+export type ProviderErrorCategory = 'EXTERNAL_ERROR' | 'TOOL_ERROR' | 'INTERNAL_ERROR';
+export interface ProviderProtocolErrorOptions {
+    code: ProviderProtocolErrorCode;
+    protocol?: string;
+    providerType?: string;
+    /**
+     * 粗粒度错误类别；若未显式指定，将基于 code 自动推导。
+     */
+    category?: ProviderErrorCategory;
+    details?: Record<string, unknown>;
+}
+export declare class ProviderProtocolError extends Error {
+    readonly code: ProviderProtocolErrorCode;
+    readonly protocol?: string;
+    readonly providerType?: string;
+    readonly category: ProviderErrorCategory;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options: ProviderProtocolErrorOptions);
+}

package/node_modules/@jsonstudio/llms/dist/conversion/shared/errors.js

@@ -0,0 +1,28 @@
+function inferCategoryFromCode(code) {
+    switch (code) {
+        case 'TOOL_PROTOCOL_ERROR':
+            return 'TOOL_ERROR';
+        case 'SSE_DECODE_ERROR':
+        case 'MALFORMED_RESPONSE':
+        case 'MALFORMED_REQUEST':
+        default:
+            // 默认视为外部协议/载荷问题；真正的内部错误由上层使用 INTERNAL_ERROR 显式标记。
+            return 'EXTERNAL_ERROR';
+    }
+}
+export class ProviderProtocolError extends Error {
+    code;
+    protocol;
+    providerType;
+    category;
+    details;
+    constructor(message, options) {
+        super(message);
+        this.name = 'ProviderProtocolError';
+        this.code = options.code;
+        this.protocol = options.protocol;
+        this.providerType = options.providerType;
+        this.category = options.category ?? inferCategoryFromCode(options.code);
+        this.details = options.details;
+    }
+}

package/node_modules/@jsonstudio/llms/dist/conversion/shared/responses-conversation-store.js

@@ -1,3 +1,4 @@
+import { ProviderProtocolError } from './errors.js';
 const TTL_MS = 1000 * 60 * 30; // 30min
 function cloneDeep(value) {
     try {
@@ -205,16 +206,42 @@ class ResponsesConversationStore {
     }
     resumeConversation(responseId, submitPayload, options) {
         if (typeof responseId !== 'string' || !responseId.trim()) {
-            throw new Error('Responses conversation requires valid response_id');
+            throw new ProviderProtocolError('Responses conversation requires valid response_id', {
+                code: 'MALFORMED_REQUEST',
+                protocol: 'openai-responses',
+                providerType: 'responses',
+                details: {
+                    context: 'responses-conversation-store.resumeConversation',
+                    reason: 'missing_or_empty_response_id'
+                }
+            });
         }
         this.prune();
         const entry = this.responseIndex.get(responseId);
         if (!entry) {
-            throw new Error('Responses conversation expired or not found');
+            throw new ProviderProtocolError('Responses conversation expired or not found', {
+                code: 'MALFORMED_REQUEST',
+                protocol: 'openai-responses',
+                providerType: 'responses',
+                details: {
+                    context: 'responses-conversation-store.resumeConversation',
+                    reason: 'expired_or_unknown_response_id',
+                    responseId
+                }
+            });
         }
         const toolOutputs = Array.isArray(submitPayload.tool_outputs) ? submitPayload.tool_outputs : [];
         if (!toolOutputs.length) {
-            throw new Error('tool_outputs array is required when submitting Responses tool results');
+            throw new ProviderProtocolError('tool_outputs array is required when submitting Responses tool results', {
+                code: 'MALFORMED_REQUEST',
+                protocol: 'openai-responses',
+                providerType: 'responses',
+                details: {
+                    context: 'responses-conversation-store.resumeConversation',
+                    reason: 'missing_tool_outputs',
+                    responseId
+                }
+            });
         }
         const mergedInput = coerceInputArray(entry.input);
         const normalizedOutputs = normalizeSubmittedToolOutputs(toolOutputs);