@jsonstudio/llms 0.6.473 → 0.6.568

package/dist/servertool/handlers/stop-message-auto.js

@@ -0,0 +1,204 @@
+import { registerServerToolHandler } from '../registry.js';
+import { cloneJson } from '../server-side-tools.js';
+import { loadRoutingInstructionStateSync, saveRoutingInstructionStateAsync } from '../../router/virtual-router/sticky-session-store.js';
+const STOPMESSAGE_DEBUG = (process.env.ROUTECODEX_STOPMESSAGE_DEBUG || '').trim() === '1';
+function debugLog(message, extra) {
+    if (!STOPMESSAGE_DEBUG) {
+        return;
+    }
+    try {
+        // eslint-disable-next-line no-console
+        console.log(`\x1b[38;5;33m[stopMessage][debug] ${message}` +
+            (extra ? ` ${JSON.stringify(extra)}` : '') +
+            '\x1b[0m');
+    }
+    catch {
+        /* ignore logging failures */
+    }
+}
+const FLOW_ID = 'stop_message_flow';
+const handler = async (ctx) => {
+    const record = ctx.adapterContext;
+    debugLog('handler_start', {
+        requestId: record.requestId,
+        providerProtocol: record.providerProtocol
+    });
+    const followupRaw = record.serverToolFollowup;
+    if (followupRaw === true || (typeof followupRaw === 'string' && followupRaw.trim().toLowerCase() === 'true')) {
+        debugLog('skip_servertool_followup_flag');
+        return null;
+    }
+    const connectionState = resolveClientConnectionState(record.clientConnectionState);
+    if (connectionState?.disconnected === true) {
+        debugLog('skip_client_disconnected');
+        return null;
+    }
+    const clientDisconnectedRaw = record.clientDisconnected;
+    if (clientDisconnectedRaw === true ||
+        (typeof clientDisconnectedRaw === 'string' && clientDisconnectedRaw.trim().toLowerCase() === 'true')) {
+        debugLog('skip_client_disconnected_flag');
+        return null;
+    }
+    const stickyKey = resolveStickyKey(record);
+    if (!stickyKey) {
+        debugLog('skip_no_sticky_key');
+        return null;
+    }
+    const state = loadRoutingInstructionStateSync(stickyKey);
+    if (!state || !state.stopMessageText || !state.stopMessageMaxRepeats) {
+        debugLog('skip_no_state', { stickyKey });
+        return null;
+    }
+    const text = typeof state.stopMessageText === 'string' ? state.stopMessageText.trim() : '';
+    const maxRepeats = typeof state.stopMessageMaxRepeats === 'number' && Number.isFinite(state.stopMessageMaxRepeats)
+        ? Math.max(1, Math.floor(state.stopMessageMaxRepeats))
+        : 0;
+    if (!text || maxRepeats <= 0) {
+        debugLog('skip_invalid_text_or_maxRepeats', {
+            stickyKey,
+            textLength: text.length,
+            maxRepeats
+        });
+        return null;
+    }
+    const used = typeof state.stopMessageUsed === 'number' && Number.isFinite(state.stopMessageUsed)
+        ? Math.max(0, Math.floor(state.stopMessageUsed))
+        : 0;
+    if (used >= maxRepeats) {
+        debugLog('skip_reached_max_repeats', {
+            stickyKey,
+            used,
+            maxRepeats
+        });
+        return null;
+    }
+    if (!isStopFinishReason(ctx.base)) {
+        debugLog('skip_not_stop_finish_reason', {
+            stickyKey
+        });
+        return null;
+    }
+    const captured = getCapturedRequest(ctx.adapterContext);
+    if (!captured) {
+        debugLog('skip_no_captured_request', {
+            stickyKey
+        });
+        return null;
+    }
+    state.stopMessageUsed = used + 1;
+    state.stopMessageLastUsedAt = Date.now();
+    saveRoutingInstructionStateAsync(stickyKey, state);
+    const followupPayload = buildStopMessageFollowupPayload(captured, text);
+    if (!followupPayload) {
+        debugLog('skip_failed_build_followup', {
+            stickyKey
+        });
+        return null;
+    }
+    return {
+        chatResponse: ctx.base,
+        execution: {
+            flowId: FLOW_ID,
+            followup: {
+                requestIdSuffix: ':stop_followup',
+                payload: followupPayload,
+                metadata: {
+                    serverToolFollowup: true,
+                    stream: false,
+                    preserveRouteHint: false,
+                    disableStickyRoutes: true,
+                    ...(connectionState ? { clientConnectionState: connectionState } : {})
+                }
+            }
+        }
+    };
+};
+registerServerToolHandler('stop_message_auto', handler, { trigger: 'auto' });
+function resolveStickyKey(record) {
+    const sessionId = typeof record.sessionId === 'string' && record.sessionId.trim() ? record.sessionId.trim() : '';
+    const conversationId = typeof record.conversationId === 'string' && record.conversationId.trim()
+        ? record.conversationId.trim()
+        : '';
+    if (sessionId) {
+        return `session:${sessionId}`;
+    }
+    if (conversationId) {
+        return `conversation:${conversationId}`;
+    }
+    return undefined;
+}
+function isStopFinishReason(base) {
+    if (!base || typeof base !== 'object' || Array.isArray(base)) {
+        return false;
+    }
+    const payload = base;
+    const choicesRaw = payload.choices;
+    if (!Array.isArray(choicesRaw) || !choicesRaw.length) {
+        return false;
+    }
+    const first = choicesRaw[0];
+    if (!first || typeof first !== 'object' || Array.isArray(first)) {
+        return false;
+    }
+    const finishReasonRaw = first.finish_reason;
+    const finishReason = typeof finishReasonRaw === 'string' && finishReasonRaw.trim()
+        ? finishReasonRaw.trim().toLowerCase()
+        : '';
+    if (finishReason !== 'stop') {
+        return false;
+    }
+    const message = first.message &&
+        typeof first.message === 'object' &&
+        !Array.isArray(first.message)
+        ? first.message
+        : null;
+    if (!message) {
+        return false;
+    }
+    const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+    if (toolCalls.length > 0) {
+        return false;
+    }
+    return true;
+}
+function getCapturedRequest(adapterContext) {
+    if (!adapterContext || typeof adapterContext !== 'object') {
+        return null;
+    }
+    const captured = adapterContext.capturedChatRequest;
+    if (!captured || typeof captured !== 'object' || Array.isArray(captured)) {
+        return null;
+    }
+    return captured;
+}
+function buildStopMessageFollowupPayload(source, text) {
+    if (!source || typeof source !== 'object') {
+        return null;
+    }
+    const payload = {};
+    if (typeof source.model === 'string' && source.model.trim()) {
+        payload.model = source.model.trim();
+    }
+    const rawMessages = source.messages;
+    const messages = Array.isArray(rawMessages) ? cloneJson(rawMessages) : [];
+    messages.push({
+        role: 'user',
+        content: text
+    });
+    payload.messages = messages;
+    if (Array.isArray(source.tools) && source.tools.length) {
+        payload.tools = cloneJson(source.tools);
+    }
+    const parameters = source.parameters;
+    if (parameters && typeof parameters === 'object' && !Array.isArray(parameters)) {
+        const params = cloneJson(parameters);
+        Object.assign(payload, params);
+    }
+    return payload;
+}
+function resolveClientConnectionState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}

package/dist/servertool/handlers/vision.js

@@ -60,7 +60,26 @@ function shouldRunVisionFlow(ctx) {
     if (followupFlag) {
         return false;
     }
-    return record.hasImageAttachment === true || record.hasImageAttachment === 'true';
+    const hasImageAttachment = record.hasImageAttachment === true || record.hasImageAttachment === 'true';
+    if (!hasImageAttachment) {
+        return false;
+    }
+    // 若当前已经使用具备内建多模态能力的 Provider（例如 Gemini/Claude/ChatGPT 路径），
+    // 且未显式 forceVision，则不再触发额外的 vision 二跳，避免同一轮请求跑两次。
+    const forceVision = record.forceVision === true || record.forceVision === 'true';
+    if (forceVision) {
+        return true;
+    }
+    const providerType = typeof record.providerType === 'string' ? record.providerType.toLowerCase() : '';
+    const providerProtocol = typeof record.providerProtocol === 'string' ? record.providerProtocol.toLowerCase() : '';
+    const inlineMultimodal = providerType === 'gemini' ||
+        providerType === 'responses' ||
+        providerProtocol === 'gemini-chat' ||
+        providerProtocol === 'openai-responses';
+    if (inlineMultimodal) {
+        return false;
+    }
+    return true;
 }
 function getCapturedRequest(adapterContext) {
     if (!adapterContext || typeof adapterContext !== 'object') {
@@ -80,15 +99,15 @@ function buildVisionAnalysisPayload(source) {
     if (typeof source.model === 'string' && source.model.trim()) {
         payload.model = source.model.trim();
     }
-    if (Array.isArray(source.messages)) {
-        payload.messages = cloneJson(source.messages);
-    }
-    else {
+    const rawMessages = source.messages;
+    if (!Array.isArray(rawMessages) || !rawMessages.length) {
         return null;
     }
-    if (Array.isArray(source.tools) && source.tools.length) {
-        payload.tools = cloneJson(source.tools);
+    const visionMessages = buildVisionAnalysisMessages(rawMessages);
+    if (!visionMessages.length) {
+        return null;
     }
+    payload.messages = visionMessages;
     const parameters = source.parameters;
     if (parameters && typeof parameters === 'object' && !Array.isArray(parameters)) {
         const params = cloneJson(parameters);
@@ -96,6 +115,85 @@ function buildVisionAnalysisPayload(source) {
     }
     return payload;
 }
+function buildVisionAnalysisMessages(sourceMessages) {
+    const latestUser = extractLatestUserMessageForVision(sourceMessages);
+    if (!latestUser) {
+        return [];
+    }
+    const userMessage = buildVisionUserMessage(latestUser);
+    if (!userMessage) {
+        return [];
+    }
+    const messages = [];
+    const systemMessage = buildVisionSystemMessage();
+    if (systemMessage) {
+        messages.push(systemMessage);
+    }
+    messages.push(userMessage);
+    return messages;
+}
+function extractLatestUserMessageForVision(sourceMessages) {
+    for (let idx = sourceMessages.length - 1; idx >= 0; idx -= 1) {
+        const msg = sourceMessages[idx];
+        if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
+            continue;
+        }
+        const role = msg.role;
+        if (typeof role === 'string' && role.trim().toLowerCase() === 'user') {
+            return cloneJson(msg);
+        }
+    }
+    return null;
+}
+function buildVisionSystemMessage() {
+    const content = '你是一名专业的图像分析助手。无论输入是界面截图、文档、图表、代码编辑器、应用窗口还是普通照片，都需要先用结构化、详细的自然语言完整描述画面内容（关键区域、文字信息、布局层次、颜色与对比度、元素之间的关系等），然后总结出与用户任务最相关的关键信息和潜在问题，最后给出具体、可执行的改进建议或结论，避免泛泛而谈。';
+    return {
+        role: 'system',
+        content
+    };
+}
+function buildVisionUserMessage(source) {
+    const roleRaw = source.role;
+    const role = typeof roleRaw === 'string' && roleRaw.trim().length
+        ? roleRaw.trim()
+        : 'user';
+    const rawContent = source.content;
+    const message = { role };
+    if (Array.isArray(rawContent)) {
+        const textParts = [];
+        const imageParts = [];
+        for (const part of rawContent) {
+            if (!part || typeof part !== 'object' || Array.isArray(part)) {
+                textParts.push(part);
+                continue;
+            }
+            const record = part;
+            const typeValue = typeof record.type === 'string' ? record.type.toLowerCase() : '';
+            if (typeValue.includes('image')) {
+                imageParts.push(part);
+            }
+            else {
+                textParts.push(part);
+            }
+        }
+        const combined = [];
+        if (textParts.length)
+            combined.push(...textParts);
+        if (imageParts.length)
+            combined.push(...imageParts);
+        if (!combined.length) {
+            return null;
+        }
+        message.content = combined;
+    }
+    else if (typeof rawContent === 'string' && rawContent.trim().length) {
+        message.content = rawContent.trim();
+    }
+    else {
+        return null;
+    }
+    return message;
+}
 function buildVisionFollowupPayload(source, summary) {
     if (!source || typeof source !== 'object') {
         return null;

package/dist/servertool/server-side-tools.d.ts

@@ -2,6 +2,9 @@ import type { JsonObject } from '../conversion/hub/types/json.js';
 import type { ServerSideToolEngineOptions, ServerSideToolEngineResult, ToolCall } from './types.js';
 import './handlers/web-search.js';
 import './handlers/vision.js';
+import './handlers/gemini-empty-reply-continue.js';
+import './handlers/iflow-model-error-retry.js';
+import './handlers/stop-message-auto.js';
 export declare function runServerSideToolEngine(options: ServerSideToolEngineOptions): Promise<ServerSideToolEngineResult>;
 export declare function extractToolCalls(chatResponse: JsonObject): ToolCall[];
 export declare function cloneJson<T>(value: T): T;

package/dist/servertool/server-side-tools.js

@@ -1,11 +1,17 @@
 import { getServerToolHandler, listAutoServerToolHandlers } from './registry.js';
 import './handlers/web-search.js';
 import './handlers/vision.js';
+import './handlers/gemini-empty-reply-continue.js';
+import './handlers/iflow-model-error-retry.js';
+import './handlers/stop-message-auto.js';
 export async function runServerSideToolEngine(options) {
     const base = asObject(options.chatResponse);
     if (!base) {
         return { mode: 'passthrough', finalChatResponse: options.chatResponse };
     }
+    if (isClientDisconnected(options.adapterContext)) {
+        return { mode: 'passthrough', finalChatResponse: base };
+    }
     const toolCalls = extractToolCalls(base);
     const contextBase = {
         base,
@@ -89,6 +95,29 @@ function getArray(value) {
 export function cloneJson(value) {
     return JSON.parse(JSON.stringify(value));
 }
+function isClientDisconnected(adapterContext) {
+    if (!adapterContext || typeof adapterContext !== 'object') {
+        return false;
+    }
+    const state = adapterContext.clientConnectionState;
+    if (state && typeof state === 'object' && !Array.isArray(state)) {
+        const disconnected = state.disconnected;
+        if (disconnected === true) {
+            return true;
+        }
+        if (typeof disconnected === 'string' && disconnected.trim().toLowerCase() === 'true') {
+            return true;
+        }
+    }
+    const raw = adapterContext.clientDisconnected;
+    if (raw === true) {
+        return true;
+    }
+    if (typeof raw === 'string' && raw.trim().toLowerCase() === 'true') {
+        return true;
+    }
+    return false;
+}
 export function extractTextFromChatLike(payload) {
     let current = payload;
     const visited = new Set();

package/dist/sse/sse-to-json/builders/anthropic-response-builder.js

@@ -132,6 +132,22 @@ export function createAnthropicResponseBuilder(options) {
         },
         getResult() {
             if (!state.completed) {
+                // 对部分实现（或网络提前关闭）导致缺失 message_stop 的 SSE 流，
+                // 只要已经累计到可用内容，就以最佳努力方式返回结果，而不是直接抛错。
+                if (state.content.length > 0) {
+                    return {
+                        success: true,
+                        response: {
+                            id: state.id || `msg_${Date.now()}`,
+                            type: 'message',
+                            role: state.role || 'assistant',
+                            model: state.model || 'unknown',
+                            content: state.content,
+                            usage: state.usage,
+                            stop_reason: state.stopReason ?? 'end_turn'
+                        }
+                    };
+                }
                 return { success: false, error: new Error('Anthropic SSE stream incomplete') };
             }
             return {

package/dist/tools/apply-patch-structured.d.ts

@@ -0,0 +1,20 @@
+export type StructuredApplyPatchKind = 'insert_after' | 'insert_before' | 'replace' | 'delete' | 'create_file' | 'delete_file';
+export interface StructuredApplyPatchChange {
+    file?: string;
+    kind: StructuredApplyPatchKind | string;
+    anchor?: string;
+    target?: string;
+    lines?: string[] | string;
+    use_anchor_indent?: boolean;
+}
+export interface StructuredApplyPatchPayload extends Record<string, unknown> {
+    instructions?: string;
+    file?: string;
+    changes: StructuredApplyPatchChange[];
+}
+export declare class StructuredApplyPatchError extends Error {
+    reason: string;
+    constructor(reason: string, message: string);
+}
+export declare function buildStructuredPatch(payload: StructuredApplyPatchPayload): string;
+export declare function isStructuredApplyPatchPayload(candidate: unknown): candidate is StructuredApplyPatchPayload;

package/dist/tools/apply-patch-structured.js

@@ -0,0 +1,239 @@
+export class StructuredApplyPatchError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+const SUPPORTED_KINDS = [
+    'insert_after',
+    'insert_before',
+    'replace',
+    'delete',
+    'create_file',
+    'delete_file'
+];
+const FILE_PATH_INVALID_RE = /[\r\n]/;
+const INVALID_FILE_FORMAT_RE = /^([A-Za-z]:|\/)/;
+const toSafeString = (value, label) => {
+    const str = typeof value === 'string' ? value : '';
+    if (!str.trim()) {
+        throw new StructuredApplyPatchError('missing_field', `${label} is required`);
+    }
+    return str;
+};
+const normalizeFilePath = (raw, label) => {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new StructuredApplyPatchError('invalid_file', `${label} must not be empty`);
+    }
+    if (FILE_PATH_INVALID_RE.test(trimmed)) {
+        throw new StructuredApplyPatchError('invalid_file', `${label} must be a single-line relative path`);
+    }
+    if (INVALID_FILE_FORMAT_RE.test(trimmed)) {
+        throw new StructuredApplyPatchError('invalid_file', `${label} must be relative to the workspace root`);
+    }
+    return trimmed.replace(/\\/g, '/');
+};
+const splitTextIntoLines = (input) => {
+    const normalized = input.replace(/\r/g, '');
+    const parts = normalized.split('\n');
+    if (parts.length && parts[parts.length - 1] === '') {
+        parts.pop();
+    }
+    return parts.length ? parts : [''];
+};
+const normalizeLines = (value, label) => {
+    if (Array.isArray(value)) {
+        if (!value.length) {
+            return [];
+        }
+        return value.map((entry, idx) => {
+            if (typeof entry !== 'string') {
+                if (entry === null || entry === undefined) {
+                    return '';
+                }
+                return String(entry);
+            }
+            // Preserve intentional whitespace
+            return entry.replace(/\r/g, '');
+        });
+    }
+    if (typeof value === 'string') {
+        return splitTextIntoLines(value);
+    }
+    if (value === null || value === undefined) {
+        throw new StructuredApplyPatchError('invalid_lines', `${label} must be an array of strings or a multi-line string`);
+    }
+    return [String(value)];
+};
+const buildContextLines = (raw) => splitTextIntoLines(raw).map((line) => ` ${line}`);
+const buildPrefixedLines = (lines, prefix) => lines.map((line) => `${prefix}${line}`);
+const detectIndentFromAnchor = (anchorLines, mode) => {
+    const source = mode === 'first' ? anchorLines[0] ?? '' : anchorLines[anchorLines.length - 1] ?? '';
+    const match = source.match(/^(\s*)/);
+    return match ? match[1] ?? '' : '';
+};
+const applyAnchorIndent = (lines, anchorLines, position, enabled) => {
+    if (!enabled) {
+        return lines;
+    }
+    const indent = detectIndentFromAnchor(anchorLines, position);
+    if (!indent) {
+        return lines;
+    }
+    return lines.map((line) => {
+        if (!line.trim()) {
+            return line;
+        }
+        if (/^\s/.test(line)) {
+            return line;
+        }
+        return `${indent}${line}`;
+    });
+};
+export function buildStructuredPatch(payload) {
+    if (!payload || typeof payload !== 'object') {
+        throw new StructuredApplyPatchError('missing_payload', 'apply_patch arguments must be a JSON object');
+    }
+    if (!Array.isArray(payload.changes) || payload.changes.length === 0) {
+        throw new StructuredApplyPatchError('missing_changes', 'apply_patch requires a non-empty "changes" array');
+    }
+    const topLevelFile = typeof payload.file === 'string' && payload.file.trim()
+        ? normalizeFilePath(payload.file, 'file')
+        : undefined;
+    const sectionOrder = [];
+    const fileSections = new Map();
+    const ensureUpdateSection = (file) => {
+        const existing = fileSections.get(file);
+        if (existing) {
+            if (existing.type !== 'update') {
+                throw new StructuredApplyPatchError('invalid_change_sequence', `File "${file}" already marked as ${existing.type}`);
+            }
+            return existing;
+        }
+        const created = { type: 'update', hunks: [] };
+        sectionOrder.push(file);
+        fileSections.set(file, created);
+        return created;
+    };
+    for (const [index, change] of payload.changes.entries()) {
+        if (!change || typeof change !== 'object') {
+            throw new StructuredApplyPatchError('invalid_change', `Change at index ${index} must be an object`);
+        }
+        const kindRaw = typeof change.kind === 'string' ? change.kind.trim().toLowerCase() : '';
+        if (!kindRaw) {
+            throw new StructuredApplyPatchError('invalid_change_kind', `Change at index ${index} is missing "kind"`);
+        }
+        if (!SUPPORTED_KINDS.includes(kindRaw)) {
+            throw new StructuredApplyPatchError('invalid_change_kind', `Unsupported change kind "${change.kind}" at index ${index}`);
+        }
+        const file = change.file ? normalizeFilePath(change.file, `changes[${index}].file`) : topLevelFile;
+        if (!file) {
+            throw new StructuredApplyPatchError('invalid_file', `Change at index ${index} is missing "file"`);
+        }
+        if (kindRaw === 'create_file') {
+            if (fileSections.has(file)) {
+                throw new StructuredApplyPatchError('invalid_change_sequence', `File "${file}" already has pending changes`);
+            }
+            const lines = normalizeLines(change.lines, `changes[${index}].lines`);
+            sectionOrder.push(file);
+            fileSections.set(file, { type: 'add', lines });
+            continue;
+        }
+        if (kindRaw === 'delete_file') {
+            if (fileSections.has(file)) {
+                throw new StructuredApplyPatchError('invalid_change_sequence', `File "${file}" already has pending changes`);
+            }
+            sectionOrder.push(file);
+            fileSections.set(file, { type: 'delete' });
+            continue;
+        }
+        const section = ensureUpdateSection(file);
+        switch (kindRaw) {
+            case 'insert_after': {
+                const anchor = toSafeString(change.anchor, `changes[${index}].anchor`);
+                const anchorLines = splitTextIntoLines(anchor);
+                const additions = normalizeLines(change.lines, `changes[${index}].lines`);
+                if (!additions.length) {
+                    throw new StructuredApplyPatchError('invalid_lines', `changes[${index}].lines must include at least one line`);
+                }
+                const prepared = applyAnchorIndent(additions, anchorLines, 'last', change.use_anchor_indent);
+                const hunkBody = [...buildContextLines(anchor), ...buildPrefixedLines(prepared, '+')];
+                section.hunks.push(hunkBody);
+                break;
+            }
+            case 'insert_before': {
+                const anchor = toSafeString(change.anchor, `changes[${index}].anchor`);
+                const anchorLines = splitTextIntoLines(anchor);
+                const additions = normalizeLines(change.lines, `changes[${index}].lines`);
+                if (!additions.length) {
+                    throw new StructuredApplyPatchError('invalid_lines', `changes[${index}].lines must include at least one line`);
+                }
+                const prepared = applyAnchorIndent(additions, anchorLines, 'first', change.use_anchor_indent);
+                const hunkBody = [...buildPrefixedLines(prepared, '+'), ...buildContextLines(anchor)];
+                section.hunks.push(hunkBody);
+                break;
+            }
+            case 'replace': {
+                const target = toSafeString(change.target, `changes[${index}].target`);
+                const replacements = normalizeLines(change.lines, `changes[${index}].lines`);
+                const hunkBody = [
+                    ...buildPrefixedLines(splitTextIntoLines(target), '-'),
+                    ...buildPrefixedLines(replacements, '+')
+                ];
+                section.hunks.push(hunkBody);
+                break;
+            }
+            case 'delete': {
+                const target = toSafeString(change.target, `changes[${index}].target`);
+                const hunkBody = buildPrefixedLines(splitTextIntoLines(target), '-');
+                section.hunks.push(hunkBody);
+                break;
+            }
+            default: {
+                throw new StructuredApplyPatchError('invalid_change_kind', `Unsupported change kind "${change.kind}" at index ${index}`);
+            }
+        }
+    }
+    if (!sectionOrder.length) {
+        throw new StructuredApplyPatchError('missing_changes', 'apply_patch payload produced no file operations');
+    }
+    const lines = ['*** Begin Patch'];
+    for (const file of sectionOrder) {
+        const section = fileSections.get(file);
+        if (!section)
+            continue;
+        if (section.type === 'add') {
+            lines.push(`*** Add File: ${file}`);
+            for (const line of section.lines) {
+                lines.push(`+${line}`);
+            }
+        }
+        else if (section.type === 'delete') {
+            lines.push(`*** Delete File: ${file}`);
+        }
+        else {
+            lines.push(`*** Update File: ${file}`);
+            for (const hunk of section.hunks) {
+                lines.push('@@');
+                for (const entry of hunk) {
+                    lines.push(entry);
+                }
+                lines.push('@@');
+            }
+        }
+    }
+    lines.push('*** End Patch');
+    return lines.join('\n');
+}
+export function isStructuredApplyPatchPayload(candidate) {
+    if (!candidate || typeof candidate !== 'object') {
+        return false;
+    }
+    const record = candidate;
+    if (!Array.isArray(record.changes)) {
+        return false;
+    }
+    return true;
+}

package/dist/tools/tool-description-utils.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeToolName(value: unknown): string;
+export declare function isShellToolName(value: unknown): boolean;
+export declare function hasApplyPatchToolDeclared(tools: unknown[] | undefined): boolean;
+export declare function buildShellDescription(toolDisplayName: string, hasApplyPatch: boolean): string;
+export declare function appendApplyPatchReminder(description: string, hasApplyPatch: boolean): string;