@jsonstudio/llms 0.4.3 → 0.4.5

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

@@ -1,5 +1,10 @@
 import { isJsonObject, jsonClone } from '../types/json.js';
 import { buildOpenAIChatFromGeminiRequest } from '../../codecs/gemini-openai-codec.js';
+import { createBridgeActionState, runBridgeActionPipeline } from '../../shared/bridge-actions.js';
+import { resolveBridgePolicy, resolvePolicyActions } from '../../shared/bridge-policies.js';
+import { encodeMetadataPassthrough, extractMetadataPassthrough } from '../../shared/metadata-passthrough.js';
+import { mapBridgeToolsToChat, mapChatToolsToBridge } from '../../shared/tool-mapping.js';
+import { prepareGeminiToolsForBridge, buildGeminiToolsFromBridge } from '../../shared/gemini-tool-utils.js';
 const GENERATION_CONFIG_KEYS = [
     { source: 'temperature', target: 'temperature' },
     { source: 'topP', target: 'top_p' },
@@ -9,65 +14,8 @@ const GENERATION_CONFIG_KEYS = [
     { source: 'responseMimeType', target: 'response_mime_type' },
     { source: 'stopSequences', target: 'stop_sequences' }
 ];
-const GEMINI_TOP_LEVEL_FIELDS = new Set([
-    'model',
-    'contents',
-    'tools',
-    'systemInstruction',
-    'generationConfig',
-    'safetySettings',
-    'metadata',
-    'toolConfig'
-]);
 const PASSTHROUGH_METADATA_PREFIX = 'rcc_passthrough_';
 const PASSTHROUGH_PARAMETERS = ['tool_choice'];
-function encodePassthroughParametersFromChat(chat) {
-    if (!chat.parameters)
-        return undefined;
-    const encoded = {};
-    for (const key of PASSTHROUGH_PARAMETERS) {
-        const value = chat.parameters[key];
-        if (value === undefined)
-            continue;
-        try {
-            encoded[`${PASSTHROUGH_METADATA_PREFIX}${key}`] = JSON.stringify(value);
-        }
-        catch {
-            continue;
-        }
-    }
-    return Object.keys(encoded).length ? encoded : undefined;
-}
-function extractPassthroughParametersFromMetadata(metadataField) {
-    if (!metadataField)
-        return {};
-    const cloned = jsonClone(metadataField);
-    const passthrough = {};
-    let mutated = false;
-    for (const key of Object.keys(cloned)) {
-        if (!key.startsWith(PASSTHROUGH_METADATA_PREFIX))
-            continue;
-        const paramKey = key.slice(PASSTHROUGH_METADATA_PREFIX.length);
-        if (!PASSTHROUGH_PARAMETERS.includes(paramKey))
-            continue;
-        const rawValue = cloned[key];
-        if (typeof rawValue !== 'string')
-            continue;
-        try {
-            const parsed = rawValue ? JSON.parse(rawValue) : undefined;
-            passthrough[paramKey] = parsed;
-            delete cloned[key];
-            mutated = true;
-        }
-        catch {
-            continue;
-        }
-    }
-    return {
-        cleaned: mutated ? (Object.keys(cloned).length ? cloned : undefined) : cloned,
-        passthrough: Object.keys(passthrough).length ? passthrough : undefined
-    };
-}
 function normalizeToolOutputs(messages, missing) {
     const outputs = [];
     messages.forEach((msg, index) => {
@@ -119,53 +67,6 @@ function collectSystemSegments(systemInstruction) {
     const text = flatten(systemInstruction).trim();
     return text ? [text] : [];
 }
-function normalizeGeminiTools(rawTools, missing) {
-    if (!rawTools)
-        return undefined;
-    const arr = Array.isArray(rawTools) ? rawTools : [rawTools];
-    const tools = [];
-    arr.forEach((entry, index) => {
-        if (!entry || typeof entry !== 'object') {
-            missing.push({ path: `tools[${index}]`, reason: 'invalid_entry', originalValue: jsonClone(entry) });
-            return;
-        }
-        const obj = entry;
-        const declarations = Array.isArray(obj.functionDeclarations) ? obj.functionDeclarations : undefined;
-        if (declarations && declarations.length) {
-            declarations.forEach((decl, declIndex) => {
-                if (!decl || typeof decl !== 'object') {
-                    missing.push({ path: `tools[${index}].functionDeclarations[${declIndex}]`, reason: 'invalid_entry' });
-                    return;
-                }
-                const def = decl;
-                const name = typeof def.name === 'string' ? def.name : undefined;
-                if (!name)
-                    return;
-                tools.push({
-                    type: 'function',
-                    function: {
-                        name,
-                        description: typeof def.description === 'string' ? def.description : undefined,
-                        parameters: isJsonObject(def.parameters) ? jsonClone(def.parameters) : { type: 'object', properties: {} }
-                    }
-                });
-            });
-            return;
-        }
-        const name = typeof obj.name === 'string' ? obj.name : undefined;
-        if (!name)
-            return;
-        tools.push({
-            type: 'function',
-            function: {
-                name,
-                description: typeof obj.description === 'string' ? obj.description : undefined,
-                parameters: isJsonObject(obj.parameters) ? jsonClone(obj.parameters) : { type: 'object', properties: {} }
-            }
-        });
-    });
-    return tools.length ? tools : undefined;
-}
 function collectParameters(payload) {
     const params = {};
     if (typeof payload.model === 'string') {
@@ -189,15 +90,6 @@ function collectParameters(payload) {
     }
     return Object.keys(params).length ? params : undefined;
 }
-function collectExtraFields(payload) {
-    const extras = {};
-    for (const key of Object.keys(payload)) {
-        if (GEMINI_TOP_LEVEL_FIELDS.has(key))
-            continue;
-        extras[key] = payload[key];
-    }
-    return Object.keys(extras).length ? extras : undefined;
-}
 function buildGeminiRequestFromChat(chat, metadata) {
     const contents = [];
     for (const message of chat.messages) {
@@ -276,7 +168,11 @@ function buildGeminiRequestFromChat(chat, metadata) {
         }
     }
     if (chat.tools && chat.tools.length) {
-        request.tools = buildGeminiToolsFromChat(chat.tools);
+        const bridgeDefs = mapChatToolsToBridge(chat.tools);
+        const geminiTools = buildGeminiToolsFromBridge(bridgeDefs);
+        if (geminiTools) {
+            request.tools = geminiTools;
+        }
     }
     const generationConfig = buildGenerationConfigFromParameters(chat.parameters || {});
     if (Object.keys(generationConfig).length) {
@@ -309,7 +205,10 @@ function buildGeminiRequestFromChat(chat, metadata) {
         request.metadata = request.metadata ?? {};
         request.metadata.__rcc_tools_field_present = '1';
     }
-    const passthrough = encodePassthroughParametersFromChat(chat);
+    const passthrough = encodeMetadataPassthrough(chat.parameters, {
+        prefix: PASSTHROUGH_METADATA_PREFIX,
+        keys: PASSTHROUGH_PARAMETERS
+    });
     if (passthrough) {
         request.metadata = request.metadata ?? {};
         for (const [key, value] of Object.entries(passthrough)) {
@@ -318,26 +217,6 @@ function buildGeminiRequestFromChat(chat, metadata) {
     }
     return request;
 }
-function buildGeminiToolsFromChat(tools) {
-    const geminiTools = [];
-    tools.forEach((tool) => {
-        if (!tool || tool.type !== 'function')
-            return;
-        const fn = tool.function;
-        if (!fn || typeof fn.name !== 'string')
-            return;
-        geminiTools.push({
-            functionDeclarations: [
-                {
-                    name: fn.name,
-                    description: fn.description,
-                    parameters: cloneAsJsonValue(fn.parameters ?? { type: 'object', properties: {} })
-                }
-            ]
-        });
-    });
-    return geminiTools;
-}
 function buildGenerationConfigFromParameters(parameters) {
     const config = {};
     for (const { source, target } of GENERATION_CONFIG_KEYS) {
@@ -391,12 +270,13 @@ export class GeminiSemanticMapper {
     async toChat(format, ctx) {
         const payload = (format.payload ?? {});
         const missing = [];
-        const { messages } = buildOpenAIChatFromGeminiRequest(payload);
+        const { messages: builtMessages } = buildOpenAIChatFromGeminiRequest(payload);
+        let messages = Array.isArray(builtMessages) ? builtMessages : [];
         if (!Array.isArray(payload.contents)) {
             missing.push({ path: 'contents', reason: 'absent' });
         }
-        const toolOutputs = normalizeToolOutputs(messages, missing);
-        const tools = payload.tools ? normalizeGeminiTools(payload.tools, missing) : undefined;
+        const bridgeTools = prepareGeminiToolsForBridge(payload.tools, missing);
+        const tools = bridgeTools ? mapBridgeToolsToChat(bridgeTools) : undefined;
         let parameters = collectParameters(payload);
         const metadata = { context: ctx };
         const systemSegments = collectSystemSegments(payload.systemInstruction);
@@ -414,15 +294,38 @@ export class GeminiSemanticMapper {
         if (missing.length) {
             metadata.missingFields = missing;
         }
-        const extraFields = collectExtraFields(payload);
-        if (extraFields) {
-            metadata.extraFields = extraFields;
+        try {
+            const bridgePolicy = resolveBridgePolicy({ protocol: 'gemini-chat' });
+            const actions = resolvePolicyActions(bridgePolicy, 'request_inbound');
+            if (actions?.length) {
+                const actionState = createBridgeActionState({
+                    messages: messages,
+                    rawRequest: payload,
+                    metadata: metadata
+                });
+                runBridgeActionPipeline({
+                    stage: 'request_inbound',
+                    actions,
+                    protocol: bridgePolicy?.protocol ?? 'gemini-chat',
+                    moduleType: bridgePolicy?.moduleType ?? 'gemini-chat',
+                    requestId: ctx.requestId,
+                    state: actionState
+                });
+                messages = actionState.messages;
+            }
         }
-        const passthrough = extractPassthroughParametersFromMetadata(payload.metadata);
+        catch {
+            // best-effort policy execution
+        }
+        const toolOutputs = normalizeToolOutputs(messages, missing);
+        const passthrough = extractMetadataPassthrough(payload.metadata, {
+            prefix: PASSTHROUGH_METADATA_PREFIX,
+            keys: PASSTHROUGH_PARAMETERS
+        });
         if (passthrough.passthrough) {
             parameters = { ...(parameters || {}), ...passthrough.passthrough };
         }
-        const providerMetadataSource = passthrough.cleaned ?? payload.metadata;
+        const providerMetadataSource = passthrough.metadata ?? payload.metadata;
         if (providerMetadataSource) {
             const providerMetadata = jsonClone(providerMetadataSource);
             let toolsFieldPresent = false;
@@ -465,6 +368,36 @@ export class GeminiSemanticMapper {
     }
     async fromChat(chat, ctx) {
         const envelopePayload = buildGeminiRequestFromChat(chat, chat.metadata);
+        try {
+            const bridgePolicy = resolveBridgePolicy({ protocol: 'gemini-chat' });
+            const actions = resolvePolicyActions(bridgePolicy, 'request_outbound');
+            if (actions?.length) {
+                const capturedToolResults = Array.isArray(chat.toolOutputs)
+                    ? chat.toolOutputs.map((entry) => ({
+                        tool_call_id: entry.tool_call_id,
+                        output: entry.content,
+                        name: entry.name
+                    }))
+                    : undefined;
+                const actionState = createBridgeActionState({
+                    messages: Array.isArray(chat.messages) ? chat.messages : [],
+                    rawRequest: envelopePayload,
+                    metadata: chat.metadata,
+                    capturedToolResults
+                });
+                runBridgeActionPipeline({
+                    stage: 'request_outbound',
+                    actions,
+                    protocol: bridgePolicy?.protocol ?? 'gemini-chat',
+                    moduleType: bridgePolicy?.moduleType ?? 'gemini-chat',
+                    requestId: ctx.requestId,
+                    state: actionState
+                });
+            }
+        }
+        catch {
+            // ignore policy failures
+        }
         return {
             protocol: 'gemini-chat',
             direction: 'response',

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

@@ -1,4 +1,6 @@
 import { isJsonObject, jsonClone } from '../types/json.js';
+import { createBridgeActionState, runBridgeActionPipeline } from '../../shared/bridge-actions.js';
+import { resolveBridgePolicy, resolvePolicyActions } from '../../shared/bridge-policies.js';
 import { captureResponsesContext, buildChatRequestFromResponses, buildResponsesRequestFromChat } from '../../responses/responses-openai-bridge.js';
 const RESPONSES_PARAMETER_KEYS = [
     'model',
@@ -20,34 +22,6 @@ const RESPONSES_PARAMETER_KEYS = [
     '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;
@@ -146,15 +120,6 @@ function normalizeMessages(value, missing) {
     });
     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;
@@ -192,40 +157,37 @@ export class ResponsesSemanticMapper {
         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];
-                }
+        try {
+            const bridgePolicy = resolveBridgePolicy({ protocol: 'openai-responses', moduleType: 'openai-responses' });
+            const actions = resolvePolicyActions(bridgePolicy, 'request_inbound');
+            if (actions?.length) {
+                const actionState = createBridgeActionState({
+                    rawRequest: payload,
+                    metadata: metadata
+                });
+                runBridgeActionPipeline({
+                    stage: 'request_inbound',
+                    actions,
+                    protocol: bridgePolicy?.protocol ?? 'openai-responses',
+                    moduleType: bridgePolicy?.moduleType ?? 'openai-responses',
+                    requestId: ctx.requestId,
+                    state: actionState
+                });
             }
-            metadata.providerMetadata = providerMetadata;
+        }
+        catch {
+            // ignore policy hook failures
         }
         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),
@@ -254,100 +216,6 @@ export class ResponsesSemanticMapper {
             : { 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;
         }
@@ -358,15 +226,27 @@ export class ResponsesSemanticMapper {
                 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;
-                }
+        try {
+            const bridgePolicy = resolveBridgePolicy({ protocol: 'openai-responses', moduleType: 'openai-responses' });
+            const actions = resolvePolicyActions(bridgePolicy, 'request_outbound');
+            if (actions?.length) {
+                const actionState = createBridgeActionState({
+                    rawRequest: responses,
+                    metadata: chat.metadata
+                });
+                runBridgeActionPipeline({
+                    stage: 'request_outbound',
+                    actions,
+                    protocol: bridgePolicy?.protocol ?? 'openai-responses',
+                    moduleType: bridgePolicy?.moduleType ?? 'openai-responses',
+                    requestId: ctx.requestId,
+                    state: actionState
+                });
             }
         }
+        catch {
+            // ignore metadata propagation failures
+        }
         return {
             protocol: 'openai-responses',
             direction: 'response',

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

@@ -56,6 +56,9 @@ export function standardizedToChatEnvelope(request, options) {
     const metadata = {
         context: adapterContext
     };
+    if (typeof adapterContext.toolCallIdStyle === 'string' && adapterContext.toolCallIdStyle.length) {
+        metadata.toolCallIdStyle = adapterContext.toolCallIdStyle;
+    }
     if (hubState?.missingFields) {
         metadata.missingFields = hubState.missingFields;
     }

package/dist/conversion/hub/tool-governance/engine.d.ts

@@ -0,0 +1,16 @@
+import type { JsonObject } from '../types/json.js';
+import type { StandardizedRequest } from '../types/standardized.js';
+import type { GovernedChatCompletionPayload, GovernedStandardizedRequest, ToolGovernanceProtocol, ToolGovernanceRegistry } from './types.js';
+export declare class ToolGovernanceError extends Error {
+    readonly protocol: ToolGovernanceProtocol;
+    readonly direction: 'request' | 'response';
+    readonly field: string;
+    constructor(message: string, protocol: ToolGovernanceProtocol, direction: 'request' | 'response', field: string);
+}
+export declare class ToolGovernanceEngine {
+    private readonly registry;
+    constructor(registry?: ToolGovernanceRegistry);
+    governRequest(request: StandardizedRequest, protocol: ToolGovernanceProtocol): GovernedStandardizedRequest;
+    governResponse(payload: JsonObject, protocol: ToolGovernanceProtocol): GovernedChatCompletionPayload;
+    private resolveRules;
+}