@jsonstudio/llms 0.6.2979 → 0.6.3214

package/dist/router/virtual-router/engine-legacy/route-selection.js

@@ -0,0 +1,205 @@
+import { DEFAULT_ROUTE, VirtualRouterError, VirtualRouterErrorCode } from '../types.js';
+import { buildRoutingFeatures } from '../features.js';
+import { persistRoutingInstructionState } from '../engine/routing-state/store.js';
+import { selectDirectProviderModel, selectFromStickyPool as selectFromStickyPoolImpl } from '../engine/routing-pools/index.js';
+export function selectRoutingTarget(engine, request, metadata, routingState, stateKey) {
+    const features = buildRoutingFeatures(request, metadata);
+    const directProviderModel = engine.parseDirectProviderModel(request?.model);
+    let classification;
+    let requestedRoute;
+    let selection = null;
+    const selectionDeps = {
+        routing: engine.routing,
+        providerRegistry: engine.providerRegistry,
+        healthManager: engine.healthManager,
+        contextAdvisor: engine.contextAdvisor,
+        loadBalancer: engine.loadBalancer,
+        isProviderCoolingDown: (key) => engine.isProviderCoolingDown(key),
+        resolveStickyKey: (m) => engine.resolveStickyKey(m),
+        quotaView: engine.quotaView
+    };
+    if (directProviderModel) {
+        const forceMediaFallback = engine.shouldFallbackDirectModelForMedia(directProviderModel, features);
+        const providerKeys = engine.providerRegistry.listProviderKeys(directProviderModel.providerId);
+        let hasModel = false;
+        for (const key of providerKeys) {
+            try {
+                const profile = engine.providerRegistry.get(key);
+                if (profile?.modelId === directProviderModel.modelId) {
+                    hasModel = true;
+                    break;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!hasModel) {
+            throw new VirtualRouterError(`Unknown model ${directProviderModel.modelId} for provider ${directProviderModel.providerId}`, VirtualRouterErrorCode.CONFIG_ERROR, { providerId: directProviderModel.providerId, modelId: directProviderModel.modelId });
+        }
+        if (!forceMediaFallback) {
+            const directSelection = selectDirectProviderModel(directProviderModel.providerId, directProviderModel.modelId, metadata, features, routingState, selectionDeps);
+            if (!directSelection) {
+                throw new VirtualRouterError(`All providers unavailable for model ${directProviderModel.providerId}.${directProviderModel.modelId}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { providerId: directProviderModel.providerId, modelId: directProviderModel.modelId });
+            }
+            classification = {
+                routeName: 'direct',
+                confidence: 1,
+                reasoning: `direct_model:${directProviderModel.providerId}.${directProviderModel.modelId}`,
+                fallback: false,
+                candidates: ['direct']
+            };
+            requestedRoute = 'direct';
+            selection = directSelection;
+        }
+        else {
+            classification = engine.classifier.classify(features);
+            requestedRoute = engine.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
+            selection = engine.selectProvider(requestedRoute, metadata, classification, features, routingState);
+        }
+    }
+    else {
+        // Prefer target (from "<**!provider.model**>") is evaluated before routing classification.
+        const preferTarget = routingState.preferTarget;
+        if (preferTarget && typeof preferTarget.provider === 'string' && preferTarget.provider.trim()) {
+            const providerId = preferTarget.provider.trim();
+            const keyAlias = typeof preferTarget.keyAlias === 'string' ? preferTarget.keyAlias.trim() : '';
+            const modelId = typeof preferTarget.model === 'string' ? preferTarget.model.trim() : '';
+            const keyIndex = typeof preferTarget.keyIndex === 'number' && Number.isFinite(preferTarget.keyIndex)
+                ? Math.floor(preferTarget.keyIndex)
+                : undefined;
+            const candidateKeys = [];
+            if (keyIndex !== undefined && keyIndex > 0) {
+                const runtimeKey = engine.providerRegistry.resolveRuntimeKeyByIndex(providerId, keyIndex);
+                if (runtimeKey) {
+                    candidateKeys.push(runtimeKey);
+                }
+            }
+            else if (modelId) {
+                const allKeys = engine.providerRegistry.listProviderKeys(providerId);
+                for (const key of allKeys) {
+                    if (keyAlias) {
+                        const prefix = `${providerId}.${keyAlias}.`;
+                        if (!key.startsWith(prefix)) {
+                            continue;
+                        }
+                    }
+                    try {
+                        const profile = engine.providerRegistry.get(key);
+                        if (profile?.modelId === modelId) {
+                            candidateKeys.push(key);
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            }
+            const allowAliasRotation = !keyAlias && keyIndex === undefined;
+            const eligibleKeys = (() => {
+                if (candidateKeys.length === 0) {
+                    return [];
+                }
+                const quotaView = selectionDeps.quotaView;
+                const now = quotaView ? Date.now() : 0;
+                return candidateKeys.filter((key) => {
+                    if (!quotaView) {
+                        if (engine.isProviderCoolingDown(key)) {
+                            return false;
+                        }
+                        if (!engine.healthManager.isAvailable(key)) {
+                            return false;
+                        }
+                        return true;
+                    }
+                    const entry = quotaView(key);
+                    if (!entry) {
+                        return true;
+                    }
+                    if (!entry.inPool) {
+                        return false;
+                    }
+                    if (entry.cooldownUntil && entry.cooldownUntil > now) {
+                        return false;
+                    }
+                    if (entry.blacklistUntil && entry.blacklistUntil > now) {
+                        return false;
+                    }
+                    return true;
+                });
+            })();
+            const preferSelection = eligibleKeys.length > 0
+                ? selectFromStickyPoolImpl(new Set(eligibleKeys), metadata, features, routingState, selectionDeps, {
+                    allowAliasRotation
+                })
+                : null;
+            if (preferSelection) {
+                classification = {
+                    routeName: 'prefer',
+                    confidence: 1,
+                    reasoning: keyIndex !== undefined ? `prefer_key:${providerId}.${keyIndex}` : `prefer_model:${providerId}.${modelId}`,
+                    fallback: false,
+                    candidates: ['prefer']
+                };
+                requestedRoute = 'prefer';
+                selection = {
+                    ...preferSelection,
+                    routeUsed: 'prefer',
+                    poolId: 'prefer-primary'
+                };
+            }
+            else if (routingState.preferTarget) {
+                // Auto-clear only when the target becomes invalid or blocked by explicit routing instructions.
+                // Do NOT clear for temporary unavailability (e.g. 429 cooldown, quota cooldown, transient health).
+                const shouldAutoClear = (() => {
+                    if (candidateKeys.length === 0) {
+                        return true;
+                    }
+                    // Prefer selection failed despite eligible keys existing: treat as a hard block (e.g. routing rules).
+                    if (eligibleKeys.length > 0) {
+                        return true;
+                    }
+                    // If quota explicitly marks the preferred target as out-of-pool, clear the prefer instruction so
+                    // the router can fall back to other targets without repeatedly retrying an impossible preference.
+                    if (selectionDeps.quotaView) {
+                        for (const key of candidateKeys) {
+                            const entry = selectionDeps.quotaView(key);
+                            if (entry && entry.inPool === false) {
+                                return true;
+                            }
+                        }
+                    }
+                    return false;
+                })();
+                if (shouldAutoClear) {
+                    routingState = {
+                        ...routingState,
+                        preferTarget: undefined
+                    };
+                    engine.routingInstructionState.set(stateKey, routingState);
+                    persistRoutingInstructionState(stateKey, routingState, engine.routingStateStore);
+                }
+            }
+        }
+        if (!selection) {
+            classification = metadata.routeHint && metadata.routeHint.trim()
+                ? {
+                    routeName: metadata.routeHint.trim(),
+                    confidence: 1,
+                    reasoning: `route_hint:${metadata.routeHint.trim()}`,
+                    fallback: false,
+                    candidates: [metadata.routeHint.trim()]
+                }
+                : engine.classifier.classify(features);
+            requestedRoute = engine.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
+            selection = engine.selectProvider(requestedRoute, metadata, classification, features, routingState);
+        }
+    }
+    return {
+        routingState,
+        requestedRoute,
+        classification: classification,
+        selection: selection,
+        features
+    };
+}

package/dist/router/virtual-router/engine-legacy/route-state-allowlist.d.ts

@@ -0,0 +1,3 @@
+import type { RoutingInstructionState } from '../routing-instructions.js';
+import type { VirtualRouterEngine } from '../engine-legacy.js';
+export declare function enforceAllowlistIntersection(engine: VirtualRouterEngine, routingState: RoutingInstructionState, stateKey: string): RoutingInstructionState;

package/dist/router/virtual-router/engine-legacy/route-state-allowlist.js

@@ -0,0 +1,36 @@
+import { extractProviderId } from '../engine/provider-key/parse.js';
+import { persistRoutingInstructionState } from '../engine/routing-state/store.js';
+export function enforceAllowlistIntersection(engine, routingState, stateKey) {
+    if (routingState.allowedProviders.size === 0) {
+        return routingState;
+    }
+    const providersInRouting = new Set();
+    for (const pools of Object.values(engine.routing)) {
+        if (!Array.isArray(pools))
+            continue;
+        for (const pool of pools) {
+            if (!pool || !Array.isArray(pool.targets))
+                continue;
+            for (const key of pool.targets) {
+                if (typeof key !== 'string' || !key)
+                    continue;
+                const providerId = extractProviderId(key);
+                if (providerId) {
+                    providersInRouting.add(providerId);
+                }
+            }
+        }
+    }
+    const allowed = Array.from(routingState.allowedProviders).filter((provider) => typeof provider === 'string');
+    const hasIntersection = allowed.some((provider) => providersInRouting.has(provider));
+    if (!hasIntersection) {
+        const nextState = {
+            ...routingState,
+            allowedProviders: new Set()
+        };
+        engine.routingInstructionState.set(stateKey, nextState);
+        persistRoutingInstructionState(stateKey, nextState, engine.routingStateStore);
+        return nextState;
+    }
+    return routingState;
+}

package/dist/router/virtual-router/engine-legacy/route-state.d.ts

@@ -0,0 +1,12 @@
+import type { ProcessedRequest, StandardizedRequest } from '../../../conversion/hub/types/standardized.js';
+import type { RouterMetadataInput } from '../types.js';
+import type { RoutingInstruction, RoutingInstructionState } from '../routing-instructions.js';
+import type { VirtualRouterEngine } from '../engine-legacy.js';
+export type RoutingStateResult = {
+    routingState: RoutingInstructionState;
+    stateKey: string;
+    stopMessageScope?: string;
+    metadataInstructions: RoutingInstruction[];
+    instructions: RoutingInstruction[];
+};
+export declare function buildRoutingState(engine: VirtualRouterEngine, request: StandardizedRequest | ProcessedRequest, metadata: RouterMetadataInput): RoutingStateResult;

package/dist/router/virtual-router/engine-legacy/route-state.js

@@ -0,0 +1,386 @@
+import { applyRoutingInstructions, cleanMessagesFromRoutingInstructions, parseRoutingInstructions } from '../routing-instructions.js';
+import { buildMetadataInstructions } from '../engine/routing-state/metadata.js';
+import { getRoutingInstructionState, persistRoutingInstructionState, resolveStopMessageScope } from '../engine/routing-state/store.js';
+import { ensureStopMessageModeMaxRepeats } from '../routing-stop-message-state-codec.js';
+import { extractMessageText } from '../message-utils.js';
+import { cleanResponsesContextFromRoutingInstructions, getLatestUserTextFromResponsesContext, hasLatestUserRoutingInstructionMarker, hasRoutingInstructionMarker, hasRoutingInstructionMarkerInResponsesContext, isServerToolFollowupRequest, isStopScopeTraceEnabled, normalizeStopMessageAiMode, normalizeStopMessageStageMode, stripClientInjectScopedFields, stripStopMessageFields } from './helpers.js';
+import { enforceAllowlistIntersection } from './route-state-allowlist.js';
+export function buildRoutingState(engine, request, metadata) {
+    const stickyKey = engine.resolveStickyKey(metadata);
+    const sessionScope = engine.resolveSessionScope(metadata);
+    const stopMessageScope = resolveStopMessageScope(metadata);
+    // Route sticky state remains session/request scoped for routing behavior,
+    // but stopMessage state is tmux/clockd scoped and merged separately below.
+    const stateKey = sessionScope || stickyKey || 'default';
+    const baseState = getRoutingInstructionState(stateKey, engine.routingInstructionState, engine.routingStateStore);
+    let routingState = stripStopMessageFields(baseState);
+    const metadataInstructions = buildMetadataInstructions(metadata);
+    if (metadataInstructions.length > 0) {
+        routingState = applyRoutingInstructions(metadataInstructions, routingState);
+    }
+    const disableStickyRoutes = metadata &&
+        typeof metadata === 'object' &&
+        metadata.disableStickyRoutes === true;
+    if (disableStickyRoutes && (routingState.stickyTarget || routingState.preferTarget)) {
+        routingState = {
+            ...routingState,
+            stickyTarget: undefined,
+            preferTarget: undefined
+        };
+    }
+    if (stopMessageScope) {
+        const sessionState = getRoutingInstructionState(stopMessageScope, engine.routingInstructionState, engine.routingStateStore);
+        if (ensureStopMessageModeMaxRepeats(sessionState)) {
+            engine.routingInstructionState.set(stopMessageScope, sessionState);
+            persistRoutingInstructionState(stopMessageScope, sessionState, engine.routingStateStore);
+        }
+        if (typeof sessionState.stopMessageText === 'string' ||
+            typeof sessionState.stopMessageMaxRepeats === 'number' ||
+            typeof sessionState.stopMessageStageMode === 'string' ||
+            typeof sessionState.stopMessageAiMode === 'string' ||
+            typeof sessionState.stopMessageAiSeedPrompt === 'string' ||
+            Array.isArray(sessionState.stopMessageAiHistory)) {
+            routingState = {
+                ...routingState,
+                stopMessageText: sessionState.stopMessageText,
+                stopMessageMaxRepeats: sessionState.stopMessageMaxRepeats,
+                stopMessageUsed: sessionState.stopMessageUsed,
+                stopMessageUpdatedAt: sessionState.stopMessageUpdatedAt,
+                stopMessageLastUsedAt: sessionState.stopMessageLastUsedAt,
+                stopMessageStageMode: sessionState.stopMessageStageMode,
+                stopMessageAiMode: sessionState.stopMessageAiMode,
+                stopMessageAiSeedPrompt: sessionState.stopMessageAiSeedPrompt,
+                stopMessageAiHistory: sessionState.stopMessageAiHistory
+            };
+        }
+        if (typeof sessionState.preCommandScriptPath === 'string' && sessionState.preCommandScriptPath.trim()) {
+            routingState = {
+                ...routingState,
+                preCommandSource: sessionState.preCommandSource,
+                preCommandScriptPath: sessionState.preCommandScriptPath,
+                preCommandUpdatedAt: sessionState.preCommandUpdatedAt
+            };
+        }
+    }
+    let parsedInstructions = parseRoutingInstructions(request.messages);
+    const responsesContext = request.semantics && typeof request.semantics === 'object'
+        ? request.semantics.responses?.context
+        : undefined;
+    const responsesLatestUserText = getLatestUserTextFromResponsesContext(responsesContext);
+    const responsesHasMarker = hasRoutingInstructionMarkerInResponsesContext(responsesContext);
+    if (!parsedInstructions.length && responsesHasMarker) {
+        parsedInstructions = parseRoutingInstructions([
+            { role: 'user', content: responsesLatestUserText }
+        ]);
+    }
+    const markerDetected = hasRoutingInstructionMarker(request.messages) || responsesHasMarker;
+    const latestMessage = request.messages.length > 0 ? request.messages[request.messages.length - 1] : undefined;
+    const latestUserText = latestMessage && latestMessage.role === 'user' ? extractMessageText(latestMessage).trim() : '';
+    const stopMessageLogText = responsesHasMarker ? responsesLatestUserText : latestUserText;
+    const containsStopMessage = Boolean(stopMessageLogText && /stopmessage/i.test(stopMessageLogText));
+    const stopMessageTypes = parsedInstructions
+        .filter((entry) => entry.type === 'stopMessageSet' ||
+        entry.type === 'stopMessageMode' ||
+        entry.type === 'stopMessageClear')
+        .map((entry) => entry.type);
+    if (containsStopMessage || stopMessageTypes.length > 0) {
+        const preview = stopMessageLogText.replace(/\s+/g, ' ').slice(0, 120);
+        engine.debug?.log?.(`[virtual-router][stop_message_parse] requestId=${metadata.requestId || 'n/a'} marker=${markerDetected ? 'detected' : 'missing'} parsed=${stopMessageTypes.join(',') || 'none'} preview=${preview}`);
+    }
+    if (markerDetected && isStopScopeTraceEnabled()) {
+        const parsedTypes = parsedInstructions.map((entry) => entry.type);
+        engine.debug?.log?.(`[virtual-router][instruction_parse] requestId=${metadata.requestId || 'n/a'} marker=detected parsed=${parsedTypes.join(',') || 'none'}`);
+    }
+    else if (isStopScopeTraceEnabled()) {
+        if (stopMessageLogText && /stopmessage/i.test(stopMessageLogText)) {
+            const preview = stopMessageLogText.replace(/\s+/g, ' ').slice(0, 120);
+            engine.debug?.log?.(`[virtual-router][instruction_parse] requestId=${metadata.requestId || 'n/a'} marker=missing contains_stopmessage=yes preview=${preview}`);
+        }
+    }
+    const serverToolFollowup = isServerToolFollowupRequest(metadata);
+    const latestUserHasMarker = hasLatestUserRoutingInstructionMarker(request.messages) || responsesHasMarker;
+    let instructions = parsedInstructions;
+    if (serverToolFollowup && instructions.length > 0) {
+        instructions = instructions.filter((entry) => entry.type !== 'stopMessageSet' &&
+            entry.type !== 'stopMessageMode' &&
+            entry.type !== 'stopMessageClear' &&
+            entry.type !== 'preCommandSet' &&
+            entry.type !== 'preCommandClear');
+    }
+    if (stopMessageScope && parsedInstructions.length > 0) {
+        const sessionState = getRoutingInstructionState(stopMessageScope, engine.routingInstructionState, engine.routingStateStore);
+        const hasStaleStopMessageInstruction = !latestUserHasMarker &&
+            parsedInstructions.some((entry) => entry.type === 'stopMessageSet' || entry.type === 'stopMessageMode');
+        if (hasStaleStopMessageInstruction) {
+            const hasActiveStopState = typeof sessionState.stopMessageText === 'string' ||
+                typeof sessionState.stopMessageMaxRepeats === 'number' ||
+                typeof sessionState.stopMessageStageMode === 'string' ||
+                typeof sessionState.stopMessageAiMode === 'string' ||
+                typeof sessionState.stopMessageAiSeedPrompt === 'string' ||
+                Array.isArray(sessionState.stopMessageAiHistory);
+            const hasStopLifecycleStamp = (typeof sessionState.stopMessageUpdatedAt === 'number' &&
+                Number.isFinite(sessionState.stopMessageUpdatedAt)) ||
+                (typeof sessionState.stopMessageLastUsedAt === 'number' &&
+                    Number.isFinite(sessionState.stopMessageLastUsedAt));
+            if (hasActiveStopState || hasStopLifecycleStamp) {
+                instructions = instructions.filter((entry) => entry.type !== 'stopMessageSet' && entry.type !== 'stopMessageMode');
+            }
+        }
+    }
+    // stopMessage/precommand require explicit client inject scope (tmux).
+    // When scope is missing, drop only these instructions and keep request passthrough.
+    if (instructions.length > 0 && !stopMessageScope) {
+        const blockedInstructionTypes = instructions
+            .filter((entry) => entry.type === 'stopMessageSet' ||
+            entry.type === 'stopMessageMode' ||
+            entry.type === 'stopMessageClear' ||
+            entry.type === 'preCommandSet' ||
+            entry.type === 'preCommandClear')
+            .map((entry) => entry.type);
+        if (blockedInstructionTypes.length > 0 && isStopScopeTraceEnabled()) {
+            engine.debug?.log?.(`[virtual-router][stop_scope] requestId=${metadata.requestId || 'n/a'} stage=drop reason=missing_tmux_scope instructions=${blockedInstructionTypes.join(',')}`);
+        }
+        instructions = instructions.filter((entry) => entry.type !== 'stopMessageSet' &&
+            entry.type !== 'stopMessageMode' &&
+            entry.type !== 'stopMessageClear' &&
+            entry.type !== 'preCommandSet' &&
+            entry.type !== 'preCommandClear');
+    }
+    if (hasRoutingInstructionMarker(request.messages) || responsesHasMarker) {
+        request.messages = cleanMessagesFromRoutingInstructions(request.messages);
+        cleanResponsesContextFromRoutingInstructions(responsesContext);
+    }
+    let appliedRoutingState = routingState;
+    if (instructions.length > 0) {
+        appliedRoutingState = applyRoutingInstructions(instructions, routingState);
+        const persistedBaseState = stopMessageScope
+            ? stripClientInjectScopedFields(appliedRoutingState)
+            : appliedRoutingState;
+        routingState = persistedBaseState;
+        engine.routingInstructionState.set(stateKey, persistedBaseState);
+        persistRoutingInstructionState(stateKey, persistedBaseState, engine.routingStateStore);
+        // Persist stopMessage under tmux/clockd scope so client injection and trigger matching
+        // use the same scope and never fall back to generic session keys.
+        if (stopMessageScope) {
+            const hasStopMessageSet = instructions.some((entry) => entry.type === 'stopMessageSet');
+            const hasStopMessageMode = instructions.some((entry) => entry.type === 'stopMessageMode');
+            const hasGlobalClear = instructions.some((entry) => entry.type === 'clear');
+            const hasStopMessageClear = hasGlobalClear || instructions.some((entry) => entry.type === 'stopMessageClear');
+            if (hasStopMessageSet || hasStopMessageMode || hasStopMessageClear) {
+                const activeInstructionTypes = instructions
+                    .filter((entry) => entry.type === 'stopMessageSet' ||
+                    entry.type === 'stopMessageMode' ||
+                    entry.type === 'stopMessageClear')
+                    .map((entry) => entry.type);
+                if (isStopScopeTraceEnabled()) {
+                    engine.debug?.log?.(`[virtual-router][stop_scope] requestId=${metadata.requestId || 'n/a'} stage=apply scope=${stopMessageScope} instructions=${activeInstructionTypes.join(',') || 'none'}`);
+                }
+                const sessionState = getRoutingInstructionState(stopMessageScope, engine.routingInstructionState, engine.routingStateStore);
+                let nextSessionState = {
+                    ...sessionState
+                };
+                let shouldPersistSessionState = false;
+                const hasStopMessageStateChanged = () => {
+                    return (nextSessionState.stopMessageText !== sessionState.stopMessageText ||
+                        nextSessionState.stopMessageMaxRepeats !== sessionState.stopMessageMaxRepeats ||
+                        nextSessionState.stopMessageUsed !== sessionState.stopMessageUsed ||
+                        nextSessionState.stopMessageUpdatedAt !== sessionState.stopMessageUpdatedAt ||
+                        nextSessionState.stopMessageLastUsedAt !== sessionState.stopMessageLastUsedAt ||
+                        nextSessionState.stopMessageSource !== sessionState.stopMessageSource ||
+                        nextSessionState.stopMessageStageMode !== sessionState.stopMessageStageMode ||
+                        nextSessionState.stopMessageAiMode !== sessionState.stopMessageAiMode ||
+                        nextSessionState.stopMessageAiSeedPrompt !== sessionState.stopMessageAiSeedPrompt ||
+                        JSON.stringify(nextSessionState.stopMessageAiHistory || []) !==
+                            JSON.stringify(sessionState.stopMessageAiHistory || []));
+                };
+                if (hasStopMessageClear) {
+                    if (hasGlobalClear) {
+                        // <**clear**> is a hard reset: clear all session-scoped routing state
+                        // and let persistRoutingInstructionState delete persistence markers.
+                        nextSessionState = {
+                            forcedTarget: undefined,
+                            stickyTarget: undefined,
+                            preferTarget: undefined,
+                            allowedProviders: new Set(),
+                            disabledProviders: new Set(),
+                            disabledKeys: new Map(),
+                            disabledModels: new Map(),
+                            stopMessageSource: undefined,
+                            stopMessageText: undefined,
+                            stopMessageMaxRepeats: undefined,
+                            stopMessageUsed: undefined,
+                            stopMessageUpdatedAt: undefined,
+                            stopMessageLastUsedAt: undefined,
+                            stopMessageStageMode: undefined,
+                            stopMessageAiMode: undefined,
+                            stopMessageAiSeedPrompt: undefined,
+                            stopMessageAiHistory: undefined,
+                            preCommandSource: undefined,
+                            preCommandScriptPath: undefined,
+                            preCommandUpdatedAt: undefined
+                        };
+                        shouldPersistSessionState = true;
+                    }
+                    else {
+                        nextSessionState.stopMessageText = undefined;
+                        nextSessionState.stopMessageMaxRepeats = undefined;
+                        nextSessionState.stopMessageUsed = undefined;
+                        nextSessionState.stopMessageUpdatedAt = undefined;
+                        nextSessionState.stopMessageLastUsedAt = undefined;
+                        nextSessionState.stopMessageSource = undefined;
+                        nextSessionState.stopMessageStageMode = undefined;
+                        nextSessionState.stopMessageAiMode = undefined;
+                        nextSessionState.stopMessageAiSeedPrompt = undefined;
+                        nextSessionState.stopMessageAiHistory = undefined;
+                        shouldPersistSessionState = true;
+                    }
+                }
+                else if (hasStopMessageSet || hasStopMessageMode) {
+                    nextSessionState.stopMessageText =
+                        typeof appliedRoutingState.stopMessageText === 'string' &&
+                            appliedRoutingState.stopMessageText.trim()
+                            ? appliedRoutingState.stopMessageText
+                            : undefined;
+                    nextSessionState.stopMessageMaxRepeats =
+                        typeof appliedRoutingState.stopMessageMaxRepeats === 'number' &&
+                            Number.isFinite(appliedRoutingState.stopMessageMaxRepeats)
+                            ? Math.floor(appliedRoutingState.stopMessageMaxRepeats)
+                            : undefined;
+                    nextSessionState.stopMessageUsed =
+                        typeof appliedRoutingState.stopMessageUsed === 'number' &&
+                            Number.isFinite(appliedRoutingState.stopMessageUsed)
+                            ? Math.max(0, Math.floor(appliedRoutingState.stopMessageUsed))
+                            : undefined;
+                    nextSessionState.stopMessageUpdatedAt =
+                        typeof appliedRoutingState.stopMessageUpdatedAt === 'number' &&
+                            Number.isFinite(appliedRoutingState.stopMessageUpdatedAt)
+                            ? appliedRoutingState.stopMessageUpdatedAt
+                            : undefined;
+                    nextSessionState.stopMessageLastUsedAt =
+                        typeof appliedRoutingState.stopMessageLastUsedAt === 'number' &&
+                            Number.isFinite(appliedRoutingState.stopMessageLastUsedAt)
+                            ? appliedRoutingState.stopMessageLastUsedAt
+                            : undefined;
+                    nextSessionState.stopMessageSource =
+                        typeof appliedRoutingState.stopMessageSource === 'string' &&
+                            appliedRoutingState.stopMessageSource.trim()
+                            ? appliedRoutingState.stopMessageSource.trim()
+                            : undefined;
+                    nextSessionState.stopMessageStageMode = normalizeStopMessageStageMode(appliedRoutingState.stopMessageStageMode);
+                    nextSessionState.stopMessageAiMode = normalizeStopMessageAiMode(appliedRoutingState.stopMessageAiMode);
+                    nextSessionState.stopMessageAiSeedPrompt =
+                        typeof appliedRoutingState.stopMessageAiSeedPrompt === 'string' &&
+                            appliedRoutingState.stopMessageAiSeedPrompt.trim()
+                            ? appliedRoutingState.stopMessageAiSeedPrompt.trim()
+                            : undefined;
+                    nextSessionState.stopMessageAiHistory = Array.isArray(appliedRoutingState.stopMessageAiHistory)
+                        ? appliedRoutingState.stopMessageAiHistory
+                        : undefined;
+                    shouldPersistSessionState = hasStopMessageStateChanged();
+                }
+                if (shouldPersistSessionState) {
+                    engine.routingInstructionState.set(stopMessageScope, nextSessionState);
+                    persistRoutingInstructionState(stopMessageScope, nextSessionState, engine.routingStateStore);
+                }
+                else {
+                    nextSessionState = sessionState;
+                }
+                // 日志展示使用 session scope 的 stopMessage 状态，避免每次解析重复刷新时间/次数。
+                if (typeof nextSessionState.stopMessageText === 'string' ||
+                    typeof nextSessionState.stopMessageMaxRepeats === 'number' ||
+                    typeof nextSessionState.stopMessageStageMode === 'string' ||
+                    typeof nextSessionState.stopMessageAiMode === 'string' ||
+                    typeof nextSessionState.stopMessageAiSeedPrompt === 'string' ||
+                    Array.isArray(nextSessionState.stopMessageAiHistory)) {
+                    routingState.stopMessageText = nextSessionState.stopMessageText;
+                    routingState.stopMessageMaxRepeats = nextSessionState.stopMessageMaxRepeats;
+                    routingState.stopMessageUsed = nextSessionState.stopMessageUsed;
+                    routingState.stopMessageUpdatedAt = nextSessionState.stopMessageUpdatedAt;
+                    routingState.stopMessageLastUsedAt = nextSessionState.stopMessageLastUsedAt;
+                    routingState.stopMessageStageMode = nextSessionState.stopMessageStageMode;
+                    routingState.stopMessageAiMode = nextSessionState.stopMessageAiMode;
+                    routingState.stopMessageAiSeedPrompt = nextSessionState.stopMessageAiSeedPrompt;
+                    routingState.stopMessageAiHistory = nextSessionState.stopMessageAiHistory;
+                }
+            }
+        }
+    }
+    if (instructions.length > 0 && stopMessageScope) {
+        const hasPreCommandSet = instructions.some((entry) => entry.type === 'preCommandSet');
+        const hasPreCommandClear = instructions.some((entry) => entry.type === 'preCommandClear');
+        if (hasPreCommandSet || hasPreCommandClear) {
+            const sessionState = getRoutingInstructionState(stopMessageScope, engine.routingInstructionState, engine.routingStateStore);
+            const nextSessionState = {
+                ...sessionState
+            };
+            let changed = false;
+            if (hasPreCommandClear) {
+                changed =
+                    typeof sessionState.preCommandScriptPath === 'string' ||
+                        typeof sessionState.preCommandSource === 'string' ||
+                        typeof sessionState.preCommandUpdatedAt === 'number';
+                nextSessionState.preCommandScriptPath = undefined;
+                nextSessionState.preCommandSource = undefined;
+                nextSessionState.preCommandUpdatedAt = Date.now();
+            }
+            if (hasPreCommandSet) {
+                const scriptPath = typeof appliedRoutingState.preCommandScriptPath === 'string'
+                    ? appliedRoutingState.preCommandScriptPath.trim()
+                    : '';
+                if (scriptPath) {
+                    if (sessionState.preCommandScriptPath !== scriptPath) {
+                        changed = true;
+                    }
+                    nextSessionState.preCommandScriptPath = scriptPath;
+                    nextSessionState.preCommandSource = 'explicit';
+                    nextSessionState.preCommandUpdatedAt =
+                        typeof appliedRoutingState.preCommandUpdatedAt === 'number' &&
+                            Number.isFinite(appliedRoutingState.preCommandUpdatedAt)
+                            ? appliedRoutingState.preCommandUpdatedAt
+                            : Date.now();
+                }
+            }
+            if (changed) {
+                engine.routingInstructionState.set(stopMessageScope, nextSessionState);
+                persistRoutingInstructionState(stopMessageScope, nextSessionState, engine.routingStateStore);
+                routingState.preCommandScriptPath = nextSessionState.preCommandScriptPath;
+                routingState.preCommandSource = nextSessionState.preCommandSource;
+                routingState.preCommandUpdatedAt = nextSessionState.preCommandUpdatedAt;
+            }
+        }
+    }
+    if (instructions.length === 0 && stopMessageScope) {
+        const sessionState = getRoutingInstructionState(stopMessageScope, engine.routingInstructionState, engine.routingStateStore);
+        if (typeof sessionState.stopMessageText === 'string' ||
+            typeof sessionState.stopMessageMaxRepeats === 'number' ||
+            typeof sessionState.stopMessageStageMode === 'string' ||
+            typeof sessionState.stopMessageAiMode === 'string' ||
+            typeof sessionState.stopMessageAiSeedPrompt === 'string' ||
+            Array.isArray(sessionState.stopMessageAiHistory)) {
+            routingState.stopMessageText = sessionState.stopMessageText;
+            routingState.stopMessageMaxRepeats = sessionState.stopMessageMaxRepeats;
+            routingState.stopMessageUsed = sessionState.stopMessageUsed;
+            routingState.stopMessageUpdatedAt = sessionState.stopMessageUpdatedAt;
+            routingState.stopMessageLastUsedAt = sessionState.stopMessageLastUsedAt;
+            routingState.stopMessageStageMode = sessionState.stopMessageStageMode;
+            routingState.stopMessageAiMode = sessionState.stopMessageAiMode;
+            routingState.stopMessageAiSeedPrompt = sessionState.stopMessageAiSeedPrompt;
+            routingState.stopMessageAiHistory = sessionState.stopMessageAiHistory;
+        }
+        if (typeof sessionState.preCommandScriptPath === 'string' && sessionState.preCommandScriptPath.trim()) {
+            routingState.preCommandScriptPath = sessionState.preCommandScriptPath;
+            routingState.preCommandSource = sessionState.preCommandSource;
+            routingState.preCommandUpdatedAt = sessionState.preCommandUpdatedAt;
+        }
+    }
+    // Guardrail: if a session is restricted to providers that do not exist in any routing pools,
+    // we must not hard-fail the request loop. Auto-clear the allowlist and fall back to normal routing.
+    routingState = enforceAllowlistIntersection(engine, routingState, stateKey);
+    return {
+        routingState,
+        stateKey,
+        stopMessageScope,
+        metadataInstructions,
+        instructions
+    };
+}