@jsonstudio/llms 0.6.567 → 0.6.568

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

@@ -360,7 +360,9 @@ export function buildOpenAIChatFromGeminiResponse(payload) {
     if (Number.isFinite(totalTokens))
         usage.total_tokens = totalTokens;
     const combinedText = textParts.join('\n');
-    const normalized = combinedText.length ? normalizeChatMessageContent(combinedText) : { contentText: undefined, reasoningText: undefined };
+    const normalized = combinedText.length
+        ? normalizeChatMessageContent(combinedText)
+        : { contentText: undefined, reasoningText: undefined };
     const baseContent = normalized.contentText ?? combinedText ?? '';
     const toolResultBlock = toolResultTexts.length ? toolResultTexts.join('\n') : '';
     const finalContent = toolResultBlock && baseContent
@@ -525,16 +527,43 @@ export function buildGeminiFromOpenAIChat(chatResp) {
         let argsStruct;
         const rawArgs = fn.arguments;
         if (typeof rawArgs === 'string') {
+            const trimmed = rawArgs.trim();
+            if (trimmed.startsWith('{')) {
+                try {
+                    const parsed = JSON.parse(rawArgs);
+                    if (isObject(parsed)) {
+                        argsStruct = parsed;
+                    }
+                    else {
+                        argsStruct = { _raw: rawArgs };
+                    }
+                }
+                catch {
+                    argsStruct = { _raw: rawArgs };
+                }
+            }
+            else {
+                argsStruct = { _raw: rawArgs };
+            }
+        }
+        else if (isObject(rawArgs)) {
+            argsStruct = rawArgs;
+        }
+        else if (Array.isArray(rawArgs)) {
             try {
-                argsStruct = JSON.parse(rawArgs);
+                argsStruct = { _raw: JSON.stringify(rawArgs) };
             }
             catch {
-                argsStruct = { _raw: rawArgs };
+                argsStruct = { _raw: String(rawArgs) };
             }
         }
+        else if (rawArgs != null) {
+            argsStruct = { _raw: String(rawArgs) };
+        }
         else {
-            argsStruct = rawArgs ?? {};
+            argsStruct = {};
         }
+        // Gemini request/response wire uses `args` for functionCall payload.
         const functionCall = { name, args: argsStruct };
         const id = typeof tc.id === 'string' ? String(tc.id) : undefined;
         if (id)

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

@@ -89,8 +89,9 @@ export class OpenAIOpenAIConversionCodec {
         // Response-side filters (idempotent w.r.t existing logic)
         engine.registerFilter(new ResponseToolTextCanonicalizeFilter()); // response_pre
         try {
-            const { ResponseToolArgumentsToonDecodeFilter } = await import('../../filters/index.js');
+            const { ResponseToolArgumentsToonDecodeFilter, ResponseApplyPatchToonDecodeFilter } = await import('../../filters/index.js');
             engine.registerFilter(new ResponseToolArgumentsToonDecodeFilter()); // response_pre, runs before stringify
+            engine.registerFilter(new ResponseApplyPatchToonDecodeFilter()); // response_pre, runs before stringify
         }
         catch { /* optional */ }
         engine.registerFilter(new ResponseToolArgumentsStringifyFilter()); // response_post

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

@@ -147,11 +147,12 @@ export class ResponsesOpenAIConversionCodec {
             debug: { emit: () => { } }
         };
         const engine = new FilterEngine();
-        // Response-side filters：文本标准化 → TOON decode（可选）→ shell/basics → finish_reason 不变式
+        // Response-side filters：文本标准化 → TOON decode（可选）→ apply_patch 结构化补丁规范化 → shell/basics → finish_reason 不变式
         engine.registerFilter(new ResponseToolTextCanonicalizeFilter()); // response_pre
         try {
-            const { ResponseToolArgumentsToonDecodeFilter } = await import('../../filters/index.js');
+            const { ResponseToolArgumentsToonDecodeFilter, ResponseApplyPatchToonDecodeFilter } = await import('../../filters/index.js');
             engine.registerFilter(new ResponseToolArgumentsToonDecodeFilter()); // response_pre, runs before stringify
+            engine.registerFilter(new ResponseApplyPatchToonDecodeFilter()); // response_pre, runs before stringify
         }
         catch { /* optional */ }
         engine.registerFilter(new ResponseToolArgumentsStringifyFilter()); // response_post

package/dist/conversion/compat/actions/glm-history-image-trim.d.ts

@@ -0,0 +1,2 @@
+import type { JsonObject } from '../../hub/types/json.js';
+export declare function applyGlmHistoryImageTrim(payload: JsonObject): JsonObject;

package/dist/conversion/compat/actions/glm-history-image-trim.js

@@ -0,0 +1,88 @@
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function shouldDropInlineImagePart(part) {
+    const rawType = typeof part.type === 'string' ? part.type.toLowerCase() : '';
+    if (rawType !== 'image' && rawType !== 'image_url' && rawType !== 'input_image') {
+        return false;
+    }
+    const imageUrlBlock = isRecord(part.image_url)
+        ? part.image_url
+        : part;
+    const urlRaw = typeof imageUrlBlock.url === 'string'
+        ? imageUrlBlock.url
+        : typeof imageUrlBlock.data === 'string'
+            ? imageUrlBlock.data
+            : '';
+    const url = urlRaw.trim();
+    if (!url) {
+        return false;
+    }
+    // GLM 4.7 在历史消息中携带 data:image/base64 时会返回 1210，
+    // 因此仅在历史中丢弃这类 inline image 片段。
+    return url.startsWith('data:image');
+}
+export function applyGlmHistoryImageTrim(payload) {
+    const root = structuredClone(payload);
+    const modelRaw = root.model;
+    const modelId = typeof modelRaw === 'string' ? modelRaw.trim().toLowerCase() : '';
+    if (!modelId || !modelId.startsWith('glm-4.7')) {
+        return root;
+    }
+    const messagesValue = root.messages;
+    if (!Array.isArray(messagesValue)) {
+        return root;
+    }
+    const messages = messagesValue.filter(msg => isRecord(msg));
+    if (!messages.length) {
+        return root;
+    }
+    // 仅在历史消息中进行裁剪：保留最后一条 user 完整内容。
+    let lastUserIdx = -1;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const msg = messages[i];
+        const role = typeof msg.role === 'string' ? msg.role.toLowerCase() : '';
+        if (role === 'user') {
+            lastUserIdx = i;
+            break;
+        }
+    }
+    if (lastUserIdx === -1) {
+        return root;
+    }
+    const nextMessages = [];
+    for (let i = 0; i < messages.length; i += 1) {
+        const msg = messages[i];
+        const role = typeof msg.role === 'string' ? msg.role.toLowerCase() : '';
+        if (i < lastUserIdx && role === 'user') {
+            const contentValue = msg.content;
+            if (!Array.isArray(contentValue)) {
+                nextMessages.push(msg);
+                continue;
+            }
+            const newContent = [];
+            for (const part of contentValue) {
+                if (!isRecord(part)) {
+                    newContent.push(part);
+                    continue;
+                }
+                if (shouldDropInlineImagePart(part)) {
+                    // 丢弃历史中的 data:image/* 片段
+                    // eslint-disable-next-line no-continue
+                    continue;
+                }
+                newContent.push(part);
+            }
+            if (!newContent.length) {
+                // 历史消息只剩下 inline image 时，直接移除整条消息。
+                // 避免向 GLM 发送纯图片历史导致 1210。
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            const cloned = { ...msg, content: newContent };
+            nextMessages.push(cloned);
+            continue;
+        }
+        nextMessages.push(msg);
+    }
+    root.messages = nextMessages;
+    return root;
+}

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

@@ -1,10 +1,15 @@
 import { Readable } from 'node:stream';
 import type { StandardizedRequest, ProcessedRequest } from '../types/standardized.js';
 import type { JsonObject } from '../types/json.js';
-import type { VirtualRouterConfig, RoutingDecision, RoutingDiagnostics, TargetMetadata } from '../../../router/virtual-router/types.js';
+import type { VirtualRouterConfig, RoutingDecision, RoutingDiagnostics, TargetMetadata, VirtualRouterHealthStore } from '../../../router/virtual-router/types.js';
 import { type HubProcessNodeResult } from '../process/chat-process.js';
 export interface HubPipelineConfig {
     virtualRouter: VirtualRouterConfig;
+    /**
+     * 可选：供 VirtualRouterEngine 使用的健康状态持久化存储。
+     * 当提供时，VirtualRouterEngine 将在初始化时恢复上一次快照，并在 cooldown/熔断变化时调用 persistSnapshot。
+     */
+    healthStore?: VirtualRouterHealthStore;
 }
 export interface HubPipelineRequestMetadata extends Record<string, unknown> {
     entryEndpoint?: string;

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

@@ -28,7 +28,9 @@ export class HubPipeline {
     unsubscribeProviderErrors;
     constructor(config) {
         this.config = config;
-        this.routerEngine = new VirtualRouterEngine();
+        this.routerEngine = new VirtualRouterEngine({
+            healthStore: config.healthStore
+        });
         this.routerEngine.initialize(config.virtualRouter);
         try {
             this.unsubscribeProviderErrors = providerErrorCenter.subscribe((event) => {
@@ -242,19 +244,22 @@ export class HubPipeline {
         }
         // 为响应侧 servertool/web_search 提供一次性 Chat 请求快照，便于在 Hub 内部实现
         // 第三跳（将工具结果注入消息历史后重新调用主模型）。
+        //
+        // 注意：这里不再根据 processMode(passthrough/chat) 做分支判断——即使某些
+        // route 将 processMode 标记为 passthrough，我们仍然需要保留一次规范化后的
+        // Chat 请求快照，供 stopMessage / gemini_empty_reply_continue 等被动触发型
+        // servertool 在响应阶段使用。
         let capturedChatRequest;
-        if (normalized.processMode !== 'passthrough') {
-            try {
-                capturedChatRequest = JSON.parse(JSON.stringify({
-                    model: workingRequest.model,
-                    messages: workingRequest.messages,
-                    tools: workingRequest.tools,
-                    parameters: workingRequest.parameters
-                }));
-            }
-            catch {
-                capturedChatRequest = undefined;
-            }
+        try {
+            capturedChatRequest = JSON.parse(JSON.stringify({
+                model: workingRequest.model,
+                messages: workingRequest.messages,
+                tools: workingRequest.tools,
+                parameters: workingRequest.parameters
+            }));
+        }
+        catch {
+            capturedChatRequest = undefined;
         }
         const metadata = {
             ...normalized.metadata,
@@ -397,6 +402,13 @@ export class HubPipeline {
         if (conversationId) {
             adapterContext.conversationId = conversationId;
         }
+        const responsesResume = metadata.responsesResume &&
+            typeof metadata.responsesResume === 'object'
+            ? metadata.responsesResume
+            : undefined;
+        if (responsesResume) {
+            adapterContext.responsesResume = responsesResume;
+        }
         if (target?.compatibilityProfile && typeof target.compatibilityProfile === 'string') {
             adapterContext.compatibilityProfile = target.compatibilityProfile;
         }

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

@@ -1,6 +1,7 @@
 import { runChatRequestToolFilters } from '../../shared/tool-filter-pipeline.js';
 import { ToolGovernanceEngine } from '../tool-governance/index.js';
 import { detectLastAssistantToolCategory } from '../../../router/virtual-router/tool-signals.js';
+import { ensureApplyPatchSchema } from '../../shared/tool-mapping.js';
 const toolGovernanceEngine = new ToolGovernanceEngine();
 export async function runHubChatProcess(options) {
     const startTime = Date.now();
@@ -72,6 +73,12 @@ async function applyRequestToolGovernance(request, context) {
             governanceTimestamp: Date.now()
         }
     };
+    // 清理历史图片：仅保留「最新一条 user 消息」中的图片分段，
+    // 避免历史对话中的图片在后续多轮工具 / 普通对话中继续作为多模态负载发给不支持图片的模型。
+    merged = {
+        ...merged,
+        messages: stripHistoricalImageAttachments(merged.messages)
+    };
     if (containsImageAttachment(merged.messages)) {
         if (!merged.metadata) {
             merged.metadata = {
@@ -205,6 +212,63 @@ function castSingleTool(tool) {
         }
     };
 }
+function stripHistoricalImageAttachments(messages) {
+    if (!Array.isArray(messages) || !messages.length) {
+        return messages;
+    }
+    // 找到最新一条 user 消息，仅允许该消息保留图片分段；
+    // 更早的 user 消息中若存在图片，则移除其 image* 分段，保留纯文本与非图片内容。
+    let latestUserIndex = -1;
+    for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
+        const candidate = messages[idx];
+        if (candidate && typeof candidate === 'object' && candidate.role === 'user') {
+            latestUserIndex = idx;
+            break;
+        }
+    }
+    if (latestUserIndex < 0) {
+        return messages;
+    }
+    let changed = false;
+    const next = messages.slice();
+    for (let idx = 0; idx < messages.length; idx += 1) {
+        if (idx === latestUserIndex) {
+            continue;
+        }
+        const message = messages[idx];
+        if (!message || typeof message !== 'object') {
+            continue;
+        }
+        if (message.role !== 'user') {
+            continue;
+        }
+        const content = message.content;
+        if (!Array.isArray(content) || !content.length) {
+            continue;
+        }
+        const filtered = [];
+        let removed = false;
+        for (const part of content) {
+            if (part && typeof part === 'object' && !Array.isArray(part)) {
+                const typeValue = part.type;
+                if (typeof typeValue === 'string' && typeValue.toLowerCase().includes('image')) {
+                    removed = true;
+                    continue;
+                }
+            }
+            filtered.push(part);
+        }
+        if (removed) {
+            const cloned = {
+                ...message,
+                content: filtered
+            };
+            next[idx] = cloned;
+            changed = true;
+        }
+    }
+    return changed ? next : messages;
+}
 function containsImageAttachment(messages) {
     if (!Array.isArray(messages) || !messages.length) {
         return false;
@@ -278,17 +342,7 @@ function castCustomTool(tool) {
         function: {
             name: 'apply_patch',
             description,
-            parameters: {
-                type: 'object',
-                properties: {
-                    patch: {
-                        type: 'string',
-                        description: 'Unified diff patch content (FREEFORM, not JSON)'
-                    }
-                },
-                required: ['patch'],
-                additionalProperties: false
-            },
+            parameters: ensureApplyPatchSchema(),
             strict: true
         }
     };

package/dist/conversion/hub/semantic-mappers/gemini-mapper.js

@@ -286,6 +286,14 @@ function appendChatContentToGeminiParts(message, targetParts) {
 function buildGeminiRequestFromChat(chat, metadata) {
     const contents = [];
     const emittedToolOutputs = new Set();
+    const adapterContext = metadata?.context;
+    const rawProviderId = adapterContext?.providerId;
+    const normalizedProviderId = typeof rawProviderId === 'string' ? rawProviderId.toLowerCase() : '';
+    const providerIdPrefix = normalizedProviderId.split('.')[0];
+    // 保持对通用 gemini-cli 的保护（避免上游直接执行 functionCall），
+    // 但对于 antigravity.* 明确允许通过 Gemini functionCall 协议执行工具，
+    // 以便完整打通 tools → functionCall → functionResponse 链路。
+    const omitFunctionCallPartsForCli = providerIdPrefix === 'gemini-cli';
     for (const message of chat.messages) {
         if (!message || typeof message !== 'object')
             continue;
@@ -304,10 +312,15 @@ function buildGeminiRequestFromChat(chat, metadata) {
             parts: []
         };
         appendChatContentToGeminiParts(message, entry.parts);
-        const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+        const toolCalls = Array.isArray(message.tool_calls)
+            ? message.tool_calls
+            : [];
         for (const tc of toolCalls) {
             if (!tc || typeof tc !== 'object')
                 continue;
+            if (omitFunctionCallPartsForCli) {
+                continue;
+            }
             const fn = tc.function || {};
             const name = typeof fn.name === 'string' ? fn.name : undefined;
             if (!name)
@@ -324,7 +337,8 @@ function buildGeminiRequestFromChat(chat, metadata) {
             else {
                 argsStruct = fn.arguments ?? {};
             }
-            const part = { functionCall: { name, args: cloneAsJsonValue(argsStruct) } };
+            const functionCall = { name, args: cloneAsJsonValue(argsStruct) };
+            const part = { functionCall };
             if (typeof tc.id === 'string') {
                 part.functionCall.id = tc.id;
             }
@@ -409,7 +423,6 @@ function buildGeminiRequestFromChat(chat, metadata) {
     }
     // Apply claude-thinking compat directly at Gemini mapping time to ensure it is always active
     // for antigravity.*.claude-sonnet-4-5-thinking, regardless of compatibilityProfile wiring.
-    const adapterContext = metadata?.context;
     const compatRequest = applyClaudeThinkingToolSchemaCompat(request, adapterContext);
     return compatRequest;
 }

package/dist/conversion/hub/semantic-mappers/responses-mapper.js

@@ -53,6 +53,41 @@ function mapToolOutputs(entries, missing) {
     });
     return outputs.length ? outputs : undefined;
 }
+function deriveResumeToolOutputs(ctx) {
+    if (!ctx || typeof ctx !== 'object') {
+        return undefined;
+    }
+    const resume = ctx.responsesResume;
+    if (!resume || typeof resume !== 'object') {
+        return undefined;
+    }
+    const detailed = Array.isArray(resume.toolOutputsDetailed)
+        ? resume.toolOutputsDetailed
+        : undefined;
+    if (!detailed || detailed.length === 0) {
+        return undefined;
+    }
+    const outputs = [];
+    detailed.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object') {
+            return;
+        }
+        const callIdRaw = typeof entry.callId === 'string' && entry.callId.trim().length
+            ? entry.callId.trim()
+            : typeof entry.originalId === 'string' && entry.originalId.trim().length
+                ? entry.originalId.trim()
+                : `resume_tool_${index}`;
+        if (!callIdRaw) {
+            return;
+        }
+        const outputText = typeof entry.outputText === 'string' ? entry.outputText : '';
+        outputs.push({
+            tool_call_id: callIdRaw,
+            content: outputText
+        });
+    });
+    return outputs.length ? outputs : undefined;
+}
 function collectParameters(payload, streamHint) {
     const params = {};
     for (const key of RESPONSES_PARAMETER_KEYS) {
@@ -169,16 +204,30 @@ export class ResponsesSemanticMapper {
         const { request, toolsNormalized } = buildChatRequestFromResponses(payload, responsesContext);
         const missingFields = [];
         const messages = normalizeMessages(request.messages, missingFields);
-        const toolOutputs = mapToolOutputs(payload.tool_outputs, missingFields);
+        let toolOutputs = mapToolOutputs(payload.tool_outputs, missingFields);
+        if (!toolOutputs || toolOutputs.length === 0) {
+            const resumeToolOutputs = deriveResumeToolOutputs(ctx);
+            if (resumeToolOutputs && resumeToolOutputs.length) {
+                toolOutputs = resumeToolOutputs;
+            }
+        }
         const parameters = collectParameters(payload, responsesContext.stream);
         const metadata = { context: ctx };
         try {
             const bridgePolicy = resolveBridgePolicy({ protocol: 'openai-responses', moduleType: 'openai-responses' });
             const actions = resolvePolicyActions(bridgePolicy, 'request_inbound');
             if (actions?.length) {
+                const capturedToolResults = Array.isArray(toolOutputs)
+                    ? toolOutputs.map((entry) => ({
+                        tool_call_id: entry.tool_call_id,
+                        output: entry.content,
+                        name: entry.name
+                    }))
+                    : undefined;
                 const actionState = createBridgeActionState({
                     rawRequest: payload,
-                    metadata: metadata
+                    metadata: metadata,
+                    capturedToolResults
                 });
                 runBridgeActionPipeline({
                     stage: 'request_inbound',

package/dist/conversion/hub/types/chat-envelope.d.ts

@@ -53,6 +53,7 @@ export interface AdapterContext {
     originalModelId?: string;
     clientModelId?: string;
     toolCallIdStyle?: 'fc' | 'preserve';
+    responsesResume?: JsonObject;
     [key: string]: JsonValue;
 }
 export interface ChatEnvelope {

package/dist/conversion/shared/anthropic-message-utils.js

@@ -647,6 +647,56 @@ function createAnthropicToolNameResolver(source) {
         return lookup.get(trimmed) ?? lookup.get(trimmed.toLowerCase()) ?? trimmed;
     };
 }
+function normalizeAnthropicToolChoice(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (isPlainRecord(value)) {
+        // Already an object – best-effort clone while trimming type, and also support
+        // Chat-style { type: 'function', function: { name } } by mapping to Anthropic's
+        // { type: 'tool', name } shape.
+        const cloned = cloneAnthropicSchema(value);
+        const rawType = typeof cloned.type === 'string' ? String(cloned.type).trim() : '';
+        if (rawType) {
+            cloned.type = rawType;
+            return cloned;
+        }
+        const selectorType = typeof cloned.type === 'string' ? String(cloned.type).trim() : '';
+        const fn = cloned.function;
+        if (selectorType === 'function' &&
+            fn &&
+            typeof fn === 'object' &&
+            typeof fn.name === 'string' &&
+            String(fn.name).trim().length) {
+            return { type: 'tool', name: String(fn.name).trim() };
+        }
+        return cloned;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed.length) {
+            return undefined;
+        }
+        const lower = trimmed.toLowerCase();
+        if (lower === 'auto') {
+            return { type: 'auto' };
+        }
+        if (lower === 'none') {
+            return { type: 'none' };
+        }
+        if (lower === 'any') {
+            return { type: 'any' };
+        }
+        if (lower === 'required') {
+            // "required" in canonical Chat roughly maps to Anthropic's "any" semantics:
+            // the model must choose some tool if available.
+            return { type: 'any' };
+        }
+        // Fallback: preserve custom mode as-is in type field.
+        return { type: trimmed };
+    }
+    return undefined;
+}
 export function buildAnthropicRequestFromOpenAIChat(chatReq) {
     const requestBody = isObject(chatReq) ? chatReq : {};
     const model = String(requestBody?.model || 'unknown');
@@ -882,6 +932,10 @@ export function buildAnthropicRequestFromOpenAIChat(chatReq) {
     if (anthropicTools !== undefined) {
         out.tools = anthropicTools;
     }
+    const normalizedToolChoice = normalizeAnthropicToolChoice(requestBody.tool_choice);
+    if (normalizedToolChoice !== undefined) {
+        out.tool_choice = normalizedToolChoice;
+    }
     try {
         if (requestBody.metadata && typeof requestBody.metadata === 'object') {
             out.metadata = JSON.parse(JSON.stringify(requestBody.metadata));

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

@@ -1,4 +1,4 @@
-// Shared tool + argument mapping helpers (schema-driven)
+import { buildShellDescription, hasApplyPatchToolDeclared, isShellToolName } from '../../tools/tool-description-utils.js';
 function isObject(v) {
     return !!v && typeof v === 'object' && !Array.isArray(v);
 }
@@ -155,6 +155,7 @@ export function normalizeTools(tools) {
     if (!Array.isArray(tools))
         return [];
     const out = [];
+    const applyPatchAvailable = hasApplyPatchToolDeclared(tools);
     for (const t of tools) {
         if (!t || typeof t !== 'object')
             continue;
@@ -175,7 +176,7 @@ export function normalizeTools(tools) {
         }
         // Enforce schema for known tools with minimal, compatible constraints
         let finalParams;
-        if (typeof name === 'string' && name.trim().toLowerCase() === 'shell') {
+        if (isShellToolName(name)) {
             // Do NOT downgrade an existing schema; prefer string command, allow argv array as fallback
             const base = isObject(params) ? params : {};
             const props = isObject(base.properties) ? base.properties : {};
@@ -205,7 +206,14 @@ export function normalizeTools(tools) {
         else {
             finalParams = { type: 'object', properties: {}, additionalProperties: true };
         }
-        const norm = { type: 'function', function: { name, ...(desc ? { description: desc } : {}), parameters: finalParams } };
+        const functionNode = { name, ...(desc ? { description: desc } : {}), parameters: finalParams };
+        if (isShellToolName(name)) {
+            const display = (typeof name === 'string' && name.trim().length > 0)
+                ? name.trim()
+                : ((typeof topName === 'string' && topName.trim().length > 0) ? topName.trim() : 'shell');
+            functionNode.description = buildShellDescription(display, applyPatchAvailable);
+        }
+        const norm = { type: 'function', function: functionNode };
         if (norm.function?.name)
             out.push(norm);
     }