@jsonstudio/llms 0.4.2

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

@@ -0,0 +1,379 @@
+import { isJsonObject, jsonClone } from '../types/json.js';
+import { captureResponsesContext, buildChatRequestFromResponses, buildResponsesRequestFromChat } from '../../responses/responses-openai-bridge.js';
+const RESPONSES_PARAMETER_KEYS = [
+    'model',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'max_output_tokens',
+    'response_format',
+    'tool_choice',
+    'parallel_tool_calls',
+    'metadata',
+    'store',
+    'user',
+    'include',
+    'logit_bias',
+    'seed',
+    'stop',
+    'stop_sequences',
+    'modalities'
+];
+const RESPONSES_TOP_LEVEL_FIELDS = new Set([
+    'input',
+    'tools',
+    'tool_outputs',
+    'instructions',
+    'response_id',
+    'previous_response_id',
+    'conversation',
+    'parallel_tool_calls',
+    'tool_choice',
+    'stream',
+    'metadata',
+    'include',
+    'store',
+    'user',
+    'response_format',
+    'model',
+    'temperature',
+    'top_p',
+    'top_k',
+    'max_tokens',
+    'max_output_tokens',
+    'logit_bias',
+    'seed',
+    'modalities',
+    'instructions_is_raw'
+]);
+const RESPONSES_METADATA_SENTINEL_TOOLS = '__rcc_tools_field_present';
+function mapToolOutputs(entries, missing) {
+    if (!entries || !entries.length)
+        return undefined;
+    const outputs = [];
+    entries.forEach((entry, index) => {
+        if (!isJsonObject(entry)) {
+            missing.push({ path: `tool_outputs[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(entry) });
+            return;
+        }
+        const callId = entry.tool_call_id || entry.call_id || entry.id;
+        if (!callId) {
+            missing.push({ path: `tool_outputs[${index}].tool_call_id`, reason: 'missing_tool_call_id' });
+            return;
+        }
+        let content = '';
+        if (typeof entry.output === 'string') {
+            content = entry.output;
+        }
+        else if (entry.output != null) {
+            try {
+                content = JSON.stringify(entry.output);
+            }
+            catch {
+                content = String(entry.output);
+            }
+        }
+        outputs.push({
+            tool_call_id: String(callId),
+            content,
+            name: typeof entry.name === 'string' ? entry.name : undefined
+        });
+    });
+    return outputs.length ? outputs : undefined;
+}
+function collectParameters(payload, streamHint) {
+    const params = {};
+    for (const key of RESPONSES_PARAMETER_KEYS) {
+        if (payload[key] !== undefined) {
+            params[key] = payload[key];
+        }
+    }
+    if (streamHint !== undefined) {
+        params.stream = streamHint;
+    }
+    return Object.keys(params).length ? params : undefined;
+}
+function normalizeTools(rawTools, missing) {
+    if (!rawTools || rawTools.length === 0)
+        return undefined;
+    const tools = [];
+    rawTools.forEach((tool, index) => {
+        if (!tool || typeof tool !== 'object' || Array.isArray(tool)) {
+            missing.push({ path: `tools[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(tool) });
+            return;
+        }
+        const fn = tool.function;
+        if (!fn || typeof fn !== 'object' || Array.isArray(fn))
+            return;
+        const name = fn.name;
+        const nameValue = typeof name === 'string' ? name : undefined;
+        if (!nameValue)
+            return;
+        const descriptionValue = fn.description;
+        const parametersValue = fn.parameters;
+        const strictValue = fn.strict;
+        const definition = {
+            type: 'function',
+            function: {
+                name: nameValue,
+                description: typeof descriptionValue === 'string' ? descriptionValue : undefined,
+                parameters: parametersValue,
+                strict: typeof strictValue === 'boolean' ? strictValue : undefined
+            }
+        };
+        tools.push(definition);
+    });
+    return tools.length ? tools : undefined;
+}
+function normalizeMessages(value, missing) {
+    if (!Array.isArray(value)) {
+        if (value !== undefined) {
+            missing.push({ path: 'messages', reason: 'invalid_type', originalValue: jsonClone(value) });
+        }
+        else {
+            missing.push({ path: 'messages', reason: 'absent' });
+        }
+        return [];
+    }
+    const messages = [];
+    value.forEach((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            missing.push({ path: `messages[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(item) });
+            return;
+        }
+        messages.push(item);
+    });
+    return messages;
+}
+function collectExtraFields(payload) {
+    const extras = {};
+    for (const key of Object.keys(payload)) {
+        if (RESPONSES_TOP_LEVEL_FIELDS.has(key) || RESPONSES_PARAMETER_KEYS.includes(key))
+            continue;
+        extras[key] = payload[key];
+    }
+    return Object.keys(extras).length ? extras : undefined;
+}
+function serializeSystemContent(message) {
+    if (!message)
+        return undefined;
+    const content = message.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const parts = [];
+        content.forEach(part => {
+            if (typeof part === 'string') {
+                parts.push(part);
+            }
+            else if (part && typeof part === 'object') {
+                const text = part.text;
+                if (typeof text === 'string') {
+                    parts.push(text);
+                }
+            }
+        });
+        return parts.join('');
+    }
+    if (content != null) {
+        try {
+            return JSON.stringify(content);
+        }
+        catch {
+            return String(content);
+        }
+    }
+    return undefined;
+}
+export class ResponsesSemanticMapper {
+    async toChat(format, ctx) {
+        const payload = format.payload || {};
+        const responsesContext = captureResponsesContext(payload, { route: { requestId: ctx.requestId } });
+        const { request, toolsNormalized } = buildChatRequestFromResponses(payload, responsesContext);
+        const missingFields = [];
+        if (!responsesContext.instructions) {
+            missingFields.push({ path: 'instructions', reason: 'absent' });
+        }
+        const messages = normalizeMessages(request.messages, missingFields);
+        const toolOutputs = mapToolOutputs(payload.tool_outputs, missingFields);
+        const parameters = collectParameters(payload, responsesContext.stream);
+        const metadata = { context: ctx };
+        if (payload.metadata && typeof payload.metadata === 'object') {
+            const providerMetadata = jsonClone(payload.metadata);
+            if (isJsonObject(providerMetadata)) {
+                if (Object.prototype.hasOwnProperty.call(providerMetadata, RESPONSES_METADATA_SENTINEL_TOOLS)) {
+                    const sentinel = providerMetadata[RESPONSES_METADATA_SENTINEL_TOOLS];
+                    if (sentinel === '1' || sentinel === true) {
+                        metadata.toolsFieldPresent = true;
+                    }
+                    delete providerMetadata[RESPONSES_METADATA_SENTINEL_TOOLS];
+                }
+            }
+            metadata.providerMetadata = providerMetadata;
+        }
+        if (missingFields.length) {
+            metadata.missingFields = missingFields;
+        }
+        const extraFields = collectExtraFields(payload);
+        if (extraFields) {
+            metadata.extraFields = extraFields;
+        }
+        if (responsesContext.responseFormat) {
+            metadata.responseFormat = jsonClone(responsesContext.responseFormat);
+        }
+        const hasSystemMessage = messages.some(message => message?.role === 'system');
+        if (!hasSystemMessage && typeof responsesContext.instructions === 'string' && responsesContext.instructions.length) {
+            messages.unshift({ role: 'system', content: responsesContext.instructions });
+        }
+        return {
+            messages,
+            tools: normalizeTools(toolsNormalized, missingFields),
+            toolOutputs,
+            parameters,
+            metadata
+        };
+    }
+    async fromChat(chat, ctx) {
+        const modelValue = chat.parameters?.model;
+        if (typeof modelValue !== 'string' || !modelValue.trim()) {
+            throw new Error('ChatEnvelope.parameters.model is required for openai-responses outbound conversion');
+        }
+        const requestShape = {
+            ...(chat.parameters || {}),
+            model: modelValue,
+            messages: chat.messages,
+            tools: chat.tools
+        };
+        const originalSystemMessages = (chat.messages || [])
+            .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 responsesResult = buildResponsesRequestFromChat(requestShape, responsesContext);
+        const responses = responsesResult.request;
+        const normalizeUserInstructionFromMessage = (message) => {
+            if (!message)
+                return undefined;
+            const content = message.content;
+            if (typeof content === 'string') {
+                const trimmed = content.trim();
+                return trimmed.length ? trimmed : undefined;
+            }
+            if (Array.isArray(content)) {
+                const fragments = [];
+                for (const fragment of content) {
+                    if (typeof fragment === 'string') {
+                        fragments.push(fragment);
+                    }
+                    else if (fragment && typeof fragment === 'object') {
+                        const partText = typeof fragment.text === 'string'
+                            ? String(fragment.text)
+                            : (typeof fragment.content === 'string'
+                                ? String(fragment.content)
+                                : undefined);
+                        if (partText && partText.trim().length) {
+                            fragments.push(partText);
+                        }
+                    }
+                }
+                if (fragments.length) {
+                    const joined = fragments.join('').trim();
+                    return joined.length ? joined : undefined;
+                }
+            }
+            return undefined;
+        };
+        const normalizeUserInstructionFromInput = (payload) => {
+            const entries = Array.isArray(payload.input) ? payload.input : [];
+            for (let i = entries.length - 1; i >= 0; i -= 1) {
+                const entry = entries[i];
+                const roleSource = entry.role ?? entry?.message?.role;
+                const role = typeof roleSource === 'string' ? roleSource.toLowerCase() : '';
+                if (role !== 'user')
+                    continue;
+                const content = entry?.content ?? entry?.message?.content;
+                if (typeof content === 'string') {
+                    const trimmed = content.trim();
+                    if (trimmed.length)
+                        return trimmed;
+                    continue;
+                }
+                if (Array.isArray(content)) {
+                    const parts = [];
+                    for (const fragment of content) {
+                        if (typeof fragment === 'string') {
+                            parts.push(fragment);
+                        }
+                        else if (fragment && typeof fragment === 'object') {
+                            const text = typeof fragment.text === 'string'
+                                ? String(fragment.text)
+                                : (typeof fragment.content === 'string'
+                                    ? String(fragment.content)
+                                    : undefined);
+                            if (text && text.trim().length) {
+                                parts.push(text);
+                            }
+                        }
+                    }
+                    if (parts.length) {
+                        const joined = parts.join('').trim();
+                        if (joined.length)
+                            return joined;
+                    }
+                }
+            }
+            return undefined;
+        };
+        const latestUserMessage = [...(chat.messages || [])]
+            .reverse()
+            .find((message) => typeof message?.role === 'string' && message.role.toLowerCase() === 'user');
+        const existingInstruction = typeof responses.instructions === 'string'
+            ? responses.instructions.trim()
+            : undefined;
+        if (!existingInstruction || !existingInstruction.length) {
+            const messageInstruction = normalizeUserInstructionFromMessage(latestUserMessage);
+            if (messageInstruction && messageInstruction.trim().length) {
+                responses.instructions = messageInstruction.trim();
+            }
+            else {
+                const inputInstruction = normalizeUserInstructionFromInput(responses);
+                if (inputInstruction && inputInstruction.trim().length) {
+                    responses.instructions = inputInstruction.trim();
+                }
+            }
+        }
+        else {
+            responses.instructions = existingInstruction;
+        }
+        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
+            }));
+        }
+        // Responses outbound 不再附带 metadata；系统提示由 instructions 字段承担
+        const extraFields = chat.metadata?.extraFields;
+        if (isJsonObject(extraFields)) {
+            for (const [key, value] of Object.entries(extraFields)) {
+                if (responses[key] === undefined) {
+                    responses[key] = value;
+                }
+            }
+        }
+        return {
+            protocol: 'openai-responses',
+            direction: 'response',
+            payload: responses,
+            meta: {
+                context: ctx
+            }
+        };
+    }
+}

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

@@ -0,0 +1,12 @@
+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;
+    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

@@ -0,0 +1,69 @@
+import { writeSnapshotViaHooks } from '../shared/snapshot-hooks.js';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+export class SnapshotStageRecorder {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    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 */
+        });
+    }
+}
+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';
+}
+async function ensureDir(dir) {
+    try {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    catch {
+        // ignore
+    }
+}
+async function writeSnapshotFile(options) {
+    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');
+    }
+    catch (error) {
+        console.warn('[hub-snapshot] failed to write local snapshot', error);
+    }
+}

package/dist/conversion/hub/standardized-bridge.d.ts

@@ -0,0 +1,12 @@
+import type { StandardizedRequest } from './types/standardized.js';
+import type { AdapterContext, ChatEnvelope } from './types/chat-envelope.js';
+export interface ChatToStandardizedOptions {
+    adapterContext: AdapterContext;
+    endpoint: string;
+    requestId?: string;
+}
+export interface StandardizedToChatOptions {
+    adapterContext: AdapterContext;
+}
+export declare function chatEnvelopeToStandardized(chat: ChatEnvelope, options: ChatToStandardizedOptions): StandardizedRequest;
+export declare function standardizedToChatEnvelope(request: StandardizedRequest, options: StandardizedToChatOptions): ChatEnvelope;