@jsonstudio/llms 0.6.795 → 0.6.938

package/dist/router/virtual-router/error-center.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderErrorEvent } from './types.js';
+type ProviderErrorListener = (event: ProviderErrorEvent) => void;
+export declare class ProviderErrorCenter {
+    private readonly listeners;
+    subscribe(listener: ProviderErrorListener): () => void;
+    emit(event: ProviderErrorEvent): ProviderErrorEvent;
+    private normalize;
+}
+export declare const providerErrorCenter: ProviderErrorCenter;
+export {};

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

@@ -0,0 +1,3 @@
+import type { ProcessedRequest, StandardizedRequest } from '../../conversion/hub/types/standardized.js';
+import type { RouterMetadataInput, RoutingFeatures } from './types.js';
+export declare function buildRoutingFeatures(request: StandardizedRequest | ProcessedRequest, metadata: RouterMetadataInput): RoutingFeatures;

package/dist/router/virtual-router/routing-instructions.d.ts

@@ -1,6 +1,6 @@
 import type { StandardizedMessage } from '../../conversion/hub/types/standardized.js';
 export interface RoutingInstruction {
-    type: 'force' | 'sticky' | 'disable' | 'enable' | 'clear' | 'allow' | 'stopMessageSet' | 'stopMessageClear';
+    type: 'force' | 'sticky' | 'prefer' | 'disable' | 'enable' | 'clear' | 'allow' | 'stopMessageSet' | 'stopMessageClear';
     provider?: string;
     keyAlias?: string;
     keyIndex?: number;
@@ -24,6 +24,13 @@ export interface RoutingInstructionState {
         model?: string;
         pathLength?: number;
     };
+    preferTarget?: {
+        provider?: string;
+        keyAlias?: string;
+        keyIndex?: number;
+        model?: string;
+        pathLength?: number;
+    };
     allowedProviders: Set<string>;
     disabledProviders: Set<string>;
     disabledKeys: Map<string, Set<string | number>>;
@@ -41,6 +48,21 @@ export interface RoutingInstructionState {
     stopMessageLastUsedAt?: number;
 }
 export declare function parseRoutingInstructions(messages: StandardizedMessage[]): RoutingInstruction[];
+/**
+ * 解析并预处理路由指令，优先处理 clear 指令，确保新指令能够覆盖旧状态。
+ * 返回清理后的指令列表，移除冗余的 stopMessageSet 指令。
+ */
+export declare function parseAndPreprocessRoutingInstructions(messages: StandardizedMessage[]): RoutingInstruction[];
+/**
+ * 提取 clear 指令（如果存在）。用于在路由选择前优先执行清理操作。
+ * @returns 是否存在 clear 指令
+ */
+export declare function extractClearInstruction(messages: StandardizedMessage[]): boolean;
+/**
+ * 提取 stopMessageClear 指令（如果存在）。
+ * @returns 是否存在 stopMessageClear 指令
+ */
+export declare function extractStopMessageClearInstruction(messages: StandardizedMessage[]): boolean;
 export declare function applyRoutingInstructions(instructions: RoutingInstruction[], currentState: RoutingInstructionState): RoutingInstructionState;
 export declare function cleanMessagesFromRoutingInstructions(messages: StandardizedMessage[]): StandardizedMessage[];
 export declare function serializeRoutingInstructionState(state: RoutingInstructionState): Record<string, unknown>;

package/dist/router/virtual-router/routing-instructions.js

@@ -2,8 +2,8 @@ import { extractMessageText } from './message-utils.js';
 export function parseRoutingInstructions(messages) {
     const instructions = [];
     // 从最新一条携带路由指令标记（<** ... **>）的 user 消息中解析指令，
-    // 而不是简单地取“最后一条 user 消息”。这样可以在服务重启后，通过完整
-    // 会话历史恢复 sticky/黑名单状态，同时保持“最后一次指令生效”的语义。
+    // 而不是简单地取"最后一条 user 消息"。这样可以在服务重启后，通过完整
+    // 会话历史恢复 sticky/黑名单状态，同时保持"最后一次指令生效"的语义。
     let sanitized = null;
     for (let idx = messages.length - 1; idx >= 0; idx -= 1) {
         const message = messages[idx];
@@ -44,6 +44,44 @@ export function parseRoutingInstructions(messages) {
     }
     return instructions;
 }
+/**
+ * 解析并预处理路由指令，优先处理 clear 指令，确保新指令能够覆盖旧状态。
+ * 返回清理后的指令列表，移除冗余的 stopMessageSet 指令。
+ */
+export function parseAndPreprocessRoutingInstructions(messages) {
+    const rawInstructions = parseRoutingInstructions(messages);
+    if (rawInstructions.length === 0) {
+        return [];
+    }
+    // 检查是否有 clear 指令
+    const hasClear = rawInstructions.some(inst => inst.type === 'clear');
+    if (!hasClear) {
+        return rawInstructions;
+    }
+    // 如果有 clear 指令，clear 之后的指令才有效，clear 之前的指令被清除
+    const clearIndex = rawInstructions.findIndex(inst => inst.type === 'clear');
+    const effectiveInstructions = rawInstructions.slice(clearIndex + 1);
+    // 移除 clear 后冗余的 stopMessageSet 指令（如果与原指令相同）
+    // 这里的逻辑会在 applyRoutingInstructions 中处理，
+    // 所以我们只需要返回 clear 之后的指令即可
+    return effectiveInstructions;
+}
+/**
+ * 提取 clear 指令（如果存在）。用于在路由选择前优先执行清理操作。
+ * @returns 是否存在 clear 指令
+ */
+export function extractClearInstruction(messages) {
+    const instructions = parseRoutingInstructions(messages);
+    return instructions.some((inst) => inst.type === 'clear');
+}
+/**
+ * 提取 stopMessageClear 指令（如果存在）。
+ * @returns 是否存在 stopMessageClear 指令
+ */
+export function extractStopMessageClearInstruction(messages) {
+    const instructions = parseRoutingInstructions(messages);
+    return instructions.some((inst) => inst.type === 'stopMessageClear');
+}
 function expandInstructionSegments(instruction) {
     const trimmed = instruction.trim();
     if (!trimmed) {
@@ -153,9 +191,10 @@ function parseSingleInstruction(instruction) {
         }
         // 约定：
         // - "!providerA,providerB"：允许列表（whitelist），用于快速限制可用 provider 集合；
-        // - "!provider.model" / "!provider.alias.model" / "!provider.2"：sticky 语义，按 provider / alias / model 过滤当前路由池。
+        // - "!provider.model" / "!provider[alias].model" / "!provider.2"：prefer 语义；
+        //   model 可用时只命中该 model（忽略路由），不可用则自动清除并回退到正常路由命中。
         //
-        // 这样可以在不破坏既有 "!glm,openai" 语义的前提下，引入基于模型 / alias 的 sticky 行为。
+        // 这样可以在不破坏既有 "!glm,openai" 语义的前提下，引入基于模型的优先命中行为。
         if (!target.includes('.')) {
             if (parsed.provider) {
                 return { type: 'allow', provider: parsed.provider, pathLength: parsed.pathLength };
@@ -163,7 +202,7 @@ function parseSingleInstruction(instruction) {
             return null;
         }
         const normalized = normalizeStickyOrForceTarget(parsed);
-        return { type: 'sticky', ...normalized };
+        return { type: 'prefer', ...normalized };
     }
     else if (instruction.startsWith('#')) {
         const target = instruction.substring(1).trim();
@@ -202,38 +241,71 @@ function parseTarget(target) {
     if (!target) {
         return null;
     }
-    const parts = target.split('.');
-    const pathLength = parts.length;
-    if (parts.length === 0) {
-        return null;
-    }
-    const provider = parts[0];
-    if (!provider || !isValidIdentifier(provider)) {
-        return null;
-    }
-    if (parts.length === 1) {
-        return { provider, pathLength };
-    }
-    if (parts.length === 2) {
-        const second = parts[1];
-        const keyIndex = parseInt(second, 10);
-        if (!isNaN(keyIndex) && keyIndex > 0) {
-            return { provider, keyIndex, pathLength };
+    // Accept "provider[alias].model" (as printed in virtual-router-hit logs) to avoid users
+    // needing to translate bracket notation back to dot notation manually.
+    // With the alias disambiguated, allow dots in model ids (e.g. gpt-5.2) without ambiguity.
+    const bracketMatch = target.match(/^([a-zA-Z0-9_-]+)\[([a-zA-Z0-9_-]*)\](?:\.(.+))?$/);
+    if (bracketMatch) {
+        const provider = bracketMatch[1];
+        const keyAliasRaw = bracketMatch[2];
+        const keyAlias = typeof keyAliasRaw === 'string' ? keyAliasRaw.trim() : '';
+        const model = typeof bracketMatch[3] === 'string' ? bracketMatch[3].trim() : '';
+        if (!provider || !isValidIdentifier(provider)) {
+            return null;
+        }
+        // Allow omitting the alias: "provider[].model" means "provider.model across all aliases".
+        // This also enables disambiguating model ids that contain dots, without requiring the user
+        // to specify the alias.
+        if (!keyAlias) {
+            if (!model) {
+                return { provider, pathLength: 1 };
+            }
+            if (!/^[a-zA-Z0-9_.-]+$/.test(model)) {
+                return null;
+            }
+            return { provider, model, pathLength: 2 };
+        }
+        if (!isValidIdentifier(keyAlias)) {
+            return null;
         }
-        if (isValidIdentifier(second)) {
-            return { provider, model: second, keyAlias: second, pathLength };
+        if (!model) {
+            // Treat as explicit alias selection. Use pathLength=3 so engine resolves keyAlias directly.
+            return { provider, keyAlias, pathLength: 3 };
         }
+        // Model ids may contain dots (e.g. gpt-5.2); allow them here because alias is already explicit.
+        if (!/^[a-zA-Z0-9_.-]+$/.test(model)) {
+            return null;
+        }
+        return { provider, keyAlias, model, pathLength: 3 };
+    }
+    // Dot syntax: align with config parsing used by routing entries.
+    // - "provider.modelId" -> modelId may contain dots; it always means model across all aliases.
+    // - Key/alias selection must use bracket syntax: "provider[alias]" or "provider[alias].modelId".
+    const firstDot = target.indexOf('.');
+    if (firstDot < 0) {
+        const provider = target.trim();
+        if (!provider || !isValidIdentifier(provider)) {
+            return null;
+        }
+        return { provider, pathLength: 1 };
+    }
+    const provider = target.slice(0, firstDot).trim();
+    const remainder = target.slice(firstDot + 1).trim();
+    if (!provider || !isValidIdentifier(provider) || !remainder) {
         return null;
     }
-    if (parts.length === 3) {
-        const keyAlias = parts[1];
-        const model = parts[2];
-        if (isValidIdentifier(keyAlias) && isValidIdentifier(model)) {
-            return { provider, keyAlias, model, pathLength };
+    // Support "provider.2" key-index notation (only when remainder is a plain integer).
+    if (/^\d+$/.test(remainder)) {
+        const keyIndex = Number.parseInt(remainder, 10);
+        if (Number.isFinite(keyIndex) && keyIndex > 0) {
+            return { provider, keyIndex, pathLength: 2 };
         }
+    }
+    // Treat everything after the first dot as the model id, allowing dots.
+    if (!/^[a-zA-Z0-9_.-]+$/.test(remainder)) {
         return null;
     }
-    return null;
+    return { provider, model: remainder, pathLength: 2 };
 }
 function normalizeStickyOrForceTarget(target) {
     if (target &&
@@ -269,6 +341,7 @@ export function applyRoutingInstructions(instructions, currentState) {
     const newState = {
         forcedTarget: currentState.forcedTarget ? { ...currentState.forcedTarget } : undefined,
         stickyTarget: currentState.stickyTarget ? { ...currentState.stickyTarget } : undefined,
+        preferTarget: currentState.preferTarget ? { ...currentState.preferTarget } : undefined,
         allowedProviders: new Set(currentState.allowedProviders),
         disabledProviders: new Set(currentState.disabledProviders),
         disabledKeys: new Map(Array.from(currentState.disabledKeys.entries()).map(([k, v]) => [k, new Set(v)])),
@@ -304,6 +377,17 @@ export function applyRoutingInstructions(instructions, currentState) {
                 };
                 newState.forcedTarget = undefined;
                 break;
+            case 'prefer':
+                newState.preferTarget = {
+                    provider: instruction.provider,
+                    keyAlias: instruction.keyAlias,
+                    keyIndex: instruction.keyIndex,
+                    model: instruction.model,
+                    pathLength: instruction.pathLength
+                };
+                newState.forcedTarget = undefined;
+                newState.stickyTarget = undefined;
+                break;
             case 'allow':
                 if (!allowReset) {
                     newState.allowedProviders.clear();
@@ -385,6 +469,7 @@ export function applyRoutingInstructions(instructions, currentState) {
             case 'clear':
                 newState.forcedTarget = undefined;
                 newState.stickyTarget = undefined;
+                newState.preferTarget = undefined;
                 newState.allowedProviders.clear();
                 newState.disabledProviders.clear();
                 newState.disabledKeys.clear();
@@ -452,6 +537,7 @@ export function serializeRoutingInstructionState(state) {
     return {
         forcedTarget: state.forcedTarget,
         stickyTarget: state.stickyTarget,
+        preferTarget: state.preferTarget,
         allowedProviders: Array.from(state.allowedProviders),
         disabledProviders: Array.from(state.disabledProviders),
         disabledKeys: Array.from(state.disabledKeys.entries()).map(([provider, keys]) => ({
@@ -486,6 +572,7 @@ export function deserializeRoutingInstructionState(data) {
     const state = {
         forcedTarget: undefined,
         stickyTarget: undefined,
+        preferTarget: undefined,
         allowedProviders: new Set(),
         disabledProviders: new Set(),
         disabledKeys: new Map(),
@@ -500,6 +587,9 @@ export function deserializeRoutingInstructionState(data) {
     if (data.stickyTarget && typeof data.stickyTarget === 'object') {
         state.stickyTarget = data.stickyTarget;
     }
+    if (data.preferTarget && typeof data.preferTarget === 'object') {
+        state.preferTarget = data.preferTarget;
+    }
     if (Array.isArray(data.allowedProviders)) {
         state.allowedProviders = new Set(data.allowedProviders);
     }

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

@@ -127,6 +127,15 @@ export interface VirtualRouterWebSearchConfig {
      */
     force?: boolean;
 }
+export interface VirtualRouterExecCommandGuardConfig {
+    enabled: boolean;
+    /**
+     * Optional JSON policy file path for additional deny rules.
+     * When enabled=true but policyFile is missing/empty/unreadable,
+     * llmswitch-core will still apply baseline "must-deny" rules.
+     */
+    policyFile?: string;
+}
 export interface VirtualRouterConfig {
     routing: RoutingPools;
     providers: Record<string, ProviderProfile>;
@@ -135,6 +144,7 @@ export interface VirtualRouterConfig {
     health?: ProviderHealthConfig;
     contextRouting?: VirtualRouterContextRoutingConfig;
     webSearch?: VirtualRouterWebSearchConfig;
+    execCommandGuard?: VirtualRouterExecCommandGuardConfig;
 }
 export interface VirtualRouterContextRoutingConfig {
     warnRatio: number;
@@ -150,6 +160,7 @@ export interface VirtualRouterBootstrapInput extends Record<string, unknown> {
     health?: ProviderHealthConfig;
     contextRouting?: VirtualRouterContextRoutingConfig;
     webSearch?: VirtualRouterWebSearchConfig | Record<string, unknown>;
+    execCommandGuard?: VirtualRouterExecCommandGuardConfig | Record<string, unknown>;
 }
 export type ProviderRuntimeMap = Record<string, ProviderRuntimeProfile>;
 export interface VirtualRouterBootstrapResult {

package/dist/servertool/engine.js

@@ -58,6 +58,101 @@ function createServerToolTimeoutError(options) {
     err.status = 504;
     return err;
 }
+function coerceFollowupPayloadStream(payload, stream) {
+    if (!payload || typeof payload !== 'object') {
+        return payload;
+    }
+    // ServerTool followup requests must be non-streaming to keep parsing deterministic and avoid
+    // provider-side SSE wrappers leaking into internal reenter calls.
+    if (stream === false) {
+        payload.stream = false;
+    }
+    return payload;
+}
+function hasNonEmptyText(value) {
+    if (typeof value === 'string') {
+        return value.trim().length > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.some((entry) => hasNonEmptyText(entry));
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const record = value;
+        if (hasNonEmptyText(record.text))
+            return true;
+        if (hasNonEmptyText(record.output_text))
+            return true;
+        if (hasNonEmptyText(record.content))
+            return true;
+    }
+    return false;
+}
+function isEmptyClientResponsePayload(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return true;
+    }
+    // If upstream returned an explicit error shape, treat as non-empty (caller should surface it).
+    if (Object.prototype.hasOwnProperty.call(payload, 'error')) {
+        return false;
+    }
+    // OpenAI Responses: requires_action (function_call output) is a meaningful response and must not be
+    // treated as "empty". Some auto-followup servertools (stop_message_flow / gemini_empty_reply_continue)
+    // previously misclassified this as empty because there is no output_text/content yet.
+    const requiredAction = payload.required_action;
+    if (requiredAction && typeof requiredAction === 'object') {
+        return false;
+    }
+    const outputForResponses = Array.isArray(payload.output) ? payload.output : [];
+    if (outputForResponses.length > 0) {
+        for (const item of outputForResponses) {
+            if (!item || typeof item !== 'object' || Array.isArray(item))
+                continue;
+            const type = typeof item.type === 'string' ? String(item.type).trim().toLowerCase() : '';
+            if (type === 'function_call' || type === 'tool_call' || type === 'tool_use' || type.includes('tool')) {
+                return false;
+            }
+        }
+    }
+    const choices = Array.isArray(payload.choices) ? payload.choices : [];
+    if (choices.length > 0) {
+        const first = choices[0] && typeof choices[0] === 'object' && !Array.isArray(choices[0]) ? choices[0] : null;
+        const message = first && typeof first.message === 'object' && first.message !== null && !Array.isArray(first.message)
+            ? first.message
+            : null;
+        if (!message) {
+            return true;
+        }
+        const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+        if (toolCalls.length > 0) {
+            return false;
+        }
+        // Support common chat shapes: content string/array, reasoning_content, etc.
+        if (hasNonEmptyText(message.content))
+            return false;
+        if (hasNonEmptyText(message.reasoning_content))
+            return false;
+        if (hasNonEmptyText(message.reasoning))
+            return false;
+        return true;
+    }
+    const output = Array.isArray(payload.output) ? payload.output : [];
+    if (output.length > 0) {
+        for (const item of output) {
+            if (!item || typeof item !== 'object' || Array.isArray(item))
+                continue;
+            const content = item.content;
+            if (hasNonEmptyText(content)) {
+                return false;
+            }
+            if (hasNonEmptyText(item.text))
+                return false;
+            if (hasNonEmptyText(item.output_text))
+                return false;
+        }
+        return true;
+    }
+    return true;
+}
 export async function runServerToolOrchestration(options) {
     const serverToolTimeoutMs = resolveServerToolTimeoutMs();
     const followupTimeoutMs = resolveServerToolFollowupTimeoutMs(serverToolTimeoutMs);
@@ -89,11 +184,13 @@ export async function runServerToolOrchestration(options) {
         };
     }
     const isStopMessageFlow = engineResult.execution.flowId === 'stop_message_flow';
+    const isGeminiEmptyReplyContinue = engineResult.execution.flowId === 'gemini_empty_reply_continue';
     const stopMessageSource = isStopMessageFlow ? getStopMessageSource(options.adapterContext) : undefined;
     const isAutoStopMessage = isStopMessageFlow && stopMessageSource !== 'explicit';
     const isErrorAutoFlow = engineResult.execution.flowId === 'iflow_model_error_retry';
     const applyAutoLimit = isAutoStopMessage || isErrorAutoFlow;
-    const routeHint = resolveRouteHint(options.adapterContext, engineResult.execution.flowId);
+    // ServerTool followups must not inherit or inject any routeHint; always route fresh.
+    const preserveRouteHint = false;
     const loopState = buildServerToolLoopState(options.adapterContext, engineResult.execution.flowId, engineResult.execution.followup.payload);
     if (applyAutoLimit && loopState && typeof loopState.repeatCount === 'number' && loopState.repeatCount >= 3) {
         return {
@@ -118,23 +215,35 @@ export async function runServerToolOrchestration(options) {
         ...(loopState ? { serverToolLoopState: loopState } : {}),
         ...(engineResult.execution.followup.metadata ?? {})
     };
-    if (routeHint && typeof metadata.routeHint !== 'string') {
-        metadata.routeHint = routeHint;
-    }
-    const maxAttempts = isStopMessageFlow ? 2 : 1;
+    // Enforce unified followup contract:
+    // - clear any inherited routeHint
+    // - do not inherit sticky target
+    // - record original entry endpoint for downstream formatting/debug
+    metadata.preserveRouteHint = preserveRouteHint;
+    // Use empty string (falsy) to avoid VirtualRouter calling `.trim()` on non-string values.
+    metadata.routeHint = '';
+    metadata.disableStickyRoutes = true;
+    metadata.serverToolOriginalEntryEndpoint =
+        (typeof options.entryEndpoint === 'string' && options.entryEndpoint.trim().length
+            ? options.entryEndpoint
+            : followupEntryEndpoint);
+    const retryEmptyFollowupOnce = isStopMessageFlow || isGeminiEmptyReplyContinue;
+    const maxAttempts = retryEmptyFollowupOnce ? 2 : 1;
     const followupRequestId = buildFollowupRequestId(options.requestId, engineResult.execution.followup.requestIdSuffix);
+    const followupPayload = coerceFollowupPayloadStream(engineResult.execution.followup.payload, metadata.stream === true);
     let followup;
     let lastError;
-    let reservation = null;
+    // stopMessage 是一种“状态型” servertool：一旦触发，我们需要尽量避免因 followup 失败而把状态留在可继续触发的位置，
+    // 否则会出现下一轮仍然自动触发 → 再次失败 → 客户端永远 502 的死循环。
+    //
+    // 因此这里对 stop_message_flow 做一次性 reservation，并在最终判定 followup 为空时清理 stopMessage 状态。
+    const stopMessageReservation = isStopMessageFlow ? reserveStopMessageUsage(options.adapterContext) : null;
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
         try {
-            if (isStopMessageFlow) {
-                reservation = reserveStopMessageUsage(options.adapterContext);
-            }
             followup = await withTimeout(options.reenterPipeline({
                 entryEndpoint: followupEntryEndpoint,
                 requestId: followupRequestId,
-                body: engineResult.execution.followup.payload,
+                body: followupPayload,
                 metadata
             }), followupTimeoutMs, () => createServerToolTimeoutError({
                 requestId: options.requestId,
@@ -144,14 +253,25 @@ export async function runServerToolOrchestration(options) {
                 attempt,
                 maxAttempts
             }));
+            // Treat empty followup as failure for auto followup flows:
+            // - retry once (maxAttempts=2)
+            // - if still empty, surface as HTTP error so client can retry.
+            if (retryEmptyFollowupOnce) {
+                const body = followup && followup.body && typeof followup.body === 'object'
+                    ? followup.body
+                    : undefined;
+                if (body && isEmptyClientResponsePayload(body)) {
+                    followup = undefined;
+                    lastError = new Error('SERVERTOOL_EMPTY_FOLLOWUP');
+                    if (attempt < maxAttempts) {
+                        continue;
+                    }
+                }
+            }
             lastError = undefined;
             break;
         }
         catch (error) {
-            if (reservation) {
-                rollbackStopMessageUsage(reservation);
-                reservation = null;
-            }
             if (isServerToolTimeoutError(error)) {
                 throw error;
             }
@@ -176,15 +296,27 @@ export async function runServerToolOrchestration(options) {
     const followupBody = followup && followup.body && typeof followup.body === 'object'
         ? followup.body
         : undefined;
-    if (isStopMessageFlow && !followupBody) {
+    if (retryEmptyFollowupOnce && (!followupBody || isEmptyClientResponsePayload(followupBody))) {
+        if (isStopMessageFlow) {
+            // 对 stopMessage：避免把 empty followup 升级为 502，直接清理 stopMessage 状态并返回原始响应。
+            // 这样客户端至少能拿到本轮输出，且 stopMessage 不会在后续请求里继续触发导致“永远 502”。
+            disableStopMessageAfterFailedFollowup(options.adapterContext, stopMessageReservation);
+            return {
+                chat: engineResult.finalChatResponse,
+                executed: true,
+                flowId: engineResult.execution.flowId
+            };
+        }
         const wrapped = new ProviderProtocolError(`[servertool] Followup returned empty response for flow ${engineResult.execution.flowId ?? 'unknown'}`, {
-            code: 'SERVERTOOL_FOLLOWUP_FAILED',
+            code: 'SERVERTOOL_EMPTY_FOLLOWUP',
+            category: 'EXTERNAL_ERROR',
             details: {
                 flowId: engineResult.execution.flowId,
                 requestId: options.requestId,
                 error: lastError instanceof Error ? lastError.message : undefined
             }
         });
+        wrapped.status = 502;
         wrapped.cause = lastError;
         throw wrapped;
     }
@@ -244,6 +376,47 @@ function reserveStopMessageUsage(adapterContext) {
 function rollbackStopMessageUsage(reservation) {
     saveRoutingInstructionStateSync(reservation.stickyKey, reservation.previousState);
 }
+function disableStopMessageAfterFailedFollowup(adapterContext, reservation) {
+    try {
+        const key = reservation && typeof reservation.stickyKey === 'string' && reservation.stickyKey.trim()
+            ? reservation.stickyKey.trim()
+            : resolveStickyKeyFromAdapterContext(adapterContext);
+        if (!key) {
+            return;
+        }
+        const state = loadRoutingInstructionStateSync(key);
+        if (!state) {
+            return;
+        }
+        state.stopMessageText = undefined;
+        state.stopMessageMaxRepeats = undefined;
+        state.stopMessageUsed = undefined;
+        state.stopMessageUpdatedAt = undefined;
+        state.stopMessageLastUsedAt = undefined;
+        saveRoutingInstructionStateSync(key, state);
+    }
+    catch {
+        // best-effort: do not crash the request due to state cleanup failures
+    }
+}
+function resolveStickyKeyFromAdapterContext(adapterContext) {
+    if (!adapterContext || typeof adapterContext !== 'object') {
+        return undefined;
+    }
+    const sessionId = typeof adapterContext.sessionId === 'string'
+        ? adapterContext.sessionId.trim()
+        : '';
+    const conversationId = typeof adapterContext.conversationId === 'string'
+        ? adapterContext.conversationId.trim()
+        : '';
+    if (sessionId) {
+        return `session:${sessionId}`;
+    }
+    if (conversationId) {
+        return `conversation:${conversationId}`;
+    }
+    return undefined;
+}
 function cloneRoutingInstructionState(state) {
     if (!state) {
         return null;