@jsonstudio/llms 0.4.2

package/dist/filters/special/response-tool-arguments-whitelist.js

@@ -0,0 +1,56 @@
+function parseJson(str) { try {
+    return JSON.parse(str);
+}
+catch {
+    return null;
+} }
+function isObject(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+/**
+ * Whitelist tool function arguments keys after decode to match schema (e.g., keep only 'command'/'workdir').
+ * Stage: response_pre. Runs after TOON decode and before stringify.
+ */
+export class ResponseToolArgumentsWhitelistFilter {
+    name = 'response_tool_arguments_whitelist';
+    stage = 'response_pre';
+    getWhitelist(_ctx) {
+        // For now, keep minimal keys for shell schema. Can be extended/configured later.
+        const env = String(process?.env?.ROUTECODEX_SHELL_ARGS_KEYS || '').trim();
+        if (env)
+            return env.split(',').map(s => s.trim()).filter(Boolean);
+        return ['command', 'workdir'];
+    }
+    apply(input, context) {
+        try {
+            const out = JSON.parse(JSON.stringify(input || {}));
+            const choices = Array.isArray(out.choices) ? out.choices : [];
+            const keys = this.getWhitelist(context);
+            for (const ch of choices) {
+                const msg = ch && ch.message ? ch.message : undefined;
+                const tcs = msg && Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+                for (const tc of tcs) {
+                    const fn = tc && tc.function ? tc.function : undefined;
+                    const argStr = fn && typeof fn.arguments === 'string' ? fn.arguments : undefined;
+                    if (!argStr)
+                        continue;
+                    const parsed = parseJson(argStr);
+                    if (!isObject(parsed))
+                        continue;
+                    const whitelisted = {};
+                    for (const k of keys) {
+                        if (k in parsed)
+                            whitelisted[k] = parsed[k];
+                    }
+                    try {
+                        fn.arguments = JSON.stringify(whitelisted);
+                    }
+                    catch { /* keep original */ }
+                }
+            }
+            out.choices = choices;
+            return { ok: true, data: out };
+        }
+        catch {
+            return { ok: true, data: input };
+        }
+    }
+}

package/dist/filters/special/response-tool-text-canonicalize.d.ts

@@ -0,0 +1,10 @@
+import type { Filter, FilterContext, FilterResult, JsonObject } from '../types.js';
+/**
+ * Canonicalize assistant textual tool markup into tool_calls (Chat path).
+ * Wrapper around existing canonicalizer to fit the Filter pipeline.
+ */
+export declare class ResponseToolTextCanonicalizeFilter implements Filter<JsonObject> {
+    readonly name = "response_tool_text_canonicalize";
+    readonly stage: FilterContext['stage'];
+    apply(input: JsonObject): FilterResult<JsonObject>;
+}

package/dist/filters/special/response-tool-text-canonicalize.js

@@ -0,0 +1,20 @@
+/**
+ * Canonicalize assistant textual tool markup into tool_calls (Chat path).
+ * Wrapper around existing canonicalizer to fit the Filter pipeline.
+ */
+export class ResponseToolTextCanonicalizeFilter {
+    name = 'response_tool_text_canonicalize';
+    stage = 'response_pre';
+    apply(input) {
+        try {
+            // Defer to existing canonicalizer for behavior parity
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { canonicalizeChatResponseTools } = require('../../conversion/shared/tool-canonicalizer.js');
+            const out = canonicalizeChatResponseTools(input);
+            return { ok: true, data: out };
+        }
+        catch {
+            return { ok: true, data: input };
+        }
+    }
+}

package/dist/filters/special/tool-filter-hooks.d.ts

@@ -0,0 +1,19 @@
+import type { Filter, FilterContext, FilterResult, JsonObject } from '../types.js';
+interface ToolFilterConfigCategoryPolicy {
+    mode?: 'allow' | 'block' | 'require_content';
+    requireContentTypes?: string[];
+}
+interface ToolFilterConfig {
+    categories?: {
+        vision?: ToolFilterConfigCategoryPolicy;
+        mcp?: ToolFilterConfigCategoryPolicy;
+    };
+}
+export declare function setGlobalToolFilterConfig(cfg: ToolFilterConfig | undefined): void;
+export declare function getGlobalToolFilterConfig(): ToolFilterConfig;
+export declare class ToolFilterHookFilter implements Filter<JsonObject> {
+    readonly name = "tool_filter_hook";
+    readonly stage: FilterContext['stage'];
+    apply(input: JsonObject, ctx: FilterContext): FilterResult<JsonObject>;
+}
+export {};

package/dist/filters/special/tool-filter-hooks.js

@@ -0,0 +1,341 @@
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function clone(v) {
+    return JSON.parse(JSON.stringify(v));
+}
+// Global (process-level) config – expected to be filled by host via setGlobalToolFilterConfig。
+// 默认空配置：不改变行为，仅当 hints/配置显式要求时才执行过滤。
+let globalConfig = {};
+export function setGlobalToolFilterConfig(cfg) {
+    if (!cfg || !isObject(cfg)) {
+        globalConfig = {};
+        return;
+    }
+    globalConfig = clone(cfg);
+}
+export function getGlobalToolFilterConfig() {
+    return globalConfig;
+}
+// --- Vision 工具 Hook：仅在 hints/categoryOverrides 明确要求时启用 ---
+function hasImageContent(messages) {
+    try {
+        for (const m of messages) {
+            if (!m || typeof m !== 'object')
+                continue;
+            const c = m.content;
+            if (Array.isArray(c)) {
+                for (const part of c) {
+                    if (part && typeof part === 'object') {
+                        const t = String(part.type || '').toLowerCase();
+                        if (t.includes('image'))
+                            return true;
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // non-fatal
+    }
+    return false;
+}
+function isVisionTool(tool) {
+    try {
+        const name = tool &&
+            typeof tool === 'object' &&
+            tool.function &&
+            typeof tool.function.name === 'string'
+            ? String(tool.function.name).toLowerCase()
+            : '';
+        if (!name)
+            return false;
+        // 保守实现：仅将 view_image 视为视觉工具；其他名称可通过上层配置扩展。
+        if (name === 'view_image')
+            return true;
+        if (name.includes('vision'))
+            return true;
+    }
+    catch {
+        // ignore
+    }
+    return false;
+}
+const visionToolHook = ctx => {
+    const { tools, messages, hints, config, recordDecision } = ctx;
+    if (!tools.length)
+        return;
+    const hasVision = tools.some(t => isVisionTool(t));
+    if (!hasVision)
+        return;
+    const override = hints.categoryOverrides?.vision;
+    const cfgPolicy = config.categories?.vision?.mode;
+    // 默认策略：require_content —— 有视觉工具但无图像内容时进行过滤提示
+    const mode = override || cfgPolicy || 'require_content';
+    if (mode === 'allow')
+        return;
+    const hasImage = hasImageContent(messages);
+    const next = [];
+    for (const t of tools) {
+        if (isVisionTool(t)) {
+            if (mode === 'block' || (mode === 'require_content' && !hasImage)) {
+                const name = t &&
+                    typeof t === 'object' &&
+                    t.function &&
+                    typeof t.function.name === 'string'
+                    ? String(t.function.name)
+                    : 'unknown';
+                recordDecision({
+                    name,
+                    action: 'block',
+                    category: 'vision',
+                    reason: mode === 'block'
+                        ? 'vision_tool_blocked_by_policy'
+                        : 'vision_tool_without_image_link',
+                });
+                continue;
+            }
+        }
+        next.push(t);
+    }
+    ctx.tools = next;
+};
+// --- MCP 工具 Hook：会话内阶段性暴露策略 ---
+function isMcpToolName(name) {
+    const lower = name.toLowerCase();
+    return (lower === 'list_mcp_resources' ||
+        lower === 'read_mcp_resource' ||
+        lower === 'list_mcp_resource_templates');
+}
+function deriveMcpSessionState(messages) {
+    let listRequested = false;
+    let listEmpty = false;
+    try {
+        for (const m of messages) {
+            if (!m || typeof m !== 'object')
+                continue;
+            const role = String(m.role || '').toLowerCase();
+            // assistant.tool_calls: 视为对 list_mcp_resources 的“请求”
+            if (role === 'assistant' && Array.isArray(m.tool_calls)) {
+                for (const tc of m.tool_calls) {
+                    try {
+                        const fn = tc && tc.function;
+                        const name = fn && typeof fn.name === 'string'
+                            ? String(fn.name).toLowerCase()
+                            : '';
+                        if (name === 'list_mcp_resources') {
+                            listRequested = true;
+                        }
+                    }
+                    catch {
+                        /* ignore single tool_call */
+                    }
+                }
+            }
+            // tool 角色消息：检查 rcc.tool.v1 包装的结果是否为空
+            if (role === 'tool' && typeof m.content === 'string') {
+                try {
+                    const parsed = JSON.parse(m.content);
+                    if (parsed &&
+                        typeof parsed === 'object' &&
+                        parsed.version === 'rcc.tool.v1' &&
+                        parsed.tool &&
+                        typeof parsed.tool.name === 'string') {
+                        const nm = String(parsed.tool.name).toLowerCase();
+                        if (nm === 'list_mcp_resources') {
+                            listRequested = true;
+                            const out = parsed.result?.output;
+                            if (Array.isArray(out) && out.length === 0) {
+                                listEmpty = true;
+                            }
+                            else if (out &&
+                                typeof out === 'object' &&
+                                Array.isArray(out.resources) &&
+                                out.resources.length === 0) {
+                                listEmpty = true;
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // ignore parse errors
+                }
+            }
+        }
+    }
+    catch {
+        // ignore errors
+    }
+    return { listRequested, listEmpty };
+}
+const mcpToolHook = ctx => {
+    const { tools, messages, hints, recordDecision } = ctx;
+    if (!tools.length)
+        return;
+    const mcpTools = tools.filter(t => {
+        try {
+            const n = t &&
+                typeof t === 'object' &&
+                t.function &&
+                typeof t.function.name === 'string'
+                ? String(t.function.name)
+                : '';
+            return isMcpToolName(n);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!mcpTools.length)
+        return;
+    const override = hints.categoryOverrides?.mcp;
+    if (override === 'block') {
+        // 请求级别完全关闭 MCP
+        ctx.tools = tools.filter(t => !mcpTools.includes(t));
+        for (const t of mcpTools) {
+            const name = t &&
+                typeof t === 'object' &&
+                t.function &&
+                typeof t.function.name === 'string'
+                ? String(t.function.name)
+                : 'unknown';
+            recordDecision({
+                name,
+                action: 'block',
+                category: 'mcp',
+                reason: 'mcp_blocked_by_override',
+            });
+        }
+        return;
+    }
+    // 会话内阶段性策略：
+    // 1) 如果 list_mcp_resources 从未在本会话中被请求过 → 仅暴露 list_mcp_resources，过滤 read/templates。
+    // 2) 如果 list_mcp_resources 已请求且结果为空 → 完全过滤所有 MCP 工具。
+    const { listRequested, listEmpty } = deriveMcpSessionState(messages);
+    const next = [];
+    for (const t of tools) {
+        let name = '';
+        try {
+            name =
+                t &&
+                    typeof t === 'object' &&
+                    t.function &&
+                    typeof t.function.name === 'string'
+                    ? String(t.function.name)
+                    : '';
+        }
+        catch {
+            name = '';
+        }
+        const lower = name.toLowerCase();
+        const isMcp = isMcpToolName(name);
+        if (!isMcp) {
+            next.push(t);
+            continue;
+        }
+        if (!listRequested) {
+            // list 未被请求过：保留 list_mcp_resources，其它 MCP 工具全部过滤
+            if (lower === 'list_mcp_resources') {
+                next.push(t);
+                recordDecision({
+                    name,
+                    action: 'allow',
+                    category: 'mcp',
+                    reason: 'mcp_list_exposed_before_first_use',
+                });
+            }
+            else {
+                recordDecision({
+                    name,
+                    action: 'block',
+                    category: 'mcp',
+                    reason: 'mcp_non_list_blocked_until_list_called',
+                });
+            }
+            continue;
+        }
+        if (listEmpty) {
+            // list 已请求且结果为空：完全屏蔽所有 MCP 工具
+            recordDecision({
+                name,
+                action: 'block',
+                category: 'mcp',
+                reason: 'mcp_disabled_for_session_after_empty_list',
+            });
+            continue;
+        }
+        // list 已请求且非空：保留现有行为（交由其它层/配置控制）
+        next.push(t);
+    }
+    ctx.tools = next;
+};
+const requestHooks = [visionToolHook, mcpToolHook];
+export class ToolFilterHookFilter {
+    name = 'tool_filter_hook';
+    stage = 'request_finalize';
+    apply(input, ctx) {
+        try {
+            const out = clone(input || {});
+            const tools = Array.isArray(out.tools)
+                ? out.tools
+                : [];
+            if (!tools.length) {
+                return { ok: true, data: out };
+            }
+            const messages = Array.isArray(out.messages)
+                ? out.messages
+                : [];
+            const hints = (ctx.toolFilterHints && clone(ctx.toolFilterHints)) || {
+                requestedDecisions: [],
+            };
+            const config = getGlobalToolFilterConfig();
+            const decisions = [];
+            const hookCtx = {
+                tools,
+                messages,
+                hints,
+                config,
+                stage: 'request',
+                recordDecision: d => {
+                    decisions.push(d);
+                },
+            };
+            for (const hook of requestHooks) {
+                try {
+                    const res = hook(hookCtx);
+                    if (res && typeof res.then === 'function') {
+                        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                        res.catch(() => { });
+                    }
+                }
+                catch {
+                    // ignore single hook failure
+                }
+            }
+            out.tools = hookCtx.tools;
+            if (Array.isArray(out.tools) && out.tools.length === 0) {
+                try {
+                    if ('tool_choice' in out)
+                        delete out.tool_choice;
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            // 记录决策（供调试/快照使用）
+            if (!Array.isArray(hints.decided))
+                hints.decided = [];
+            hints.decided = hints.decided.concat(decisions);
+            return {
+                ok: true,
+                data: out,
+                metrics: decisions.length
+                    ? { toolFilterDecisions: clone(decisions) }
+                    : undefined,
+            };
+        }
+        catch {
+            return { ok: true, data: input };
+        }
+    }
+}

package/dist/filters/special/tool-post-constraints.d.ts

@@ -0,0 +1,31 @@
+import type { Filter, FilterContext, FilterResult, JsonObject } from '../types.js';
+type ConstraintMatchCondition = 'missing' | 'empty' | 'missingOrEmpty';
+interface ToolConstraintRule {
+    id: string;
+    direction: 'request' | 'response' | 'both';
+    providerProtocol?: string;
+    providerId?: string;
+    modelId?: string;
+    toolNamePattern?: string;
+    path: string;
+    when: ConstraintMatchCondition;
+    action: 'warn' | 'patch' | 'drop';
+    patchText?: string;
+}
+interface ToolGovernanceConstraintsConfig {
+    rules: ToolConstraintRule[];
+}
+/**
+ * Tool post-constraints filter（请求/响应阶段的最后一小步约束）：
+ * - 默认只记录（warn），不修改 payload；
+ * - 修剪/修复行为完全由配置驱动（ToolGovernanceConstraintsConfig）；
+ * - 当前仅实现缺失/空 description 的简单场景，后续可按配置扩展。
+ */
+export declare class ToolPostConstraintsFilter implements Filter<JsonObject> {
+    readonly name = "tool_post_constraints";
+    readonly stage: FilterContext['stage'];
+    private readonly config;
+    constructor(stage: FilterContext['stage'], config?: ToolGovernanceConstraintsConfig);
+    apply(input: JsonObject, ctx: FilterContext): FilterResult<JsonObject>;
+}
+export {};

package/dist/filters/special/tool-post-constraints.js

@@ -0,0 +1,120 @@
+function matchesPattern(name, pattern) {
+    if (!pattern)
+        return true;
+    if (!name)
+        return false;
+    // very small glob subset: '*' wildcard
+    const esc = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    const re = new RegExp(`^${esc}$`, 'i');
+    return re.test(name);
+}
+function getToolArray(root) {
+    const tools = (root && Array.isArray(root.tools)) ? root.tools : [];
+    return tools;
+}
+function checkCondition(v, cond) {
+    if (cond === 'missing')
+        return v === undefined;
+    if (cond === 'empty')
+        return typeof v === 'string' && v.trim() === '';
+    return v === undefined || (typeof v === 'string' && v.trim() === '');
+}
+/**
+ * Tool post-constraints filter（请求/响应阶段的最后一小步约束）：
+ * - 默认只记录（warn），不修改 payload；
+ * - 修剪/修复行为完全由配置驱动（ToolGovernanceConstraintsConfig）；
+ * - 当前仅实现缺失/空 description 的简单场景，后续可按配置扩展。
+ */
+export class ToolPostConstraintsFilter {
+    name = 'tool_post_constraints';
+    stage;
+    config;
+    constructor(stage, config) {
+        this.stage = stage;
+        if (config) {
+            this.config = config;
+            return;
+        }
+        const defaultRules = [];
+        // 默认行为：在请求侧最终阶段（request_finalize）修复缺失/空 description 的工具，
+        // 避免因为 description 不合规导致整组工具被清空。
+        if (stage === 'request_finalize') {
+            defaultRules.push({
+                id: 'patch_missing_tool_description',
+                direction: 'request',
+                path: 'tools[*].function.description',
+                when: 'missingOrEmpty',
+                action: 'patch',
+                patchText: 'Auto-generated description for ${toolName}'
+            });
+        }
+        this.config = { rules: defaultRules };
+    }
+    apply(input, ctx) {
+        try {
+            if (!this.config.rules || !this.config.rules.length) {
+                return { ok: true, data: input };
+            }
+            const out = JSON.parse(JSON.stringify(input || {}));
+            const direction = (typeof ctx.stage === 'string' && ctx.stage.startsWith('request_')) ? 'request' : 'response';
+            const providerProtocol = ctx.profile || '';
+            const providerId = ctx.providerId || '';
+            const modelId = ctx.modelId || '';
+            const tools = getToolArray(out);
+            if (!tools.length) {
+                return { ok: true, data: out };
+            }
+            const issues = [];
+            for (const rule of this.config.rules) {
+                if (rule.direction !== 'both' && rule.direction !== direction)
+                    continue;
+                if (rule.providerProtocol && rule.providerProtocol !== providerProtocol)
+                    continue;
+                if (rule.providerId && rule.providerId !== providerId)
+                    continue;
+                if (rule.modelId && rule.modelId !== modelId)
+                    continue;
+                // 当前仅支持 tools[*].function.description 这一类路径
+                if (rule.path !== 'tools[*].function.description')
+                    continue;
+                for (let i = 0; i < tools.length; i++) {
+                    const t = tools[i];
+                    if (!t || typeof t !== 'object')
+                        continue;
+                    const fn = t.function;
+                    const name = typeof fn?.name === 'string' ? fn.name : '';
+                    if (!matchesPattern(name, rule.toolNamePattern))
+                        continue;
+                    const desc = fn?.description;
+                    if (!checkCondition(desc, rule.when))
+                        continue;
+                    if (rule.action === 'patch' && rule.patchText) {
+                        fn.description = rule.patchText.replace('${toolName}', name || 'tool');
+                    }
+                    else if (rule.action === 'drop') {
+                        tools.splice(i, 1);
+                        i--;
+                    }
+                    issues.push({ ruleId: rule.id, toolName: name, action: rule.action });
+                }
+            }
+            if (issues.length && ctx?.logger && typeof ctx.logger.log === 'function') {
+                try {
+                    ctx.logger.log('tool-post-constraints', {
+                        requestId: ctx.requestId,
+                        endpoint: ctx.endpoint,
+                        profile: ctx.profile,
+                        issues
+                    });
+                }
+                catch {
+                    // ignore logging failures
+                }
+            }
+            return { ok: true, data: out };
+        }
+        catch {
+            return { ok: true, data: input };
+        }
+    }
+}

package/dist/filters/types.d.ts

@@ -0,0 +1,68 @@
+export type JsonObject = Record<string, unknown>;
+export type FilterStage = 'request_pre' | 'request_map' | 'request_post' | 'request_finalize' | 'response_pre' | 'response_map' | 'response_post' | 'response_finalize';
+export interface FilterContext {
+    requestId?: string;
+    model?: string;
+    endpoint?: string;
+    provider?: string;
+    profile?: string;
+    stage: FilterStage;
+    stream?: boolean;
+    toolFilterHints?: ToolFilterHints;
+    debug?: {
+        emit?: (event: string, data: unknown) => void;
+    };
+}
+export interface FilterResult<T = JsonObject> {
+    ok: boolean;
+    data: T;
+    warnings?: string[];
+    metrics?: Record<string, unknown>;
+}
+export interface Filter<T = JsonObject> {
+    readonly name: string;
+    readonly stage: FilterStage;
+    apply(input: T, ctx: FilterContext): Promise<FilterResult<T>> | FilterResult<T>;
+}
+export type ToolFilterAction = 'allow' | 'block' | 'rewrite';
+export interface ToolFilterDecision {
+    name: string;
+    action: ToolFilterAction;
+    reason?: string;
+    category?: string;
+}
+export interface ToolFilterHints {
+    requestedDecisions?: ToolFilterDecision[];
+    categories?: {
+        vision?: boolean;
+        mcp?: boolean;
+        webSearch?: boolean;
+        codeExecution?: boolean;
+        fileSearch?: boolean;
+        dataAnalysis?: boolean;
+    };
+    categoryOverrides?: {
+        vision?: 'allow' | 'block' | 'require_content';
+        mcp?: 'allow' | 'block';
+    };
+    decided?: ToolFilterDecision[];
+}
+export interface FieldMapRule {
+    sourcePath: string;
+    targetPath: string;
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    transform?: string;
+}
+export interface FieldMapConfig {
+    request?: FieldMapRule[];
+    response?: FieldMapRule[];
+}
+export interface WhitelistConfig {
+    allow: string[];
+}
+export interface BlacklistConfig {
+    deny: string[];
+}
+export interface AddFieldsConfig {
+    fields: Record<string, unknown>;
+}

package/dist/filters/types.js

@@ -0,0 +1,3 @@
+// Filter architecture: types and contracts (V2)
+// This module defines a minimal, composable filter pipeline for request/response shaping.
+export {};

package/dist/filters/utils/fieldmap-loader.d.ts

@@ -0,0 +1,2 @@
+import type { FieldMapConfig } from '../types.js';
+export declare function loadFieldMapConfig(relativeJsonPath: string): Promise<FieldMapConfig | null>;