@jsonstudio/llms 0.4.2

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

@@ -0,0 +1,269 @@
+// Unified tool governance API (标准)
+// Centralizes tool augmentation, guidance injection/refinement, and textual→tool_calls canonicalization
+function isObject(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+// Note: tool schema strict augmentation removed per alignment
+function enforceChatBudget(chat, _modelId) { return chat; }
+function tryWriteSnapshot(options, stage, data) {
+    try {
+        // 仅在 verbose 级别保存快照（环境变量）
+        const envLevel = String(process.env.RCC_HOOKS_VERBOSITY || process.env.ROUTECODEX_HOOKS_VERBOSITY || '').toLowerCase();
+        const isVerbose = envLevel === 'verbose';
+        if (!isVerbose)
+            return;
+        const snap = options?.snapshot;
+        if (!snap || snap.enabled === false)
+            return;
+        const os = require('os');
+        const fs = require('fs');
+        const path = require('path');
+        const home = os.homedir?.() || process.env.HOME || '';
+        const base = snap.baseDir || path.join(home, '.routecodex', 'codex-samples');
+        const ep = String(snap.endpoint || 'chat').toLowerCase();
+        const group = ep.includes('responses') ? 'openai-responses' : ep.includes('messages') ? 'anthropic-messages' : 'openai-chat';
+        const rid = String(snap.requestId || `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`);
+        const dir = path.join(base, group);
+        const file = path.join(dir, `${rid}_govern-${stage}.json`);
+        if (fs.existsSync(file))
+            return; // 不重复
+        fs.mkdirSync(dir, { recursive: true });
+        const payload = JSON.stringify(data, null, 2);
+        fs.writeFileSync(file, payload, 'utf-8');
+    }
+    catch { /* ignore snapshot errors */ }
+}
+/**
+ * Process OpenAI Chat request (messages/tools) with unified 标准 governance.
+ * - Augment tools (strict schemas)
+ * - Inject/Refine system tool guidance (idempotent)
+ * - Canonicalize textual tool markup to tool_calls; set content=null when applicable
+ */
+export function processChatRequestTools(request, opts) {
+    const options = { ...(opts || {}) };
+    if (!isObject(request))
+        return request;
+    const out = JSON.parse(JSON.stringify(request));
+    // tools 形状最小修复：为缺失 function.parameters 的工具补一个空对象，避免上游
+    // Responses/OpenAI 校验 422（外部错误必须暴露，但这里属于规范化入口）。
+    try {
+        const tools = Array.isArray(out?.tools) ? out.tools : [];
+        if (tools.length > 0) {
+            for (const t of tools) {
+                if (!t || typeof t !== 'object')
+                    continue;
+                const fn = t.function;
+                if (!fn || typeof fn !== 'object')
+                    continue;
+                const typeStr = String(t.type || '').toLowerCase();
+                const nameStr = typeof fn.name === 'string' ? String(fn.name).toLowerCase() : '';
+                const shouldPatch = typeStr === 'function' ||
+                    nameStr === 'apply_patch';
+                if (!shouldPatch)
+                    continue;
+                if (!Object.prototype.hasOwnProperty.call(fn, 'parameters')) {
+                    t.function = { ...fn, parameters: {} };
+                }
+            }
+        }
+    }
+    catch { /* best-effort: 保持原样 */ }
+    // 1) 移除工具 schema 严格化（与 统一标准，不在此处约束 tools 结构）
+    // NOTE: system guidance injection removed by design (align with parameter-level strategy)
+    try {
+        // 请求侧不再对历史消息做 shell 形状包装；仅维持最小字符串化等轻度修复
+        const canonical = out;
+        // 3.1) tool_choice 策略（与标准 tooluse 对齐）：对特定模型可设置 required；默认 auto
+        try {
+            const modelId = typeof canonical?.model === 'string' ? String(canonical.model) : 'unknown';
+            const raw = String(process?.env?.RCC_TOOL_CHOICE_REQUIRED || '').trim();
+            const wanted = raw ? raw.split(',').map((s) => s.trim()).filter(Boolean) : [];
+            if (Array.isArray(canonical?.tools) && canonical.tools.length > 0) {
+                // default auto
+                if (!canonical.tool_choice)
+                    canonical.tool_choice = 'auto';
+                if (wanted.length > 0 && wanted.some((p) => modelId.includes(p))) {
+                    canonical.tool_choice = 'required';
+                }
+            }
+        }
+        catch { /* ignore */ }
+        // 4) Enforce payload budget (context bytes) with minimal loss policy
+        const modelId = typeof canonical?.model === 'string' ? String(canonical.model) : 'unknown';
+        return enforceChatBudget(canonical, modelId);
+    }
+    catch {
+        return out;
+    }
+}
+/**
+ * Process OpenAI Chat response (choices[0].message) with unified 标准 governance.
+ * - Canonicalize textual tool markup to tool_calls; ensure finish_reason and content=null policy
+ */
+import { repairArgumentsToString, parseLenient } from './jsonish.js';
+function enhanceResponseToolArguments(chat) {
+    try {
+        const enable = String(process?.env?.RCC_TOOL_ENHANCE ?? '1').trim() !== '0';
+        if (!enable)
+            return chat;
+        const out = JSON.parse(JSON.stringify(chat));
+        const choices = Array.isArray(out?.choices) ? out.choices : [];
+        for (const ch of choices) {
+            const msg = ch && ch.message ? ch.message : undefined;
+            const tcs = Array.isArray(msg?.tool_calls) ? msg.tool_calls : [];
+            if (!tcs.length)
+                continue;
+            // Helpers for shell normalization (idempotent, aligned with ResponseToolArgumentsStringifyFilter)
+            const toStr = (v) => String(v);
+            const isBashLc = (arr) => arr.length >= 2 && arr[0] === 'bash' && arr[1] === '-lc';
+            const hasMetaToken = (arr) => {
+                const metas = ['|', '>', '>>', '<', '<<', ';', '&&', '||', '(', ')'];
+                return arr.some(t => {
+                    const s = String(t);
+                    if (metas.includes(s))
+                        return true;
+                    return /[|<>;&]/.test(s) || s.includes('&&') || s.includes('||') || s.includes('<<');
+                });
+            };
+            const repairFindMeta = (s) => {
+                try {
+                    const hasFind = /(^|\s)find\s/.test(s);
+                    if (!hasFind)
+                        return s;
+                    let out = s;
+                    out = out.replace(/-exec([^;]*?)(?<!\\);/g, (_m, g1) => `-exec${g1} \\;`);
+                    out = out.replace(/-exec([^;]*?)\\+;/g, (_m, g1) => `-exec${g1} \\;`);
+                    out = out.replace(/(?<!\\)\(/g, '\\(').replace(/(?<!\\)\)/g, '\\)');
+                    return out;
+                }
+                catch {
+                    return s;
+                }
+            };
+            for (const tc of tcs) {
+                try {
+                    const fn = tc && tc.function ? tc.function : undefined;
+                    const name = typeof fn?.name === 'string' ? String(fn.name).toLowerCase() : '';
+                    const argIn = fn?.arguments;
+                    const repaired = repairArgumentsToString(argIn);
+                    // Default to repaired JSON string
+                    let finalStr = repaired;
+                    // Extra normalization for shell
+                    if (name === 'shell') {
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(repaired);
+                        }
+                        catch {
+                            parsed = parseLenient(repaired);
+                        }
+                        if (parsed && typeof parsed === 'object') {
+                            const cmd = parsed.command;
+                            if (Array.isArray(cmd)) {
+                                const tokens = cmd.map(toStr);
+                                if (isBashLc(tokens)) {
+                                    const joined = tokens.slice(2).join(' ');
+                                    parsed.command = ['bash', '-lc', repairFindMeta(joined)];
+                                }
+                                else if (hasMetaToken(tokens)) {
+                                    parsed.command = ['bash', '-lc', repairFindMeta(tokens.join(' '))];
+                                }
+                            }
+                            else if (typeof cmd === 'string') {
+                                const s = cmd.trim();
+                                const hasMeta = /[|<>;&]/.test(s) || s.includes('&&') || s.includes('||') || s.includes('<<');
+                                if (hasMeta && !/^\s*bash\s+-lc\s+/.test(s)) {
+                                    parsed.command = ['bash', '-lc', repairFindMeta(s)];
+                                }
+                                else if (hasMeta && /^\s*bash\s+-lc\s+/.test(s)) {
+                                    // Already wrapped but ensure idempotent repairs
+                                    const body = s.replace(/^\s*bash\s+-lc\s+/, '');
+                                    parsed.command = ['bash', '-lc', repairFindMeta(body)];
+                                }
+                            }
+                            try {
+                                finalStr = JSON.stringify(parsed);
+                            }
+                            catch {
+                                finalStr = repaired;
+                            }
+                        }
+                    }
+                    if (fn)
+                        fn.arguments = finalStr;
+                }
+                catch { /* keep original */ }
+            }
+            // Ensure finish_reason/tool_calls invariant if missing (idempotent with canonicalizer)
+            try {
+                if (!ch.finish_reason)
+                    ch.finish_reason = 'tool_calls';
+            }
+            catch { /* ignore */ }
+            try {
+                if (msg && typeof msg === 'object' && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0)
+                    msg.content = null;
+            }
+            catch { /* ignore */ }
+        }
+        return out;
+    }
+    catch {
+        return chat;
+    }
+}
+export function processChatResponseTools(resp) {
+    if (!isObject(resp))
+        return resp;
+    try {
+        const { canonicalizeChatResponseTools } = require('./tool-canonicalizer.js');
+        const canon = canonicalizeChatResponseTools(resp);
+        return enhanceResponseToolArguments(canon);
+    }
+    catch {
+        return resp;
+    }
+}
+// Unified, 对齐 governance entry
+export function governTools(payload, ctx) {
+    const phase = ctx?.phase || 'request';
+    const ep = ctx?.endpoint || 'chat';
+    if (phase === 'request') {
+        return processChatRequestTools(payload, {
+            injectGuidance: ctx?.injectGuidance !== false,
+            snapshot: ctx?.snapshot || { enabled: true, endpoint: ep, requestId: ctx?.requestId }
+        });
+    }
+    // response phase
+    // 变更前快照：响应侧 canonicalize 之前
+    try {
+        const opts = { snapshot: ctx?.snapshot || { enabled: true, endpoint: ep, requestId: ctx?.requestId } };
+        tryWriteSnapshot(opts, 'response_before_canonicalize', payload);
+    }
+    catch { /* ignore */ }
+    let out = processChatResponseTools(payload);
+    // 变更后快照：响应侧 canonicalize 之后
+    try {
+        const opts = { snapshot: ctx?.snapshot || { enabled: true, endpoint: ep, requestId: ctx?.requestId } };
+        tryWriteSnapshot(opts, 'response_after_canonicalize', out);
+    }
+    catch { /* ignore */ }
+    if (ep === 'responses' && ctx?.stream !== true && ctx?.produceRequiredAction !== false) {
+        // 变更前快照：构造 required_action 之前
+        try {
+            const opts = { snapshot: ctx?.snapshot || { enabled: true, endpoint: ep, requestId: ctx?.requestId } };
+            tryWriteSnapshot(opts, 'response_before_required_action', out);
+        }
+        catch { /* ignore */ }
+        try {
+            const { buildResponsesPayloadFromChat } = require('../responses/responses-openai-bridge.js');
+            const res = buildResponsesPayloadFromChat(out, { requestId: ctx?.requestId });
+            try {
+                const opts = { snapshot: ctx?.snapshot || { enabled: true, endpoint: ep, requestId: ctx?.requestId } };
+                tryWriteSnapshot(opts, 'response_after_required_action', res);
+            }
+            catch { /* ignore */ }
+            return res;
+        }
+        catch { /* ignore mapping errors and return canonicalized chat */ }
+    }
+    return out;
+}

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

@@ -0,0 +1,31 @@
+type Unknown = Record<string, unknown>;
+export interface HarvestContext {
+    requestId?: string;
+    idPrefix?: string;
+    chunkSize?: number;
+    source?: 'chat' | 'responses' | 'messages';
+}
+export interface HarvestSignal {
+    type: 'delta' | 'final' | 'compat';
+    payload: Unknown;
+}
+export interface DeltaEvent {
+    tool_calls?: Array<{
+        index: number;
+        id: string;
+        type: 'function';
+        function: {
+            name?: string;
+            arguments?: string;
+        };
+    }>;
+    content?: string;
+    role?: string;
+}
+export interface HarvestResult {
+    deltaEvents: DeltaEvent[];
+    normalized?: Unknown;
+    stats?: Unknown;
+}
+export declare function harvestTools(signal: HarvestSignal, ctx?: HarvestContext): HarvestResult;
+export {};

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

@@ -0,0 +1,321 @@
+// Unified tool harvesting (对齐, single entry)
+// - First-time harvesting only (no late-stage repair)
+// - Handles textual markers (<function=execute>, unified diff)
+// - Handles structural shapes (function_call legacy, tool_calls)
+// - Normalizes arguments (single JSON string), sets finish_reason when applicable
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+// Adjacent dedupe state (per request)
+const dedupeState = new Map();
+function hashString(s) {
+    try {
+        return require('crypto').createHash('sha1').update(s).digest('hex');
+    }
+    catch {
+        return String(s.length);
+    }
+}
+function toJsonString(v) {
+    if (typeof v === 'string')
+        return v;
+    try {
+        return JSON.stringify(v ?? {});
+    }
+    catch {
+        return '{}';
+    }
+}
+function genId(ctx, i = 0) {
+    const p = ctx?.idPrefix || 'call';
+    return `${p}_${Date.now()}_${(Math.random().toString(36).slice(2, 8))}_${i}`;
+}
+function chunkString(input, size) {
+    try {
+        const s = String(input ?? '');
+        if (!s)
+            return [];
+        const out = [];
+        for (let i = 0; i < s.length; i += size)
+            out.push(s.slice(i, i + size));
+        return out;
+    }
+    catch {
+        return [String(input ?? '')];
+    }
+}
+function extractFromTextual(content, ctx) {
+    const events = [];
+    if (typeof content !== 'string' || !content)
+        return events;
+    // 1) unified diff
+    const beginIdx = content.indexOf('*** Begin Patch');
+    const endIdx = content.indexOf('*** End Patch');
+    if (beginIdx >= 0 && endIdx > beginIdx) {
+        const patchText = content.slice(beginIdx, endIdx + '*** End Patch'.length);
+        const id = genId(ctx, 0);
+        const argStr = toJsonString({ patch: patchText });
+        events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { name: 'apply_patch' } }] });
+        const parts = chunkString(argStr, Math.max(32, Math.min(1024, ctx?.chunkSize || 256)));
+        for (const d of parts) {
+            events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { arguments: d } }] });
+        }
+        return events;
+    }
+    // 2) <function=execute>
+    const execRe = /<function=execute>[\s\S]*?<parameter=command>([\s\S]*?)<\/parameter>[\s\S]*?<\/function=execute>/i;
+    const mExec = execRe.exec(content);
+    if (mExec && mExec[1]) {
+        const cmdRaw = mExec[1].trim();
+        const argv = splitCommand(cmdRaw);
+        const id = genId(ctx, 0);
+        const argStr = toJsonString({ command: argv });
+        events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { name: 'shell' } }] });
+        const parts = chunkString(argStr, Math.max(32, Math.min(1024, ctx?.chunkSize || 256)));
+        for (const d of parts) {
+            events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { arguments: d } }] });
+        }
+        return events;
+    }
+    // 3) rcc.tool.v1 JSON envelope (removed)
+    // 4) Generic <tool_call> textual block with <arg_key>/<arg_value>
+    try {
+        // Explicit wrapper form
+        const blockRe = /<tool_call[^>]*>[\s\S]*?<\/tool_call>/gi;
+        const blocks = content.match(blockRe) || [];
+        let matched = false;
+        for (const b of blocks) {
+            const nameTag = /<tool_name>([\s\S]*?)<\/tool_name>/i.exec(b);
+            let nm = nameTag && nameTag[1] ? String(nameTag[1]).trim() : '';
+            if (!nm) {
+                if (/<arg_key>\s*command\s*<\/arg_key>/i.test(b))
+                    nm = 'shell';
+                else if (/\bapply_patch\b/i.test(b))
+                    nm = 'apply_patch';
+                else if (/\bupdate_plan\b/i.test(b))
+                    nm = 'update_plan';
+                else if (/\bview_image\b/i.test(b))
+                    nm = 'view_image';
+            }
+            const pairRe = /<arg_key>([\s\S]*?)<\/arg_key>\s*<arg_value>([\s\S]*?)<\/arg_value>/gi;
+            const argsObj = {};
+            let m;
+            while ((m = pairRe.exec(b)) !== null) {
+                const k = String((m[1] || '').trim());
+                const vRaw = (m[2] || '').trim();
+                let v = vRaw;
+                try {
+                    v = JSON.parse(vRaw);
+                }
+                catch { /* keep as string */ }
+                if (nm === 'shell' && k === 'command') {
+                    if (!Array.isArray(v))
+                        v = splitCommand(String(vRaw));
+                }
+                argsObj[k] = v;
+            }
+            if (nm) {
+                const id = genId(ctx, 0);
+                events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { name: nm } }] });
+                const argStr = toJsonString(argsObj);
+                const parts = chunkString(argStr, Math.max(32, Math.min(1024, ctx?.chunkSize || 256)));
+                for (const d of parts) {
+                    events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { arguments: d } }] });
+                }
+                matched = true;
+            }
+        }
+        if (matched)
+            return events;
+        // Inline fallback: e.g., 'shell\n<arg_key>command</arg_key>...'
+        const inlineRe = /(shell|apply_patch|update_plan|view_image)[\s\S]*?<arg_key>([\s\S]*?)<\/arg_key>\s*<arg_value>([\s\S]*?)<\/arg_value>/i;
+        const mi = inlineRe.exec(content);
+        if (mi) {
+            const nm = String(mi[1]).trim();
+            const k = String(mi[2]).trim();
+            const vRaw = String(mi[3]).trim();
+            let v = vRaw;
+            try {
+                v = JSON.parse(vRaw);
+            }
+            catch { /* keep as string */ }
+            const args = {};
+            if (nm === 'shell' && k === 'command') {
+                if (!Array.isArray(v))
+                    v = splitCommand(String(vRaw));
+            }
+            args[k] = v;
+            const id = genId(ctx, 0);
+            events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { name: nm } }] });
+            const argStr = toJsonString(args);
+            for (const d of chunkString(argStr, Math.max(32, Math.min(1024, ctx?.chunkSize || 256)))) {
+                events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { arguments: d } }] });
+            }
+            return events;
+        }
+    }
+    catch { /* ignore textual tool_call parse errors */ }
+    return events;
+}
+function splitCommand(s) {
+    try {
+        const out = [];
+        let cur = '';
+        let quote = null;
+        for (let i = 0; i < s.length; i++) {
+            const ch = s[i];
+            if (quote) {
+                if (ch === quote) {
+                    quote = null;
+                }
+                else {
+                    cur += ch;
+                }
+            }
+            else {
+                if (ch === '"' || ch === '\'') {
+                    quote = ch;
+                }
+                else if (/\s/.test(ch)) {
+                    if (cur) {
+                        out.push(cur);
+                        cur = '';
+                    }
+                }
+                else {
+                    cur += ch;
+                }
+            }
+        }
+        if (cur)
+            out.push(cur);
+        return out;
+    }
+    catch {
+        return [s];
+    }
+}
+export function harvestTools(signal, ctx) {
+    const result = { deltaEvents: [] };
+    const chunkSize = Math.max(32, Math.min(1024, ctx?.chunkSize || 256));
+    try {
+        if (signal.type === 'delta') {
+            // OpenAI streaming chunk delta
+            const delta = signal.payload;
+            const events = [];
+            const content = delta?.choices?.[0]?.delta?.content;
+            if (typeof content === 'string' && content.trim()) {
+                events.push(...extractFromTextual(content, ctx));
+            }
+            // legacy function_call → tool_calls
+            const fc = delta?.choices?.[0]?.delta?.function_call;
+            if (isObject(fc)) {
+                const name = typeof fc.name === 'string' ? fc.name : undefined;
+                const argStr = toJsonString(fc.arguments);
+                const id = genId(ctx, 0);
+                if (name) {
+                    events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { name } }] });
+                    for (const d of chunkString(argStr, chunkSize)) {
+                        events.push({ tool_calls: [{ index: 0, id, type: 'function', function: { arguments: d } }] });
+                    }
+                }
+            }
+            // direct delta.tool_calls
+            const tcd = delta?.choices?.[0]?.delta?.tool_calls;
+            if (Array.isArray(tcd)) {
+                let idx = 0;
+                for (const tc of tcd) {
+                    const id = typeof tc?.id === 'string' ? tc.id : genId(ctx, idx);
+                    const name = typeof tc?.function?.name === 'string' ? tc.function.name : undefined;
+                    const args = (tc?.function?.arguments !== undefined) ? toJsonString(tc.function.arguments) : undefined;
+                    // Adjacent dedupe per requestId
+                    const key = ctx?.requestId || 'default';
+                    const state = dedupeState.get(key) || {};
+                    const argsHash = typeof args === 'string' ? hashString(args) : undefined;
+                    const isDup = (state.name === name && state.argsHash && argsHash && state.argsHash === argsHash);
+                    if (!isDup) {
+                        if (name) {
+                            events.push({ tool_calls: [{ index: idx, id, type: 'function', function: { name } }] });
+                        }
+                        if (typeof args === 'string') {
+                            for (const d of chunkString(args, chunkSize)) {
+                                events.push({ tool_calls: [{ index: idx, id, type: 'function', function: { arguments: d } }] });
+                            }
+                        }
+                        dedupeState.set(key, { name, argsHash });
+                    }
+                    idx += 1;
+                }
+            }
+            result.deltaEvents = events;
+            return result;
+        }
+        // final/compat: normalize choices[0].message.tool_calls (no synthesis)
+        const src = signal.payload;
+        const choice = Array.isArray(src?.choices) ? src.choices[0] : null;
+        const msg = choice?.message || {};
+        const toolCalls = Array.isArray(msg?.tool_calls) ? msg.tool_calls : [];
+        if (toolCalls.length > 0) {
+            // Ensure arguments are stringified
+            for (const tc of toolCalls) {
+                const fn = tc.function || {};
+                if (fn && fn.arguments && typeof fn.arguments !== 'string') {
+                    fn.arguments = toJsonString(fn.arguments);
+                }
+            }
+            // finish_reason
+            if (choice && choice.finish_reason !== 'tool_calls') {
+                choice.finish_reason = 'tool_calls';
+            }
+            // content policy: set to empty string or null unchanged
+            result.normalized = src;
+            return result;
+        }
+        // If no structured tool_calls, attempt textual harvesting from message.content
+        try {
+            const content = msg?.content;
+            if (typeof content === 'string' && content.trim()) {
+                const evs = extractFromTextual(content, ctx);
+                if (Array.isArray(evs) && evs.length > 0) {
+                    // Aggregate deltaEvents into final tool_calls (group by id)
+                    const map = {};
+                    for (const e of evs) {
+                        const tcs = Array.isArray(e.tool_calls) ? e.tool_calls : [];
+                        for (const t of tcs) {
+                            const id = String(t.id || genId(ctx, 0));
+                            if (!map[id])
+                                map[id] = { name: undefined, args: [], type: 'function' };
+                            const nm = t.function?.name;
+                            const arg = t.function?.arguments;
+                            if (typeof nm === 'string' && !map[id].name)
+                                map[id].name = nm;
+                            if (typeof arg === 'string')
+                                map[id].args.push(arg);
+                        }
+                    }
+                    const merged = [];
+                    for (const [id, item] of Object.entries(map)) {
+                        const argStr = item.args.join('');
+                        merged.push({ id, type: 'function', function: { name: item.name, arguments: argStr } });
+                    }
+                    if (merged.length > 0) {
+                        msg.tool_calls = merged;
+                        // Clear textual content to avoid duplicate display
+                        msg.content = '';
+                        if (choice && choice.finish_reason !== 'tool_calls') {
+                            choice.finish_reason = 'tool_calls';
+                        }
+                        result.normalized = src;
+                        return result;
+                    }
+                }
+            }
+        }
+        catch { /* ignore textual harvest on final */ }
+        result.normalized = src;
+        return result;
+    }
+    catch {
+        return result;
+    }
+}

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

@@ -0,0 +1,10 @@
+export interface ToolCallFunction {
+    name: string;
+    arguments: string;
+}
+export interface ToolCallItem {
+    id?: string;
+    type: 'function';
+    function: ToolCallFunction;
+}
+export declare function stringifyArgs(args: unknown): string;

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

@@ -0,0 +1,10 @@
+export function stringifyArgs(args) {
+    if (typeof args === 'string')
+        return args;
+    try {
+        return JSON.stringify(args ?? {});
+    }
+    catch {
+        return String(args);
+    }
+}

package/dist/conversion/shared/tooling.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared helpers for standard tool normalization (shell packing rules).
+ * The goal is deterministic, minimal shaping so executors succeed consistently.
+ */
+export interface ShellArgs {
+    command: string | string[];
+    workdir?: string;
+    timeout_ms?: number;
+}
+export declare function splitCommandString(input: string): string[];
+/**
+ * Pack shell arguments per unified rules:
+ * - command: string -> ["bash","-lc","<string>"]
+ * - command: tokens[]
+ *   - if starts with ["cd", path, ...rest]:
+ *       - set workdir to path when absent
+ *       - if rest empty => command=["pwd"]
+ *       - else if rest has control tokens => command=["bash","-lc", join(rest)]
+ *       - else command=rest (argv)
+ *   - else if tokens contain control tokens => command=["bash","-lc", join(tokens)]
+ *   - else command=tokens (argv)
+ * - join(rest) uses single-space join without extra quoting
+ */
+export declare function packShellArgs(input: Record<string, unknown>): Record<string, unknown>;
+export declare function flattenByComma(arr: string[]): string[];
+export declare function chunkString(s: string, minParts?: number, maxParts?: number, targetChunk?: number): string[];