@jsonstudio/llms 0.4.5 → 0.6.0

package/dist/conversion/shared/reasoning-normalizer.js

@@ -6,26 +6,58 @@ function isRecord(value) {
     return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
 export function normalizeReasoningInChatPayload(payload) {
-    if (!payload || !Array.isArray(payload.messages)) {
+    if (!payload) {
         return;
     }
-    payload.messages = payload.messages.map((entry) => {
-        if (!entry || typeof entry !== 'object') {
-            return entry;
-        }
-        const msg = entry;
-        const normalized = normalizeChatMessageContent(msg.content);
-        if (normalized.contentText !== undefined) {
-            msg.content = normalized.contentText;
-        }
-        if (normalized.reasoningText && normalized.reasoningText.trim().length) {
-            msg.reasoning_content = normalized.reasoningText.trim();
-        }
-        else {
-            delete msg.reasoning_content;
-        }
-        return msg;
-    });
+    if (Array.isArray(payload.messages)) {
+        payload.messages = payload.messages.map(entry => normalizeChatMessageEntry(entry));
+    }
+    if (Array.isArray(payload.choices)) {
+        payload.choices.forEach(choice => {
+            normalizeChatChoice(choice);
+        });
+    }
+}
+function normalizeChatMessageEntry(entry) {
+    if (!entry || typeof entry !== 'object') {
+        return entry;
+    }
+    const msg = entry;
+    applyNormalizedChatContent(msg);
+    return msg;
+}
+function normalizeChatChoice(choice) {
+    if (!choice || typeof choice !== 'object') {
+        return;
+    }
+    const record = choice;
+    const containers = [];
+    if (record.message && typeof record.message === 'object') {
+        containers.push(record.message);
+    }
+    if (record.delta && typeof record.delta === 'object') {
+        containers.push(record.delta);
+    }
+    containers.forEach(container => applyNormalizedChatContent(container));
+}
+function applyNormalizedChatContent(container) {
+    const normalized = normalizeChatMessageContent(container.content);
+    const role = typeof container.role === 'string' ? container.role : undefined;
+    if (normalized.contentText !== undefined && normalized.contentText.trim().length) {
+        container.content = normalized.contentText;
+    }
+    else if (typeof container.reasoning_content === 'string' && container.reasoning_content.trim().length) {
+        container.content = container.reasoning_content.trim();
+    }
+    else if (role && role !== 'system' && role !== 'tool') {
+        container.content = '';
+    }
+    if (normalized.reasoningText && normalized.reasoningText.trim().length) {
+        container.reasoning_content = normalized.reasoningText.trim();
+    }
+    else if ('reasoning_content' in container) {
+        delete container.reasoning_content;
+    }
 }
 export function normalizeReasoningInResponsesPayload(payload, options = { includeOutput: true }) {
     if (!payload) {

package/dist/conversion/shared/responses-output-builder.d.ts

@@ -7,7 +7,7 @@ export interface BuildResponsesOutputOptions {
 }
 export interface BuildResponsesOutputResult {
     outputItems: ResponsesOutputItem[];
-    outputText: string;
+    outputText?: string;
     status: string;
     requiredAction?: Record<string, unknown>;
     usage?: unknown;

package/dist/conversion/shared/responses-output-builder.js

@@ -1,17 +1,64 @@
 import { normalizeFunctionCallId } from './bridge-id-utils.js';
 import { normalizeContentPart } from './output-content-normalizer.js';
 import { expandResponsesMessageItem } from '../../sse/shared/responses-output-normalizer.js';
+function appendReasoningSegments(target, raw) {
+    if (typeof raw !== 'string' || !raw.length) {
+        return;
+    }
+    const segments = raw.split('\n');
+    let previousValue;
+    for (const segment of segments) {
+        if (!segment.length)
+            continue;
+        let value = segment;
+        if (previousValue) {
+            const prevLast = previousValue.charAt(previousValue.length - 1) || '';
+            const currFirst = segment.charAt(0) || '';
+            const prevWord = /[A-Za-z0-9_]$/.test(prevLast);
+            const currWord = /^[A-Za-z0-9]/.test(currFirst);
+            const currQuote = currFirst === '"' || currFirst === "'";
+            const prevPunct = /[:;]/.test(prevLast);
+            const prevEndsWhitespace = /\s$/.test(previousValue);
+            const prevSentenceEnd = /[.?!"]$/.test(prevLast);
+            if (((prevWord || prevSentenceEnd) && currWord && !prevEndsWhitespace) ||
+                (prevPunct && currQuote)) {
+                value = ` ${segment}`;
+            }
+        }
+        target.push(value);
+        previousValue = value;
+    }
+}
 export function buildResponsesOutputFromChat(options) {
     const { response, message, requestId, sanitizeFunctionName } = options;
     const outputItems = [];
     const allocateOutputId = (prefix) => `${prefix}_${requestId ?? Date.now()}_${outputItems.length + 1}`;
     const role = message?.role || 'assistant';
     const content = message?.content;
-    const reasoningText = typeof message?.reasoning_content === 'string' && message.reasoning_content.trim().length
-        ? String(message.reasoning_content).trim()
+    let toolCalls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
+    try {
+        toolCalls = toolCalls.filter((it) => {
+            const nm = (it && typeof it === 'object') ? (it?.function?.name || it.name) : undefined;
+            return typeof nm === 'string' && nm.trim().length > 0 && nm.toLowerCase() !== 'tool';
+        });
+    }
+    catch {
+        /* ignore */
+    }
+    const hasToolCalls = toolCalls.length > 0;
+    const reasoningChunks = [];
+    const preservedReasoning = Array.isArray(response?.__responses_reasoning)
+        ? response.__responses_reasoning
         : undefined;
+    if (preservedReasoning && preservedReasoning.length) {
+        reasoningChunks.push(...preservedReasoning);
+    }
+    else {
+        appendReasoningSegments(reasoningChunks, message?.reasoning_content);
+    }
     const convertedContent = convertChatContentToResponses(content);
-    if (message || convertedContent.length > 0 || reasoningText) {
+    const shouldEmitMessage = Boolean(message) && (convertedContent.length > 0 || reasoningChunks.length > 0 || !hasToolCalls);
+    if (shouldEmitMessage) {
         const responsesMessage = {
             id: allocateOutputId('message'),
             type: 'message',
@@ -22,23 +69,13 @@ export function buildResponsesOutputFromChat(options) {
         const expandedItems = expandResponsesMessageItem(responsesMessage, {
             requestId: requestId ?? 'responses_outbound',
             outputIndex: outputItems.length,
-            extraReasoning: reasoningText
+            extraReasoning: reasoningChunks
         });
         for (const expanded of expandedItems) {
             outputItems.push(expanded);
         }
     }
-    let toolCalls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
     const normalizedToolCalls = [];
-    try {
-        toolCalls = toolCalls.filter((it) => {
-            const nm = (it && typeof it === 'object') ? (it?.function?.name || it.name) : undefined;
-            return typeof nm === 'string' && nm.trim().length > 0 && nm.toLowerCase() !== 'tool';
-        });
-    }
-    catch {
-        /* ignore */
-    }
     let toolFallbackCounter = 0;
     for (const call of toolCalls) {
         const outputEntry = buildFunctionCallOutput(call, allocateOutputId, sanitizeFunctionName, outputItems.length, ++toolFallbackCounter);
@@ -52,19 +89,20 @@ export function buildResponsesOutputFromChat(options) {
         }
     }
     const usage = normalizeUsage(response.usage);
-    const outputText = extractOutputText(convertedContent);
-    const hasToolCalls = toolCalls.length > 0;
-    if (hasToolCalls) {
+    const outputTextMeta = response?.__responses_output_text_meta;
+    const outputText = resolveOutputText(convertedContent, outputTextMeta);
+    const hasNormalizedToolCalls = normalizedToolCalls.length > 0;
+    if (hasNormalizedToolCalls) {
         for (const item of outputItems) {
             if (item.type === 'message') {
                 item.status = 'in_progress';
             }
         }
     }
-    const requiredAction = normalizedToolCalls.length
+    const requiredAction = hasNormalizedToolCalls
         ? buildRequiredActionFromNormalized(normalizedToolCalls)
         : undefined;
-    const status = hasToolCalls ? 'requires_action' : 'completed';
+    const status = hasNormalizedToolCalls ? 'requires_action' : 'completed';
     return {
         outputItems,
         outputText,
@@ -121,12 +159,10 @@ function buildFunctionCallOutput(call, allocateOutputId, sanitizeFunctionName, b
         const originalCallId = typeof call.id === 'string' && call.id.trim().length
             ? String(call.id)
             : (typeof call.call_id === 'string' && call.call_id.trim().length ? String(call.call_id) : undefined);
-        const callId = originalCallId && originalCallId.trim().length
-            ? originalCallId.trim()
-            : normalizeFunctionCallId({
-                callId: originalCallId,
-                fallback: `fc_call_${baseCount + offset}`
-            });
+        const callId = normalizeFunctionCallId({
+            callId: originalCallId,
+            fallback: `fc_call_${baseCount + offset}`
+        });
         const output = {
             id: allocateOutputId('function_call'),
             type: 'function_call',
@@ -177,3 +213,18 @@ function extractOutputText(parts) {
     const text = normalizedTexts.join('\n').trim();
     return text.length ? text : '';
 }
+function resolveOutputText(parts, meta) {
+    if (meta && typeof meta === 'object') {
+        const hasField = Boolean(meta.hasField);
+        if (hasField) {
+            const raw = meta.value;
+            if (typeof raw === 'string') {
+                return raw;
+            }
+            return '';
+        }
+        return undefined;
+    }
+    const text = extractOutputText(parts);
+    return text.length ? text : undefined;
+}

package/dist/conversion/shared/responses-reasoning-registry.d.ts

@@ -0,0 +1,8 @@
+export interface ResponsesOutputTextMeta {
+    hasField: boolean;
+    value?: string;
+}
+export declare function registerResponsesReasoning(id: unknown, segments: string[] | undefined): void;
+export declare function consumeResponsesReasoning(id: unknown): string[] | undefined;
+export declare function registerResponsesOutputTextMeta(id: unknown, meta: ResponsesOutputTextMeta | undefined): void;
+export declare function consumeResponsesOutputTextMeta(id: unknown): ResponsesOutputTextMeta | undefined;

package/dist/conversion/shared/responses-reasoning-registry.js

@@ -0,0 +1,61 @@
+const registry = new Map();
+function ensureEntry(id) {
+    let entry = registry.get(id);
+    if (!entry) {
+        entry = {};
+        registry.set(id, entry);
+    }
+    return entry;
+}
+function pruneEntry(id) {
+    const entry = registry.get(id);
+    if (!entry)
+        return;
+    if (!entry.reasoning && !entry.outputText) {
+        registry.delete(id);
+    }
+}
+export function registerResponsesReasoning(id, segments) {
+    if (typeof id !== 'string')
+        return;
+    if (!Array.isArray(segments) || segments.length === 0)
+        return;
+    const entry = ensureEntry(id);
+    entry.reasoning = [...segments];
+}
+export function consumeResponsesReasoning(id) {
+    if (typeof id !== 'string')
+        return undefined;
+    const entry = registry.get(id);
+    if (!entry?.reasoning)
+        return undefined;
+    const value = [...entry.reasoning];
+    entry.reasoning = undefined;
+    pruneEntry(id);
+    return value;
+}
+export function registerResponsesOutputTextMeta(id, meta) {
+    if (typeof id !== 'string')
+        return;
+    if (!meta)
+        return;
+    const entry = ensureEntry(id);
+    entry.outputText = {
+        hasField: Boolean(meta.hasField),
+        value: typeof meta.value === 'string' ? meta.value : undefined
+    };
+}
+export function consumeResponsesOutputTextMeta(id) {
+    if (typeof id !== 'string')
+        return undefined;
+    const entry = registry.get(id);
+    if (!entry?.outputText)
+        return undefined;
+    const value = {
+        hasField: Boolean(entry.outputText.hasField),
+        value: entry.outputText.value
+    };
+    entry.outputText = undefined;
+    pruneEntry(id);
+    return value;
+}

package/dist/conversion/shared/responses-response-utils.js

@@ -135,6 +135,24 @@ function unwrapResponsesResponse(payload) {
     }
     return undefined;
 }
+function collectRawReasoningSegments(response) {
+    const segments = [];
+    const outputItems = Array.isArray(response.output) ? response.output : [];
+    for (const item of outputItems) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const type = typeof item.type === 'string' ? String(item.type).toLowerCase() : '';
+        if (type !== 'reasoning')
+            continue;
+        const content = Array.isArray(item.content) ? item.content : [];
+        for (const part of content) {
+            if (part && typeof part === 'object' && typeof part.text === 'string') {
+                segments.push(part.text);
+            }
+        }
+    }
+    return segments;
+}
 export function buildChatResponseFromResponses(payload) {
     if (!payload || typeof payload !== 'object')
         return payload;
@@ -152,6 +170,7 @@ export function buildChatResponseFromResponses(payload) {
     const usage = response.usage;
     const toolCalls = collectToolCallsFromResponses(response);
     const { textParts, reasoningParts } = extractOutputSegments(response);
+    const rawReasoningSegments = collectRawReasoningSegments(response);
     const explicitOutput = typeof response.output_text === 'string' && response.output_text.trim().length
         ? sanitizeReasoningTaggedText(response.output_text)
         : undefined;
@@ -185,8 +204,9 @@ export function buildChatResponseFromResponses(payload) {
     if (toolCalls.length) {
         message.tool_calls = toolCalls;
     }
-    if (reasoningParts.length) {
-        message.reasoning_content = reasoningParts.join('\n');
+    const reasoningSegments = rawReasoningSegments.length ? rawReasoningSegments : reasoningParts;
+    if (reasoningSegments.length) {
+        message.reasoning_content = reasoningSegments.join('\n');
     }
     const finishReason = resolveFinishReason(response, toolCalls);
     const chat = {
@@ -202,6 +222,16 @@ export function buildChatResponseFromResponses(payload) {
             }
         ]
     };
+    const hasOutputTextField = Object.prototype.hasOwnProperty.call(response, 'output_text');
+    if (rawReasoningSegments.length) {
+        chat.__responses_reasoning = rawReasoningSegments;
+    }
+    chat.__responses_output_text_meta = {
+        hasField: hasOutputTextField,
+        value: hasOutputTextField && typeof response.output_text === 'string'
+            ? sanitizeReasoningTaggedText(response.output_text)
+            : undefined
+    };
     if (usage !== undefined) {
         chat.usage = usage;
     }

package/dist/conversion/shared/responses-tool-utils.js

@@ -68,10 +68,36 @@ export function resolveToolCallIdStyle(metadata) {
 export function stripInternalToolingMetadata(metadata) {
     if (!metadata || typeof metadata !== 'object')
         return;
-    if ('toolCallIdStyle' in metadata) {
-        delete metadata.toolCallIdStyle;
+    const record = metadata;
+    if ('toolCallIdStyle' in record) {
+        delete record.toolCallIdStyle;
+    }
+    if (RAW_SYSTEM_SENTINEL in record) {
+        delete record[RAW_SYSTEM_SENTINEL];
+    }
+    if (record.extraFields && typeof record.extraFields === 'object') {
+        prunePrivateExtraFields(record.extraFields);
+        if (!Object.keys(record.extraFields).length) {
+            delete record.extraFields;
+        }
+    }
+}
+function prunePrivateExtraFields(target) {
+    for (const key of Object.keys(target)) {
+        const value = target[key];
+        if (typeof key === 'string' && key.startsWith('__rcc_')) {
+            delete target[key];
+            continue;
+        }
+        if (value && typeof value === 'object') {
+            prunePrivateExtraFields(value);
+            if (!Object.keys(value).length) {
+                delete target[key];
+            }
+        }
     }
 }
+const RAW_SYSTEM_SENTINEL = '__rcc_raw_system';
 export function sanitizeResponsesFunctionName(rawName) {
     if (typeof rawName !== 'string') {
         return undefined;

package/dist/conversion/shared/snapshot-hooks.d.ts

@@ -0,0 +1,9 @@
+export interface SnapshotHookOptions {
+    endpoint: string;
+    stage: string;
+    requestId: string;
+    data: unknown;
+    verbosity?: 'minimal' | 'verbose';
+    channel?: string;
+}
+export declare function writeSnapshotViaHooks(options: SnapshotHookOptions): Promise<void>;

package/dist/conversion/shared/snapshot-hooks.js

@@ -1,7 +1,61 @@
-/**
- * Hub pipeline no longer exposes the legacy hooks runtime.
- * Keep a tiny shim so existing callers can continue awaiting the same API surface.
- */
-export async function writeSnapshotViaHooks(_options) {
-    return;
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+const DEFAULT_SNAPSHOT_ROOT = path.join(os.homedir(), '.routecodex', 'codex-samples');
+function resolveSnapshotRoot() {
+    const envOverride = process.env.RCC_SNAPSHOT_DIR ||
+        process.env.ROUTECODEX_SNAPSHOT_DIR;
+    if (envOverride && envOverride.trim()) {
+        return path.resolve(envOverride.trim());
+    }
+    return DEFAULT_SNAPSHOT_ROOT;
+}
+function resolveSnapshotFolder(endpoint) {
+    const lowered = (endpoint || '').toLowerCase();
+    if (lowered.includes('/responses')) {
+        return 'openai-responses';
+    }
+    if (lowered.includes('/messages')) {
+        return 'anthropic-messages';
+    }
+    return 'openai-chat';
+}
+function sanitizeToken(value, fallback) {
+    if (typeof value !== 'string') {
+        return fallback;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return fallback;
+    }
+    return trimmed.replace(/[^A-Za-z0-9_.-]/g, '_') || fallback;
+}
+function channelSuffix(channel) {
+    if (!channel) {
+        return '';
+    }
+    const token = sanitizeToken(channel, '');
+    return token ? `_${token}` : '';
+}
+async function writeSnapshotFile(options) {
+    const root = resolveSnapshotRoot();
+    const folder = resolveSnapshotFolder(options.endpoint);
+    const dir = path.join(root, folder);
+    const stageToken = sanitizeToken(options.stage, 'snapshot');
+    const requestToken = sanitizeToken(options.requestId, `req_${Date.now()}`);
+    const filePath = path.join(dir, `${requestToken}_${stageToken}${channelSuffix(options.channel)}.json`);
+    await fs.mkdir(dir, { recursive: true });
+    const spacing = options.verbosity === 'minimal' ? undefined : 2;
+    const payload = spacing !== undefined
+        ? JSON.stringify(options.data, null, spacing)
+        : JSON.stringify(options.data);
+    await fs.writeFile(filePath, payload, 'utf-8');
+}
+export async function writeSnapshotViaHooks(options) {
+    try {
+        await writeSnapshotFile(options);
+    }
+    catch {
+        // snapshot writes must never block callers
+    }
 }

package/dist/conversion/shared/snapshot-utils.d.ts

@@ -0,0 +1,16 @@
+interface SnapshotPayload {
+    stage: string;
+    requestId: string;
+    endpoint?: string;
+    data: unknown;
+    folderHint?: string;
+}
+export declare function shouldRecordSnapshots(): boolean;
+export declare function recordSnapshot(options: SnapshotPayload): Promise<void>;
+export type SnapshotWriter = (stage: string, payload: unknown) => void;
+export declare function createSnapshotWriter(opts: {
+    requestId: string;
+    endpoint?: string;
+    folderHint?: string;
+}): SnapshotWriter | undefined;
+export {};

package/dist/conversion/shared/snapshot-utils.js

@@ -0,0 +1,84 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { writeSnapshotViaHooks } from './snapshot-hooks.js';
+const SNAPSHOT_BASE = path.join(os.homedir(), '.routecodex', 'golden_samples');
+function mapEndpointToFolder(endpoint, hint) {
+    if (hint)
+        return hint;
+    const ep = String(endpoint || '').toLowerCase();
+    if (ep.includes('/responses'))
+        return 'openai-responses';
+    if (ep.includes('/messages'))
+        return 'anthropic-messages';
+    if (ep.includes('/gemini'))
+        return 'gemini-chat';
+    return 'openai-chat';
+}
+async function ensureDir(dir) {
+    try {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    catch {
+        // ignore fs errors
+    }
+}
+function sanitize(value) {
+    return value.replace(/[^\w.-]/g, '_');
+}
+export function shouldRecordSnapshots() {
+    const flag = process.env.ROUTECODEX_HUB_SNAPSHOTS;
+    if (flag && flag.trim() === '0') {
+        return false;
+    }
+    return true;
+}
+export async function recordSnapshot(options) {
+    if (!shouldRecordSnapshots())
+        return;
+    const endpoint = options.endpoint || '/v1/chat/completions';
+    const folder = mapEndpointToFolder(endpoint, options.folderHint);
+    const dir = path.join(SNAPSHOT_BASE, folder);
+    try {
+        await ensureDir(dir);
+        const safeStage = sanitize(options.stage);
+        const safeRequestId = sanitize(options.requestId);
+        const file = path.join(dir, `${safeRequestId}_${safeStage}.json`);
+        const payload = {
+            meta: {
+                stage: options.stage,
+                timestamp: Date.now(),
+                endpoint
+            },
+            body: options.data
+        };
+        await fs.writeFile(file, JSON.stringify(payload, null, 2), 'utf-8');
+    }
+    catch (error) {
+        console.warn('[snapshot-utils] failed to write snapshot', error);
+    }
+    void writeSnapshotViaHooks({
+        endpoint,
+        stage: options.stage,
+        requestId: options.requestId,
+        data: options.data,
+        verbosity: 'verbose'
+    }).catch(() => {
+        // ignore hook errors
+    });
+}
+export function createSnapshotWriter(opts) {
+    if (!shouldRecordSnapshots()) {
+        return undefined;
+    }
+    const endpoint = opts.endpoint || '/v1/chat/completions';
+    return (stage, payload) => {
+        void recordSnapshot({
+            stage,
+            requestId: opts.requestId,
+            endpoint,
+            folderHint: opts.folderHint,
+            data: payload
+        });
+    };
+}