@jsonstudio/llms 0.4.2

package/dist/filters/utils/fieldmap-loader.js

@@ -0,0 +1,16 @@
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export async function loadFieldMapConfig(relativeJsonPath) {
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const p = path.resolve(__dirname, '..', 'config', relativeJsonPath);
+        const text = await fsp.readFile(p, 'utf-8');
+        const obj = JSON.parse(text);
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/filters/utils/snapshot-writer.d.ts

@@ -0,0 +1,10 @@
+import type { FilterStage } from '../types.js';
+export declare function writeFilterSnapshot(options: {
+    requestId?: string;
+    endpoint?: string;
+    profile?: string;
+    stage: FilterStage;
+    name?: string;
+    tag?: string;
+    data: unknown;
+}): Promise<void>;

package/dist/filters/utils/snapshot-writer.js

@@ -0,0 +1,47 @@
+import os from 'node:os';
+import path from 'node:path';
+import * as fsp from 'node:fs/promises';
+function mapEndpointToFolder(ep) {
+    const e = String(ep || '').toLowerCase();
+    if (e.includes('/v1/responses'))
+        return 'openai-responses';
+    if (e.includes('/v1/messages') || e.includes('anthropic'))
+        return 'anthropic-messages';
+    return 'openai-chat';
+}
+function isSnapshotEnabled() {
+    const v = String(process?.env?.RCC_FILTER_SNAPSHOT || process?.env?.RCC_HOOKS_VERBOSITY || '').toLowerCase();
+    return v === '1' || v === 'true' || v === 'verbose';
+}
+export async function writeFilterSnapshot(options) {
+    try {
+        if (!isSnapshotEnabled())
+            return;
+        const rid = options.requestId || `req_${Date.now()}`;
+        const baseOverride = process?.env?.RCC_SNAPSHOT_DIR;
+        const base = baseOverride && baseOverride.trim()
+            ? baseOverride.trim()
+            : path.join(os.homedir(), '.routecodex', 'codex-samples');
+        const folder = mapEndpointToFolder(options.endpoint);
+        const dir = path.join(base, folder);
+        await fsp.mkdir(dir, { recursive: true });
+        const parts = ['filters', options.stage.replace(/\s+/g, ''), options.tag || (options.name ? `after_${options.name}` : 'after')]
+            .filter(Boolean)
+            .join('_');
+        const file = path.join(dir, `${rid}_${parts}.json`);
+        const payload = {
+            meta: {
+                requestId: rid,
+                stage: options.stage,
+                name: options.name,
+                tag: options.tag,
+                profile: options.profile,
+                endpoint: options.endpoint,
+                ts: new Date().toISOString()
+            },
+            data: options.data
+        };
+        await fsp.writeFile(file, JSON.stringify(payload, null, 2), 'utf-8');
+    }
+    catch { /* ignore snapshot errors */ }
+}

package/dist/guidance/index.d.ts

@@ -0,0 +1,3 @@
+export declare function augmentOpenAITools(tools: unknown[]): unknown[];
+export declare function augmentAnthropicTools(tools: unknown[]): unknown[];
+export declare function buildSystemToolGuidance(): string;

package/dist/guidance/index.js

@@ -0,0 +1,228 @@
+// Tool guidance augmentation utilities (OpenAI + Anthropic shapes)
+// Standalone module to keep guidance policy centralized and easy to evolve.
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function ensureObjectSchema(obj) {
+    const o = (obj && typeof obj === 'object') ? obj : {};
+    if (typeof o.type !== 'string')
+        o.type = 'object';
+    if (!isObject(o.properties))
+        o.properties = {};
+    if (typeof o.additionalProperties !== 'boolean')
+        o.additionalProperties = true;
+    return o;
+}
+function appendOnce(desc, guidance, marker) {
+    const base = (typeof desc === 'string') ? desc : '';
+    if (base.includes(marker))
+        return base;
+    return base ? `${base}\n\n${guidance}` : guidance;
+}
+function augmentShell(fn) {
+    const marker = '[Codex Shell Guidance]';
+    const guidance = [
+        marker,
+        'Execute shell commands. Two accepted forms:',
+        '  1) argv tokens: ["ls","-la"]',
+        '  2) bash -lc with a single string: ["bash","-lc","<single command string>"] (required for complex/multi-line/pipe/&&/||/here-doc to interpreter).',
+        'The 3rd arg of bash -lc MUST be exactly one string. Do not split meta-operators (|, >, &&, ||) into separate elements.',
+        'Do not invent extra keys. File writes are FORBIDDEN via shell (no redirection, here-doc to files, sed -i, ed -s, tee). Use apply_patch to edit files.',
+        'Examples: ["ls","-la","Obsidian"]; ["bash","-lc","cd Obsidian && ls -la"]; ["bash","-lc","python3 - <<\'PY\'\\nprint(\\"ok\\")\\nPY"]',
+        'If arguments are invalid (e.g., bash -lc without a single string), return a structured error as the tool result (role=tool, same tool_call_id) and continue the conversation.',
+        'Prefer ripgrep (rg) when available. Keep explanations in assistant text; do not mix narration into tool arguments.'
+    ].join('\n');
+    const params = ensureObjectSchema(fn.parameters);
+    const props = params.properties;
+    // 强约束：仅允许数组形态。分支A：严格 bash -lc 3 元组；分支B：纯 argv（无强校验，运行时由 governor 处理元字符）。
+    props.command = {
+        description: 'Shell command. Use argv tokens OR ["bash","-lc","<single command string>"] for complex commands.',
+        oneOf: [
+            {
+                type: 'array',
+                minItems: 3,
+                maxItems: 3,
+                items: [
+                    { const: 'bash' },
+                    { const: '-lc' },
+                    { type: 'string' }
+                ]
+            },
+            {
+                type: 'array',
+                items: { type: 'string' }
+            }
+        ]
+    };
+    params.additionalProperties = false;
+    fn.parameters = params;
+    fn.description = appendOnce(fn.description, guidance, marker);
+}
+function augmentApplyPatch(fn) {
+    const marker = '[Codex ApplyPatch Guidance]';
+    const guidance = [
+        marker,
+        'Edit files by applying a unified diff patch. Return ONLY the patch text with *** Begin Patch/*** End Patch blocks.',
+        'Example:',
+        '*** Begin Patch',
+        '*** Update File: path/to/file.ts',
+        '@@',
+        '- old line',
+        '+ new line',
+        '*** End Patch'
+    ].join('\n');
+    const params = ensureObjectSchema(fn.parameters);
+    const props = params.properties;
+    if (!isObject(props.patch)) {
+        props.patch = { type: 'string', description: 'Unified diff patch text' };
+    }
+    if (!Array.isArray(params.required)) {
+        params.required = [];
+    }
+    if (!params.required.includes('patch')) {
+        params.required.push('patch');
+    }
+    params.additionalProperties = false;
+    fn.parameters = params;
+    fn.description = appendOnce(fn.description, guidance, marker);
+}
+function augmentUpdatePlan(fn) {
+    const marker = '[Codex Plan Guidance]';
+    const guidance = [
+        marker,
+        'Maintain a short stepwise plan. Exactly one step should be in_progress; others pending/completed.'
+    ].join('\n');
+    fn.description = appendOnce(fn.description, guidance, marker);
+}
+function augmentViewImage(fn) {
+    const marker = '[Codex ViewImage Guidance]';
+    const guidance = [
+        marker,
+        'Attach a local image only. Path must point to an existing image file (.png .jpg .jpeg .gif .webp .bmp .svg .tif .tiff .ico .heic .jxl).',
+        'Never use view_image to read text documents (e.g., .md/.ts/.js/.json). For text content, use shell: {"command":["cat","<path>"]}.'
+    ].join('\n');
+    const params = ensureObjectSchema(fn.parameters);
+    const props = params.properties;
+    if (!isObject(props.path)) {
+        props.path = { type: 'string', description: 'Local filesystem path to an image file' };
+    }
+    params.additionalProperties = false;
+    fn.parameters = params;
+    fn.description = appendOnce(fn.description, guidance, marker);
+}
+function augmentMCP(fn, toolName) {
+    const marker = `[Codex MCP Guidance:${toolName}]`;
+    const guidance = [
+        marker,
+        'Use MCP resources sparingly. Provide only required fields; avoid unnecessary large reads.'
+    ].join('\n');
+    fn.description = appendOnce(fn.description, guidance, marker);
+}
+// For OpenAI tool shape: { type:'function', function:{ name, description?, parameters } }
+export function augmentOpenAITools(tools) {
+    if (!Array.isArray(tools))
+        return tools;
+    const out = [];
+    for (const t of tools) {
+        if (!t || typeof t !== 'object') {
+            out.push(t);
+            continue;
+        }
+        const copy = JSON.parse(JSON.stringify(t));
+        const fn = isObject(copy.function) ? copy.function : null;
+        const name = fn && typeof fn.name === 'string' ? String(fn.name) : undefined;
+        if (fn && name) {
+            const n = name.trim();
+            try {
+                if (n === 'shell')
+                    augmentShell(fn);
+                else if (n === 'apply_patch')
+                    augmentApplyPatch(fn);
+                else if (n === 'update_plan')
+                    augmentUpdatePlan(fn);
+                else if (n === 'view_image')
+                    augmentViewImage(fn);
+                else if (n === 'list_mcp_resources' || n === 'read_mcp_resource' || n === 'list_mcp_resource_templates')
+                    augmentMCP(fn, n);
+            }
+            catch { /* ignore */ }
+        }
+        out.push(copy);
+    }
+    return out;
+}
+// For Anthropic tool shape: { name, description?, input_schema }
+export function augmentAnthropicTools(tools) {
+    if (!Array.isArray(tools))
+        return tools;
+    const out = [];
+    for (const t of tools) {
+        if (!t || typeof t !== 'object') {
+            out.push(t);
+            continue;
+        }
+        const copy = JSON.parse(JSON.stringify(t));
+        const name = typeof copy.name === 'string' ? String(copy.name) : undefined;
+        const desc = typeof copy.description === 'string' ? String(copy.description) : undefined;
+        const schema = ensureObjectSchema(copy.input_schema);
+        if (name) {
+            const n = name.trim();
+            try {
+                if (n === 'apply_patch') {
+                    if (!isObject(schema.properties?.patch)) {
+                        schema.properties.patch = { type: 'string', description: 'Unified diff patch text' };
+                    }
+                    if (!Array.isArray(schema.required))
+                        schema.required = [];
+                    if (!schema.required.includes('patch'))
+                        schema.required.push('patch');
+                    schema.additionalProperties = false;
+                    copy.input_schema = schema;
+                    const marker = '[Codex ApplyPatch Guidance]';
+                    const guidance = [
+                        marker,
+                        'Use unified diff patch with *** Begin Patch/End Patch. Return only the patch text.'
+                    ].join('\n');
+                    copy.description = appendOnce(desc, guidance, marker);
+                }
+                if (n === 'shell') {
+                    const marker = '[Codex Shell Guidance]';
+                    const guidance = [marker, 'Execute commands via argv tokens only (no redirection).'].join('\n');
+                    copy.description = appendOnce(desc, guidance, marker);
+                }
+                if (n === 'update_plan') {
+                    const marker = '[Codex Plan Guidance]';
+                    const guidance = [marker, 'Maintain a short plan; one in_progress step only.'].join('\n');
+                    copy.description = appendOnce(desc, guidance, marker);
+                }
+                if (n === 'view_image' || n === 'list_mcp_resources' || n === 'read_mcp_resource' || n === 'list_mcp_resource_templates') {
+                    const marker = `[Codex MCP Guidance:${n}]`;
+                    const guidance = [marker, 'Use minimally; avoid unnecessary large reads.'].join('\n');
+                    copy.description = appendOnce(desc, guidance, marker);
+                }
+            }
+            catch { /* ignore */ }
+        }
+        out.push(copy);
+    }
+    return out;
+}
+// Build a minimal, consistent system tool guidance string (OpenAI tool_calls model)
+export function buildSystemToolGuidance() {
+    const bullet = (s) => `- ${s}`;
+    const lines = [];
+    lines.push('Tool usage guidance (OpenAI tool_calls) / 工具使用指引（OpenAI 标准）');
+    lines.push(bullet('Always use assistant.tool_calls[].function.{name,arguments}; never embed tool calls in plain text. / 一律通过 tool_calls 调用工具，不要把工具调用写进普通文本。'));
+    lines.push(bullet('function.arguments must be a single JSON string. / arguments 必须是单个 JSON 字符串。'));
+    lines.push(bullet('shell: Place ALL intent into the command argv array only; do not invent extra keys. / shell 所有意图写入 command 数组，不要添加额外键名。'));
+    lines.push(bullet('File writes are FORBIDDEN via shell (no redirection, no here-doc, no sed -i, no ed -s, no tee). Use apply_patch ONLY. / 通过 shell 写文件一律禁止（不得使用重定向、heredoc、sed -i、ed -s、tee）；必须使用 apply_patch。'));
+    lines.push(bullet('apply_patch: Provide a unified diff patch with *** Begin Patch/*** End Patch only. / 仅输出统一 diff 补丁。'));
+    lines.push(bullet('apply_patch example / 示例：\n*** Begin Patch\n*** Update File: path/to/file.ts\n@@\n- old line\n+ new line\n*** End Patch'));
+    lines.push(bullet('update_plan: Keep exactly one step in_progress; others pending/completed. / 仅一个 in_progress 步骤。'));
+    lines.push(bullet('view_image: Path must be an image file (.png .jpg .jpeg .gif .webp .bmp .svg). / 仅图片路径。'));
+    lines.push(bullet('Do NOT use view_image for text files (.md/.ts/.js/.json). Use shell: {"command":["cat","<path>"]}. / 文本文件请用 shell: cat。'));
+    // Preamble alignment with harness: keep a single concise preamble, but no tool-call meta narration.
+    lines.push(bullet('Preamble: Before making tool calls, send ONE brief sentence about immediate next steps (skip for trivial reads); then emit tool_calls. Do not narrate tool-call meta (e.g., “工具调用已生成”). / 预叙：调用工具前可发送一句简短计划（琐碎读取可省略），随后直接生成 tool_calls；不要叙述“已生成工具调用”等元信息。'));
+    return lines.join('\n');
+}
+// 注意：我们不再提供"精炼/替换"已有 system 提示词的能力。

package/dist/hooks/hooks-integration.d.ts

@@ -0,0 +1,161 @@
+/**
+ * LLMSwitch V2 Hooks 集成器（业务命名）
+ *
+ * 集成现有2hooks系统到LLMSwitch V2架构
+ */
+import type { LLMSwitchHookContext, LLMSwitchProcessingResult, EndpointType, ProtocolType, ProcessingMode } from '../api/llmswitch-types.js';
+import { LLMSwitchHookStage } from '../api/llmswitch-types.js';
+/**
+ * Hook执行结果
+ */
+export interface HookExecutionResult {
+    success: boolean;
+    data?: any;
+    results?: any[];
+    error?: Error;
+}
+/**
+ * Hook适配器配置
+ */
+export interface HooksIntegrationConfig {
+    enabled: boolean;
+    timeout: number;
+    retryAttempts: number;
+    parallel: boolean;
+    snapshot: {
+        enabled: boolean;
+        level?: 'verbose' | 'normal' | 'silent';
+        basePath: string;
+        endpointIsolation: {
+            enabled: boolean;
+            pathStructure: 'endpoint/date' | 'endpoint/request' | 'endpoint/timestamp';
+        };
+    };
+    modulePolicies?: Record<string, {
+        enabled?: boolean;
+        snapshotEnabled?: boolean;
+        level?: 'verbose' | 'normal' | 'silent';
+    }>;
+}
+/**
+ * Hook执行上下文构建器
+ */
+export declare class HookContextBuilder {
+    /**
+     * 构建Hook执行上下文
+     */
+    static buildContext(stage: LLMSwitchHookStage, endpoint: EndpointType, originalProtocol: ProtocolType, targetProtocol: ProtocolType, pathIdentifier: string, processingMode: ProcessingMode, hookSequence: number, totalHooks: number, additionalData?: Record<string, any>): LLMSwitchHookContext;
+    /**
+     * 生成执行ID
+     */
+    private static generateExecutionId;
+}
+/**
+ * 快照服务配置
+ */
+export interface SnapshotServiceConfig {
+    enabled: boolean;
+    level?: 'verbose' | 'normal' | 'silent';
+    basePath: string;
+    endpointIsolation: {
+        enabled: boolean;
+        pathStructure: 'endpoint/date' | 'endpoint/request' | 'endpoint/timestamp';
+    };
+}
+/**
+ * 简化的快照服务
+ */
+export declare class SnapshotService {
+    private config;
+    constructor(config: SnapshotServiceConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    saveSnapshot(path: string, data: any): Promise<void>;
+    getStats(): any;
+}
+/**
+ * Hook管理器（简化实现）
+ */
+export declare class HookManager {
+    private handlers;
+    registerHandler(stage: string, handler: Function): void;
+    executeHook(stage: string, params: any): Promise<HookExecutionResult>;
+    getStats(): any;
+    clear(): void;
+}
+/**
+ * LLMSwitch V2 Hooks适配器
+ */
+export declare class HooksIntegration {
+    private hookManager;
+    private snapshotService;
+    private config;
+    private modulePolicies;
+    constructor(config: HooksIntegrationConfig);
+    /**
+     * 初始化Hook适配器
+     */
+    initialize(): Promise<void>;
+    /**
+     * 执行Hook
+     */
+    executeHook(stage: LLMSwitchHookStage, context: LLMSwitchHookContext, data?: any): Promise<LLMSwitchProcessingResult>;
+    /**
+     * 批量执行Hooks
+     */
+    executeHooks(stages: LLMSwitchHookStage[], context: LLMSwitchHookContext, data?: any): Promise<LLMSwitchProcessingResult[]>;
+    /**
+     * 注册Hook处理器
+     */
+    registerHookHandler(stage: LLMSwitchHookStage, handler: Function): void;
+    /**
+     * 获取Hook统计信息
+     */
+    getHookStats(): Record<string, any>;
+    /**
+     * 获取快照统计信息
+     */
+    getSnapshotStats(): Record<string, any>;
+    /**
+     * 执行Hook的核心逻辑
+     */
+    private performHookExecution;
+    /**
+     * 处理快照
+     */
+    private handleSnapshot;
+    /**
+     * 构建快照路径
+     */
+    private buildSnapshotPath;
+    private static loadModulePoliciesFromEnv;
+    /**
+     * 启动适配器
+     */
+    start(): Promise<void>;
+    /**
+     * 停止适配器
+     */
+    stop(): Promise<void>;
+    /**
+     * 销毁适配器
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * 创建Hook适配器的工厂函数
+ */
+export declare function createHooksIntegration(config?: Partial<HooksIntegrationConfig>): HooksIntegration;
+/**
+ * Lightweight helper: write a snapshot using the same SnapshotService and
+ * path conventions as HooksIntegration, without requiring a live hooks
+ * pipeline. Intended for external callers (server/provider/compat) that
+ * want to unify snapshot emission through the core hooks system.
+ */
+export declare function writeSnapshotViaHooks(options: {
+    endpoint: string;
+    stage: string;
+    requestId: string;
+    data: any;
+    verbosity?: 'verbose' | 'normal' | 'silent';
+}): Promise<void>;