@jsonstudio/llms 0.6.230 → 0.6.375

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

@@ -10,6 +10,13 @@ export interface RoutePoolTier {
     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 +49,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 +75,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 +103,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 +160,13 @@ 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;
     responsesResume?: {
         previousRequestId?: string;
         restoredFromResponseId?: string;
@@ -182,6 +220,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,60 @@
+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;
+    return {
+        chat: followupBody,
+        executed: true,
+        flowId: engineResult.execution.flowId
+    };
+}
+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 {};