@jsonstudio/llms 0.6.3379 → 0.6.3409

package/dist/router/virtual-router/engine-selection/tier-load-balancing.js

@@ -0,0 +1,120 @@
+import { extractProviderId, getProviderModelId } from './key-parsing.js';
+export function resolveTierLoadBalancing(tier, globalPolicy) {
+    const tierPolicy = tier.loadBalancing;
+    return {
+        strategy: tierPolicy?.strategy ?? globalPolicy?.strategy ?? 'round-robin',
+        weights: tierPolicy?.weights ?? globalPolicy?.weights
+    };
+}
+export function resolveGroupWeight(groupId, weights) {
+    if (!weights) {
+        return 1;
+    }
+    const direct = weights[groupId];
+    if (typeof direct === 'number' && Number.isFinite(direct) && direct > 0) {
+        return direct;
+    }
+    const providerId = groupId.split('.')[0] ?? groupId;
+    const providerOnly = weights[providerId];
+    if (typeof providerOnly === 'number' && Number.isFinite(providerOnly) && providerOnly > 0) {
+        return providerOnly;
+    }
+    return 1;
+}
+export function buildGroupWeights(groups, weights) {
+    if (!groups.size || !weights) {
+        return undefined;
+    }
+    const out = {};
+    let hasExplicit = false;
+    for (const [groupId] of groups.entries()) {
+        const resolved = resolveGroupWeight(groupId, weights);
+        out[groupId] = resolved;
+        if (resolved !== 1) {
+            hasExplicit = true;
+        }
+    }
+    return hasExplicit ? out : undefined;
+}
+export function hasNonUniformWeights(candidates, weights) {
+    if (!weights || candidates.length < 2) {
+        return false;
+    }
+    let ref;
+    for (const key of candidates) {
+        const raw = weights[key];
+        if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+            continue;
+        }
+        if (ref === undefined) {
+            ref = raw;
+        }
+        else if (Math.abs(raw - ref) > 1e-6) {
+            return true;
+        }
+    }
+    return false;
+}
+export function buildCandidateWeights(opts) {
+    const { candidates, providerRegistry, staticWeights, dynamicWeights } = opts;
+    if ((!staticWeights || Object.keys(staticWeights).length === 0) && (!dynamicWeights || Object.keys(dynamicWeights).length === 0)) {
+        return undefined;
+    }
+    const out = {};
+    let hasExplicit = false;
+    for (const key of candidates) {
+        const dynamic = dynamicWeights?.[key];
+        const staticWeight = resolveCandidateWeight(key, staticWeights, providerRegistry);
+        const resolved = multiplyPositiveWeights(dynamic, staticWeight);
+        if (resolved !== undefined) {
+            out[key] = resolved;
+            if (resolved !== 1) {
+                hasExplicit = true;
+            }
+        }
+    }
+    if (!hasExplicit) {
+        return undefined;
+    }
+    return out;
+}
+function resolveCandidateWeight(key, weights, providerRegistry) {
+    if (!weights) {
+        return undefined;
+    }
+    const direct = normalizePositiveWeight(weights[key]);
+    if (direct !== undefined) {
+        return direct;
+    }
+    const providerId = extractProviderId(key) ?? '';
+    if (!providerId) {
+        return undefined;
+    }
+    try {
+        const modelId = getProviderModelId(key, providerRegistry) ?? '';
+        if (modelId) {
+            const grouped = normalizePositiveWeight(weights[`${providerId}.${modelId}`]);
+            if (grouped !== undefined) {
+                return grouped;
+            }
+        }
+    }
+    catch {
+        // Ignore registry misses and fall back to provider-only weight.
+    }
+    return normalizePositiveWeight(weights[providerId]);
+}
+function normalizePositiveWeight(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function multiplyPositiveWeights(...values) {
+    let resolved;
+    for (const value of values) {
+        const normalized = normalizePositiveWeight(value);
+        if (normalized === undefined) {
+            continue;
+        }
+        resolved = resolved === undefined ? normalized : Math.max(1, Math.round(resolved * normalized));
+    }
+    return resolved;
+}

package/dist/router/virtual-router/engine-selection/tier-selection-quota-integration.d.ts

@@ -3,6 +3,7 @@ import { type ResolvedContextWeightedConfig } from '../context-weighted.js';
 import { type ResolvedHealthWeightedConfig } from '../health-weighted.js';
 import type { RoutePoolTier } from '../types.js';
 import type { SelectionDeps, TrySelectFromTierOptions } from './selection-deps.js';
+import { type ResolvedTierLoadBalancing } from './tier-load-balancing.js';
 export declare function selectProviderKeyWithQuotaBuckets(opts: {
     routeName: string;
     tier: RoutePoolTier;
@@ -19,6 +20,7 @@ export declare function selectProviderKeyWithQuotaBuckets(opts: {
     nowForWeights: number;
     healthWeightedCfg: ResolvedHealthWeightedConfig;
     contextWeightedCfg: ResolvedContextWeightedConfig;
+    tierLoadBalancing: ResolvedTierLoadBalancing;
     quotaView: NonNullable<SelectionDeps['quotaView']>;
     isAvailable: (key: string) => boolean;
     selectFirstAvailable: (keys: string[]) => string | null;

package/dist/router/virtual-router/engine-selection/tier-selection-quota-integration.js

@@ -2,6 +2,7 @@ import { computeContextMultiplier } from '../context-weighted.js';
 import { computeHealthWeight } from '../health-weighted.js';
 import { buildQuotaBuckets } from './native-router-hotpath.js';
 import { computeContextWeightMultipliers } from './context-weight-multipliers.js';
+import { buildCandidateWeights, buildGroupWeights, hasNonUniformWeights } from './tier-load-balancing.js';
 import { pickPriorityGroup } from './tier-priority.js';
 import { extractProviderId, getProviderModelId } from './key-parsing.js';
 function buildPrimaryTargetGroups(candidates, deps) {
@@ -25,52 +26,8 @@ function buildPrimaryTargetGroups(candidates, deps) {
     }
     return groups;
 }
-function resolveGroupWeight(groupId, weights) {
-    if (!weights) {
-        return 1;
-    }
-    const direct = weights[groupId];
-    if (typeof direct === 'number' && Number.isFinite(direct) && direct > 0) {
-        return direct;
-    }
-    const providerId = groupId.split('.')[0] ?? groupId;
-    const providerOnly = weights[providerId];
-    if (typeof providerOnly === 'number' && Number.isFinite(providerOnly) && providerOnly > 0) {
-        return providerOnly;
-    }
-    return 1;
-}
-function buildGroupWeights(groups, weights) {
-    if (!groups.size) {
-        return undefined;
-    }
-    const out = {};
-    for (const [groupId] of groups.entries()) {
-        out[groupId] = resolveGroupWeight(groupId, weights);
-    }
-    return out;
-}
-function hasNonUniformWeights(candidates, weights) {
-    if (!weights || candidates.length < 2) {
-        return false;
-    }
-    let ref;
-    for (const key of candidates) {
-        const raw = weights[key];
-        if (typeof raw !== 'number' || !Number.isFinite(raw)) {
-            continue;
-        }
-        if (ref === undefined) {
-            ref = raw;
-        }
-        else if (Math.abs(raw - ref) > 1e-6) {
-            return true;
-        }
-    }
-    return false;
-}
 export function selectProviderKeyWithQuotaBuckets(opts) {
-    const { routeName, tier, stickyKey, candidates, isSafePool, deps, options, contextResult, warnRatio, isRecoveryAttempt, now, nowForWeights, healthWeightedCfg, contextWeightedCfg, quotaView, isAvailable, selectFirstAvailable, applyAliasStickyQueuePinning, preferAntigravityAliasesOnRetry } = opts;
+    const { routeName, tier, stickyKey, candidates, isSafePool, deps, options, contextResult, warnRatio, isRecoveryAttempt, now, nowForWeights, healthWeightedCfg, contextWeightedCfg, tierLoadBalancing, quotaView, isAvailable, selectFirstAvailable, applyAliasStickyQueuePinning, preferAntigravityAliasesOnRetry } = opts;
     const bucketInputs = candidates.map((key, order) => {
         const entry = quotaView(key);
         const penaltyRaw = entry?.selectionPenalty;
@@ -100,35 +57,56 @@ export function selectProviderKeyWithQuotaBuckets(opts) {
             bucketCandidates = preferAntigravityAliasesOnRetry(bucketCandidates);
         }
         bucketCandidates = applyAliasStickyQueuePinning(bucketCandidates);
-        const bucketWeights = {};
+        const quotaWeights = {};
         for (const item of bucket) {
             if (healthWeightedCfg.enabled) {
                 const entry = quotaView(item.key);
                 const { weight } = computeHealthWeight(entry, nowForWeights, healthWeightedCfg);
-                bucketWeights[item.key] = weight;
+                quotaWeights[item.key] = weight;
             }
             else {
-                bucketWeights[item.key] = Math.max(1, Math.floor(100 / (1 + Math.max(0, item.penalty))));
+                quotaWeights[item.key] = Math.max(1, Math.floor(100 / (1 + Math.max(0, item.penalty))));
             }
         }
-        if (isSafePool && contextWeightedCfg.enabled) {
+        const contextWeights = (() => {
+            if (!isSafePool || !contextWeightedCfg.enabled) {
+                return undefined;
+            }
             const ctx = computeContextWeightMultipliers({
                 candidates: bucketCandidates,
                 usage: contextResult.usage,
                 warnRatio,
                 cfg: contextWeightedCfg
             });
-            if (ctx) {
-                for (const key of bucketCandidates) {
-                    const m = computeContextMultiplier({
-                        effectiveSafeRefTokens: ctx.ref,
-                        effectiveSafeTokens: ctx.eff[key] ?? 1,
-                        cfg: contextWeightedCfg
-                    });
-                    bucketWeights[key] = Math.max(1, Math.round((bucketWeights[key] ?? 1) * m));
-                }
+            if (!ctx) {
+                return undefined;
             }
-        }
+            const out = {};
+            for (const key of bucketCandidates) {
+                const m = computeContextMultiplier({
+                    effectiveSafeRefTokens: ctx.ref,
+                    effectiveSafeTokens: ctx.eff[key] ?? 1,
+                    cfg: contextWeightedCfg
+                });
+                out[key] = Math.max(1, Math.round(100 * m));
+            }
+            return out;
+        })();
+        const bucketWeights = buildCandidateWeights({
+            candidates: bucketCandidates,
+            providerRegistry: deps.providerRegistry,
+            staticWeights: tierLoadBalancing.weights,
+            dynamicWeights: Object.keys(quotaWeights).length || contextWeights
+                ? Object.fromEntries(bucketCandidates.map((key) => {
+                    const quotaWeight = quotaWeights[key];
+                    const contextWeight = contextWeights?.[key];
+                    const combined = typeof contextWeight === 'number'
+                        ? Math.max(1, Math.round((quotaWeight ?? 1) * contextWeight))
+                        : quotaWeight;
+                    return [key, combined ?? 1];
+                }))
+                : undefined
+        });
         if (tier.mode === 'priority') {
             if (!isRecoveryAttempt) {
                 const group = pickPriorityGroup({
@@ -142,13 +120,13 @@ export function selectProviderKeyWithQuotaBuckets(opts) {
                 }
                 const groupWeights = {};
                 for (const key of group.groupCandidates) {
-                    groupWeights[key] = bucketWeights[key] ?? 1;
+                    groupWeights[key] = bucketWeights?.[key] ?? 1;
                 }
                 const allowGrouped = !hasNonUniformWeights(group.groupCandidates, bucketWeights);
-                if (allowGrouped && deps.loadBalancer.getPolicy().strategy !== 'sticky') {
+                if (allowGrouped && tierLoadBalancing.strategy !== 'sticky') {
                     const groups = buildPrimaryTargetGroups(group.groupCandidates, deps);
                     if (groups.size > 0) {
-                        const groupWeightMap = buildGroupWeights(groups, deps.loadBalancer.getPolicy().weights);
+                        const groupWeightMap = buildGroupWeights(groups, tierLoadBalancing.weights);
                         const selected = deps.loadBalancer.selectGrouped({
                             routeName: `${routeName}:${tier.id}:priority:${priority}:group:${group.groupId}`,
                             groups,
@@ -185,17 +163,17 @@ export function selectProviderKeyWithQuotaBuckets(opts) {
             continue;
         }
         const allowGrouped = !hasNonUniformWeights(bucketCandidates, bucketWeights);
-        if (allowGrouped && deps.loadBalancer.getPolicy().strategy !== 'sticky') {
+        if (allowGrouped && tierLoadBalancing.strategy !== 'sticky') {
             const groups = buildPrimaryTargetGroups(bucketCandidates, deps);
             if (groups.size > 0) {
-                const groupWeightMap = buildGroupWeights(groups, deps.loadBalancer.getPolicy().weights);
+                const groupWeightMap = buildGroupWeights(groups, tierLoadBalancing.weights);
                 const selected = deps.loadBalancer.selectGrouped({
                     routeName: `${routeName}:${tier.id}:${priority}`,
                     groups,
                     stickyKey: options.allowAliasRotation ? undefined : stickyKey,
                     weights: groupWeightMap,
                     availabilityCheck: isAvailable
-                }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
+                }, tier.mode === 'round-robin' ? 'round-robin' : tierLoadBalancing.strategy);
                 if (selected) {
                     return selected;
                 }
@@ -207,7 +185,7 @@ export function selectProviderKeyWithQuotaBuckets(opts) {
             stickyKey: options.allowAliasRotation ? undefined : stickyKey,
             weights: bucketWeights,
             availabilityCheck: isAvailable
-        }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
+        }, tier.mode === 'round-robin' ? 'round-robin' : tierLoadBalancing.strategy);
         if (selected) {
             return selected;
         }

package/dist/router/virtual-router/engine-selection/tier-selection-select.js

@@ -2,6 +2,7 @@ import { computeContextMultiplier } from '../context-weighted.js';
 import { pinCandidatesByAliasQueue, resolveAliasSelectionStrategy } from './alias-selection.js';
 import { computeContextWeightMultipliers } from './context-weight-multipliers.js';
 import { extractKeyAlias, extractProviderId, getProviderModelId } from './key-parsing.js';
+import { buildCandidateWeights, buildGroupWeights, hasNonUniformWeights, resolveTierLoadBalancing } from './tier-load-balancing.js';
 import { pickPriorityGroup } from './tier-priority.js';
 import { selectProviderKeyWithQuotaBuckets } from './tier-selection-quota-integration.js';
 function buildPrimaryTargetGroups(candidates, deps) {
@@ -25,50 +26,6 @@ function buildPrimaryTargetGroups(candidates, deps) {
     }
     return groups;
 }
-function resolveGroupWeight(groupId, weights) {
-    if (!weights) {
-        return 1;
-    }
-    const direct = weights[groupId];
-    if (typeof direct === 'number' && Number.isFinite(direct) && direct > 0) {
-        return direct;
-    }
-    const providerId = groupId.split('.')[0] ?? groupId;
-    const providerOnly = weights[providerId];
-    if (typeof providerOnly === 'number' && Number.isFinite(providerOnly) && providerOnly > 0) {
-        return providerOnly;
-    }
-    return 1;
-}
-function buildGroupWeights(groups, weights) {
-    if (!groups.size) {
-        return undefined;
-    }
-    const out = {};
-    for (const [groupId] of groups.entries()) {
-        out[groupId] = resolveGroupWeight(groupId, weights);
-    }
-    return out;
-}
-function hasNonUniformWeights(candidates, weights) {
-    if (!weights || candidates.length < 2) {
-        return false;
-    }
-    let ref;
-    for (const key of candidates) {
-        const raw = weights[key];
-        if (typeof raw !== 'number' || !Number.isFinite(raw)) {
-            continue;
-        }
-        if (ref === undefined) {
-            ref = raw;
-        }
-        else if (Math.abs(raw - ref) > 1e-6) {
-            return true;
-        }
-    }
-    return false;
-}
 function applyAliasStickyQueuePinning(opts) {
     const { candidates, orderedTargets, deps, excludedKeys } = opts;
     if (!Array.isArray(candidates) || candidates.length < 2) {
@@ -202,6 +159,7 @@ function preferAntigravityAliasesOnRetry(opts) {
 export function selectProviderKeyFromCandidatePool(opts) {
     const { routeName, tier, stickyKey, candidates, isSafePool, deps, options, contextResult, warnRatio, excludedKeys, isRecoveryAttempt, now, nowForWeights, healthWeightedCfg, contextWeightedCfg } = opts;
     const quotaView = deps.quotaView;
+    const tierLoadBalancing = resolveTierLoadBalancing(tier, deps.loadBalancer.getPolicy());
     const isAvailable = (key) => {
         if (!quotaView) {
             return deps.healthManager.isAvailable(key);
@@ -265,28 +223,33 @@ export function selectProviderKeyFromCandidatePool(opts) {
             if (!group) {
                 return null;
             }
-            const weights = (() => {
-                if (!isSafePool)
-                    return undefined;
-                const ctx = computeContextWeightMultipliers({ candidates: group.groupCandidates, usage: contextResult.usage, warnRatio, cfg: contextWeightedCfg });
-                if (!ctx)
-                    return undefined;
-                const out = {};
-                for (const key of group.groupCandidates) {
-                    const m = computeContextMultiplier({
-                        effectiveSafeRefTokens: ctx.ref,
-                        effectiveSafeTokens: ctx.eff[key] ?? 1,
-                        cfg: contextWeightedCfg
-                    });
-                    out[key] = Math.max(1, Math.round(100 * m));
-                }
-                return out;
-            })();
+            const weights = buildCandidateWeights({
+                candidates: group.groupCandidates,
+                providerRegistry: deps.providerRegistry,
+                staticWeights: tierLoadBalancing.weights,
+                dynamicWeights: (() => {
+                    if (!isSafePool)
+                        return undefined;
+                    const ctx = computeContextWeightMultipliers({ candidates: group.groupCandidates, usage: contextResult.usage, warnRatio, cfg: contextWeightedCfg });
+                    if (!ctx)
+                        return undefined;
+                    const out = {};
+                    for (const key of group.groupCandidates) {
+                        const m = computeContextMultiplier({
+                            effectiveSafeRefTokens: ctx.ref,
+                            effectiveSafeTokens: ctx.eff[key] ?? 1,
+                            cfg: contextWeightedCfg
+                        });
+                        out[key] = Math.max(1, Math.round(100 * m));
+                    }
+                    return out;
+                })()
+            });
             const allowGrouped = !hasNonUniformWeights(group.groupCandidates, weights);
-            if (allowGrouped && deps.loadBalancer.getPolicy().strategy !== 'sticky') {
+            if (allowGrouped && tierLoadBalancing.strategy !== 'sticky') {
                 const groups = buildPrimaryTargetGroups(group.groupCandidates, deps);
                 if (groups.size > 0) {
-                    const groupWeights = buildGroupWeights(groups, deps.loadBalancer.getPolicy().weights);
+                    const groupWeights = buildGroupWeights(groups, tierLoadBalancing.weights);
                     const selected = deps.loadBalancer.selectGrouped({
                         routeName: `${routeName}:${tier.id}:priority:group:${group.groupId}`,
                         groups,
@@ -307,35 +270,40 @@ export function selectProviderKeyFromCandidatePool(opts) {
                 availabilityCheck: isAvailable
             }, 'round-robin');
         }
-        const weights = (() => {
-            if (!isSafePool || !contextWeightedCfg.enabled)
-                return undefined;
-            const ctx = computeContextWeightMultipliers({ candidates: pinnedCandidates, usage: contextResult.usage, warnRatio, cfg: contextWeightedCfg });
-            if (!ctx)
-                return undefined;
-            const out = {};
-            for (const key of pinnedCandidates) {
-                const m = computeContextMultiplier({
-                    effectiveSafeRefTokens: ctx.ref,
-                    effectiveSafeTokens: ctx.eff[key] ?? 1,
-                    cfg: contextWeightedCfg
-                });
-                out[key] = Math.max(1, Math.round(100 * m));
-            }
-            return out;
-        })();
+        const weights = buildCandidateWeights({
+            candidates: pinnedCandidates,
+            providerRegistry: deps.providerRegistry,
+            staticWeights: tierLoadBalancing.weights,
+            dynamicWeights: (() => {
+                if (!isSafePool || !contextWeightedCfg.enabled)
+                    return undefined;
+                const ctx = computeContextWeightMultipliers({ candidates: pinnedCandidates, usage: contextResult.usage, warnRatio, cfg: contextWeightedCfg });
+                if (!ctx)
+                    return undefined;
+                const out = {};
+                for (const key of pinnedCandidates) {
+                    const m = computeContextMultiplier({
+                        effectiveSafeRefTokens: ctx.ref,
+                        effectiveSafeTokens: ctx.eff[key] ?? 1,
+                        cfg: contextWeightedCfg
+                    });
+                    out[key] = Math.max(1, Math.round(100 * m));
+                }
+                return out;
+            })()
+        });
         const allowGrouped = !hasNonUniformWeights(pinnedCandidates, weights);
-        if (allowGrouped && deps.loadBalancer.getPolicy().strategy !== 'sticky') {
+        if (allowGrouped && tierLoadBalancing.strategy !== 'sticky') {
             const groups = buildPrimaryTargetGroups(pinnedCandidates, deps);
             if (groups.size > 0) {
-                const groupWeights = buildGroupWeights(groups, deps.loadBalancer.getPolicy().weights);
+                const groupWeights = buildGroupWeights(groups, tierLoadBalancing.weights);
                 const selected = deps.loadBalancer.selectGrouped({
                     routeName: `${routeName}:${tier.id}`,
                     groups,
                     stickyKey: options.allowAliasRotation ? undefined : stickyKey,
                     weights: groupWeights,
                     availabilityCheck: isAvailable
-                }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
+                }, tier.mode === 'round-robin' ? 'round-robin' : tierLoadBalancing.strategy);
                 if (selected) {
                     return selected;
                 }
@@ -347,7 +315,7 @@ export function selectProviderKeyFromCandidatePool(opts) {
             stickyKey: options.allowAliasRotation ? undefined : stickyKey,
             weights,
             availabilityCheck: isAvailable
-        }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
+        }, tier.mode === 'round-robin' ? 'round-robin' : tierLoadBalancing.strategy);
     }
     return selectProviderKeyWithQuotaBuckets({
         routeName,
@@ -365,6 +333,7 @@ export function selectProviderKeyFromCandidatePool(opts) {
         nowForWeights,
         healthWeightedCfg,
         contextWeightedCfg,
+        tierLoadBalancing,
         quotaView,
         isAvailable,
         selectFirstAvailable,

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

@@ -7,6 +7,17 @@ export declare const DEFAULT_ROUTE = "default";
 export declare const ROUTE_PRIORITY: string[];
 export type RoutingInstructionMode = 'force' | 'sticky' | 'none';
 export type RoutePoolMode = 'round-robin' | 'priority';
+export interface RoutePoolLoadBalancingPolicy {
+    /**
+     * Optional pool-level override for provider selection strategy.
+     * When omitted, Virtual Router falls back to the global loadBalancing.strategy.
+     */
+    strategy?: 'round-robin' | 'weighted' | 'sticky';
+    /**
+     * Optional pool-local weights. Keys may target runtime keys, provider.model groups, or provider ids.
+     */
+    weights?: Record<string, number>;
+}
 export interface RoutePoolTier {
     id: string;
     targets: string[];
@@ -25,6 +36,11 @@ export interface RoutePoolTier {
      * - routing.web_search: force server-side web_search flow.
      */
     force?: boolean;
+    /**
+     * Optional pool-scoped load-balancing override. This lets different route pools
+     * use different strategies/weights without mutating the global policy.
+     */
+    loadBalancing?: RoutePoolLoadBalancingPolicy;
 }
 export type RoutingPools = Record<string, RoutePoolTier[]>;
 export type StreamingPreference = 'auto' | 'always' | 'never';
@@ -215,11 +231,34 @@ export interface ProviderHealthConfig {
     cooldownMs: number;
     fatalCooldownMs?: number;
 }
+export type VirtualRouterWebSearchExecutionMode = 'servertool' | 'direct';
+export type VirtualRouterWebSearchDirectActivation = 'route' | 'builtin';
 export interface VirtualRouterWebSearchEngineConfig {
     id: string;
     providerKey: string;
     description?: string;
     default?: boolean;
+    /**
+     * Search execution mode:
+     * - servertool: expose canonical web_search tool and execute through servertool engine.
+     * - direct: route to a search-capable model/provider directly; servertool injection must skip it.
+     */
+    executionMode?: VirtualRouterWebSearchExecutionMode;
+    /**
+     * When executionMode=direct, controls how the upstream search capability is activated.
+     * - route: route selection itself enables native search behavior (e.g. deepseek-web search route).
+     * - builtin: upstream requires a provider-native builtin search tool/schema.
+     */
+    directActivation?: VirtualRouterWebSearchDirectActivation;
+    /**
+     * Optional target model id for direct-mode matching when request/compat layers need to detect
+     * which routed provider payload should receive native web search activation.
+     */
+    modelId?: string;
+    /**
+     * Optional builtin max-uses hint for providers that support builtin web search tools.
+     */
+    maxUses?: number;
     /**
      * When true, this engine will never be used by server-side tools
      * (e.g. web_search). It will also be omitted from injected tool

package/dist/servertool/handlers/web-search.js

@@ -118,6 +118,27 @@ function getWebSearchConfig(ctx) {
             : undefined;
         if (!id || !providerKey)
             continue;
+        const rawExecutionMode = typeof obj.executionMode === 'string'
+            ? obj.executionMode.trim().toLowerCase()
+            : typeof obj.mode === 'string'
+                ? obj.mode.trim().toLowerCase()
+                : '';
+        const executionMode = rawExecutionMode === 'direct' ? 'direct' : 'servertool';
+        const rawDirectActivation = typeof obj.directActivation === 'string'
+            ? obj.directActivation.trim().toLowerCase()
+            : typeof obj.activation === 'string'
+                ? obj.activation.trim().toLowerCase()
+                : '';
+        const directActivation = rawDirectActivation === 'builtin'
+            ? 'builtin'
+            : rawDirectActivation === 'route'
+                ? 'route'
+                : executionMode === 'direct'
+                    ? 'route'
+                    : undefined;
+        const modelId = typeof obj.modelId === 'string' && obj.modelId.trim() ? obj.modelId.trim() : undefined;
+        const rawMaxUses = typeof obj.maxUses === 'number' ? obj.maxUses : Number(obj.maxUses);
+        const maxUses = Number.isFinite(rawMaxUses) && rawMaxUses > 0 ? Math.floor(rawMaxUses) : undefined;
         const serverToolsDisabled = obj.serverToolsDisabled === true ||
             (typeof obj.serverToolsDisabled === 'string' &&
                 obj.serverToolsDisabled.trim().toLowerCase() === 'true') ||
@@ -142,6 +163,10 @@ function getWebSearchConfig(ctx) {
             providerKey,
             description: typeof obj.description === 'string' && obj.description.trim() ? obj.description.trim() : undefined,
             default: obj.default === true,
+            executionMode,
+            ...(directActivation ? { directActivation } : {}),
+            ...(modelId ? { modelId } : {}),
+            ...(maxUses ? { maxUses } : {}),
             ...(serverToolsDisabled ? { serverToolsDisabled: true } : {}),
             ...(searchEngineList ? { searchEngineList } : {})
         });
@@ -181,7 +206,7 @@ function resolveWebSearchEngine(config, engineId) {
     return undefined;
 }
 function buildEnginePriorityList(config, engineId) {
-    const engines = (Array.isArray(config.engines) ? config.engines : []).filter((engine) => !engine.serverToolsDisabled);
+    const engines = (Array.isArray(config.engines) ? config.engines : []).filter((engine) => !engine.serverToolsDisabled && (engine.executionMode ?? 'servertool') === 'servertool');
     if (!engines.length) {
         return [];
     }

package/dist/servertool/server-side-tools.js

@@ -100,7 +100,7 @@ function normalizeFilterTokenSet(values) {
     return normalized.size > 0 ? normalized : null;
 }
 function isNameIncluded(name, includeSet, excludeSet) {
-    const normalized = name.trim().toLowerCase();
+    const normalized = normalizeServerToolCallName(name);
     if (includeSet && !includeSet.has(normalized)) {
         return false;
     }
@@ -109,6 +109,13 @@ function isNameIncluded(name, includeSet, excludeSet) {
     }
     return true;
 }
+function normalizeServerToolCallName(name) {
+    const normalized = name.trim().toLowerCase();
+    if (normalized === 'websearch' || normalized === 'web-search') {
+        return 'web_search';
+    }
+    return normalized;
+}
 function extractToolCallsFromMessage(message) {
     const toolCalls = getArray(message.tool_calls);
     const out = [];
@@ -120,7 +127,9 @@ function extractToolCallsFromMessage(message) {
         const fn = asObject(tc.function) ??
             asObject(tc.functionCall) ??
             asObject(tc.function_call);
-        const name = fn && typeof fn.name === 'string' && String(fn.name).trim() ? String(fn.name).trim() : '';
+        const name = fn && typeof fn.name === 'string' && String(fn.name).trim()
+            ? normalizeServerToolCallName(String(fn.name))
+            : '';
         const rawArgs = (fn ? fn.arguments : undefined) ??
             (fn ? fn.args : undefined) ??
             (fn ? fn.input : undefined) ??

package/dist/servertool/types.d.ts

@@ -137,6 +137,10 @@ export type ServerToolBackendPlan = {
         providerKey: string;
         description?: string;
         default?: boolean;
+        executionMode?: 'servertool' | 'direct';
+        directActivation?: 'route' | 'builtin';
+        modelId?: string;
+        maxUses?: number;
         serverToolsDisabled?: boolean;
         searchEngineList?: string[];
     }[];