@jsonstudio/llms 0.4.2

package/dist/filters/builtin/whitelist-filter.js

@@ -0,0 +1,19 @@
+export class WhitelistFilter {
+    name = 'whitelist';
+    stage;
+    allow;
+    constructor(stage, allow) {
+        this.stage = stage;
+        this.allow = new Set(allow || []);
+    }
+    apply(input) {
+        if (!input || typeof input !== 'object')
+            return { ok: true, data: input };
+        const out = {};
+        for (const k of Object.keys(input)) {
+            if (this.allow.has(k))
+                out[k] = input[k];
+        }
+        return { ok: true, data: out };
+    }
+}

package/dist/filters/engine.d.ts

@@ -0,0 +1,16 @@
+import type { Filter, FilterContext, FieldMapConfig, JsonObject } from './types.js';
+export declare class FilterEngine {
+    private readonly filters;
+    private fieldMap?;
+    private readonly transforms;
+    registerFilter(filter: Filter): void;
+    setFieldMap(config: FieldMapConfig): void;
+    registerTransform(name: string, fn: (v: unknown) => unknown): void;
+    run(stage: FilterContext['stage'], payload: JsonObject, ctxBase: Omit<FilterContext, 'stage'>): Promise<JsonObject>;
+    private applyFieldMap;
+    private coerce;
+    private deepClone;
+    private mutateWildcardPath;
+    private getByPath;
+    private setByPath;
+}

package/dist/filters/engine.js

@@ -0,0 +1,167 @@
+import { writeFilterSnapshot } from './utils/snapshot-writer.js';
+// Lightweight, dependency-free filter engine. Field-mapping supports a minimal dot-path subset.
+export class FilterEngine {
+    filters = [];
+    fieldMap;
+    transforms = {};
+    registerFilter(filter) { this.filters.push(filter); }
+    setFieldMap(config) { this.fieldMap = config; }
+    registerTransform(name, fn) { this.transforms[name] = fn; }
+    async run(stage, payload, ctxBase) {
+        let out = payload;
+        const ctx = { ...ctxBase, stage };
+        try {
+            await writeFilterSnapshot({ requestId: ctx.requestId, endpoint: ctx.endpoint, profile: ctx.profile, stage, tag: 'begin', data: out });
+        }
+        catch { }
+        // stage pre filters
+        for (const f of this.filters) {
+            if (f.stage !== stage)
+                continue;
+            const res = await Promise.resolve(f.apply(out, ctx));
+            if (!res.ok)
+                continue; // keep last good state
+            out = res.data;
+            try {
+                await writeFilterSnapshot({ requestId: ctx.requestId, endpoint: ctx.endpoint, profile: ctx.profile, stage, name: f.name, tag: 'after', data: out });
+            }
+            catch { }
+        }
+        // field map in map stages
+        if (stage === 'request_map' || stage === 'response_map') {
+            const rules = (stage === 'request_map') ? (this.fieldMap?.request || []) : (this.fieldMap?.response || []);
+            try {
+                await writeFilterSnapshot({ requestId: ctx.requestId, endpoint: ctx.endpoint, profile: ctx.profile, stage, tag: 'map_before', data: out });
+            }
+            catch { }
+            out = this.applyFieldMap(out, rules);
+            try {
+                await writeFilterSnapshot({ requestId: ctx.requestId, endpoint: ctx.endpoint, profile: ctx.profile, stage, tag: 'map_after', data: out });
+            }
+            catch { }
+        }
+        try {
+            await writeFilterSnapshot({ requestId: ctx.requestId, endpoint: ctx.endpoint, profile: ctx.profile, stage, tag: 'end', data: out });
+        }
+        catch { }
+        return out;
+    }
+    applyFieldMap(input, rules) {
+        if (!rules?.length)
+            return input;
+        const clone = this.deepClone(input);
+        for (const r of rules) {
+            // In-place wildcard support when sourcePath===targetPath and contains [*]
+            if (r.sourcePath === r.targetPath && /\[\*\]/.test(r.sourcePath)) {
+                this.mutateWildcardPath(clone, r.sourcePath, (val) => {
+                    const v1 = (r.transform && this.transforms[r.transform]) ? this.transforms[r.transform](val) : val;
+                    return this.coerce(v1, r.type);
+                });
+                continue;
+            }
+            const srcVals = this.getByPath(clone, r.sourcePath);
+            if (srcVals.length === 0)
+                continue;
+            const v0 = srcVals[0];
+            const v1 = (r.transform && this.transforms[r.transform]) ? this.transforms[r.transform](v0) : v0;
+            const v2 = this.coerce(v1, r.type);
+            this.setByPath(clone, r.targetPath, v2);
+        }
+        return clone;
+    }
+    coerce(v, t) {
+        if (!t)
+            return v;
+        try {
+            switch (t) {
+                case 'string': return (typeof v === 'string') ? v : JSON.stringify(v ?? '');
+                case 'number': return (typeof v === 'number') ? v : Number(v);
+                case 'boolean': return (typeof v === 'boolean') ? v : Boolean(v);
+                case 'object': return (v && typeof v === 'object') ? v : {};
+                case 'array': return Array.isArray(v) ? v : (v == null ? [] : [v]);
+                default: return v;
+            }
+        }
+        catch {
+            return v;
+        }
+    }
+    deepClone(o) { return JSON.parse(JSON.stringify(o)); }
+    mutateWildcardPath(obj, path, fn) {
+        const segs = path.split('.').map(s => s.trim()).filter(Boolean);
+        const recur = (node, idx) => {
+            if (idx >= segs.length)
+                return;
+            const seg = segs[idx];
+            const m = seg.match(/^(\w+)(\[\*\])?$/);
+            if (!m)
+                return;
+            const key = m[1];
+            const star = !!m[2];
+            if (!node || typeof node !== 'object' || !(key in node))
+                return;
+            const next = node[key];
+            if (!star) {
+                if (idx === segs.length - 1) {
+                    node[key] = fn(next);
+                }
+                else {
+                    recur(next, idx + 1);
+                }
+                return;
+            }
+            // star: array expected
+            if (Array.isArray(next)) {
+                if (idx === segs.length - 1) {
+                    for (let i = 0; i < next.length; i++) {
+                        next[i] = fn(next[i]);
+                    }
+                }
+                else {
+                    for (const item of next) {
+                        recur(item, idx + 1);
+                    }
+                }
+            }
+        };
+        recur(obj, 0);
+    }
+    // Minimal dot-path getter (no array wildcards). Returns array for symmetry with potential multi-matches later.
+    getByPath(obj, path) {
+        try {
+            if (!obj || typeof obj !== 'object')
+                return [];
+            const parts = path.split('.').map(s => s.trim()).filter(Boolean);
+            let cur = obj;
+            for (const p of parts) {
+                if (cur && typeof cur === 'object' && p in cur)
+                    cur = cur[p];
+                else
+                    return [];
+            }
+            return [cur];
+        }
+        catch {
+            return [];
+        }
+    }
+    setByPath(obj, path, value) {
+        try {
+            if (!obj || typeof obj !== 'object')
+                return;
+            const parts = path.split('.').map(s => s.trim()).filter(Boolean);
+            let cur = obj;
+            for (let i = 0; i < parts.length; i++) {
+                const p = parts[i];
+                if (i === parts.length - 1) {
+                    cur[p] = value;
+                    break;
+                }
+                if (!cur[p] || typeof cur[p] !== 'object')
+                    cur[p] = {};
+                cur = cur[p];
+            }
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/filters/index.d.ts

@@ -0,0 +1,19 @@
+export * from './types.js';
+export * from './engine.js';
+export * from './builtin/whitelist-filter.js';
+export * from './builtin/blacklist-filter.js';
+export * from './builtin/add-fields-filter.js';
+export * from './special/request-toolcalls-stringify.js';
+export * from './special/request-tool-choice-policy.js';
+export * from './special/request-tool-list-filter.js';
+export * from './special/tool-filter-hooks.js';
+export * from './special/request-streaming-to-nonstreaming.js';
+export * from './special/response-tool-text-canonicalize.js';
+export * from './special/response-tool-arguments-stringify.js';
+export * from './special/response-finish-invariants.js';
+export * from './special/request-tools-normalize.js';
+export * from './special/response-tool-arguments-toon-decode.js';
+export * from './special/response-tool-arguments-blacklist.js';
+export * from './special/response-tool-arguments-schema-converge.js';
+export * from './special/response-tool-arguments-whitelist.js';
+export * from './special/tool-post-constraints.js';

package/dist/filters/index.js

@@ -0,0 +1,24 @@
+export * from './types.js';
+export * from './engine.js';
+// Built-ins
+export * from './builtin/whitelist-filter.js';
+export * from './builtin/blacklist-filter.js';
+export * from './builtin/add-fields-filter.js';
+// Specialized (initial set)
+export * from './special/request-toolcalls-stringify.js';
+export * from './special/request-tool-choice-policy.js';
+export * from './special/request-tool-list-filter.js';
+export * from './special/tool-filter-hooks.js';
+export * from './special/request-streaming-to-nonstreaming.js';
+export * from './special/response-tool-text-canonicalize.js';
+export * from './special/response-tool-arguments-stringify.js';
+export * from './special/response-finish-invariants.js';
+// TOON support (default ON via RCC_TOON_ENABLE unless explicitly disabled)
+export * from './special/request-tools-normalize.js';
+export * from './special/response-tool-arguments-toon-decode.js';
+// Arguments policy filters (synced)
+export * from './special/response-tool-arguments-blacklist.js';
+export * from './special/response-tool-arguments-schema-converge.js';
+export * from './special/response-tool-arguments-whitelist.js';
+// Post-constraints（工具治理之后的轻量约束层）
+export * from './special/tool-post-constraints.js';

package/dist/filters/special/request-streaming-to-nonstreaming.d.ts

@@ -0,0 +1,12 @@
+import type { Filter, FilterContext, FilterResult, JsonObject } from '../types.js';
+/**
+ * RequestStreamingToNonStreamingFilter (request_post)
+ * - Unifies provider requests to non-streaming regardless of inbound stream flag.
+ * - Preserves original intent via `originalStream` and `_originalStreamOptions`,
+ *   but ensures `stream: false` is sent to providers.
+ */
+export declare class RequestStreamingToNonStreamingFilter implements Filter<JsonObject> {
+    readonly name = "request_streaming_to_nonstreaming";
+    readonly stage: FilterContext['stage'];
+    apply(input: JsonObject): FilterResult<JsonObject>;
+}

package/dist/filters/special/request-streaming-to-nonstreaming.js

@@ -0,0 +1,27 @@
+/**
+ * RequestStreamingToNonStreamingFilter (request_post)
+ * - Unifies provider requests to non-streaming regardless of inbound stream flag.
+ * - Preserves original intent via `originalStream` and `_originalStreamOptions`,
+ *   but ensures `stream: false` is sent to providers.
+ */
+export class RequestStreamingToNonStreamingFilter {
+    name = 'request_streaming_to_nonstreaming';
+    stage = 'request_post';
+    apply(input) {
+        try {
+            const out = JSON.parse(JSON.stringify(input || {}));
+            if (out.stream === true) {
+                out.originalStream = true;
+                out.stream = false;
+            }
+            if (out.stream_options != null) {
+                out._originalStreamOptions = out.stream_options;
+                delete out.stream_options;
+            }
+            return { ok: true, data: out };
+        }
+        catch {
+            return { ok: true, data: input };
+        }
+    }
+}

package/dist/filters/special/request-tool-choice-policy.d.ts

@@ -0,0 +1,11 @@
+import type { Filter, FilterContext, FilterResult, JsonObject } from '../types.js';
+/**
+ * Tool choice policy:
+ * - If tools exist and no tool_choice, set tool_choice='auto'
+ * - If no tools, remove tool_choice
+ */
+export declare class RequestToolChoicePolicyFilter implements Filter<JsonObject> {
+    readonly name = "request_tool_choice_policy";
+    readonly stage: FilterContext['stage'];
+    apply(input: JsonObject): FilterResult<JsonObject>;
+}

package/dist/filters/special/request-tool-choice-policy.js

@@ -0,0 +1,27 @@
+/**
+ * Tool choice policy:
+ * - If tools exist and no tool_choice, set tool_choice='auto'
+ * - If no tools, remove tool_choice
+ */
+export class RequestToolChoicePolicyFilter {
+    name = 'request_tool_choice_policy';
+    stage = 'request_post';
+    apply(input) {
+        try {
+            const out = JSON.parse(JSON.stringify(input || {}));
+            const tools = Array.isArray(out.tools) ? out.tools : [];
+            if (tools.length > 0) {
+                if (out.tool_choice == null)
+                    out.tool_choice = 'auto';
+            }
+            else {
+                if (Object.prototype.hasOwnProperty.call(out, 'tool_choice'))
+                    delete out.tool_choice;
+            }
+            return { ok: true, data: out };
+        }
+        catch {
+            return { ok: true, data: input };
+        }
+    }
+}

package/dist/filters/special/request-tool-list-filter.d.ts

@@ -0,0 +1,11 @@
+import type { Filter, FilterContext, FilterResult, JsonObject } from '../types.js';
+/**
+ * RequestToolListFilter (request_pre)
+ * - Generic tool-list filter/augment hook
+ * - Currently only handles MCP tools with phase-based exposure
+ */
+export declare class RequestToolListFilter implements Filter<JsonObject> {
+    readonly name = "request_tool_list_filter";
+    readonly stage: FilterContext['stage'];
+    apply(input: JsonObject): FilterResult<JsonObject>;
+}

package/dist/filters/special/request-tool-list-filter.js

@@ -0,0 +1,167 @@
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function envMode() {
+    const v = String(process?.env?.RCC_MCP_EXPOSE || '').toLowerCase();
+    if (v === 'off' || v === '0' || v === 'false')
+        return 'off';
+    if (v === 'all')
+        return 'all';
+    return 'phase';
+}
+function getEnvServers() {
+    const raw = String(process?.env?.RCC_MCP_SERVERS || '').trim();
+    if (!raw)
+        return [];
+    return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+function collectServersFromMessages(messages) {
+    const out = new Set();
+    try {
+        for (const m of messages) {
+            if (!m || typeof m !== 'object')
+                continue;
+            const role = String(m.role || '').toLowerCase();
+            if (role === 'assistant') {
+                const tcs = Array.isArray(m.tool_calls) ? m.tool_calls : [];
+                for (const tc of tcs) {
+                    try {
+                        const fn = tc.function;
+                        const a = fn?.arguments;
+                        let parsed = null;
+                        if (typeof a === 'string') {
+                            try {
+                                parsed = JSON.parse(a);
+                            }
+                            catch { /* ignore */ }
+                        }
+                        else if (a && typeof a === 'object')
+                            parsed = a;
+                        const s = parsed?.server;
+                        if (typeof s === 'string' && s.trim())
+                            out.add(s.trim());
+                    }
+                    catch { /* one tool_call */ }
+                }
+            }
+            else if (role === 'tool') {
+                const c = m.content;
+                if (typeof c === 'string') {
+                    try {
+                        const obj = JSON.parse(c);
+                        const s1 = obj?.arguments?.server;
+                        if (typeof s1 === 'string' && s1.trim())
+                            out.add(s1.trim());
+                        const s2 = obj?.server;
+                        if (typeof s2 === 'string' && s2.trim())
+                            out.add(s2.trim());
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return Array.from(out);
+}
+function ensureFunctionTool(tools, name, description, parameters) {
+    const idx = tools.findIndex(t => t && typeof t === 'object' && t.type === 'function' && t.function && t.function.name === name);
+    if (idx >= 0) {
+        const cur = tools[idx];
+        const fn = (cur.function = cur.function || {});
+        fn.name = name;
+        if (typeof fn.description !== 'string')
+            fn.description = description;
+        fn.parameters = parameters;
+    }
+    else {
+        tools.push({ type: 'function', function: { name, description, parameters } });
+    }
+}
+function removeToolByName(tools, name) {
+    for (let i = tools.length - 1; i >= 0; i--) {
+        const t = tools[i];
+        if (t && typeof t === 'object' && t.type === 'function' && t.function && t.function.name === name) {
+            tools.splice(i, 1);
+        }
+    }
+}
+/**
+ * RequestToolListFilter (request_pre)
+ * - Generic tool-list filter/augment hook
+ * - Currently only handles MCP tools with phase-based exposure
+ */
+export class RequestToolListFilter {
+    name = 'request_tool_list_filter';
+    stage = 'request_pre';
+    apply(input) {
+        try {
+            const out = JSON.parse(JSON.stringify(input || {}));
+            const tools = Array.isArray(out.tools) ? out.tools : [];
+            if (!tools.length)
+                return { ok: true, data: out };
+            const mode = envMode();
+            if (mode === 'off')
+                return { ok: true, data: out };
+            const messages = Array.isArray(out.messages) ? out.messages : [];
+            const servers = new Set();
+            for (const s of getEnvServers())
+                servers.add(s);
+            for (const s of collectServersFromMessages(messages))
+                servers.add(s);
+            const knownServers = Array.from(servers);
+            // MCP tool schemas
+            const listResParams = {
+                type: 'object',
+                properties: {
+                    server: { type: 'string' },
+                    filter: { type: 'string' },
+                    root: { type: 'string' }
+                },
+                additionalProperties: false
+            };
+            const listTplParams = {
+                type: 'object',
+                properties: {
+                    cursor: { type: 'string' },
+                    server: { type: 'string' }
+                },
+                additionalProperties: false
+            };
+            const readResParamsBase = {
+                type: 'object',
+                properties: {
+                    server: { type: 'string' },
+                    uri: { type: 'string' }
+                },
+                required: ['server', 'uri'],
+                additionalProperties: false
+            };
+            if (mode === 'all') {
+                ensureFunctionTool(tools, 'list_mcp_resources', 'List resources from an MCP server.', listResParams);
+                ensureFunctionTool(tools, 'list_mcp_resource_templates', 'List resource templates from MCP servers.', listTplParams);
+                ensureFunctionTool(tools, 'read_mcp_resource', 'Read a specific MCP resource.', readResParamsBase);
+            }
+            else {
+                // phase
+                ensureFunctionTool(tools, 'list_mcp_resources', 'List resources from an MCP server.', listResParams);
+                ensureFunctionTool(tools, 'list_mcp_resource_templates', 'List resource templates from MCP servers.', listTplParams);
+                // read is only exposed when we have known servers
+                if (knownServers.length > 0) {
+                    const withEnum = JSON.parse(JSON.stringify(readResParamsBase));
+                    withEnum.properties.server = { type: 'string', enum: knownServers };
+                    ensureFunctionTool(tools, 'read_mcp_resource', 'Read a specific MCP resource.', withEnum);
+                }
+                else {
+                    // remove any existing read tool to prevent premature exposure
+                    removeToolByName(tools, 'read_mcp_resource');
+                }
+            }
+            out.tools = tools;
+            return { ok: true, data: out };
+        }
+        catch {
+            return { ok: true, data: input };
+        }
+    }
+}

package/dist/filters/special/request-toolcalls-stringify.d.ts

@@ -0,0 +1,10 @@
+import type { Filter, FilterContext, FilterResult, JsonObject } from '../types.js';
+/**
+ * Ensure assistant.tool_calls[].function.arguments is a JSON string.
+ * Also set assistant.content=null when tool_calls exist (request-side invariant).
+ */
+export declare class RequestToolCallsStringifyFilter implements Filter<JsonObject> {
+    readonly name = "request_toolcalls_stringify";
+    readonly stage: FilterContext['stage'];
+    apply(input: JsonObject): FilterResult<JsonObject>;
+}

package/dist/filters/special/request-toolcalls-stringify.js

@@ -0,0 +1,44 @@
+/**
+ * Ensure assistant.tool_calls[].function.arguments is a JSON string.
+ * Also set assistant.content=null when tool_calls exist (request-side invariant).
+ */
+export class RequestToolCallsStringifyFilter {
+    name = 'request_toolcalls_stringify';
+    stage = 'request_post';
+    apply(input) {
+        try {
+            const out = JSON.parse(JSON.stringify(input || {}));
+            const msgs = Array.isArray(out.messages) ? out.messages : [];
+            for (const m of msgs) {
+                if (!m || typeof m !== 'object')
+                    continue;
+                if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+                    try {
+                        for (const tc of m.tool_calls) {
+                            if (!tc || typeof tc !== 'object')
+                                continue;
+                            const fn = tc.function || {};
+                            if (fn && typeof fn === 'object' && fn.arguments !== undefined && typeof fn.arguments !== 'string') {
+                                try {
+                                    fn.arguments = JSON.stringify(fn.arguments ?? {});
+                                }
+                                catch {
+                                    fn.arguments = '{}';
+                                }
+                                tc.function = fn;
+                            }
+                        }
+                    }
+                    catch { /* ignore per-item errors */ }
+                    // Invariant: assistant with tool_calls should use content=null
+                    m.content = null;
+                }
+            }
+            out.messages = msgs;
+            return { ok: true, data: out };
+        }
+        catch {
+            return { ok: true, data: input };
+        }
+    }
+}

package/dist/filters/special/request-tools-normalize.d.ts

@@ -0,0 +1,12 @@
+import type { Filter, FilterContext, FilterResult, JsonObject } from '../types.js';
+/**
+ * Normalize OpenAI tools definitions at the final request stage.
+ * - Switches shell parameters schema to TOON ({ toon: string }) when enabled and not heredoc.
+ * - Otherwise enforces { command: string | string[], workdir?: string } shape.
+ * - Best-effort; never throws.
+ */
+export declare class RequestOpenAIToolsNormalizeFilter implements Filter<JsonObject> {
+    readonly name = "request_openai_tools_normalize";
+    readonly stage: FilterContext['stage'];
+    apply(input: JsonObject): Promise<FilterResult<JsonObject>>;
+}