@jsonstudio/llms 0.6.230 → 0.6.467

package/dist/router/virtual-router/token-counter.js

@@ -78,11 +78,22 @@ function encodeContent(content, encoder) {
                 total += encodeText(part, encoder);
             }
             else if (part && typeof part === 'object') {
-                if (typeof part.text === 'string') {
-                    total += encodeText(part.text, encoder);
+                const record = part;
+                const typeValue = typeof record.type === 'string' ? record.type.toLowerCase() : '';
+                // Large binary/image payloads (data URIs, base64, etc.) should not
+                // dominate context estimation. For image-like blocks, only count a
+                // small textual placeholder instead of the full JSON/body.
+                if (typeValue.startsWith('image')) {
+                    const caption = typeof record.caption === 'string' && record.caption.trim().length
+                        ? record.caption
+                        : '[image]';
+                    total += encodeText(caption, encoder);
+                }
+                else if (typeof record.text === 'string') {
+                    total += encodeText(record.text, encoder);
                 }
                 else {
-                    total += encodeText(JSON.stringify(part), encoder);
+                    total += encodeText(JSON.stringify(record), encoder);
                 }
             }
         }

package/dist/router/virtual-router/tool-signals.js

@@ -85,22 +85,6 @@ const SHELL_WRITE_PATTERNS = [
     'go install',
     'make install'
 ];
-const SHELL_SEARCH_PATTERNS = [
-    'rg ',
-    'rg-',
-    'grep ',
-    'grep-',
-    'ripgrep',
-    'find ',
-    'fd ',
-    'locate ',
-    'search ',
-    'ack ',
-    'ag ',
-    'where ',
-    'which ',
-    'codesearch'
-];
 const SHELL_READ_PATTERNS = [
     'ls',
     'dir ',
@@ -362,9 +346,6 @@ function classifyShellCommand(command) {
     if (segments.some((segment) => matchesAnyPattern(segment, SHELL_WRITE_PATTERNS))) {
         return 'write';
     }
-    if (segments.some((segment) => matchesAnyPattern(segment, SHELL_SEARCH_PATTERNS))) {
-        return 'search';
-    }
     if (segments.some((segment) => matchesAnyPattern(segment, SHELL_READ_PATTERNS))) {
         return 'read';
     }
@@ -372,9 +353,6 @@ function classifyShellCommand(command) {
     if (matchesAnyPattern(stripped, SHELL_WRITE_PATTERNS)) {
         return 'write';
     }
-    if (matchesAnyPattern(stripped, SHELL_SEARCH_PATTERNS)) {
-        return 'search';
-    }
     if (matchesAnyPattern(stripped, SHELL_READ_PATTERNS)) {
         return 'read';
     }

package/dist/router/virtual-router/types.d.ts

@@ -5,11 +5,19 @@ import type { StandardizedRequest } from '../../conversion/hub/types/standardize
 export declare const DEFAULT_MODEL_CONTEXT_TOKENS = 200000;
 export declare const DEFAULT_ROUTE = "default";
 export declare const ROUTE_PRIORITY: string[];
+export type RoutingInstructionMode = 'force' | 'sticky' | 'none';
 export interface RoutePoolTier {
     id: string;
     targets: string[];
     priority: number;
     backup?: boolean;
+    /**
+     * Optional force flag for this route pool.
+     * Currently interpreted for:
+     * - routing.vision: force dedicated vision backend handling.
+     * - routing.web_search / routing.search: force server-side web_search flow.
+     */
+    force?: boolean;
 }
 export type RoutingPools = Record<string, RoutePoolTier[]>;
 export type StreamingPreference = 'auto' | 'always' | 'never';
@@ -42,6 +50,13 @@ export interface ProviderProfile {
     responsesConfig?: ResponsesProviderConfig;
     streaming?: StreamingPreference;
     maxContextTokens?: number;
+    /**
+     * When true, this provider must be skipped for any request that
+     * requires server-side tool orchestration (e.g. web_search).
+     * Normal chat routing (without servertool injection) may still
+     * use this provider as usual.
+     */
+    serverToolsDisabled?: boolean;
 }
 export interface ProviderRuntimeProfile {
     runtimeKey: string;
@@ -61,6 +76,12 @@ export interface ProviderRuntimeProfile {
     modelContextTokens?: Record<string, number>;
     defaultContextTokens?: number;
     maxContextTokens?: number;
+    /**
+     * Provider-level flag propagated from virtualrouter.providers[*].
+     * When true, VirtualRouterEngine will skip this runtime for any
+     * request that declares serverToolRequired=true in routing metadata.
+     */
+    serverToolsDisabled?: boolean;
 }
 export interface VirtualRouterClassifierConfig {
     longContextThresholdTokens?: number;
@@ -83,10 +104,21 @@ export interface VirtualRouterWebSearchEngineConfig {
     providerKey: string;
     description?: string;
     default?: boolean;
+    /**
+     * When true, this engine will never be used by server-side tools
+     * (e.g. web_search). It will also be omitted from injected tool
+     * schemas so main models cannot select it for servertool flows.
+     */
+    serverToolsDisabled?: boolean;
 }
 export interface VirtualRouterWebSearchConfig {
     engines: VirtualRouterWebSearchEngineConfig[];
     injectPolicy?: 'always' | 'selective';
+    /**
+     * When true, always prefer server-side web_search orchestration
+     * over upstream builtin behaviours (e.g. OpenAI Responses builtin web_search).
+     */
+    force?: boolean;
 }
 export interface VirtualRouterConfig {
     routing: RoutingPools;
@@ -129,6 +161,47 @@ export interface RouterMetadataInput {
     providerProtocol?: string;
     stage?: 'inbound' | 'outbound' | 'response';
     routeHint?: string;
+    /**
+     * Indicates that current routing decision is for a request which
+     * expects server-side tools orchestration (e.g. web_search).
+     * Virtual Router should skip providers that opt out via
+     * serverToolsDisabled when this flag is true.
+     */
+    serverToolRequired?: boolean;
+    /**
+     * 强制路由模式，从消息中的 <**...**> 指令解析得出
+     */
+    routingMode?: RoutingInstructionMode;
+    /**
+     * 允许的 provider 白名单
+     */
+    allowedProviders?: string[];
+    /**
+     * 强制使用的 provider model (格式: provider.model)
+     */
+    forcedProviderModel?: string;
+    /**
+     * 强制使用的 provider keyAlias
+     */
+    forcedProviderKeyAlias?: string;
+    /**
+     * 强制使用的 provider keyIndex (从 1 开始)
+     */
+    forcedProviderKeyIndex?: number;
+    /**
+     * 禁用的 provider model 列表
+     */
+    disabledProviderModels?: string[];
+    /**
+     * 禁用的 provider keyAlias 列表
+     */
+    disabledProviderKeyAliases?: string[];
+    /**
+     * 禁用的 provider keyIndex 列表 (从 1 开始)
+     */
+    disabledProviderKeyIndexes?: number[];
+    sessionId?: string;
+    conversationId?: string;
     responsesResume?: {
         previousRequestId?: string;
         restoredFromResponseId?: string;
@@ -182,6 +255,13 @@ export interface TargetMetadata {
     responsesConfig?: ResponsesProviderConfig;
     streaming?: StreamingPreference;
     maxContextTokens?: number;
+    /**
+     * Route-level flags propagated from the virtual router.
+     * These are derived from routing pools and webSearch config and
+     * are used by hub pipeline/process layers (web_search / vision).
+     */
+    forceWebSearch?: boolean;
+    forceVision?: boolean;
 }
 export interface ResponsesProviderConfig {
     toolCallIdStyle?: 'fc' | 'preserve';

package/dist/router/virtual-router/types.js

@@ -6,7 +6,8 @@ export const DEFAULT_ROUTE = 'default';
 export const ROUTE_PRIORITY = [
     'vision',
     'longcontext',
-    'websearch',
+    'web_search',
+    'search',
     'coding',
     'thinking',
     'tools',

package/dist/servertool/engine.d.ts

@@ -0,0 +1,27 @@
+import type { AdapterContext } from '../conversion/hub/types/chat-envelope.js';
+import type { JsonObject } from '../conversion/hub/types/json.js';
+import type { ProviderInvoker } from './types.js';
+export interface ServerToolOrchestrationOptions {
+    chat: JsonObject;
+    adapterContext: AdapterContext;
+    requestId: string;
+    entryEndpoint: string;
+    providerProtocol: string;
+    reenterPipeline?: (options: {
+        entryEndpoint: string;
+        requestId: string;
+        body: JsonObject;
+        metadata?: JsonObject;
+    }) => Promise<{
+        body?: JsonObject;
+        __sse_responses?: unknown;
+        format?: string;
+    }>;
+    providerInvoker?: ProviderInvoker;
+}
+export interface ServerToolOrchestrationResult {
+    chat: JsonObject;
+    executed: boolean;
+    flowId?: string;
+}
+export declare function runServerToolOrchestration(options: ServerToolOrchestrationOptions): Promise<ServerToolOrchestrationResult>;

package/dist/servertool/engine.js

@@ -0,0 +1,101 @@
+import { runServerSideToolEngine } from './server-side-tools.js';
+export async function runServerToolOrchestration(options) {
+    const engineOptions = {
+        chatResponse: options.chat,
+        adapterContext: options.adapterContext,
+        entryEndpoint: options.entryEndpoint,
+        requestId: options.requestId,
+        providerProtocol: options.providerProtocol,
+        providerInvoker: options.providerInvoker,
+        reenterPipeline: options.reenterPipeline
+    };
+    const engineResult = await runServerSideToolEngine(engineOptions);
+    if (engineResult.mode === 'passthrough' || !engineResult.execution) {
+        return {
+            chat: engineResult.finalChatResponse,
+            executed: false
+        };
+    }
+    if (!engineResult.execution.followup || !options.reenterPipeline) {
+        return {
+            chat: engineResult.finalChatResponse,
+            executed: true,
+            flowId: engineResult.execution.flowId
+        };
+    }
+    const routeHint = resolveRouteHint(options.adapterContext, engineResult.execution.flowId);
+    const metadata = {
+        serverToolFollowup: true,
+        stream: false,
+        ...(engineResult.execution.followup.metadata ?? {})
+    };
+    if (routeHint && typeof metadata.routeHint !== 'string') {
+        metadata.routeHint = routeHint;
+    }
+    const followup = await options.reenterPipeline({
+        entryEndpoint: '/v1/chat/completions',
+        requestId: `${options.requestId}${engineResult.execution.followup.requestIdSuffix}`,
+        body: engineResult.execution.followup.payload,
+        metadata
+    });
+    const followupBody = followup.body && typeof followup.body === 'object'
+        ? followup.body
+        : engineResult.finalChatResponse;
+    const decorated = decorateFinalChatWithServerToolContext(followupBody, engineResult.execution);
+    return {
+        chat: decorated,
+        executed: true,
+        flowId: engineResult.execution.flowId
+    };
+}
+function decorateFinalChatWithServerToolContext(chat, execution) {
+    if (!execution || !execution.context) {
+        return chat;
+    }
+    // 目前仅对 web_search flow 附加原文摘要，避免影响其它 ServerTool。
+    if (execution.flowId !== 'web_search_flow') {
+        return chat;
+    }
+    const ctx = execution.context;
+    const web = ctx.web_search;
+    const summary = web && typeof web.summary === 'string' && web.summary.trim().length
+        ? web.summary.trim()
+        : '';
+    if (!summary) {
+        return chat;
+    }
+    const engineId = web && typeof web.engineId === 'string' && web.engineId.trim().length
+        ? web.engineId.trim()
+        : undefined;
+    const label = engineId
+        ? `【web_search 原文 | engine: ${engineId}】`
+        : '【web_search 原文】';
+    const cloned = JSON.parse(JSON.stringify(chat));
+    const choices = Array.isArray(cloned.choices) ? cloned.choices : [];
+    if (!choices.length) {
+        return cloned;
+    }
+    const first = choices[0] && typeof choices[0] === 'object' ? choices[0] : null;
+    if (!first || !first.message || typeof first.message !== 'object') {
+        return cloned;
+    }
+    const message = first.message;
+    const baseContent = typeof message.content === 'string' ? message.content : '';
+    const suffix = `${label}\n${summary}`;
+    message.content =
+        baseContent && baseContent.trim().length
+            ? `${baseContent}\n\n${suffix}`
+            : suffix;
+    return cloned;
+}
+function resolveRouteHint(adapterContext, flowId) {
+    const rawRoute = adapterContext.routeId;
+    const routeId = typeof rawRoute === 'string' && rawRoute.trim() ? rawRoute.trim() : '';
+    if (!routeId) {
+        return undefined;
+    }
+    if (flowId && routeId.toLowerCase() === flowId.toLowerCase()) {
+        return undefined;
+    }
+    return routeId;
+}

package/dist/servertool/flow-types.d.ts

@@ -0,0 +1,40 @@
+import type { JsonObject } from '../conversion/hub/types/json.js';
+import type { ServerToolOrchestrationOptions, ServerToolOrchestrationResult } from './orchestration-types.js';
+export interface ServerToolFlowContext {
+    options: ServerToolOrchestrationOptions;
+    baseChatResponse: JsonObject;
+    capturedChatRequest?: JsonObject;
+    routeId?: string;
+    cache: Record<string, unknown>;
+}
+export interface ServerToolHopResult {
+    body?: JsonObject;
+    __sse_responses?: unknown;
+    format?: string;
+}
+export interface ServerToolReenterCallOptions {
+    requestIdSuffix: string;
+    body: JsonObject;
+    entryEndpoint?: string;
+    metadata?: JsonObject;
+}
+export interface ServerToolProviderCallOptions {
+    requestIdSuffix: string;
+    providerKey: string;
+    providerProtocol: string;
+    entryEndpoint: string;
+    payload: JsonObject;
+    modelId?: string;
+    routeHint?: string;
+}
+export interface ServerToolFlowHelpers {
+    makeRequestId: (suffix: string) => string;
+    callReenterHop: (options: ServerToolReenterCallOptions) => Promise<ServerToolHopResult | null>;
+    callProviderHop: (options: ServerToolProviderCallOptions) => Promise<ServerToolHopResult | null>;
+    getRouteHintForFollowup: (exclude?: string) => string | undefined;
+}
+export interface ServerToolFlow {
+    id: string;
+    shouldRun: (context: ServerToolFlowContext) => Promise<boolean> | boolean;
+    run: (context: ServerToolFlowContext, helpers: ServerToolFlowHelpers) => Promise<ServerToolOrchestrationResult | null>;
+}

package/dist/servertool/flow-types.js

@@ -0,0 +1 @@
+export {};

package/dist/servertool/handlers/vision.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/servertool/handlers/vision.js

@@ -0,0 +1,194 @@
+import { registerServerToolHandler } from '../registry.js';
+import { cloneJson, extractTextFromChatLike } from '../server-side-tools.js';
+const FLOW_ID = 'vision_flow';
+const handler = async (ctx) => {
+    if (!ctx.options.reenterPipeline) {
+        return null;
+    }
+    if (!shouldRunVisionFlow(ctx)) {
+        return null;
+    }
+    const captured = getCapturedRequest(ctx.adapterContext);
+    if (!captured) {
+        return null;
+    }
+    const analysisPayload = buildVisionAnalysisPayload(captured);
+    if (!analysisPayload) {
+        return null;
+    }
+    const visionResponse = await ctx.options.reenterPipeline({
+        entryEndpoint: '/v1/chat/completions',
+        requestId: `${ctx.options.requestId}:vision`,
+        body: analysisPayload,
+        metadata: {
+            routeHint: 'vision',
+            serverToolFollowup: true,
+            stream: false
+        }
+    });
+    const visionBody = visionResponse.body && typeof visionResponse.body === 'object'
+        ? visionResponse.body
+        : null;
+    if (!visionBody) {
+        return null;
+    }
+    const visionSummary = extractTextFromChatLike(visionBody);
+    if (!visionSummary) {
+        return null;
+    }
+    const followupPayload = buildVisionFollowupPayload(captured, visionSummary);
+    if (!followupPayload) {
+        return null;
+    }
+    const execution = {
+        flowId: FLOW_ID,
+        followup: {
+            requestIdSuffix: ':vision_followup',
+            payload: followupPayload,
+            metadata: buildFollowupMetadata(ctx.adapterContext, 'vision')
+        }
+    };
+    return {
+        chatResponse: ctx.base,
+        execution
+    };
+};
+registerServerToolHandler('vision_auto', handler, { trigger: 'auto' });
+function shouldRunVisionFlow(ctx) {
+    const record = ctx.adapterContext;
+    const followupFlag = record.serverToolFollowup === true || record.serverToolFollowup === 'true';
+    if (followupFlag) {
+        return false;
+    }
+    return record.hasImageAttachment === true || record.hasImageAttachment === 'true';
+}
+function getCapturedRequest(adapterContext) {
+    if (!adapterContext || typeof adapterContext !== 'object') {
+        return null;
+    }
+    const captured = adapterContext.capturedChatRequest;
+    if (!captured || typeof captured !== 'object' || Array.isArray(captured)) {
+        return null;
+    }
+    return captured;
+}
+function buildVisionAnalysisPayload(source) {
+    if (!source || typeof source !== 'object') {
+        return null;
+    }
+    const payload = {};
+    if (typeof source.model === 'string' && source.model.trim()) {
+        payload.model = source.model.trim();
+    }
+    if (Array.isArray(source.messages)) {
+        payload.messages = cloneJson(source.messages);
+    }
+    else {
+        return null;
+    }
+    if (Array.isArray(source.tools) && source.tools.length) {
+        payload.tools = cloneJson(source.tools);
+    }
+    const parameters = source.parameters;
+    if (parameters && typeof parameters === 'object' && !Array.isArray(parameters)) {
+        const params = cloneJson(parameters);
+        Object.assign(payload, params);
+    }
+    return payload;
+}
+function buildVisionFollowupPayload(source, summary) {
+    if (!source || typeof source !== 'object') {
+        return null;
+    }
+    const payload = {};
+    if (typeof source.model === 'string' && source.model.trim()) {
+        payload.model = source.model.trim();
+    }
+    payload.messages = injectVisionSummary(source.messages, summary);
+    if (Array.isArray(source.tools) && source.tools.length) {
+        payload.tools = cloneJson(source.tools);
+    }
+    const parameters = source.parameters;
+    if (parameters && typeof parameters === 'object' && !Array.isArray(parameters)) {
+        const params = cloneJson(parameters);
+        Object.assign(payload, params);
+    }
+    return payload;
+}
+function injectVisionSummary(source, summary) {
+    const messages = Array.isArray(source) ? cloneJson(source) : [];
+    let injected = false;
+    for (const message of messages) {
+        if (!message || typeof message !== 'object')
+            continue;
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        const nextParts = [];
+        let removed = false;
+        for (const part of content) {
+            if (part && typeof part === 'object') {
+                const typeValue = typeof part.type === 'string'
+                    ? part.type.toLowerCase()
+                    : '';
+                if (typeValue.includes('image')) {
+                    removed = true;
+                    continue;
+                }
+            }
+            nextParts.push(part);
+        }
+        if (removed) {
+            nextParts.push({
+                type: 'text',
+                text: `[Vision] ${summary}`
+            });
+            message.content = nextParts;
+            injected = true;
+        }
+    }
+    if (!injected) {
+        for (let i = messages.length - 1; i >= 0; i -= 1) {
+            const msg = messages[i];
+            if (!msg || typeof msg !== 'object')
+                continue;
+            const role = typeof msg.role === 'string'
+                ? msg.role.toLowerCase()
+                : '';
+            if (role !== 'user')
+                continue;
+            const content = msg.content;
+            if (Array.isArray(content)) {
+                content.push({
+                    type: 'text',
+                    text: `[Vision] ${summary}`
+                });
+                injected = true;
+                break;
+            }
+            if (typeof content === 'string' && content.length) {
+                msg.content = `${content}\n[Vision] ${summary}`;
+            }
+            else {
+                msg.content = `[Vision] ${summary}`;
+            }
+            injected = true;
+            break;
+        }
+    }
+    if (!injected) {
+        messages.push({
+            role: 'system',
+            content: `[Vision] ${summary}`
+        });
+    }
+    return messages;
+}
+function buildFollowupMetadata(adapterContext, toolName) {
+    const ctx = adapterContext && typeof adapterContext === 'object' ? adapterContext : null;
+    const routeId = ctx && typeof ctx.routeId === 'string' && ctx.routeId.trim() ? ctx.routeId.trim() : '';
+    if (!routeId || routeId.toLowerCase() === toolName.toLowerCase()) {
+        return undefined;
+    }
+    return { routeHint: routeId };
+}

package/dist/servertool/handlers/web-search.d.ts

@@ -0,0 +1 @@
+export {};