@jsonstudio/llms 0.6.1643 → 0.6.1739

package/dist/conversion/compat/actions/harvest-tool-calls-from-text.d.ts

@@ -0,0 +1,10 @@
+import type { JsonObject } from '../../hub/types/json.js';
+/**
+ * Harvest tool calls from assistant textual markup into OpenAI `tool_calls`.
+ *
+ * Some upstreams (including certain iFlow/hosted models) emit tool calls as plain text tokens
+ * (e.g. `<|tool_call_begin|> ...`) instead of structured `tool_calls`.
+ *
+ * This action is response-only and provider-scoped via compatibility profiles.
+ */
+export declare function harvestToolCallsFromText(payload: JsonObject): JsonObject;

package/dist/conversion/compat/actions/harvest-tool-calls-from-text.js

@@ -0,0 +1,121 @@
+import { normalizeAssistantTextToToolCalls } from '../../shared/text-markup-normalizer.js';
+import { normalizeFunctionCallId } from '../../shared/bridge-id-utils.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function pickString(...candidates) {
+    for (const c of candidates) {
+        if (typeof c === 'string' && c.trim().length)
+            return c.trim();
+    }
+    return undefined;
+}
+function extractResponsesMessageText(item) {
+    const parts = [];
+    const content = Array.isArray(item.content) ? item.content : [];
+    for (const part of content) {
+        if (!part || typeof part !== 'object' || Array.isArray(part))
+            continue;
+        const text = pickString(part.text, part.content, part.value);
+        if (text)
+            parts.push(text);
+    }
+    if (typeof item.output_text === 'string' && item.output_text.trim().length) {
+        parts.push(String(item.output_text));
+    }
+    return parts.join('\n').trim();
+}
+function harvestToolCallsFromResponsesPayloadInPlace(root) {
+    const output = Array.isArray(root.output) ? root.output : [];
+    if (!output.length)
+        return false;
+    let changed = false;
+    const nextOutput = [];
+    for (const item of output) {
+        if (!isRecord(item)) {
+            nextOutput.push(item);
+            continue;
+        }
+        const type = typeof item.type === 'string' ? String(item.type).trim().toLowerCase() : '';
+        if (type !== 'message') {
+            nextOutput.push(item);
+            continue;
+        }
+        const role = typeof item.role === 'string' ? String(item.role).trim().toLowerCase() : 'assistant';
+        if (role !== 'assistant') {
+            nextOutput.push(item);
+            continue;
+        }
+        const text = extractResponsesMessageText(item);
+        if (!text) {
+            nextOutput.push(item);
+            continue;
+        }
+        const normalized = normalizeAssistantTextToToolCalls({ role: 'assistant', content: text });
+        const toolCalls = Array.isArray(normalized.tool_calls) ? normalized.tool_calls : [];
+        if (!toolCalls.length) {
+            nextOutput.push(item);
+            continue;
+        }
+        // Drop the original assistant message item (it usually only contains the tool markup),
+        // and append canonical Responses function_call output items.
+        changed = true;
+        for (const call of toolCalls) {
+            if (!call || typeof call !== 'object')
+                continue;
+            const fn = call.function && typeof call.function === 'object' ? call.function : null;
+            const name = typeof fn?.name === 'string' ? String(fn.name).trim() : '';
+            if (!name)
+                continue;
+            const args = typeof fn?.arguments === 'string' ? String(fn.arguments) : '{}';
+            const callId = pickString(call.call_id, call.id) ?? `call_${Math.random().toString(36).slice(2, 10)}`;
+            const itemId = normalizeFunctionCallId({ callId, fallback: `fc_${callId}` });
+            nextOutput.push({
+                type: 'function_call',
+                id: itemId,
+                call_id: callId,
+                name,
+                arguments: args
+            });
+        }
+    }
+    if (changed) {
+        root.output = nextOutput;
+    }
+    return changed;
+}
+/**
+ * Harvest tool calls from assistant textual markup into OpenAI `tool_calls`.
+ *
+ * Some upstreams (including certain iFlow/hosted models) emit tool calls as plain text tokens
+ * (e.g. `<|tool_call_begin|> ...`) instead of structured `tool_calls`.
+ *
+ * This action is response-only and provider-scoped via compatibility profiles.
+ */
+export function harvestToolCallsFromText(payload) {
+    const root = structuredClone(payload);
+    const choices = Array.isArray(root.choices) ? root.choices : [];
+    // Responses provider payload: harvest into canonical Responses output items first.
+    // This allows the normal semantic mapper (Responses → Chat) to surface tool_calls for servertool orchestration.
+    if (!choices.length) {
+        harvestToolCallsFromResponsesPayloadInPlace(root);
+        return root;
+    }
+    for (const choice of choices) {
+        if (!isRecord(choice))
+            continue;
+        const message = choice.message;
+        if (!isRecord(message))
+            continue;
+        const normalized = normalizeAssistantTextToToolCalls(message);
+        if (normalized !== message) {
+            choice.message = normalized;
+            const hasToolCalls = Array.isArray(normalized.tool_calls) && normalized.tool_calls.length > 0;
+            if (hasToolCalls) {
+                const finish = typeof choice.finish_reason === 'string' ? String(choice.finish_reason).trim() : '';
+                if (!finish || finish === 'stop') {
+                    choice.finish_reason = 'tool_calls';
+                }
+            }
+        }
+    }
+    return root;
+}

package/dist/conversion/compat/actions/iflow-kimi-cli-defaults.d.ts

@@ -0,0 +1,10 @@
+import type { JsonObject } from '../../hub/types/json.js';
+/**
+ * iFlow/Kimi request defaults aligned with iflow-cli:
+ * - thinking enabled path: temperature=1
+ * - thinking disabled path: temperature=0.6
+ * - shared defaults: top_p=0.95, n=1, penalties=0, max_new_tokens=max_tokens
+ *
+ * RouteCodex keeps thinking enabled by default for kimi-k2.5 unless explicitly disabled.
+ */
+export declare function applyIflowKimiCliDefaults(payload: JsonObject): JsonObject;

package/dist/conversion/compat/actions/iflow-kimi-cli-defaults.js

@@ -0,0 +1,80 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeModel(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+function isKimiK25Model(value) {
+    const model = normalizeModel(value);
+    return model === 'kimi-k2.5' || model.startsWith('kimi-k2.5-');
+}
+function mirrorMaxTokens(record) {
+    const maxTokens = record.max_tokens;
+    if (typeof maxTokens === 'number' && Number.isFinite(maxTokens) && maxTokens > 0) {
+        record.max_new_tokens = Math.floor(maxTokens);
+    }
+}
+function isThinkingExplicitlyDisabled(value) {
+    if (value === false) {
+        return true;
+    }
+    if (!isRecord(value)) {
+        return false;
+    }
+    const enabled = value.enabled;
+    if (enabled === false) {
+        return true;
+    }
+    const type = typeof value.type === 'string' ? value.type.trim().toLowerCase() : '';
+    return type === 'disabled' || type === 'off';
+}
+function normalizeThinkingForKimi(record) {
+    const current = record.thinking;
+    if (current === undefined || current === null) {
+        record.thinking = { type: 'enabled' };
+        return true;
+    }
+    if (current === true) {
+        record.thinking = { type: 'enabled' };
+        return true;
+    }
+    if (isThinkingExplicitlyDisabled(current)) {
+        return false;
+    }
+    if (isRecord(current)) {
+        if (typeof current.type !== 'string' || current.type.trim().length === 0) {
+            current.type = 'enabled';
+        }
+    }
+    return true;
+}
+/**
+ * iFlow/Kimi request defaults aligned with iflow-cli:
+ * - thinking enabled path: temperature=1
+ * - thinking disabled path: temperature=0.6
+ * - shared defaults: top_p=0.95, n=1, penalties=0, max_new_tokens=max_tokens
+ *
+ * RouteCodex keeps thinking enabled by default for kimi-k2.5 unless explicitly disabled.
+ */
+export function applyIflowKimiCliDefaults(payload) {
+    try {
+        if (!isRecord(payload)) {
+            return payload;
+        }
+        const root = structuredClone(payload);
+        if (!isKimiK25Model(root.model)) {
+            return root;
+        }
+        const thinkingEnabled = normalizeThinkingForKimi(root);
+        root.temperature = thinkingEnabled ? 1 : 0.6;
+        root.top_p = 0.95;
+        root.n = 1;
+        root.presence_penalty = 0;
+        root.frequency_penalty = 0;
+        mirrorMaxTokens(root);
+        return root;
+    }
+    catch {
+        return payload;
+    }
+}

package/dist/conversion/compat/actions/iflow-kimi-history-media-placeholder.d.ts

@@ -0,0 +1,7 @@
+import type { JsonObject } from '../../hub/types/json.js';
+/**
+ * iFlow/Kimi multimodal compat:
+ * - Preserve latest user turn media payload.
+ * - Replace historical inline-base64 image/video parts with text placeholders.
+ */
+export declare function applyIflowKimiHistoryMediaPlaceholder(payload: JsonObject): JsonObject;

package/dist/conversion/compat/actions/iflow-kimi-history-media-placeholder.js

@@ -0,0 +1,161 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function detectMediaKind(part) {
+    const typeValue = typeof part.type === 'string' ? part.type.trim().toLowerCase() : '';
+    if (!typeValue) {
+        return null;
+    }
+    if (typeValue.includes('video')) {
+        return 'video';
+    }
+    if (typeValue.includes('image')) {
+        return 'image';
+    }
+    return null;
+}
+function isInlineBase64(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    if (normalized.startsWith('data:') && normalized.includes(';base64,')) {
+        return true;
+    }
+    if (normalized.startsWith('base64,')) {
+        return true;
+    }
+    return false;
+}
+function mediaPartCarriesInlineBase64(part) {
+    const candidates = [];
+    const imageUrl = part.image_url;
+    const videoUrl = part.video_url;
+    if (typeof imageUrl === 'string') {
+        candidates.push(imageUrl);
+    }
+    if (typeof videoUrl === 'string') {
+        candidates.push(videoUrl);
+    }
+    if (isRecord(imageUrl)) {
+        const url = typeof imageUrl.url === 'string' ? imageUrl.url : '';
+        const data = typeof imageUrl.data === 'string' ? String(imageUrl.data) : '';
+        const base64 = typeof imageUrl.base64 === 'string'
+            ? String(imageUrl.base64)
+            : '';
+        if (url)
+            candidates.push(url);
+        if (data)
+            candidates.push(data);
+        if (base64)
+            candidates.push(`base64,${base64}`);
+    }
+    if (isRecord(videoUrl)) {
+        const url = typeof videoUrl.url === 'string' ? videoUrl.url : '';
+        const data = typeof videoUrl.data === 'string' ? String(videoUrl.data) : '';
+        const base64 = typeof videoUrl.base64 === 'string'
+            ? String(videoUrl.base64)
+            : '';
+        if (url)
+            candidates.push(url);
+        if (data)
+            candidates.push(data);
+        if (base64)
+            candidates.push(`base64,${base64}`);
+    }
+    const url = typeof part.url === 'string' ? String(part.url) : '';
+    const uri = typeof part.uri === 'string' ? String(part.uri) : '';
+    const data = typeof part.data === 'string' ? String(part.data) : '';
+    const base64 = typeof part.base64 === 'string' ? String(part.base64) : '';
+    if (url)
+        candidates.push(url);
+    if (uri)
+        candidates.push(uri);
+    if (data)
+        candidates.push(data);
+    if (base64)
+        candidates.push(`base64,${base64}`);
+    return candidates.some((value) => isInlineBase64(value));
+}
+function buildPlaceholderPart(kind) {
+    return {
+        type: 'text',
+        text: kind === 'video' ? '[history_video_base64_omitted]' : '[history_image_base64_omitted]'
+    };
+}
+/**
+ * iFlow/Kimi multimodal compat:
+ * - Preserve latest user turn media payload.
+ * - Replace historical inline-base64 image/video parts with text placeholders.
+ */
+export function applyIflowKimiHistoryMediaPlaceholder(payload) {
+    try {
+        if (!isRecord(payload)) {
+            return payload;
+        }
+        const root = structuredClone(payload);
+        const model = typeof root.model === 'string' ? root.model.trim().toLowerCase() : '';
+        if (model !== 'kimi-k2.5') {
+            return root;
+        }
+        const messagesValue = root.messages;
+        if (!Array.isArray(messagesValue) || !messagesValue.length) {
+            return root;
+        }
+        const messages = messagesValue.map((item) => (isRecord(item) ? item : null));
+        let latestUserIndex = -1;
+        for (let index = messages.length - 1; index >= 0; index -= 1) {
+            const message = messages[index];
+            if (!message)
+                continue;
+            const role = typeof message.role === 'string' ? message.role.trim().toLowerCase() : '';
+            if (role === 'user') {
+                latestUserIndex = index;
+                break;
+            }
+        }
+        if (latestUserIndex <= 0) {
+            return root;
+        }
+        const nextMessages = [];
+        for (let index = 0; index < messages.length; index += 1) {
+            const message = messages[index];
+            if (!message)
+                continue;
+            if (index >= latestUserIndex) {
+                nextMessages.push(message);
+                continue;
+            }
+            const contentValue = message.content;
+            if (!Array.isArray(contentValue)) {
+                nextMessages.push(message);
+                continue;
+            }
+            let changed = false;
+            const nextContent = contentValue.map((part) => {
+                if (!isRecord(part)) {
+                    return part;
+                }
+                const mediaKind = detectMediaKind(part);
+                if (!mediaKind) {
+                    return part;
+                }
+                if (!mediaPartCarriesInlineBase64(part)) {
+                    return part;
+                }
+                changed = true;
+                return buildPlaceholderPart(mediaKind);
+            });
+            if (!changed) {
+                nextMessages.push(message);
+                continue;
+            }
+            nextMessages.push({ ...message, content: nextContent });
+        }
+        root.messages = nextMessages;
+        return root;
+    }
+    catch {
+        return payload;
+    }
+}

package/dist/conversion/compat/actions/iflow-kimi-thinking-reasoning-fill.d.ts

@@ -0,0 +1,12 @@
+import type { JsonObject } from '../../hub/types/json.js';
+/**
+ * iFlow/Kimi compat:
+ * When thinking is active, iFlow requires reasoning_content to exist (and be non-empty)
+ * on assistant tool-call messages. Some tool-call surfaces omit it, causing 400 validation errors.
+ *
+ * We only apply this for kimi-k2.5 to avoid affecting other models.
+ *
+ * Note: responses→chat bridging may omit top-level thinking while upstream Kimi still
+ * enforces this contract. So for kimi-k2.5 we inject unless thinking is explicitly disabled.
+ */
+export declare function fillIflowKimiThinkingReasoningContent(payload: JsonObject): JsonObject;

package/dist/conversion/compat/actions/iflow-kimi-thinking-reasoning-fill.js

@@ -0,0 +1,67 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasNonEmptyArray(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+function isThinkingDisabled(value) {
+    if (value === false)
+        return true;
+    if (!isRecord(value))
+        return false;
+    const enabled = value.enabled;
+    if (enabled === false)
+        return true;
+    const type = typeof value.type === 'string' ? String(value.type).trim().toLowerCase() : '';
+    if (type === 'disabled' || type === 'off')
+        return true;
+    return false;
+}
+/**
+ * iFlow/Kimi compat:
+ * When thinking is active, iFlow requires reasoning_content to exist (and be non-empty)
+ * on assistant tool-call messages. Some tool-call surfaces omit it, causing 400 validation errors.
+ *
+ * We only apply this for kimi-k2.5 to avoid affecting other models.
+ *
+ * Note: responses→chat bridging may omit top-level thinking while upstream Kimi still
+ * enforces this contract. So for kimi-k2.5 we inject unless thinking is explicitly disabled.
+ */
+export function fillIflowKimiThinkingReasoningContent(payload) {
+    try {
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            return payload;
+        }
+        const root = structuredClone(payload);
+        const model = typeof root.model === 'string' ? root.model.trim().toLowerCase() : '';
+        if (!(model === 'kimi-k2.5' || model.startsWith('kimi-k2.5-'))) {
+            return root;
+        }
+        if (isThinkingDisabled(root.thinking)) {
+            return root;
+        }
+        const messages = Array.isArray(root.messages) ? root.messages : [];
+        if (!messages.length) {
+            return root;
+        }
+        for (const msg of messages) {
+            if (!isRecord(msg))
+                continue;
+            const role = typeof msg.role === 'string' ? msg.role.trim().toLowerCase() : '';
+            if (role !== 'assistant')
+                continue;
+            if (!hasNonEmptyArray(msg.tool_calls))
+                continue;
+            const rc = msg.reasoning_content;
+            const rcText = typeof rc === 'string' ? rc : '';
+            if (!rcText || !rcText.trim()) {
+                msg.reasoning_content = '.';
+            }
+        }
+        root.messages = messages;
+        return root;
+    }
+    catch {
+        return payload;
+    }
+}

package/dist/conversion/compat/actions/iflow-response-body-unwrap.d.ts

@@ -0,0 +1,9 @@
+import type { JsonObject } from '../../hub/types/json.js';
+/**
+ * iFlow compatibility: some iFlow backends wrap OpenAI-compatible payloads inside:
+ *   { status, msg, body, request_id }
+ * where `body` is the actual OpenAI-chat/Responses JSON (or a JSON string).
+ *
+ * This action unwraps `body` so hub semantic mapping and tool harvesting can proceed.
+ */
+export declare function unwrapIflowResponseBodyEnvelope(payload: JsonObject): JsonObject;

package/dist/conversion/compat/actions/iflow-response-body-unwrap.js

@@ -0,0 +1,140 @@
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function looksLikeKnownProviderResponseShape(value) {
+    if (!isRecord(value))
+        return false;
+    if (Array.isArray(value.choices))
+        return true; // openai-chat
+    if (Array.isArray(value.output) || value.object === 'response')
+        return true; // openai-responses
+    if (typeof value.type === 'string' && String(value.type).toLowerCase() === 'message' && Array.isArray(value.content)) {
+        return true; // anthropic-messages
+    }
+    if (Array.isArray(value.candidates))
+        return true; // gemini-chat
+    return false;
+}
+function stripJsonTextPrefix(text) {
+    let out = String(text || '').trimStart();
+    // anti-XSSI prefix: ")]}',\n{...}"
+    out = out.replace(/^\)\]\}',?\s*/u, '');
+    // single-line SSE-like wrapper sometimes returned as plain text
+    out = out.replace(/^data:\s*/iu, '');
+    return out;
+}
+function tryParseJsonRecord(text) {
+    try {
+        const trimmed = stripJsonTextPrefix(text).trim();
+        if (!trimmed)
+            return null;
+        if (trimmed.length > 10 * 1024 * 1024)
+            return null;
+        const first = trimmed.charAt(0);
+        const last = trimmed.charAt(trimmed.length - 1);
+        if ((first !== '{' && first !== '[') || (last !== '}' && last !== ']')) {
+            return null;
+        }
+        const parsed = JSON.parse(trimmed);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function tryParseJsonRecordFromMaybeSseText(text) {
+    if (typeof text !== 'string') {
+        return null;
+    }
+    const raw = stripJsonTextPrefix(text);
+    const direct = tryParseJsonRecord(raw);
+    if (direct) {
+        return direct;
+    }
+    // Multi-line SSE text occasionally shows up as a plain string inside iFlow envelopes.
+    // Best-effort: parse the last valid `data:` JSON object chunk.
+    if (raw.length > 10 * 1024 * 1024) {
+        return null;
+    }
+    const lines = raw.split(/\r?\n/u);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = lines[i]?.trim();
+        if (!line)
+            continue;
+        const lower = line.toLowerCase();
+        if (lower === 'data: [done]' || lower === '[done]')
+            continue;
+        const candidate = lower.startsWith('data:') ? line.slice(5).trim() : line;
+        const parsed = tryParseJsonRecord(candidate);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function tryUnwrapKnownShapeFromBody(value, depth) {
+    if (depth < 0)
+        return null;
+    if (looksLikeKnownProviderResponseShape(value)) {
+        return value;
+    }
+    if (isRecord(value)) {
+        // nested body/data wrappers
+        for (const key of ['data', 'body', 'response', 'payload', 'result']) {
+            const nested = value[key];
+            const unwrapped = tryUnwrapKnownShapeFromBody(nested, depth - 1);
+            if (unwrapped)
+                return unwrapped;
+        }
+        return null;
+    }
+    if (typeof value === 'string') {
+        const parsed = tryParseJsonRecord(value) ?? tryParseJsonRecordFromMaybeSseText(value);
+        if (!parsed)
+            return null;
+        return tryUnwrapKnownShapeFromBody(parsed, depth - 1);
+    }
+    return null;
+}
+/**
+ * iFlow compatibility: some iFlow backends wrap OpenAI-compatible payloads inside:
+ *   { status, msg, body, request_id }
+ * where `body` is the actual OpenAI-chat/Responses JSON (or a JSON string).
+ *
+ * This action unwraps `body` so hub semantic mapping and tool harvesting can proceed.
+ */
+export function unwrapIflowResponseBodyEnvelope(payload) {
+    try {
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            return payload;
+        }
+        const root = structuredClone(payload);
+        // Only unwrap when it looks like the iFlow envelope.
+        if (!('body' in root) || !('status' in root) || !('msg' in root)) {
+            return root;
+        }
+        // If the root is already a known provider response, don't touch it.
+        if (looksLikeKnownProviderResponseShape(root)) {
+            return root;
+        }
+        const body = root.body;
+        const unwrapped = tryUnwrapKnownShapeFromBody(body, 6);
+        if (unwrapped) {
+            return unwrapped;
+        }
+        // Fallback: unwrap to `body` even when we can't yet recognize the nested shape.
+        // This avoids treating the iFlow envelope as the provider payload and improves
+        // downstream diagnostics / error handling.
+        if (isRecord(body)) {
+            return body;
+        }
+        if (typeof body === 'string') {
+            const parsed = tryParseJsonRecordFromMaybeSseText(body);
+            if (parsed) {
+                return parsed;
+            }
+        }
+        return root;
+    }
+    catch {
+        return payload;
+    }
+}

package/dist/conversion/compat/actions/lmstudio-responses-fc-ids.d.ts

@@ -0,0 +1,10 @@
+import type { JsonObject } from '../../hub/types/json.js';
+/**
+ * LM Studio compat:
+ * Some LM Studio OpenAI-Responses endpoints accept tool-call items but are picky about ids:
+ * - `call_id` should remain `call_*` (used to link tool outputs)
+ * - `id` for `function_call` / `function_call_output` should be `fc_*` (OpenAI Responses convention)
+ *
+ * We apply this in compat (profile: chat:lmstudio) to keep provider layer transport-only.
+ */
+export declare function enforceLmstudioResponsesFcToolCallIds(payload: JsonObject): JsonObject;