@jsonstudio/llms 0.4.2 → 0.4.4

package/dist/conversion/hub/response/provider-response.js

@@ -5,6 +5,7 @@ import { buildProcessedRequestFromChatResponse } from './chat-response-utils.js'
 import { buildAnthropicResponseFromChat } from './response-runtime.js';
 import { buildResponsesPayloadFromChat } from '../../responses/responses-openai-bridge.js';
 import { defaultSseCodecRegistry } from '../../../sse/registry/sse-codec-registry.js';
+import { ToolGovernanceEngine } from '../tool-governance/index.js';
 import { ChatFormatAdapter } from '../format-adapters/chat-format-adapter.js';
 import { ResponsesFormatAdapter } from '../format-adapters/responses-format-adapter.js';
 import { AnthropicFormatAdapter } from '../format-adapters/anthropic-format-adapter.js';
@@ -21,6 +22,7 @@ const STAGES = {
     ssePre: 'resp_sse_output_pre',
     ssePost: 'resp_sse_output_post'
 };
+const toolGovernanceEngine = new ToolGovernanceEngine();
 const PROVIDER_RESPONSE_REGISTRY = {
     'openai-chat': {
         protocol: 'openai-chat',
@@ -155,12 +157,16 @@ export async function convertProviderResponse(options) {
     recordStage(options.stageRecorder, STAGES.formatParse, formatEnvelope);
     const chatResponse = await mapper.toChatCompletion(formatEnvelope, options.context);
     recordStage(options.stageRecorder, STAGES.semanticMap, chatResponse);
-    const governed = await runChatResponseToolFilters(chatResponse, {
+    const filtered = await runChatResponseToolFilters(chatResponse, {
         entryEndpoint: options.entryEndpoint,
         requestId: options.context.requestId,
         profile: 'openai-chat'
     });
-    recordStage(options.stageRecorder, STAGES.governance, governed);
+    const { payload: governed, summary: responseGovernance } = toolGovernanceEngine.governResponse(filtered, clientProtocol);
+    recordStage(options.stageRecorder, STAGES.governance, {
+        ...governed,
+        __toolGovernanceSummary: responseGovernance
+    });
     const finalized = await finalizeOpenAIChatResponse(governed, {
         requestId: options.context.requestId,
         endpoint: options.entryEndpoint,

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;
+}

package/dist/conversion/hub/tool-governance/engine.js

@@ -0,0 +1,266 @@
+import { DEFAULT_TOOL_GOVERNANCE_RULES } from './rules.js';
+export class ToolGovernanceError extends Error {
+    protocol;
+    direction;
+    field;
+    constructor(message, protocol, direction, field) {
+        super(message);
+        this.protocol = protocol;
+        this.direction = direction;
+        this.field = field;
+        this.name = 'ToolGovernanceError';
+    }
+}
+function normalizeProtocol(protocol) {
+    if (!protocol)
+        return 'openai-chat';
+    const normalized = String(protocol).toLowerCase();
+    if (normalized === 'anthropic-messages') {
+        return 'anthropic';
+    }
+    if (normalized === 'gemini-chat') {
+        return 'gemini';
+    }
+    if (normalized === 'responses' || normalized === 'openai-responses') {
+        return 'openai-responses';
+    }
+    if (normalized === 'openai-chat') {
+        return 'openai-chat';
+    }
+    return protocol;
+}
+export class ToolGovernanceEngine {
+    registry;
+    constructor(registry = DEFAULT_TOOL_GOVERNANCE_RULES) {
+        this.registry = registry;
+    }
+    governRequest(request, protocol) {
+        const rules = this.resolveRules(protocol, 'request');
+        if (!rules) {
+            return {
+                request,
+                summary: buildSummary(protocol, 'request', false)
+            };
+        }
+        const stats = createStats(protocol, 'request');
+        const sanitizedMessages = request.messages.map((msg) => sanitizeStandardizedMessage(msg, rules, stats));
+        const sanitizedTools = request.tools?.map((tool) => sanitizeStandardizedTool(tool, rules, stats));
+        const governed = {
+            ...request,
+            messages: sanitizedMessages,
+            tools: sanitizedTools,
+            metadata: {
+                ...request.metadata,
+                toolGovernance: {
+                    ...request.metadata?.toolGovernance,
+                    request: finalizeSummary(stats)
+                }
+            }
+        };
+        return {
+            request: governed,
+            summary: finalizeSummary(stats)
+        };
+    }
+    governResponse(payload, protocol) {
+        const rules = this.resolveRules(protocol, 'response');
+        if (!rules) {
+            return {
+                payload,
+                summary: buildSummary(protocol, 'response', false)
+            };
+        }
+        const stats = createStats(protocol, 'response');
+        const cloned = JSON.parse(JSON.stringify(payload));
+        const choices = Array.isArray(cloned?.choices) ? cloned.choices : [];
+        for (const choice of choices) {
+            sanitizeChatCompletionChoice(choice, rules, stats);
+        }
+        if (Array.isArray(cloned?.tool_calls)) {
+            cloned.tool_calls = cloned.tool_calls.map((tc) => sanitizeChatCompletionToolCall(tc, rules, stats));
+        }
+        return {
+            payload: cloned,
+            summary: finalizeSummary(stats)
+        };
+    }
+    resolveRules(protocol, direction) {
+        const resolved = normalizeProtocol(protocol);
+        const entry = this.registry[resolved] ?? this.registry['openai-chat'];
+        return entry?.[direction];
+    }
+}
+function sanitizeStandardizedMessage(message, rules, stats) {
+    let changed = false;
+    const next = { ...message };
+    if (Array.isArray(message.tool_calls) && message.tool_calls.length) {
+        next.tool_calls = message.tool_calls.map((call) => sanitizeToolCall(call, rules, stats));
+        if (next.tool_calls !== message.tool_calls) {
+            changed = true;
+        }
+    }
+    if (typeof message.name === 'string' || message.role === 'tool') {
+        const sanitizedName = sanitizeName(message.name, rules, stats, 'message.name');
+        if (sanitizedName !== message.name) {
+            next.name = sanitizedName;
+            changed = true;
+        }
+    }
+    return changed ? next : message;
+}
+function sanitizeStandardizedTool(tool, rules, stats) {
+    const sanitizedName = sanitizeName(tool.function?.name, rules, stats, 'tool.function.name');
+    if (sanitizedName === tool.function?.name) {
+        return tool;
+    }
+    return {
+        ...tool,
+        function: {
+            ...tool.function,
+            name: sanitizedName
+        }
+    };
+}
+function sanitizeToolCall(call, rules, stats) {
+    if (!call?.function) {
+        return call;
+    }
+    const sanitizedName = sanitizeName(call.function.name, rules, stats, 'tool_call.function.name');
+    if (sanitizedName === call.function.name) {
+        return call;
+    }
+    return {
+        ...call,
+        function: {
+            ...call.function,
+            name: sanitizedName
+        }
+    };
+}
+function sanitizeChatCompletionChoice(choice, rules, stats) {
+    const message = choice?.message;
+    if (!message || typeof message !== 'object') {
+        return;
+    }
+    const msg = message;
+    if (Array.isArray(msg.tool_calls)) {
+        msg.tool_calls = msg.tool_calls.map((tc, index) => sanitizeChatCompletionToolCall(tc, rules, stats, `choices[].message.tool_calls[${index}].function.name`));
+    }
+    if (msg.function_call && typeof msg.function_call === 'object') {
+        const orig = msg.function_call.name;
+        const sanitizedName = sanitizeName(orig, rules, stats, 'choices[].message.function_call.name');
+        msg.function_call.name = sanitizedName;
+    }
+    if (typeof msg.name === 'string' || msg.role === 'tool') {
+        msg.name = sanitizeName(msg.name, rules, stats, 'choices[].message.name');
+    }
+}
+function sanitizeChatCompletionToolCall(tc, rules, stats, context = 'choices[].message.tool_calls[].function.name') {
+    if (!tc || typeof tc !== 'object') {
+        return tc;
+    }
+    const fn = tc.function;
+    if (!fn || typeof fn !== 'object') {
+        return tc;
+    }
+    const sanitizedName = sanitizeName(fn.name, rules, stats, context);
+    if (sanitizedName === fn.name) {
+        return tc;
+    }
+    return {
+        ...tc,
+        function: {
+            ...fn,
+            name: sanitizedName
+        }
+    };
+}
+function createStats(protocol, direction) {
+    return {
+        protocol,
+        direction,
+        applied: false,
+        sanitizedNames: 0,
+        truncatedNames: 0,
+        defaultedNames: 0
+    };
+}
+function sanitizeName(rawName, rules, stats, field) {
+    const defaultName = rules.defaultName ?? 'tool';
+    let next = typeof rawName === 'string' ? rawName : '';
+    let changed = false;
+    if (rules.trimWhitespace !== false) {
+        next = next.trim();
+    }
+    if (!next) {
+        next = defaultName;
+        stats.defaultedNames += 1;
+        changed = true;
+    }
+    if (rules.forceCase === 'lower') {
+        const forced = next.toLowerCase();
+        if (forced !== next) {
+            next = forced;
+            changed = true;
+        }
+    }
+    else if (rules.forceCase === 'upper') {
+        const forced = next.toUpperCase();
+        if (forced !== next) {
+            next = forced;
+            changed = true;
+        }
+    }
+    if (rules.allowedCharacters) {
+        const matcher = new RegExp(rules.allowedCharacters.source);
+        const filtered = next
+            .split('')
+            .filter((ch) => matcher.test(ch))
+            .join('');
+        matcher.lastIndex = 0;
+        if (filtered.length === 0) {
+            next = defaultName;
+            stats.defaultedNames += 1;
+            changed = true;
+        }
+        else if (filtered !== next) {
+            next = filtered;
+            changed = true;
+        }
+    }
+    if (rules.maxNameLength && next.length > rules.maxNameLength) {
+        if (rules.onViolation === 'reject') {
+            throw new ToolGovernanceError(`Tool name exceeds max length of ${rules.maxNameLength}`, stats.protocol, stats.direction, field);
+        }
+        next = next.slice(0, rules.maxNameLength);
+        stats.truncatedNames += 1;
+        changed = true;
+    }
+    if (changed || (typeof rawName === 'string' && rawName !== next)) {
+        stats.sanitizedNames += 1;
+    }
+    stats.applied = true;
+    return next || defaultName;
+}
+function finalizeSummary(stats) {
+    return {
+        protocol: stats.protocol,
+        direction: stats.direction,
+        applied: stats.applied,
+        sanitizedNames: stats.sanitizedNames,
+        truncatedNames: stats.truncatedNames,
+        defaultedNames: stats.defaultedNames,
+        timestamp: Date.now()
+    };
+}
+function buildSummary(protocol, direction, applied) {
+    return {
+        protocol,
+        direction,
+        applied,
+        sanitizedNames: 0,
+        truncatedNames: 0,
+        defaultedNames: 0,
+        timestamp: Date.now()
+    };
+}

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

@@ -0,0 +1,3 @@
+export { ToolGovernanceEngine, ToolGovernanceError } from './engine.js';
+export { DEFAULT_TOOL_GOVERNANCE_RULES } from './rules.js';
+export type { ToolGovernanceProtocol, ToolGovernanceRules, ToolGovernanceRegistry, ToolGovernanceSummary } from './types.js';

package/dist/conversion/hub/tool-governance/index.js

@@ -0,0 +1,2 @@
+export { ToolGovernanceEngine, ToolGovernanceError } from './engine.js';
+export { DEFAULT_TOOL_GOVERNANCE_RULES } from './rules.js';

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

@@ -0,0 +1,2 @@
+import type { ToolGovernanceRegistry } from './types.js';
+export declare const DEFAULT_TOOL_GOVERNANCE_RULES: ToolGovernanceRegistry;

package/dist/conversion/hub/tool-governance/rules.js

@@ -0,0 +1,76 @@
+const ALPHA_NUMERIC = /[A-Za-z0-9._-]/;
+const LOWER_SNAKE = /[a-z0-9._-]/;
+function clonePattern(pattern) {
+    if (!pattern)
+        return undefined;
+    const flags = pattern.flags.replace(/g/g, '');
+    return new RegExp(pattern.source, flags);
+}
+export const DEFAULT_TOOL_GOVERNANCE_RULES = {
+    'openai-chat': {
+        request: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        },
+        response: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        }
+    },
+    'openai-responses': {
+        request: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        },
+        response: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        }
+    },
+    anthropic: {
+        request: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(LOWER_SNAKE),
+            forceCase: 'lower',
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        },
+        response: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(LOWER_SNAKE),
+            forceCase: 'lower',
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        }
+    },
+    gemini: {
+        request: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        },
+        response: {
+            maxNameLength: 64,
+            allowedCharacters: clonePattern(ALPHA_NUMERIC),
+            defaultName: 'tool',
+            trimWhitespace: true,
+            onViolation: 'truncate'
+        }
+    }
+};

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

@@ -0,0 +1,38 @@
+import type { JsonObject } from '../types/json.js';
+import type { StandardizedMessage, StandardizedRequest, StandardizedTool } from '../types/standardized.js';
+export type ToolGovernanceProtocol = 'openai-chat' | 'openai-responses' | 'anthropic' | 'gemini' | string;
+export type ToolGovernanceViolationMode = 'truncate' | 'reject';
+export interface ToolGovernanceRules {
+    maxNameLength?: number;
+    allowedCharacters?: RegExp;
+    forceCase?: 'lower' | 'upper';
+    defaultName?: string;
+    trimWhitespace?: boolean;
+    onViolation?: ToolGovernanceViolationMode;
+}
+export interface ToolGovernanceRegistryEntry {
+    request?: ToolGovernanceRules;
+    response?: ToolGovernanceRules;
+}
+export type ToolGovernanceRegistry = Record<ToolGovernanceProtocol, ToolGovernanceRegistryEntry>;
+export interface ToolGovernanceSummary {
+    protocol: ToolGovernanceProtocol;
+    direction: 'request' | 'response';
+    applied: boolean;
+    sanitizedNames: number;
+    truncatedNames: number;
+    defaultedNames: number;
+    timestamp: number;
+}
+export interface GovernedStandardizedRequest {
+    request: StandardizedRequest;
+    summary: ToolGovernanceSummary;
+}
+export interface GovernedChatCompletionPayload {
+    payload: JsonObject;
+    summary: ToolGovernanceSummary;
+}
+export type MutableStandardizedMessage = StandardizedMessage & {
+    tool_calls?: StandardizedMessage['tool_calls'];
+};
+export type MutableStandardizedTool = StandardizedTool;

package/dist/conversion/index.d.ts

@@ -7,6 +7,7 @@ export * from './hub/registry.js';
 export * from './hub/pipelines/inbound.js';
 export * from './hub/pipelines/outbound.js';
 export * from './hub/response/provider-response.js';
+export * from './hub/response/response-runtime.js';
 export * from './hub/pipeline/hub-pipeline.js';
 export * from './hub/format-adapters/index.js';
 export * from './hub/semantic-mappers/index.js';

package/dist/conversion/index.js

@@ -7,6 +7,7 @@ export * from './hub/registry.js';
 export * from './hub/pipelines/inbound.js';
 export * from './hub/pipelines/outbound.js';
 export * from './hub/response/provider-response.js';
+export * from './hub/response/response-runtime.js';
 export * from './hub/pipeline/hub-pipeline.js';
 export * from './hub/format-adapters/index.js';
 export * from './hub/semantic-mappers/index.js';

package/dist/conversion/responses/responses-openai-bridge.js

@@ -237,8 +237,8 @@ export function buildResponsesRequestFromChat(payload, ctx) {
             if (anyT.type === 'function' && anyT.function && typeof anyT.function === 'object') {
                 const fn = anyT.function;
                 const base = { type: 'function' };
-                if (typeof fn.name === 'string')
-                    base.name = fn.name;
+                if (typeof fn.name === 'string' && fn.name.trim())
+                    base.name = fn.name.trim();
                 if (typeof fn.description === 'string')
                     base.description = fn.description;
                 if (Object.prototype.hasOwnProperty.call(fn, 'parameters'))
@@ -385,7 +385,9 @@ export function buildResponsesRequestFromChat(payload, ctx) {
                         toolCallIdAliases.set(rawId, normalizedCallId);
                     }
                     const fn = tc?.function || {};
-                    const name = typeof fn?.name === 'string' ? String(fn.name) : 'tool';
+                    const name = typeof fn?.name === 'string' && fn.name.trim()
+                        ? String(fn.name).trim()
+                        : 'tool';
                     const argsRaw = fn?.arguments;
                     const args = typeof argsRaw === 'string' ? argsRaw : normalizeArgumentsBySchema(argsRaw, name, out.tools);
                     const entry = {

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

@@ -1,16 +1,29 @@
+function sanitizeCore(value) {
+    return value
+        .replace(/[^A-Za-z0-9_-]/g, '_')
+        .replace(/_{2,}/g, '_')
+        .replace(/^_+/, '')
+        .replace(/_+$/, '');
+}
 function stripPrefix(value) {
     if (typeof value !== 'string')
         return null;
     const trimmed = value.trim();
     if (!trimmed)
         return null;
-    if (/^fc[_-]/i.test(trimmed)) {
-        return `fc_${trimmed.replace(/^fc[_-]?/i, '')}`;
+    let sanitized = sanitizeCore(trimmed);
+    if (!sanitized)
+        return null;
+    if (/^fc[_-]/i.test(sanitized)) {
+        sanitized = sanitized.replace(/^fc[_-]?/i, '');
+    }
+    else if (/^call[_-]/i.test(sanitized)) {
+        sanitized = sanitized.replace(/^call[_-]?/i, '');
     }
-    if (/^call[_-]/i.test(trimmed)) {
-        return `fc_${trimmed.replace(/^call[_-]?/i, '')}`;
+    if (!sanitized) {
+        sanitized = Math.random().toString(36).slice(2, 10);
     }
-    return `fc_${trimmed}`;
+    return `fc_${sanitized}`;
 }
 function normalizeWithFallback(options) {
     const normalized = stripPrefix(options.callId);

package/dist/sse/sse-to-json/builders/response-builder.js

@@ -594,7 +594,8 @@ export class ResponsesResponseBuilder {
      * 处理错误事件
      */
     handleError(event) {
-        const msg = event.data?.error?.message;
+        const payload = event.data;
+        const msg = typeof payload?.error?.message === 'string' ? payload.error.message : undefined;
         // 容错：若无有效错误消息或当前响应已标记 completed，则将错误降级为非致命告警
         const status = this.response?.status;
         if (!msg || status === 'completed' || this.config.enableEventRecovery) {