@jsonstudio/llms 0.6.1172 → 0.6.1397

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

@@ -1,8 +1,11 @@
 import { runChatRequestToolFilters } from '../../shared/tool-filter-pipeline.js';
 import { ToolGovernanceEngine } from '../tool-governance/index.js';
+import { readRuntimeMetadata } from '../../shared/runtime-metadata.js';
 import { ensureApplyPatchSchema } from '../../shared/tool-mapping.js';
 import { normalizeApplyPatchToolCallsOnRequest } from '../../shared/tool-governor.js';
-import { clearClockSession, normalizeClockConfig, reserveDueTasksForRequest, startClockDaemonIfNeeded } from '../../../servertool/clock/task-store.js';
+import { clearClockSession, resolveClockConfig, reserveDueTasksForRequest, startClockDaemonIfNeeded } from '../../../servertool/clock/task-store.js';
+import { logClock } from '../../../servertool/clock/log.js';
+import { clearPendingServerToolInjection, loadPendingServerToolInjection } from '../../../servertool/pending-session.js';
 import { isJsonObject } from '../types/json.js';
 import { applyHubOperations } from '../ops/operations.js';
 const toolGovernanceEngine = new ToolGovernanceEngine();
@@ -83,6 +86,9 @@ async function applyRequestToolGovernance(request, context) {
         messages: stripHistoricalImageAttachments(merged.messages)
     };
     merged = normalizeApplyPatchToolCallsOnRequest(merged);
+    // Mixed-tools support: if previous response executed servertools alongside client tools,
+    // inject servertool tool_call + tool_result messages after the client's tool results on next request.
+    merged = await maybeInjectPendingServerToolResultsAfterClientTools(merged, metadata);
     if (containsImageAttachment(merged.messages)) {
         if (!merged.metadata) {
             merged.metadata = {
@@ -106,7 +112,7 @@ async function applyRequestToolGovernance(request, context) {
     // Server-side web_search tool injection (config-driven, best-effort).
     merged = applyHubOperations(merged, buildWebSearchOperations(merged, metadata));
     // Server-side clock tool + scheduled reminders injection (config-driven, best-effort).
-    merged = applyHubOperations(merged, buildClockOperations(metadata));
+    merged = applyHubOperations(merged, buildClockOperations(merged, metadata));
     merged = await maybeInjectClockRemindersAndApplyDirectives(merged, metadata, context.requestId);
     const { request: sanitized, summary } = toolGovernanceEngine.governRequest(merged, providerProtocol);
     if (summary.applied) {
@@ -118,7 +124,191 @@ async function applyRequestToolGovernance(request, context) {
             }
         };
     }
-    return sanitized;
+    return pruneUndeclaredToolHistory(sanitized);
+}
+function resolveSessionIdForPending(metadata, request) {
+    const candidate = readString(metadata.sessionId) ?? readString(request.metadata?.sessionId);
+    return candidate && candidate.trim() ? candidate.trim() : null;
+}
+function pruneUndeclaredToolHistory(request) {
+    const tools = Array.isArray(request.tools) ? request.tools : [];
+    const allowedToolNames = new Set();
+    for (const tool of tools) {
+        const name = tool && typeof tool === 'object' && tool.function && typeof tool.function.name === 'string'
+            ? String(tool.function.name).trim()
+            : '';
+        if (name) {
+            allowedToolNames.add(name);
+        }
+    }
+    // If no tools are declared, do not carry any tool calls/results in history.
+    const hasAnyTools = allowedToolNames.size > 0;
+    let prunedToolCalls = 0;
+    let prunedToolResults = 0;
+    const prunedToolNames = new Set();
+    const keptToolCallIds = new Set();
+    const nextMessages = [];
+    for (const msg of request.messages) {
+        if (!msg || typeof msg !== 'object')
+            continue;
+        if (msg.role === 'assistant' && Array.isArray(msg.tool_calls) && msg.tool_calls.length) {
+            if (!hasAnyTools) {
+                prunedToolCalls += msg.tool_calls.length;
+                for (const tc of msg.tool_calls) {
+                    const n = tc && tc.function && typeof tc.function.name === 'string' ? tc.function.name.trim() : '';
+                    if (n)
+                        prunedToolNames.add(n);
+                }
+                // Drop tool_calls when no tools are declared.
+                const keptContent = msg.content;
+                const hasContent = typeof keptContent === 'string'
+                    ? keptContent.trim().length > 0
+                    : Array.isArray(keptContent)
+                        ? keptContent.length > 0
+                        : false;
+                if (hasContent) {
+                    nextMessages.push({ ...msg, tool_calls: [] });
+                }
+                continue;
+            }
+            const keptCalls = [];
+            for (const tc of msg.tool_calls) {
+                if (!tc || typeof tc !== 'object')
+                    continue;
+                const name = tc.function && typeof tc.function.name === 'string' ? tc.function.name.trim() : '';
+                if (!name || !allowedToolNames.has(name)) {
+                    prunedToolCalls += 1;
+                    if (name)
+                        prunedToolNames.add(name);
+                    continue;
+                }
+                keptCalls.push(tc);
+                if (typeof tc.id === 'string' && tc.id.trim()) {
+                    keptToolCallIds.add(tc.id.trim());
+                }
+            }
+            const keptContent = msg.content;
+            const hasContent = typeof keptContent === 'string'
+                ? keptContent.trim().length > 0
+                : Array.isArray(keptContent)
+                    ? keptContent.length > 0
+                    : false;
+            if (!hasContent && keptCalls.length === 0) {
+                continue;
+            }
+            if (keptCalls.length === msg.tool_calls.length) {
+                nextMessages.push(msg);
+            }
+            else {
+                nextMessages.push({ ...msg, tool_calls: keptCalls.length ? keptCalls : undefined });
+            }
+            continue;
+        }
+        if (msg.role === 'tool') {
+            const name = typeof msg.name === 'string' ? msg.name.trim() : '';
+            const toolCallId = typeof msg.tool_call_id === 'string' ? msg.tool_call_id.trim() : '';
+            if (!hasAnyTools) {
+                prunedToolResults += 1;
+                if (name)
+                    prunedToolNames.add(name);
+                continue;
+            }
+            if (name && !allowedToolNames.has(name)) {
+                prunedToolResults += 1;
+                prunedToolNames.add(name);
+                continue;
+            }
+            // If the result references a tool_call_id that no longer exists, drop it to avoid
+            // provider-side strict pairing errors (Gemini/Anthropic tool pairing).
+            if (toolCallId && !keptToolCallIds.has(toolCallId)) {
+                prunedToolResults += 1;
+                if (name)
+                    prunedToolNames.add(name);
+                continue;
+            }
+            nextMessages.push(msg);
+            continue;
+        }
+        nextMessages.push(msg);
+    }
+    if (prunedToolCalls === 0 && prunedToolResults === 0) {
+        return request;
+    }
+    return {
+        ...request,
+        messages: nextMessages,
+        metadata: {
+            ...request.metadata,
+            toolHistoryPrune: {
+                prunedToolCalls,
+                prunedToolResults,
+                prunedToolNames: Array.from(prunedToolNames).sort()
+            }
+        }
+    };
+}
+function extractToolCallIdsFromToolMessages(messages) {
+    const ids = new Set();
+    for (const msg of messages) {
+        if (!msg || typeof msg !== 'object')
+            continue;
+        if (msg.role !== 'tool')
+            continue;
+        const toolCallId = typeof msg.tool_call_id === 'string'
+            ? String(msg.tool_call_id).trim()
+            : typeof msg.toolCallId === 'string'
+                ? String(msg.toolCallId).trim()
+                : '';
+        if (toolCallId)
+            ids.add(toolCallId);
+    }
+    return ids;
+}
+function findLastToolMessageIndex(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const msg = messages[i];
+        if (msg && typeof msg === 'object' && msg.role === 'tool') {
+            return i;
+        }
+    }
+    return -1;
+}
+async function maybeInjectPendingServerToolResultsAfterClientTools(request, metadata) {
+    const sessionId = resolveSessionIdForPending(metadata, request);
+    if (!sessionId) {
+        return request;
+    }
+    const pending = await loadPendingServerToolInjection(sessionId);
+    if (!pending) {
+        return request;
+    }
+    const afterIds = Array.isArray(pending.afterToolCallIds) ? pending.afterToolCallIds : [];
+    if (!afterIds.length) {
+        return request;
+    }
+    const messages = Array.isArray(request.messages) ? request.messages : [];
+    const toolIds = extractToolCallIdsFromToolMessages(messages);
+    const ready = afterIds.every((id) => toolIds.has(id));
+    if (!ready) {
+        return request;
+    }
+    const insertAt = findLastToolMessageIndex(messages);
+    if (insertAt < 0) {
+        return request;
+    }
+    const inject = Array.isArray(pending.messages) ? pending.messages : [];
+    if (!inject.length) {
+        return request;
+    }
+    const nextMessages = messages.slice();
+    nextMessages.splice(insertAt + 1, 0, ...inject);
+    try {
+        await clearPendingServerToolInjection(sessionId);
+    }
+    catch {
+        // best-effort
+    }
+    return { ...request, messages: nextMessages };
 }
 function buildProcessedRequest(request) {
     const timestamp = Date.now();
@@ -423,13 +613,38 @@ function buildToolChoiceOperations(toolChoice) {
         }
     ];
 }
+function isGeminiAntigravityLike(metadata) {
+    const providerProtocol = readString(metadata.providerProtocol) ?? readString(metadata.provider) ?? '';
+    if (!providerProtocol.toLowerCase().includes('gemini')) {
+        return false;
+    }
+    const rt = readRuntimeMetadata(metadata);
+    const providerId = readString(metadata.providerId) ??
+        readString(rt?.providerId) ??
+        '';
+    const providerKey = readString(metadata.providerKey) ??
+        readString(rt?.providerKey) ??
+        '';
+    const loweredId = providerId.toLowerCase();
+    const loweredKey = providerKey.toLowerCase();
+    return (loweredId.includes('antigravity') ||
+        loweredId === 'gemini-cli' ||
+        loweredKey.startsWith('antigravity.') ||
+        loweredKey.startsWith('gemini-cli.'));
+}
 function buildWebSearchOperations(request, metadata) {
+    const rt = readRuntimeMetadata(metadata);
+    // gcli2api-style: do not force-inject server-side web_search tools for Gemini/Antigravity.
+    // Tools must be present only when supplied by the client payload/config, not auto-appended.
+    if (isGeminiAntigravityLike(metadata)) {
+        return [];
+    }
     // ServerTool 二/三跳（serverToolFollowup=true）不再注入 web_search 工具，
     // 以避免在 web_search 流程内部形成循环命中。
-    if (metadata.serverToolFollowup === true) {
+    if (rt?.serverToolFollowup === true) {
         return [];
     }
-    const rawConfig = metadata.webSearch;
+    const rawConfig = rt?.webSearch;
     if (!rawConfig || !Array.isArray(rawConfig.engines) || rawConfig.engines.length === 0) {
         return [];
     }
@@ -535,12 +750,20 @@ function buildWebSearchOperations(request, metadata) {
     });
     return ops;
 }
-function buildClockOperations(metadata) {
-    const rawConfig = metadata.clock;
-    const clockConfig = normalizeClockConfig(rawConfig);
+function buildClockOperations(request, metadata) {
+    const rt = readRuntimeMetadata(metadata);
+    // gcli2api-style: do not force-inject server-side clock tools for Gemini/Antigravity.
+    if (isGeminiAntigravityLike(metadata)) {
+        return [];
+    }
+    const rawConfig = rt?.clock;
+    const clockConfig = resolveClockConfig(rawConfig);
     if (!clockConfig) {
         return [];
     }
+    const sessionId = readString(metadata.sessionId);
+    const hasSessionId = Boolean(sessionId && sessionId.trim());
+    logClock('inject_schema', { hasSessionId });
     const parameters = {
         type: 'object',
         properties: {
@@ -568,12 +791,13 @@ function buildClockOperations(metadata) {
                             description: 'Optional suggested tool name (hint only).'
                         },
                         arguments: {
-                            type: 'object',
-                            description: 'Optional suggested tool arguments (hint only).',
-                            additionalProperties: true
+                            type: 'string',
+                            description: 'Optional suggested tool arguments as a JSON string (hint only). Use "{}" when unsure.'
                         }
                     },
-                    required: ['dueAt', 'task'],
+                    // For strict tool schemas (OpenAI Responses), required must include every key in properties.
+                    // We keep tool/arguments as hints but allow empty string when not used.
+                    required: ['dueAt', 'task', 'tool', 'arguments'],
                     additionalProperties: false
                 }
             },
@@ -582,7 +806,9 @@ function buildClockOperations(metadata) {
                 description: 'For cancel: taskId to remove.'
             }
         },
-        required: ['action'],
+        // For strict tool schemas (OpenAI Responses), required must include every key in properties.
+        // Fields unused for certain actions can be set to empty string / empty list.
+        required: ['action', 'items', 'taskId'],
         additionalProperties: false
     };
     const clockTool = {
@@ -595,7 +821,10 @@ function buildClockOperations(metadata) {
         }
     };
     return [
-        { op: 'set_request_metadata_fields', fields: { clockEnabled: true, serverToolRequired: true } },
+        {
+            op: 'set_request_metadata_fields',
+            fields: { clockEnabled: true, ...(hasSessionId ? { serverToolRequired: true } : {}) }
+        },
         { op: 'append_tool_if_missing', toolName: 'clock', tool: clockTool }
     ];
 }
@@ -657,8 +886,13 @@ function findLastUserMessageIndex(messages) {
     return -1;
 }
 async function maybeInjectClockRemindersAndApplyDirectives(request, metadata, requestId) {
-    const rawConfig = metadata.clock;
-    const clockConfig = normalizeClockConfig(rawConfig);
+    const rt = readRuntimeMetadata(metadata);
+    // Do not inject reminders or apply clock directives during internal servertool followup hops.
+    if (rt?.serverToolFollowup === true) {
+        return request;
+    }
+    const rawConfig = rt?.clock;
+    const clockConfig = resolveClockConfig(rawConfig);
     if (!clockConfig) {
         return request;
     }
@@ -687,6 +921,7 @@ async function maybeInjectClockRemindersAndApplyDirectives(request, metadata, re
         if (sessionId) {
             try {
                 await clearClockSession(sessionId);
+                logClock('cleared', { sessionId });
             }
             catch {
                 // best-effort: user directive should not crash request
@@ -707,6 +942,11 @@ async function maybeInjectClockRemindersAndApplyDirectives(request, metadata, re
         if (!reservation || typeof injectText !== 'string' || !injectText.trim()) {
             return request;
         }
+        logClock('inject_due', {
+            sessionId,
+            reservationId: reservation.reservationId,
+            taskIds: Array.isArray(reservation.taskIds) ? reservation.taskIds.length : 0
+        });
         const baseMetadata = request.metadata && typeof request.metadata === 'object'
             ? request.metadata
             : {

package/dist/conversion/hub/response/provider-response.d.ts

@@ -10,6 +10,14 @@ export interface ProviderResponseConversionOptions {
     context: AdapterContext;
     entryEndpoint: string;
     wantsStream: boolean;
+    /**
+     * Canonical chat semantics from the request-side chat_process output.
+     * This is the only allowed carrier for mappable cross-protocol semantics
+     * (tool alias maps, client tool schemas, responses resume, etc.).
+     *
+     * Must not be stuffed into metadata/AdapterContext.
+     */
+    requestSemantics?: JsonObject;
     stageRecorder?: StageRecorder;
     providerInvoker?: ProviderInvoker;
     /**

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

@@ -8,12 +8,15 @@ import { OpenAIChatResponseMapper, ResponsesResponseMapper, AnthropicResponseMap
 import { runRespInboundStage1SseDecode } from '../pipeline/stages/resp_inbound/resp_inbound_stage1_sse_decode/index.js';
 import { runRespInboundStage2FormatParse } from '../pipeline/stages/resp_inbound/resp_inbound_stage2_format_parse/index.js';
 import { runRespInboundStage3SemanticMap } from '../pipeline/stages/resp_inbound/resp_inbound_stage3_semantic_map/index.js';
+import { runRespInboundStage3ThoughtSignatureCapture } from '../pipeline/stages/resp_inbound/resp_inbound_stage3_thought_signature_capture/index.js';
 import { runRespInboundStageCompatResponse } from '../pipeline/stages/req_outbound/req_outbound_stage3_compat/index.js';
 import { runRespProcessStage1ToolGovernance } from '../pipeline/stages/resp_process/resp_process_stage1_tool_governance/index.js';
 import { runRespProcessStage2Finalize } from '../pipeline/stages/resp_process/resp_process_stage2_finalize/index.js';
 import { runRespOutboundStage1ClientRemap } from '../pipeline/stages/resp_outbound/resp_outbound_stage1_client_remap/index.js';
 import { runRespOutboundStage2SseStream } from '../pipeline/stages/resp_outbound/resp_outbound_stage2_sse_stream/index.js';
 import { recordResponsesResponse } from '../../shared/responses-conversation-store.js';
+import { ProviderProtocolError } from '../../shared/errors.js';
+import { readRuntimeMetadata } from '../../shared/runtime-metadata.js';
 import { runServerToolOrchestration } from '../../../servertool/engine.js';
 import { commitClockReservation, normalizeClockConfig } from '../../../servertool/clock/task-store.js';
 const PROVIDER_RESPONSE_REGISTRY = {
@@ -35,7 +38,8 @@ const PROVIDER_RESPONSE_REGISTRY = {
     }
 };
 function isServerToolFollowup(context) {
-    const raw = context.serverToolFollowup;
+    const rt = readRuntimeMetadata(context);
+    const raw = rt?.serverToolFollowup;
     if (raw === true) {
         return true;
     }
@@ -85,7 +89,8 @@ function coerceClockReservation(value) {
 }
 async function maybeCommitClockReservationFromContext(context) {
     try {
-        const clockConfig = normalizeClockConfig(context.clock);
+        const rt = readRuntimeMetadata(context);
+        const clockConfig = normalizeClockConfig(rt?.clock);
         if (!clockConfig) {
             return;
         }
@@ -114,6 +119,42 @@ function detectProviderResponseShape(payload) {
         return 'gemini-chat';
     return 'unknown';
 }
+function isCanonicalChatCompletion(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        return false;
+    }
+    const obj = payload;
+    const choices = Array.isArray(obj.choices) ? obj.choices : [];
+    if (!choices.length)
+        return false;
+    const first = choices[0] && typeof choices[0] === 'object' && !Array.isArray(choices[0]) ? choices[0] : null;
+    if (!first)
+        return false;
+    const msg = first.message;
+    return Boolean(msg && typeof msg === 'object' && !Array.isArray(msg));
+}
+async function coerceClientPayloadToCanonicalChatCompletionOrThrow(options) {
+    if (isCanonicalChatCompletion(options.payload)) {
+        return options.payload;
+    }
+    const detected = detectProviderResponseShape(options.payload);
+    if (detected === 'unknown') {
+        throw new ProviderProtocolError(`[hub_response] Non-canonical response payload at ${options.scope}`, {
+            code: 'MALFORMED_RESPONSE',
+            details: { detected }
+        });
+    }
+    const plan = PROVIDER_RESPONSE_REGISTRY[detected];
+    const mapper = plan.createMapper();
+    const coerced = await mapper.toChatCompletion({ payload: options.payload }, options.adapterContext, { requestSemantics: options.requestSemantics });
+    if (isCanonicalChatCompletion(coerced)) {
+        return coerced;
+    }
+    throw new ProviderProtocolError(`[hub_response] Failed to canonicalize response payload at ${options.scope}`, {
+        code: 'MALFORMED_RESPONSE',
+        details: { detected }
+    });
+}
 function summarizeToolCallsFromProviderResponse(payload) {
     try {
         if (!isJsonRecord(payload))
@@ -169,6 +210,7 @@ function stripInternalPolicyDebugFields(payload) {
     delete target.__responses_reasoning;
     delete target.__responses_payload_snapshot;
     delete target.__responses_passthrough;
+    delete target.anthropicToolNameMap;
 }
 function supportsSseProtocol(protocol) {
     return protocol === 'openai-chat' || protocol === 'openai-responses' || protocol === 'anthropic-messages' || protocol === 'gemini-chat';
@@ -212,23 +254,20 @@ function resolveChatReasoningMode(_entryEndpoint) {
     return 'keep';
 }
 export async function convertProviderResponse(options) {
-    const clientProtocol = resolveClientProtocol(options.entryEndpoint);
+    const isFollowup = isServerToolFollowup(options.context);
+    // ServerTool followups are internal hops. They must return canonical OpenAI-chat-like payloads
+    // to re-enter the hub chat process deterministically (tools harvesting, governance, etc.).
+    // Client protocol remapping happens only on the outermost request.
+    const clientProtocol = isFollowup ? 'openai-chat' : resolveClientProtocol(options.entryEndpoint);
     const hasServerToolSupport = Boolean(options.providerInvoker) || Boolean(options.reenterPipeline);
-    // 是否跳过 ServerTool 编排：
-    // - 仅在当前 Provider 完全不支持 ServerTool（没有 invoker/reenterPipeline）时跳过；
-    // - 对于 serverToolFollowup=true 的二/三跳请求，也允许再次进入 ServerTool 流程，
-    //   由具体 handler（例如 gemini_empty_reply_continue / iflow_model_error_retry 等）
-    //   自行通过 serverToolFollowup 标记决定是否生效。
-    const skipServerTools = !hasServerToolSupport;
-    // 对于由 server-side 工具触发的内部跳转（二跳/三跳），统一禁用 SSE 聚合输出，
-    // 始终返回完整的 ChatCompletion JSON，便于在 llms 内部直接解析，而不是拿到
-    // __sse_responses 可读流。
-    const wantsStream = isServerToolFollowup(options.context) ? false : options.wantsStream;
+    // ServerTool followup hop: always return a fully materialized ChatCompletion JSON (non-SSE).
+    // This is an internal hop used by the servertool engine, and it must be deterministic.
+    const wantsStream = isFollowup ? false : options.wantsStream;
     try {
         // eslint-disable-next-line no-console
         console.log(`\x1b[38;5;33m[servertool][orchestrator][debug] requestId=${options.context.requestId} ` +
             `protocol=${options.providerProtocol} endpoint=${options.entryEndpoint} ` +
-            `skipServerTools=${skipServerTools} hasInvoker=${Boolean(options.providerInvoker)} ` +
+            `serverTools=${hasServerToolSupport} hasInvoker=${Boolean(options.providerInvoker)} ` +
             `hasReenter=${Boolean(options.reenterPipeline)}\x1b[0m`);
     }
     catch {
@@ -255,23 +294,17 @@ export async function convertProviderResponse(options) {
         formatAdapter,
         stageRecorder: options.stageRecorder
     });
-    if (options.providerProtocol === 'openai-responses') {
-        try {
-            recordResponsesResponse({
-                requestId: options.context.requestId,
-                response: formatEnvelope.payload
-            });
-        }
-        catch {
-            // ignore conversation capture errors
-        }
-    }
     formatEnvelope.payload = runRespInboundStageCompatResponse({
         payload: formatEnvelope.payload,
         adapterContext: options.context,
         stageRecorder: options.stageRecorder
     });
     stripInternalPolicyDebugFields(formatEnvelope.payload);
+    formatEnvelope.payload = await runRespInboundStage3ThoughtSignatureCapture({
+        payload: formatEnvelope.payload,
+        adapterContext: options.context,
+        stageRecorder: options.stageRecorder
+    });
     // Phase 2 (shadow): response tool surface mismatch detection (provider inbound).
     // Only records diffs; does not rewrite payload.
     try {
@@ -311,14 +344,15 @@ export async function convertProviderResponse(options) {
         adapterContext: options.context,
         formatEnvelope,
         mapper,
+        requestSemantics: options.requestSemantics,
         stageRecorder: options.stageRecorder
     });
     // 记录语义映射后的 ChatCompletion，便于回放 server-side 工具流程。
-    recordStage(options.stageRecorder, 'resp_inbound_stage3_semantic_map.chat', chatResponse);
+    recordStage(options.stageRecorder, 'chat_process.resp.stage4.semantic_map_to_chat.chat', chatResponse);
     // 检查是否需要进行 ServerTool 编排
     // 使用新的 ChatEnvelope 级别的 servertool 实现
     let effectiveChatResponse = chatResponse;
-    if (!skipServerTools && options.reenterPipeline) {
+    if (hasServerToolSupport) {
         try {
             // eslint-disable-next-line no-console
             console.log(`\x1b[38;5;33m[servertool][orchestrator] start requestId=${options.context.requestId} ` +
@@ -348,6 +382,12 @@ export async function convertProviderResponse(options) {
                 /* logging best-effort */
             }
             effectiveChatResponse = orchestration.chat;
+            recordStage(options.stageRecorder, 'chat_process.resp.stage5.servertool_orchestration', {
+                executed: true,
+                flowId: orchestration.flowId,
+                inputShape: detectProviderResponseShape(chatResponse),
+                outputShape: detectProviderResponseShape(effectiveChatResponse)
+            });
         }
         else {
             try {
@@ -358,8 +398,20 @@ export async function convertProviderResponse(options) {
             catch {
                 /* logging best-effort */
             }
+            recordStage(options.stageRecorder, 'chat_process.resp.stage5.servertool_orchestration', {
+                executed: false,
+                inputShape: detectProviderResponseShape(chatResponse)
+            });
         }
     }
+    // Hard gate: response-side chat_process requires an OpenAI-chat-like surface (choices[].message).
+    // ServerTool followups must never replace the canonical chat completion with a client-protocol shape.
+    effectiveChatResponse = await coerceClientPayloadToCanonicalChatCompletionOrThrow({
+        payload: effectiveChatResponse,
+        adapterContext: options.context,
+        requestSemantics: options.requestSemantics,
+        scope: 'chat_process.response.entry'
+    });
     // 如果没有执行 servertool，继续原来的处理流程
     const governanceResult = await runRespProcessStage1ToolGovernance({
         payload: effectiveChatResponse,
@@ -382,10 +434,22 @@ export async function convertProviderResponse(options) {
         clientProtocol,
         requestId: clientFacingRequestId,
         adapterContext: options.context,
+        requestSemantics: options.requestSemantics,
         stageRecorder: options.stageRecorder
     });
     applyModelOverride(clientPayload, displayModel);
     stripInternalPolicyDebugFields(clientPayload);
+    if (clientProtocol === 'openai-responses') {
+        try {
+            recordResponsesResponse({
+                requestId: options.context.requestId,
+                response: clientPayload
+            });
+        }
+        catch {
+            // ignore conversation capture errors
+        }
+    }
     // Phase 2 (shadow): response tool surface mismatch detection (client outbound).
     try {
         if (options.stageRecorder && isToolSurfaceShadowEnabled()) {

package/dist/conversion/hub/response/response-mappers.d.ts

@@ -1,9 +1,12 @@
 import type { FormatEnvelope } from '../types/format-envelope.js';
 import type { AdapterContext } from '../types/chat-envelope.js';
 import type { JsonObject } from '../types/json.js';
+import type { ChatSemantics } from '../types/chat-envelope.js';
 export type ChatCompletionLike = JsonObject;
 export interface ResponseMapper {
-    toChatCompletion(format: FormatEnvelope, ctx: AdapterContext): Promise<ChatCompletionLike> | ChatCompletionLike;
+    toChatCompletion(format: FormatEnvelope, ctx: AdapterContext, options?: {
+        requestSemantics?: ChatSemantics | JsonObject;
+    }): Promise<ChatCompletionLike> | ChatCompletionLike;
 }
 export declare class OpenAIChatResponseMapper implements ResponseMapper {
     toChatCompletion(format: FormatEnvelope, _ctx: AdapterContext): ChatCompletionLike;
@@ -12,8 +15,12 @@ export declare class ResponsesResponseMapper implements ResponseMapper {
     toChatCompletion(format: FormatEnvelope, _ctx: AdapterContext): ChatCompletionLike;
 }
 export declare class AnthropicResponseMapper implements ResponseMapper {
-    toChatCompletion(format: FormatEnvelope, ctx: AdapterContext): ChatCompletionLike;
+    toChatCompletion(format: FormatEnvelope, _ctx: AdapterContext, options?: {
+        requestSemantics?: ChatSemantics | JsonObject;
+    }): ChatCompletionLike;
 }
 export declare class GeminiResponseMapper implements ResponseMapper {
-    toChatCompletion(format: FormatEnvelope, _ctx: AdapterContext): ChatCompletionLike;
+    toChatCompletion(format: FormatEnvelope, ctx: AdapterContext, options?: {
+        requestSemantics?: ChatSemantics | JsonObject;
+    }): ChatCompletionLike;
 }