@jsonstudio/llms 0.4.6 → 0.6.0

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

@@ -25,7 +25,9 @@ const KNOWN_TOP_LEVEL_FIELDS = new Set([
     'messages',
     'tools',
     'tool_outputs',
-    ...CHAT_PARAMETER_KEYS
+    ...CHAT_PARAMETER_KEYS,
+    'stageExpectations',
+    'stages'
 ]);
 function flattenSystemContent(content) {
     if (typeof content === 'string')
@@ -56,6 +58,37 @@ function normalizeToolContent(content) {
         return String(content ?? '');
     }
 }
+function recordToolCallIssues(message, messageIndex, missing) {
+    const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : undefined;
+    if (!toolCalls?.length)
+        return;
+    toolCalls.forEach((entry, callIndex) => {
+        if (!isJsonObject(entry)) {
+            missing.push({
+                path: `messages[${messageIndex}].tool_calls[${callIndex}]`,
+                reason: 'invalid_tool_call_entry',
+                originalValue: jsonClone(entry)
+            });
+            return;
+        }
+        const fnBlock = entry.function;
+        if (!isJsonObject(fnBlock)) {
+            missing.push({
+                path: `messages[${messageIndex}].tool_calls[${callIndex}].function`,
+                reason: 'missing_tool_function',
+                originalValue: jsonClone(fnBlock)
+            });
+            return;
+        }
+        const fnName = fnBlock.name;
+        if (typeof fnName !== 'string' || !fnName.trim().length) {
+            missing.push({
+                path: `messages[${messageIndex}].tool_calls[${callIndex}].function.name`,
+                reason: 'missing_tool_name'
+            });
+        }
+    });
+}
 function collectSystemRawBlocks(raw) {
     if (!Array.isArray(raw))
         return undefined;
@@ -120,7 +153,8 @@ function normalizeChatMessages(raw) {
         const chatMessage = value;
         if (roleValue !== 'system' && roleValue !== 'tool') {
             const normalizedContent = normalizeChatMessageContent(chatMessage.content);
-            if (normalizedContent.contentText !== undefined) {
+            const shouldOverwriteContent = !Array.isArray(chatMessage.content);
+            if (shouldOverwriteContent && normalizedContent.contentText !== undefined) {
                 chatMessage.content = normalizedContent.contentText;
             }
             if (typeof normalizedContent.reasoningText === 'string' && normalizedContent.reasoningText.trim().length) {
@@ -128,6 +162,10 @@ function normalizeChatMessages(raw) {
             }
         }
         norm.messages.push(chatMessage);
+        const toolCallCandidate = value.tool_calls;
+        if (Array.isArray(toolCallCandidate) && toolCallCandidate.length) {
+            recordToolCallIssues(value, index, norm.missingFields);
+        }
         if (roleValue === 'system') {
             const segment = flattenSystemContent(chatMessage.content);
             if (segment.trim().length) {
@@ -197,6 +235,29 @@ function extractParameters(body) {
     }
     return Object.keys(params).length ? params : undefined;
 }
+function collectExtraFields(body) {
+    const extras = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (KNOWN_TOP_LEVEL_FIELDS.has(key)) {
+            continue;
+        }
+        if (value !== undefined) {
+            extras[key] = jsonClone(value);
+        }
+    }
+    return Object.keys(extras).length ? extras : undefined;
+}
+function applyExtraFields(body, metadata) {
+    if (!metadata || !metadata.extraFields || !isJsonObject(metadata.extraFields)) {
+        return;
+    }
+    for (const [key, value] of Object.entries(metadata.extraFields)) {
+        if (body[key] !== undefined) {
+            continue;
+        }
+        body[key] = jsonClone(value);
+    }
+}
 export class ChatSemanticMapper {
     async toChat(format, ctx) {
         const payload = (format.payload ?? {});
@@ -219,6 +280,10 @@ export class ChatSemanticMapper {
         if (normalized.missingFields.length) {
             metadata.missingFields = normalized.missingFields;
         }
+        const extraFields = collectExtraFields(payload);
+        if (extraFields) {
+            metadata.extraFields = extraFields;
+        }
         try {
             const bridgePolicy = resolveBridgePolicy({ protocol: 'openai-chat' });
             const actions = resolvePolicyActions(bridgePolicy, 'request_inbound');
@@ -258,6 +323,7 @@ export class ChatSemanticMapper {
             tools: chat.tools ?? (chat.metadata?.toolsFieldPresent ? [] : undefined),
             ...(chat.parameters || {})
         };
+        applyExtraFields(payload, chat.metadata);
         try {
             const bridgePolicy = resolveBridgePolicy({ protocol: 'openai-chat' });
             const actions = resolvePolicyActions(bridgePolicy, 'request_outbound');
@@ -288,17 +354,12 @@ export class ChatSemanticMapper {
         catch {
             // ignore policy failures
         }
-        if (chat.metadata?.rawSystem !== undefined) {
-            try {
-                payload.__rcc_raw_system = JSON.stringify(chat.metadata.rawSystem);
-            }
-            catch {
-                // ignore serialization errors
-            }
-        }
-        if (chat.toolOutputs?.length) {
-            payload.tool_outputs = chat.toolOutputs;
-        }
+        // Do not forward tool_outputs to provider wire formats. OpenAI Chat
+        // endpoints expect tool results to appear as tool role messages, and
+        // sending the legacy top-level field causes upstream HTTP 400 responses.
+        // Concrete translation happens earlier when responses input is unfolded
+        // into ChatEnvelope.messages, so the provider request only needs the
+        // canonical message list.
         if (payload.max_tokens === undefined && typeof payload.max_output_tokens === 'number') {
             payload.max_tokens = payload.max_output_tokens;
             delete payload.max_output_tokens;

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

@@ -192,15 +192,6 @@ function buildGeminiRequestFromChat(chat, metadata) {
         request.metadata = request.metadata ?? {};
         request.metadata.__rcc_stream = chat.parameters.stream;
     }
-    if (metadata?.rawSystem !== undefined) {
-        request.metadata = request.metadata ?? {};
-        try {
-            request.metadata.__rcc_raw_system = JSON.stringify(metadata.rawSystem);
-        }
-        catch {
-            // ignore serialization errors
-        }
-    }
     if (chat.metadata?.toolsFieldPresent && (!Array.isArray(chat.tools) || chat.tools.length === 0)) {
         request.metadata = request.metadata ?? {};
         request.metadata.__rcc_tools_field_present = '1';

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

@@ -12,10 +12,7 @@ const RESPONSES_PARAMETER_KEYS = [
     'response_format',
     'tool_choice',
     'parallel_tool_calls',
-    'metadata',
-    'store',
     'user',
-    'include',
     'logit_bias',
     'seed',
     'stop',
@@ -211,21 +208,27 @@ export class ResponsesSemanticMapper {
             .filter((message) => Boolean(message && typeof message === 'object' && message.role === 'system'))
             .map(message => serializeSystemContent(message))
             .filter((content) => typeof content === 'string' && content.length > 0);
-        const responsesContext = chat.metadata
-            ? { metadata: chat.metadata, originalSystemMessages }
-            : { originalSystemMessages };
+        const capturedContext = chat.metadata?.responsesContext;
+        const responsesContext = isJsonObject(capturedContext)
+            ? {
+                ...capturedContext,
+                originalSystemMessages
+            }
+            : {
+                metadata: (chat.metadata && isJsonObject(chat.metadata) ? chat.metadata : undefined),
+                originalSystemMessages
+            };
         const responsesResult = buildResponsesRequestFromChat(requestShape, responsesContext);
         const responses = responsesResult.request;
         if (chat.parameters && chat.parameters.stream !== undefined) {
             responses.stream = chat.parameters.stream;
         }
-        if (chat.toolOutputs && chat.toolOutputs.length) {
-            responses.tool_outputs = chat.toolOutputs.map(entry => ({
-                tool_call_id: entry.tool_call_id,
-                output: entry.content,
-                name: entry.name
-            }));
-        }
+        // Do not forward ChatEnvelope.toolOutputs to OpenAI Responses create requests.
+        // Upstream expects historical tool results to remain inside input[] as
+        // tool role messages; sending the legacy top-level `tool_outputs` field
+        // causes providers like FAI to reject the request (HTTP 400). Any actual
+        // submit_tool_outputs call should be issued via the dedicated endpoint
+        // upstream, not through this mapper.
         try {
             const bridgePolicy = resolveBridgePolicy({ protocol: 'openai-responses', moduleType: 'openai-responses' });
             const actions = resolvePolicyActions(bridgePolicy, 'request_outbound');

package/dist/conversion/hub/snapshot-recorder.d.ts

@@ -0,0 +1,13 @@
+import type { StageRecorder } from './format-adapters/index.js';
+import type { AdapterContext } from './types/chat-envelope.js';
+export interface SnapshotStageRecorderOptions {
+    context: AdapterContext;
+    endpoint: string;
+}
+export declare class SnapshotStageRecorder implements StageRecorder {
+    private readonly options;
+    private readonly writer?;
+    constructor(options: SnapshotStageRecorderOptions);
+    record(stage: string, payload: object): void;
+}
+export declare function createSnapshotRecorder(context: AdapterContext, endpoint: string): StageRecorder;

package/dist/conversion/hub/snapshot-recorder.js

@@ -1,69 +1,109 @@
-import { writeSnapshotViaHooks } from '../shared/snapshot-hooks.js';
-import os from 'node:os';
-import path from 'node:path';
-import fs from 'node:fs/promises';
+import { createSnapshotWriter } from '../shared/snapshot-utils.js';
+import { jsonClone } from './types/json.js';
 export class SnapshotStageRecorder {
     options;
+    writer;
     constructor(options) {
         this.options = options;
+        this.writer = createSnapshotWriter({
+            requestId: options.context.requestId,
+            endpoint: options.endpoint
+        });
     }
     record(stage, payload) {
-        void writeSnapshotFile({
-            endpoint: this.options.endpoint,
-            stage,
-            requestId: this.options.context.requestId,
-            data: payload
-        });
-        void writeSnapshotViaHooks({
-            endpoint: this.options.endpoint,
-            stage,
-            requestId: this.options.context.requestId,
-            data: payload,
-            verbosity: 'verbose'
-        }).catch(() => {
-            /* ignore hook errors */
-        });
+        if (!this.writer) {
+            return;
+        }
+        const normalized = normalizeStagePayload(stage, payload);
+        if (!normalized) {
+            return;
+        }
+        try {
+            this.writer(stage, normalized);
+        }
+        catch {
+            // ignore snapshot write errors
+        }
     }
 }
 export function createSnapshotRecorder(context, endpoint) {
     return new SnapshotStageRecorder({ context, endpoint });
 }
-const SNAPSHOT_BASE = path.join(os.homedir(), '.routecodex', 'codex-samples');
-function mapEndpointToFolder(endpoint) {
-    const ep = String(endpoint || '').toLowerCase();
-    if (ep.includes('/responses'))
-        return 'openai-responses';
-    if (ep.includes('/messages'))
-        return 'anthropic-messages';
-    return 'openai-chat';
+const STAGE_KIND_MAP = {
+    req_inbound_stage2_semantic_map: 'request_inbound',
+    req_outbound_stage1_semantic_map: 'request_outbound',
+    resp_inbound_stage3_semantic_map: 'response_inbound',
+    resp_outbound_stage1_client_remap: 'response_outbound'
+};
+function normalizeStagePayload(stage, payload) {
+    const kind = STAGE_KIND_MAP[stage];
+    if (!kind) {
+        return payload;
+    }
+    if ((kind === 'request_inbound' || kind === 'request_outbound') && isChatEnvelope(payload)) {
+        return buildOpenAIChatSnapshot(payload);
+    }
+    if (kind === 'response_inbound' || kind === 'response_outbound') {
+        return cloneJson(payload);
+    }
+    return payload;
 }
-async function ensureDir(dir) {
-    try {
-        await fs.mkdir(dir, { recursive: true });
+function isChatEnvelope(value) {
+    return Boolean(value &&
+        typeof value === 'object' &&
+        Array.isArray(value.messages) &&
+        value.metadata &&
+        typeof value.metadata === 'object');
+}
+function buildOpenAIChatSnapshot(envelope) {
+    const snapshot = {};
+    if (envelope.parameters && Object.keys(envelope.parameters).length) {
+        Object.assign(snapshot, jsonClone(envelope.parameters));
     }
-    catch {
-        // ignore
+    snapshot.messages = jsonClone(envelope.messages);
+    if (envelope.tools && envelope.tools.length) {
+        snapshot.tools = jsonClone(envelope.tools);
     }
+    if (envelope.toolOutputs && envelope.toolOutputs.length) {
+        snapshot.tool_outputs = jsonClone(envelope.toolOutputs);
+    }
+    const meta = buildMetaSnapshot(envelope.metadata);
+    if (meta) {
+        snapshot.meta = meta;
+    }
+    return snapshot;
+}
+function buildMetaSnapshot(metadata) {
+    if (!metadata || typeof metadata !== 'object') {
+        return undefined;
+    }
+    const meta = {};
+    if (metadata.context) {
+        meta.context = jsonClone(metadata.context);
+    }
+    if (Array.isArray(metadata.missingFields) && metadata.missingFields.length) {
+        meta.missing_fields = jsonClone(metadata.missingFields);
+    }
+    const extraKeys = Object.keys(metadata).filter((key) => key !== 'context' && key !== 'missingFields');
+    if (extraKeys.length) {
+        const extras = {};
+        for (const key of extraKeys) {
+            const value = metadata[key];
+            if (value !== undefined) {
+                extras[key] = jsonClone(value);
+            }
+        }
+        if (Object.keys(extras).length) {
+            meta.extra = extras;
+        }
+    }
+    return Object.keys(meta).length ? meta : undefined;
 }
-async function writeSnapshotFile(options) {
+function cloneJson(payload) {
     try {
-        const folder = mapEndpointToFolder(options.endpoint);
-        const dir = path.join(SNAPSHOT_BASE, folder);
-        await ensureDir(dir);
-        const safeStage = options.stage.replace(/[^\w.-]/g, '_');
-        const safeRequestId = options.requestId.replace(/[^\w.-]/g, '_');
-        const file = path.join(dir, `${safeRequestId}_${safeStage}.json`);
-        const payload = {
-            meta: {
-                stage: options.stage,
-                timestamp: Date.now(),
-                endpoint: options.endpoint
-            },
-            body: options.data
-        };
-        await fs.writeFile(file, JSON.stringify(payload, null, 2), 'utf-8');
+        return JSON.parse(JSON.stringify(payload));
     }
-    catch (error) {
-        console.warn('[hub-snapshot] failed to write local snapshot', error);
+    catch {
+        return payload;
     }
 }

package/dist/conversion/hub/standardized-bridge.js

@@ -1,3 +1,4 @@
+import { jsonClone } from './types/json.js';
 const HUB_CAPTURE_KEY = '__hub_capture';
 export function chatEnvelopeToStandardized(chat, options) {
     const parameters = { ...(chat.parameters ?? {}) };
@@ -41,13 +42,16 @@ export function chatEnvelopeToStandardized(chat, options) {
 export function standardizedToChatEnvelope(request, options) {
     const adapterContext = options.adapterContext;
     const hubState = extractHubCapture(request);
-    const messages = request.messages.map((message) => ({
-        role: message.role,
-        content: message.content ?? '',
-        tool_calls: mapToolCalls(message.tool_calls),
-        tool_call_id: message.tool_call_id,
-        name: message.name
-    }));
+    const messages = request.messages.map((message) => {
+        const restoredContent = restoreMessageContent(message.content);
+        return {
+            role: message.role,
+            content: restoredContent,
+            tool_calls: mapToolCalls(message.tool_calls),
+            tool_call_id: message.tool_call_id,
+            name: message.name
+        };
+    });
     const tools = mapStandardizedTools(request.tools);
     const parameters = {
         ...(request.parameters ?? {}),
@@ -88,7 +92,7 @@ function extractModel(parameters) {
 function normalizeChatMessage(message) {
     const normalized = {
         role: message.role,
-        content: normalizeContent(message.content)
+        content: cloneMessageContent(message.content)
     };
     if (Array.isArray(message.tool_calls) && message.tool_calls.length) {
         normalized.tool_calls = message.tool_calls
@@ -103,7 +107,7 @@ function normalizeChatMessage(message) {
     }
     return normalized;
 }
-function normalizeContent(content) {
+function cloneMessageContent(content) {
     if (content === undefined || content === null) {
         return null;
     }
@@ -111,21 +115,35 @@ function normalizeContent(content) {
         return content;
     }
     if (Array.isArray(content)) {
-        const parts = content
-            .map((part) => {
-            if (part && typeof part === 'object') {
-                if (typeof part.text === 'string') {
-                    return String(part.text);
-                }
-                return JSON.stringify(part);
-            }
-            return '';
-        })
-            .filter(Boolean);
-        return parts.join('\n');
+        return cloneContentArray(content);
     }
     return String(content);
 }
+function restoreMessageContent(content) {
+    if (content === undefined) {
+        return undefined;
+    }
+    if (content === null) {
+        return null;
+    }
+    if (typeof content === 'string') {
+        return content;
+    }
+    return cloneContentArray(content);
+}
+function cloneContentArray(parts) {
+    return parts.map((part) => {
+        if (part && typeof part === 'object') {
+            return jsonClone(part);
+        }
+        const text = typeof part === 'string' ? part : String(part ?? '');
+        const fallback = {
+            type: 'text',
+            text
+        };
+        return fallback;
+    });
+}
 function normalizeToolCall(toolCall) {
     if (!toolCall || typeof toolCall !== 'object') {
         return null;
@@ -137,20 +155,16 @@ function normalizeToolCall(toolCall) {
     if (type !== 'function') {
         return null;
     }
-    if (!fn || typeof fn !== 'object') {
-        return null;
-    }
-    const fnName = fn.name;
-    if (typeof fnName !== 'string' || !fnName.trim()) {
-        return null;
-    }
-    const args = fn.arguments;
+    const fnRecord = fn && typeof fn === 'object' ? fn : undefined;
+    const rawName = typeof fnRecord?.name === 'string' ? fnRecord.name : '';
+    const normalizedName = rawName.trim();
+    const args = fnRecord?.arguments;
     const serializedArgs = typeof args === 'string' ? args : safeStringify(args ?? {});
     return {
         id: id.trim(),
         type: 'function',
         function: {
-            name: fnName.trim(),
+            name: normalizedName.length ? normalizedName : rawName,
             arguments: serializedArgs
         }
     };

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

@@ -0,0 +1,68 @@
+export type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
+import type { JsonObject, JsonValue } from './json.js';
+export interface ChatMessageContentPart {
+    type: string;
+    text?: string;
+    [key: string]: JsonValue;
+}
+export interface ChatToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+    [key: string]: JsonValue;
+}
+export interface ChatMessage {
+    role: ChatRole;
+    content?: string | ChatMessageContentPart[] | null;
+    tool_calls?: ChatToolCall[];
+    name?: string;
+    [key: string]: JsonValue;
+}
+export interface ChatToolDefinition {
+    type: 'function' | string;
+    function: {
+        name: string;
+        description?: string;
+        parameters?: JsonValue;
+        strict?: boolean;
+    };
+    [key: string]: JsonValue;
+}
+export interface ChatToolOutput {
+    tool_call_id: string;
+    content: string;
+    name?: string;
+    [key: string]: JsonValue;
+}
+export interface MissingField extends JsonObject {
+    path: string;
+    reason: string;
+    originalValue?: JsonValue;
+}
+export interface AdapterContext {
+    requestId: string;
+    entryEndpoint: string;
+    providerProtocol: string;
+    providerId?: string;
+    routeId?: string;
+    profileId?: string;
+    streamingHint?: 'auto' | 'force' | 'disable';
+    originalModelId?: string;
+    clientModelId?: string;
+    toolCallIdStyle?: 'fc' | 'preserve';
+    [key: string]: JsonValue;
+}
+export interface ChatEnvelope {
+    messages: ChatMessage[];
+    tools?: ChatToolDefinition[];
+    toolOutputs?: ChatToolOutput[];
+    parameters?: JsonObject;
+    metadata: {
+        context: AdapterContext;
+        missingFields?: MissingField[];
+        [key: string]: JsonValue;
+    };
+}

package/dist/conversion/hub/types/standardized.d.ts

@@ -0,0 +1,97 @@
+import type { ChatMessageContentPart } from './chat-envelope.js';
+import type { JsonObject } from './json.js';
+export type ToolChoice = 'none' | 'auto' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+} | Record<string, unknown>;
+export interface StandardizedTool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters: {
+            type?: string | string[];
+            properties?: Record<string, unknown>;
+            required?: string[];
+            additionalProperties?: boolean;
+            [key: string]: unknown;
+        };
+        strict?: boolean;
+    };
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ToolCallResult {
+    tool_call_id: string;
+    status: 'success' | 'error' | 'timeout' | 'pending';
+    result?: JsonObject | JsonObject[] | string | number | boolean | null;
+    error?: string;
+    executionTime?: number;
+}
+export type StandardizedMessageContent = string | ChatMessageContentPart[] | null;
+export interface StandardizedMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: StandardizedMessageContent;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface StandardizedParameters {
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    stop?: string | string[];
+    stream?: boolean;
+    [key: string]: unknown;
+}
+export interface StandardizedMetadata {
+    originalEndpoint: string;
+    capturedContext?: Record<string, unknown>;
+    requestId?: string;
+    stream?: boolean;
+    toolChoice?: ToolChoice;
+    providerKey?: string;
+    providerType?: string;
+    processMode?: 'chat' | 'passthrough';
+    routeHint?: string;
+    [key: string]: unknown;
+}
+export interface StandardizedRequest {
+    model: string;
+    messages: StandardizedMessage[];
+    tools?: StandardizedTool[];
+    parameters: StandardizedParameters;
+    metadata: StandardizedMetadata;
+}
+export interface ProcessedRequest extends StandardizedRequest {
+    processed: {
+        timestamp: number;
+        appliedRules: string[];
+        status: 'success' | 'partial' | 'failed';
+    };
+    processingMetadata: {
+        toolCalls?: ToolCallResult[];
+        streaming?: {
+            enabled: boolean;
+            chunkCount?: number;
+            totalTokens?: number;
+        };
+        context?: {
+            systemPrompt?: string;
+            conversationHistory?: string[];
+            relevantContext?: Record<string, unknown>;
+        };
+        passthrough?: boolean;
+    };
+}