@jsonstudio/llms 0.6.1397 → 0.6.1402

package/dist/conversion/hub/pipeline/hub-pipeline.js

@@ -1,10 +1,112 @@
+import { Readable } from 'node:stream';
+import { isJsonObject, jsonClone } from '../types/json.js';
 import { VirtualRouterEngine } from '../../../router/virtual-router/engine.js';
 import { providerErrorCenter } from '../../../router/virtual-router/error-center.js';
-import { setHubPolicyRuntimePolicy } from '../policy/policy-engine.js';
-import { executeChatProcessEntryPipeline } from './hub-pipeline/execute-chat-process-entry.js';
-import { executeRequestStagePipeline } from './hub-pipeline/execute-request-stage.js';
-import { normalizeHubPipelineRequest } from './hub-pipeline/payload-normalize.js';
-import { resolveProtocolHooks } from './hub-pipeline/resolve-protocol-hooks.js';
+import { defaultSseCodecRegistry } from '../../../sse/index.js';
+import { ResponsesFormatAdapter } from '../format-adapters/responses-format-adapter.js';
+import { ResponsesSemanticMapper } from '../semantic-mappers/responses-mapper.js';
+import { AnthropicFormatAdapter } from '../format-adapters/anthropic-format-adapter.js';
+import { AnthropicSemanticMapper } from '../semantic-mappers/anthropic-mapper.js';
+import { GeminiFormatAdapter } from '../format-adapters/gemini-format-adapter.js';
+import { GeminiSemanticMapper } from '../semantic-mappers/gemini-mapper.js';
+import { ChatFormatAdapter } from '../format-adapters/chat-format-adapter.js';
+import { ChatSemanticMapper } from '../semantic-mappers/chat-mapper.js';
+import { createSnapshotRecorder } from '../snapshot-recorder.js';
+import { shouldRecordSnapshots } from '../../shared/snapshot-utils.js';
+import { runReqInboundStage1FormatParse } from './stages/req_inbound/req_inbound_stage1_format_parse/index.js';
+import { runReqInboundStage2SemanticMap } from './stages/req_inbound/req_inbound_stage2_semantic_map/index.js';
+import { runChatContextCapture, captureResponsesContextSnapshot } from './stages/req_inbound/req_inbound_stage3_context_capture/index.js';
+import { createResponsesContextCapture, createNoopContextCapture } from './stages/req_inbound/req_inbound_stage3_context_capture/context-factories.js';
+import { runReqProcessStage1ToolGovernance } from './stages/req_process/req_process_stage1_tool_governance/index.js';
+import { runReqProcessStage2RouteSelect } from './stages/req_process/req_process_stage2_route_select/index.js';
+import { runReqOutboundStage1SemanticMap } from './stages/req_outbound/req_outbound_stage1_semantic_map/index.js';
+import { runReqOutboundStage2FormatBuild } from './stages/req_outbound/req_outbound_stage2_format_build/index.js';
+import { runReqOutboundStage3Compat } from './stages/req_outbound/req_outbound_stage3_compat/index.js';
+import { extractSessionIdentifiersFromMetadata } from './session-identifiers.js';
+import { computeRequestTokens } from '../../../router/virtual-router/token-estimator.js';
+import { isCompactionRequest } from '../../shared/compaction-detect.js';
+import { applyHubProviderOutboundPolicy, recordHubPolicyObservation, setHubPolicyRuntimePolicy } from '../policy/policy-engine.js';
+import { applyProviderOutboundToolSurface } from '../tool-surface/tool-surface-engine.js';
+import { applyHubOperations } from '../ops/operations.js';
+import { cloneRuntimeMetadata, ensureRuntimeMetadata, readRuntimeMetadata } from '../../shared/runtime-metadata.js';
+function isTruthyEnv(value) {
+    const v = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+function resolveApplyPatchToolModeFromEnv() {
+    const rawMode = String(process.env.RCC_APPLY_PATCH_TOOL_MODE || process.env.ROUTECODEX_APPLY_PATCH_TOOL_MODE || '')
+        .trim()
+        .toLowerCase();
+    if (rawMode === 'freeform')
+        return 'freeform';
+    if (rawMode === 'schema' || rawMode === 'json_schema')
+        return 'schema';
+    const freeformFlag = process.env.RCC_APPLY_PATCH_FREEFORM || process.env.ROUTECODEX_APPLY_PATCH_FREEFORM;
+    if (isTruthyEnv(freeformFlag))
+        return 'freeform';
+    return undefined;
+}
+function resolveApplyPatchToolModeFromTools(toolsRaw) {
+    if (!Array.isArray(toolsRaw) || toolsRaw.length === 0) {
+        return undefined;
+    }
+    for (const entry of toolsRaw) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const record = entry;
+        const type = typeof record.type === 'string' ? record.type.trim().toLowerCase() : '';
+        if (type && type !== 'function')
+            continue;
+        const fn = record.function && typeof record.function === 'object' && !Array.isArray(record.function)
+            ? record.function
+            : undefined;
+        const name = typeof fn?.name === 'string' ? fn.name.trim().toLowerCase() : '';
+        if (name !== 'apply_patch')
+            continue;
+        const format = typeof record.format === 'string'
+            ? record.format.trim().toLowerCase()
+            : typeof fn?.format === 'string'
+                ? String(fn.format).trim().toLowerCase()
+                : '';
+        if (format === 'freeform')
+            return 'freeform';
+        // If apply_patch is present without explicit freeform marker, default to schema mode.
+        return 'schema';
+    }
+    return undefined;
+}
+function extractHubPolicyOverride(metadata) {
+    const raw = metadata ? metadata.__hubPolicyOverride : undefined;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return undefined;
+    }
+    const obj = raw;
+    const mode = typeof obj.mode === 'string' ? obj.mode.trim().toLowerCase() : '';
+    const sampleRate = typeof obj.sampleRate === 'number' && Number.isFinite(obj.sampleRate) ? obj.sampleRate : undefined;
+    if (mode !== 'off' && mode !== 'observe' && mode !== 'enforce') {
+        return undefined;
+    }
+    return {
+        mode: mode,
+        ...(sampleRate !== undefined ? { sampleRate } : {})
+    };
+}
+function extractHubShadowCompareConfig(metadata) {
+    const raw = metadata ? metadata.__hubShadowCompare : undefined;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return undefined;
+    }
+    const obj = raw;
+    const modeCandidate = typeof obj.baselineMode === 'string'
+        ? obj.baselineMode.trim().toLowerCase()
+        : typeof obj.mode === 'string'
+            ? obj.mode.trim().toLowerCase()
+            : '';
+    if (modeCandidate !== 'off' && modeCandidate !== 'observe' && modeCandidate !== 'enforce') {
+        return undefined;
+    }
+    return { baselineMode: modeCandidate };
+}
 export class HubPipeline {
     routerEngine;
     config;
@@ -74,26 +176,1270 @@ export class HubPipeline {
             this.unsubscribeProviderErrors = undefined;
         }
     }
-    async execute(request) {
-        const normalized = await normalizeHubPipelineRequest(request);
-        if (normalized.direction === 'request' && normalized.hubEntryMode === 'chat_process') {
-            return await executeChatProcessEntryPipeline({
-                config: this.config,
-                routerEngine: this.routerEngine,
-                normalized,
-                resolveProtocolHooks
+    async executeRequestStagePipeline(normalized, hooks) {
+        const formatAdapter = hooks.createFormatAdapter();
+        const semanticMapper = hooks.createSemanticMapper();
+        const rawRequest = this.asJsonObject(normalized.payload);
+        // Detect applyPatchToolMode (runtime/tooling hint). Client tool schemas are captured as chat semantics
+        // in req_inbound_stage2_semantic_map; they must not be stored in metadata.
+        try {
+            const toolsRaw = Array.isArray(rawRequest?.tools) ? rawRequest.tools : null;
+            const applyPatchToolMode = resolveApplyPatchToolModeFromEnv() ?? resolveApplyPatchToolModeFromTools(toolsRaw);
+            if (applyPatchToolMode) {
+                normalized.metadata = normalized.metadata || {};
+                const rt = ensureRuntimeMetadata(normalized.metadata);
+                rt.applyPatchToolMode = applyPatchToolMode;
+            }
+        }
+        catch {
+            // best-effort: do not block request handling due to tool scan failures
+        }
+        if (isCompactionRequest(rawRequest)) {
+            normalized.metadata = normalized.metadata || {};
+            const rt = ensureRuntimeMetadata(normalized.metadata);
+            rt.compactionRequest = true;
+        }
+        const effectivePolicy = normalized.policyOverride ?? this.config.policy;
+        const shadowCompareBaselineMode = normalized.shadowCompare?.baselineMode;
+        const inboundAdapterContext = this.buildAdapterContext(normalized);
+        const inboundRecorder = this.maybeCreateStageRecorder(inboundAdapterContext, normalized.entryEndpoint, {
+            disableSnapshots: normalized.disableSnapshots === true
+        });
+        const inboundStart = Date.now();
+        // Phase 0: observe client inbound payload violations (best-effort; no rewrites).
+        recordHubPolicyObservation({
+            policy: effectivePolicy,
+            providerProtocol: this.resolveClientProtocol(normalized.entryEndpoint),
+            payload: rawRequest,
+            phase: 'client_inbound',
+            stageRecorder: inboundRecorder,
+            requestId: normalized.id
+        });
+        const formatEnvelope = await runReqInboundStage1FormatParse({
+            rawRequest,
+            adapterContext: inboundAdapterContext,
+            formatAdapter,
+            stageRecorder: inboundRecorder
+        });
+        const responsesResumeFromMetadata = normalized.metadata && typeof normalized.metadata.responsesResume === 'object'
+            ? normalized.metadata.responsesResume
+            : undefined;
+        const inboundStage2 = await runReqInboundStage2SemanticMap({
+            adapterContext: inboundAdapterContext,
+            formatEnvelope,
+            semanticMapper,
+            ...(responsesResumeFromMetadata ? { responsesResume: responsesResumeFromMetadata } : {}),
+            stageRecorder: inboundRecorder
+        });
+        // responsesResume must not enter chat_process as metadata; it is lifted into chat.semantics in stage2.
+        if (responsesResumeFromMetadata &&
+            normalized.metadata &&
+            Object.prototype.hasOwnProperty.call(normalized.metadata, 'responsesResume')) {
+            delete normalized.metadata.responsesResume;
+        }
+        const contextSnapshot = await hooks.captureContext({
+            rawRequest,
+            adapterContext: inboundAdapterContext,
+            stageRecorder: inboundRecorder
+        });
+        const standardizedRequest = inboundStage2.standardizedRequest;
+        try {
+            const rt = readRuntimeMetadata(normalized.metadata);
+            const mode = String(rt?.applyPatchToolMode || '').trim().toLowerCase();
+            if (mode === 'freeform' || mode === 'schema') {
+                standardizedRequest.metadata.applyPatchToolMode = mode;
+            }
+        }
+        catch {
+            // best-effort: do not block request handling due to metadata propagation failures
+        }
+        const inboundEnd = Date.now();
+        const nodeResults = [];
+        nodeResults.push({
+            id: 'req_inbound',
+            success: true,
+            metadata: {
+                node: 'req_inbound',
+                executionTime: inboundEnd - inboundStart,
+                startTime: inboundStart,
+                endTime: inboundEnd,
+                dataProcessed: {
+                    messages: standardizedRequest.messages.length,
+                    tools: standardizedRequest.tools?.length ?? 0
+                }
+            }
+        });
+        // 将 VirtualRouter 层的 servertool 相关配置注入到 metadata，保证响应侧
+        // servertool（第三跳 reenter）也能访问到相同配置，即使当前 route 标记为 passthrough。
+        const metaBase = {
+            ...(normalized.metadata ?? {})
+        };
+        const rtBase = ensureRuntimeMetadata(metaBase);
+        const webSearchConfig = this.config.virtualRouter?.webSearch;
+        if (webSearchConfig) {
+            rtBase.webSearch = webSearchConfig;
+        }
+        const execCommandGuard = this.config.virtualRouter?.execCommandGuard;
+        if (execCommandGuard) {
+            rtBase.execCommandGuard = execCommandGuard;
+        }
+        const clockConfig = this.config.virtualRouter?.clock;
+        if (clockConfig) {
+            rtBase.clock = clockConfig;
+        }
+        normalized.metadata = metaBase;
+        let processedRequest;
+        if (normalized.processMode !== 'passthrough') {
+            assertNoMappableSemanticsInMetadata(metaBase, 'chat_process.request.entry');
+            const processResult = await runReqProcessStage1ToolGovernance({
+                request: standardizedRequest,
+                rawPayload: rawRequest,
+                metadata: metaBase,
+                entryEndpoint: normalized.entryEndpoint,
+                requestId: normalized.id,
+                stageRecorder: inboundRecorder
             });
+            processedRequest = processResult.processedRequest;
+            // Surface request-side clock reservation into pipeline metadata so response conversion
+            // can commit delivery only after a successful response is produced.
+            try {
+                const reservation = processedRequest?.metadata?.__clockReservation;
+                if (reservation && typeof reservation === 'object') {
+                    metaBase.__clockReservation = reservation;
+                }
+            }
+            catch {
+                // best-effort: do not block request handling due to metadata propagation failures
+            }
+            if (processResult.nodeResult) {
+                nodeResults.push(this.convertProcessNodeResult('chat_process.req.stage4.tool_governance', processResult.nodeResult));
+            }
+        }
+        let workingRequest = processedRequest ?? standardizedRequest;
+        // 使用与 VirtualRouter 一致的 tiktoken 计数逻辑，对标准化请求进行一次
+        // 上下文 token 估算，供后续 usage 归一化与统计使用。
+        try {
+            const estimatedTokens = computeRequestTokens(workingRequest, '');
+            if (typeof estimatedTokens === 'number' && Number.isFinite(estimatedTokens) && estimatedTokens > 0) {
+                normalized.metadata = normalized.metadata || {};
+                normalized.metadata.estimatedInputTokens = estimatedTokens;
+            }
+        }
+        catch {
+            // 估算失败不应影响主流程
+        }
+        const normalizedMeta = normalized.metadata;
+        // responsesResume is a client-protocol semantic (/v1/responses tool loop) and must live in chat.semantics.
+        // Do not read it from metadata once entering chat_process.
+        const responsesResume = (() => {
+            try {
+                const semantics = workingRequest?.semantics;
+                const node = semantics && typeof semantics === 'object' && !Array.isArray(semantics) ? semantics.responses : undefined;
+                const resume = node && typeof node === 'object' && !Array.isArray(node) ? node.resume : undefined;
+                return resume && typeof resume === 'object' && !Array.isArray(resume) ? resume : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        const stdMetadata = workingRequest?.metadata;
+        const hasImageAttachment = (stdMetadata?.hasImageAttachment === true || stdMetadata?.hasImageAttachment === 'true') ||
+            (normalizedMeta?.hasImageAttachment === true || normalizedMeta?.hasImageAttachment === 'true');
+        const serverToolRequired = stdMetadata?.webSearchEnabled === true ||
+            stdMetadata?.serverToolRequired === true;
+        const sessionIdentifiers = extractSessionIdentifiersFromMetadata(normalized.metadata);
+        // 将从 metadata / clientHeaders 中解析出的会话标识同步回 normalized.metadata，
+        // 便于后续 AdapterContext（响应侧 servertool）也能访问到相同的 sessionId /
+        // conversationId，用于 sticky-session 相关逻辑（例如 stopMessage）。
+        if (sessionIdentifiers.sessionId && normalized.metadata && typeof normalized.metadata === 'object') {
+            normalized.metadata.sessionId = sessionIdentifiers.sessionId;
+        }
+        if (sessionIdentifiers.conversationId && normalized.metadata && typeof normalized.metadata === 'object') {
+            normalized.metadata.conversationId = sessionIdentifiers.conversationId;
+        }
+        const disableStickyRoutes = readRuntimeMetadata(normalized.metadata)?.disableStickyRoutes === true;
+        const metadataInput = {
+            requestId: normalized.id,
+            entryEndpoint: normalized.entryEndpoint,
+            processMode: normalized.processMode,
+            stream: normalized.stream,
+            direction: normalized.direction,
+            providerProtocol: normalized.providerProtocol,
+            routeHint: normalized.routeHint,
+            stage: normalized.stage,
+            responsesResume: responsesResume,
+            ...(disableStickyRoutes ? { disableStickyRoutes: true } : {}),
+            ...(serverToolRequired ? { serverToolRequired: true } : {}),
+            ...(sessionIdentifiers.sessionId ? { sessionId: sessionIdentifiers.sessionId } : {}),
+            ...(sessionIdentifiers.conversationId ? { conversationId: sessionIdentifiers.conversationId } : {})
+        };
+        const routing = runReqProcessStage2RouteSelect({
+            routerEngine: this.routerEngine,
+            request: workingRequest,
+            metadataInput,
+            normalizedMetadata: normalized.metadata,
+            stageRecorder: inboundRecorder
+        });
+        const stopMessageState = this.routerEngine.getStopMessageState(metadataInput);
+        if (stopMessageState && normalized.metadata && typeof normalized.metadata === 'object') {
+            const rt = ensureRuntimeMetadata(normalized.metadata);
+            rt.stopMessageState = stopMessageState;
         }
-        const hooks = resolveProtocolHooks(normalized.providerProtocol);
+        // Emit virtual router hit log for debugging (orange [virtual-router] ...)
+        try {
+            const routeName = routing.decision?.routeName;
+            const providerKey = routing.target?.providerKey;
+            const modelId = workingRequest.model;
+            const logger = (normalized.metadata && normalized.metadata.logger);
+            if (logger && typeof logger.logVirtualRouterHit === 'function' && routeName && providerKey) {
+                logger.logVirtualRouterHit(routeName, providerKey, typeof modelId === 'string' ? modelId : undefined);
+            }
+        }
+        catch {
+            // logging must not break routing
+        }
+        const outboundStream = this.resolveOutboundStreamIntent(routing.target?.streaming);
+        workingRequest = this.applyOutboundStreamPreference(workingRequest, outboundStream);
+        const outboundAdapterContext = this.buildAdapterContext(normalized, routing.target);
+        if (routing.target?.compatibilityProfile) {
+            outboundAdapterContext.compatibilityProfile = routing.target.compatibilityProfile;
+        }
+        const outboundProtocol = outboundAdapterContext.providerProtocol;
+        const protocolSwitch = outboundProtocol !== normalized.providerProtocol;
+        const outboundHooks = protocolSwitch ? this.resolveProtocolHooks(outboundProtocol) : hooks;
+        if (!outboundHooks) {
+            throw new Error(`[HubPipeline] Unsupported provider protocol for hub pipeline: ${outboundProtocol}`);
+        }
+        const outboundSemanticMapper = protocolSwitch ? outboundHooks.createSemanticMapper() : semanticMapper;
+        const outboundFormatAdapter = protocolSwitch ? outboundHooks.createFormatAdapter() : formatAdapter;
+        const outboundContextMetadataKey = protocolSwitch ? outboundHooks.contextMetadataKey : hooks.contextMetadataKey;
+        const outboundContextSnapshot = protocolSwitch ? undefined : contextSnapshot;
+        // Snapshots must be grouped by entry endpoint (client-facing protocol), not by provider protocol.
+        // Otherwise one request would be split across multiple folders (e.g. openai-responses + anthropic-messages),
+        // which breaks codex-samples correlation.
+        const outboundRecorder = this.maybeCreateStageRecorder(outboundAdapterContext, normalized.entryEndpoint, {
+            disableSnapshots: normalized.disableSnapshots === true
+        });
+        const outboundStart = Date.now();
+        let providerPayload;
+        const outboundStage1 = await runReqOutboundStage1SemanticMap({
+            request: workingRequest,
+            adapterContext: outboundAdapterContext,
+            semanticMapper: outboundSemanticMapper,
+            contextSnapshot: outboundContextSnapshot,
+            contextMetadataKey: outboundContextMetadataKey,
+            stageRecorder: outboundRecorder
+        });
+        let formattedPayload = await runReqOutboundStage2FormatBuild({
+            formatEnvelope: outboundStage1.formatEnvelope,
+            adapterContext: outboundAdapterContext,
+            formatAdapter: outboundFormatAdapter,
+            stageRecorder: outboundRecorder
+        });
+        formattedPayload = await runReqOutboundStage3Compat({
+            payload: formattedPayload,
+            adapterContext: outboundAdapterContext,
+            stageRecorder: outboundRecorder
+        });
+        let shadowBaselineProviderPayload;
+        if (shadowCompareBaselineMode) {
+            const baselinePolicy = {
+                ...(effectivePolicy ?? {}),
+                mode: shadowCompareBaselineMode
+            };
+            // Compute a baseline provider payload in the *same execution*, without recording
+            // snapshots/diffs and without re-running the full pipeline. This avoids side effects
+            // (conversation store, followup captures, etc.) that a second execute() would trigger.
+            const baselineFormatted = typeof globalThis.structuredClone === 'function'
+                ? globalThis.structuredClone(formattedPayload)
+                : jsonClone(formattedPayload);
+            let baselinePayload = applyHubProviderOutboundPolicy({
+                policy: baselinePolicy,
+                providerProtocol: outboundProtocol,
+                payload: baselineFormatted,
+                stageRecorder: undefined,
+                requestId: normalized.id
+            });
+            baselinePayload = applyProviderOutboundToolSurface({
+                config: this.config.toolSurface,
+                providerProtocol: outboundProtocol,
+                payload: baselinePayload,
+                stageRecorder: undefined,
+                requestId: normalized.id
+            });
+            shadowBaselineProviderPayload = baselinePayload;
+        }
+        // Phase 0/1: observe provider outbound payload violations before any enforcement rewrites.
+        // This provides black-box visibility into what the pipeline would have sent upstream.
+        recordHubPolicyObservation({
+            policy: effectivePolicy,
+            providerProtocol: outboundProtocol,
+            payload: formattedPayload,
+            stageRecorder: outboundRecorder,
+            requestId: normalized.id
+        });
+        providerPayload = applyHubProviderOutboundPolicy({
+            policy: effectivePolicy,
+            providerProtocol: outboundProtocol,
+            payload: formattedPayload,
+            stageRecorder: outboundRecorder,
+            requestId: normalized.id
+        });
+        providerPayload = applyProviderOutboundToolSurface({
+            config: this.config.toolSurface,
+            providerProtocol: outboundProtocol,
+            payload: providerPayload,
+            stageRecorder: outboundRecorder,
+            requestId: normalized.id
+        });
+        recordHubPolicyObservation({
+            policy: effectivePolicy,
+            providerProtocol: outboundProtocol,
+            payload: providerPayload,
+            stageRecorder: outboundRecorder,
+            requestId: normalized.id
+        });
+        const outboundEnd = Date.now();
+        nodeResults.push({
+            id: 'req_outbound',
+            success: true,
+            metadata: {
+                node: 'req_outbound',
+                executionTime: outboundEnd - outboundStart,
+                startTime: outboundStart,
+                endTime: outboundEnd,
+                dataProcessed: {
+                    messages: workingRequest.messages.length,
+                    tools: workingRequest.tools?.length ?? 0
+                }
+            }
+        });
+        // 为响应侧 servertool/web_search 提供一次性 Chat 请求快照，便于在 Hub 内部实现
+        // 第三跳（将工具结果注入消息历史后重新调用主模型）。
+        //
+        // 注意：这里不再根据 processMode(passthrough/chat) 做分支判断——即使某些
+        // route 将 processMode 标记为 passthrough，我们仍然需要保留一次规范化后的
+        // Chat 请求快照，供 stopMessage / gemini_empty_reply_continue 等被动触发型
+        // servertool 在响应阶段使用。
+        //
+        // 之前这里通过 JSON.stringify/parse 做深拷贝，但在部分 Responses/Gemini
+        // 场景下，workingRequest 上携带的 metadata 可能包含无法安全序列化的字段，
+        // 导致克隆过程抛错、capturedChatRequest 被静默丢弃，从而让响应侧的
+        // stop_message_auto 等 ServerTool 无法获取上一跳的 Chat 请求。
+        //
+        // 对于 capturedChatRequest，我们只需要一个“可读快照”，不会在后续流程中
+        // 对其做就地修改，因此可以直接使用浅拷贝结构，避免序列化失败导致整段
+        // 逻辑失效。
+        // Deep-clone a JSON-safe snapshot for servertool followups.
+        // Only capture the canonical Chat payload fields (model/messages/tools/parameters) to keep it serializable.
+        const capturedChatRequest = {
+            model: workingRequest.model,
+            messages: jsonClone(workingRequest.messages),
+            tools: workingRequest.tools ? jsonClone(workingRequest.tools) : workingRequest.tools,
+            parameters: workingRequest.parameters ? jsonClone(workingRequest.parameters) : workingRequest.parameters
+        };
+        const metadata = {
+            ...normalized.metadata,
+            ...(hasImageAttachment ? { hasImageAttachment: true } : {}),
+            capturedChatRequest,
+            entryEndpoint: normalized.entryEndpoint,
+            providerProtocol: outboundProtocol,
+            stream: normalized.stream,
+            processMode: normalized.processMode,
+            routeHint: normalized.routeHint,
+            target: routing.target,
+            ...(typeof outboundStream === 'boolean' ? { providerStream: outboundStream } : {}),
+            ...(shadowBaselineProviderPayload
+                ? {
+                    hubShadowCompare: {
+                        baselineMode: shadowCompareBaselineMode,
+                        candidateMode: (effectivePolicy?.mode ?? 'off'),
+                        providerProtocol: outboundProtocol,
+                        baselineProviderPayload: shadowBaselineProviderPayload
+                    }
+                }
+                : {})
+        };
+        return {
+            requestId: normalized.id,
+            providerPayload,
+            standardizedRequest,
+            processedRequest,
+            routingDecision: routing.decision,
+            routingDiagnostics: routing.diagnostics,
+            target: routing.target,
+            metadata,
+            nodeResults
+        };
+    }
+    resolveClientProtocol(entryEndpoint) {
+        const lowered = String(entryEndpoint || '').toLowerCase();
+        if (lowered.includes('/v1/responses'))
+            return 'openai-responses';
+        if (lowered.includes('/v1/messages'))
+            return 'anthropic-messages';
+        return 'openai-chat';
+    }
+    coerceStandardizedRequestFromPayload(payload, normalized) {
+        const model = typeof payload.model === 'string' && payload.model.trim().length ? payload.model.trim() : '';
+        if (!model) {
+            throw new Error('[HubPipeline] outbound stage requires payload.model');
+        }
+        const messages = Array.isArray(payload.messages) ? payload.messages : null;
+        if (!messages) {
+            throw new Error('[HubPipeline] outbound stage requires payload.messages[]');
+        }
+        const tools = Array.isArray(payload.tools) ? payload.tools : undefined;
+        const parameters = payload.parameters && typeof payload.parameters === 'object' && !Array.isArray(payload.parameters)
+            ? payload.parameters
+            : {};
+        const semanticsFromPayload = payload.semantics && typeof payload.semantics === 'object' && !Array.isArray(payload.semantics)
+            ? jsonClone(payload.semantics)
+            : undefined;
+        const metadataFromPayload = payload.metadata && typeof payload.metadata === 'object' && !Array.isArray(payload.metadata)
+            ? payload.metadata
+            : undefined;
+        const standardizedRequest = {
+            model,
+            messages,
+            ...(tools ? { tools } : {}),
+            parameters,
+            metadata: {
+                originalEndpoint: normalized.entryEndpoint,
+                ...(metadataFromPayload ? metadataFromPayload : {}),
+                requestId: normalized.id,
+                stream: normalized.stream,
+                processMode: normalized.processMode,
+                ...(normalized.routeHint ? { routeHint: normalized.routeHint } : {})
+            },
+            ...(semanticsFromPayload ? { semantics: semanticsFromPayload } : {})
+        };
+        // Ensure followup/chat_process entry can still preserve mappable semantics
+        // without injecting them into metadata.
+        try {
+            const semantics = standardizedRequest.semantics && typeof standardizedRequest.semantics === 'object'
+                ? standardizedRequest.semantics
+                : (standardizedRequest.semantics = {});
+            if (!semantics.tools || typeof semantics.tools !== 'object' || Array.isArray(semantics.tools)) {
+                semantics.tools = {};
+            }
+            const toolsNode = semantics.tools;
+            if (Array.isArray(payload.tools) && payload.tools.length && toolsNode.clientToolsRaw === undefined) {
+                toolsNode.clientToolsRaw = jsonClone(payload.tools);
+            }
+        }
+        catch {
+            // best-effort
+        }
+        // Keep rawPayload minimal and JSON-safe; chat-process only needs the OpenAI-chat-like surface here.
+        const rawPayload = {
+            model,
+            messages,
+            ...(tools ? { tools } : {}),
+            ...(parameters && Object.keys(parameters).length ? { parameters } : {})
+        };
+        return { standardizedRequest, rawPayload };
+    }
+    async executeChatProcessEntryPipeline(normalized) {
+        const hooks = this.resolveProtocolHooks(normalized.providerProtocol);
         if (!hooks) {
             throw new Error(`Unsupported provider protocol for hub pipeline: ${normalized.providerProtocol}`);
         }
-        return await executeRequestStagePipeline({
-            config: this.config,
+        const nodeResults = [];
+        nodeResults.push({
+            id: 'req_inbound',
+            success: true,
+            metadata: {
+                node: 'req_inbound',
+                skipped: true,
+                reason: 'stage=outbound',
+                dataProcessed: {}
+            }
+        });
+        const rawPayloadInput = this.asJsonObject(normalized.payload);
+        const { standardizedRequest: standardizedRequestBase, rawPayload } = this.coerceStandardizedRequestFromPayload(rawPayloadInput, normalized);
+        // Keep metadata injection consistent with the inbound path: servertool/web_search config must be available
+        // to chat-process/tool governance even when request enters at outbound stage.
+        const metaBase = {
+            ...(normalized.metadata ?? {})
+        };
+        const rtBase = ensureRuntimeMetadata(metaBase);
+        const webSearchConfig = this.config.virtualRouter?.webSearch;
+        if (webSearchConfig) {
+            rtBase.webSearch = webSearchConfig;
+        }
+        const execCommandGuard = this.config.virtualRouter?.execCommandGuard;
+        if (execCommandGuard) {
+            rtBase.execCommandGuard = execCommandGuard;
+        }
+        const clockConfig = this.config.virtualRouter?.clock;
+        if (clockConfig) {
+            rtBase.clock = clockConfig;
+        }
+        normalized.metadata = metaBase;
+        const standardizedRequest = standardizedRequestBase;
+        // Semantic Gate (chat_process entry): lift any mappable protocol semantics from metadata into request.semantics.
+        // This is the last chance before entering chat_process; after this point we fail-fast on banned metadata keys.
+        try {
+            const resumeMeta = metaBase && typeof metaBase.responsesResume === 'object' && metaBase.responsesResume
+                ? metaBase.responsesResume
+                : undefined;
+            if (resumeMeta) {
+                standardizedRequest.semantics = standardizedRequest.semantics ?? {};
+                const semantics = standardizedRequest.semantics;
+                if (!semantics.responses || typeof semantics.responses !== 'object' || Array.isArray(semantics.responses)) {
+                    semantics.responses = {};
+                }
+                const responsesNode = semantics.responses;
+                if (responsesNode.resume === undefined) {
+                    responsesNode.resume = jsonClone(resumeMeta);
+                }
+                delete metaBase.responsesResume;
+            }
+        }
+        catch {
+            // best-effort; validation happens below
+        }
+        try {
+            const rt = readRuntimeMetadata(metaBase);
+            const mode = String(rt?.applyPatchToolMode || '').trim().toLowerCase();
+            if (mode === 'freeform' || mode === 'schema') {
+                standardizedRequest.metadata.applyPatchToolMode = mode;
+            }
+        }
+        catch {
+            // ignore
+        }
+        const adapterContext = this.buildAdapterContext(normalized);
+        const stageRecorder = this.maybeCreateStageRecorder(adapterContext, normalized.entryEndpoint, {
+            disableSnapshots: normalized.disableSnapshots === true
+        });
+        let processedRequest;
+        if (normalized.processMode !== 'passthrough') {
+            assertNoMappableSemanticsInMetadata(metaBase, 'chat_process.request.entry');
+            const processResult = await runReqProcessStage1ToolGovernance({
+                request: standardizedRequest,
+                rawPayload,
+                metadata: metaBase,
+                entryEndpoint: normalized.entryEndpoint,
+                requestId: normalized.id,
+                stageRecorder
+            });
+            processedRequest = processResult.processedRequest;
+            // Surface request-side clock reservation into pipeline metadata so response conversion
+            // can commit delivery only after a successful response is produced.
+            try {
+                const reservation = processedRequest?.metadata?.__clockReservation;
+                if (reservation && typeof reservation === 'object') {
+                    metaBase.__clockReservation = reservation;
+                }
+            }
+            catch {
+                // best-effort
+            }
+            if (processResult.nodeResult) {
+                nodeResults.push(this.convertProcessNodeResult('chat_process.req.stage4.tool_governance', processResult.nodeResult));
+            }
+        }
+        let workingRequest = processedRequest ?? standardizedRequest;
+        // Token estimate for stats/diagnostics (best-effort).
+        try {
+            const estimatedTokens = computeRequestTokens(workingRequest, '');
+            if (typeof estimatedTokens === 'number' && Number.isFinite(estimatedTokens) && estimatedTokens > 0) {
+                normalized.metadata = normalized.metadata || {};
+                normalized.metadata.estimatedInputTokens = estimatedTokens;
+            }
+        }
+        catch {
+            // ignore
+        }
+        const normalizedMeta = normalized.metadata;
+        // responsesResume is a client-protocol semantic (/v1/responses tool loop) and must live in chat.semantics.
+        // Do not read it from metadata once entering chat_process.
+        const responsesResume = (() => {
+            try {
+                const semantics = workingRequest?.semantics;
+                const node = semantics && typeof semantics === 'object' && !Array.isArray(semantics) ? semantics.responses : undefined;
+                const resume = node && typeof node === 'object' && !Array.isArray(node) ? node.resume : undefined;
+                return resume && typeof resume === 'object' && !Array.isArray(resume) ? resume : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        const stdMetadata = workingRequest?.metadata;
+        const hasImageAttachment = (stdMetadata?.hasImageAttachment === true || stdMetadata?.hasImageAttachment === 'true') ||
+            (normalizedMeta?.hasImageAttachment === true || normalizedMeta?.hasImageAttachment === 'true');
+        const serverToolRequired = stdMetadata?.webSearchEnabled === true ||
+            stdMetadata?.serverToolRequired === true;
+        const sessionIdentifiers = extractSessionIdentifiersFromMetadata(normalized.metadata);
+        if (sessionIdentifiers.sessionId && normalized.metadata && typeof normalized.metadata === 'object') {
+            normalized.metadata.sessionId = sessionIdentifiers.sessionId;
+        }
+        if (sessionIdentifiers.conversationId && normalized.metadata && typeof normalized.metadata === 'object') {
+            normalized.metadata.conversationId = sessionIdentifiers.conversationId;
+        }
+        const disableStickyRoutes = readRuntimeMetadata(normalized.metadata)?.disableStickyRoutes === true;
+        const metadataInput = {
+            requestId: normalized.id,
+            entryEndpoint: normalized.entryEndpoint,
+            processMode: normalized.processMode,
+            stream: normalized.stream,
+            direction: normalized.direction,
+            providerProtocol: normalized.providerProtocol,
+            routeHint: normalized.routeHint,
+            stage: normalized.stage,
+            responsesResume: responsesResume,
+            ...(disableStickyRoutes ? { disableStickyRoutes: true } : {}),
+            ...(serverToolRequired ? { serverToolRequired: true } : {}),
+            ...(sessionIdentifiers.sessionId ? { sessionId: sessionIdentifiers.sessionId } : {}),
+            ...(sessionIdentifiers.conversationId ? { conversationId: sessionIdentifiers.conversationId } : {})
+        };
+        const routing = runReqProcessStage2RouteSelect({
             routerEngine: this.routerEngine,
-            normalized,
-            hooks,
-            resolveProtocolHooks
+            request: workingRequest,
+            metadataInput,
+            normalizedMetadata: normalized.metadata,
+            stageRecorder
         });
+        const stopMessageState = this.routerEngine.getStopMessageState(metadataInput);
+        if (stopMessageState && normalized.metadata && typeof normalized.metadata === 'object') {
+            const rt = ensureRuntimeMetadata(normalized.metadata);
+            rt.stopMessageState = stopMessageState;
+        }
+        // Emit virtual router hit log for debugging (same as inbound path).
+        try {
+            const routeName = routing.decision?.routeName;
+            const providerKey = routing.target?.providerKey;
+            const modelId = workingRequest.model;
+            const logger = (normalized.metadata && normalized.metadata.logger);
+            if (logger && typeof logger.logVirtualRouterHit === 'function' && routeName && providerKey) {
+                logger.logVirtualRouterHit(routeName, providerKey, typeof modelId === 'string' ? modelId : undefined);
+            }
+        }
+        catch {
+            // ignore
+        }
+        const outboundStream = this.resolveOutboundStreamIntent(routing.target?.streaming);
+        workingRequest = this.applyOutboundStreamPreference(workingRequest, outboundStream);
+        const outboundAdapterContext = this.buildAdapterContext(normalized, routing.target);
+        if (routing.target?.compatibilityProfile) {
+            outboundAdapterContext.compatibilityProfile = routing.target.compatibilityProfile;
+        }
+        const outboundProtocol = outboundAdapterContext.providerProtocol;
+        const protocolSwitch = outboundProtocol !== normalized.providerProtocol;
+        const outboundHooks = protocolSwitch ? this.resolveProtocolHooks(outboundProtocol) : hooks;
+        if (!outboundHooks) {
+            throw new Error(`[HubPipeline] Unsupported provider protocol for hub pipeline: ${outboundProtocol}`);
+        }
+        const outboundSemanticMapper = protocolSwitch ? outboundHooks.createSemanticMapper() : hooks.createSemanticMapper();
+        const outboundFormatAdapter = protocolSwitch ? outboundHooks.createFormatAdapter() : hooks.createFormatAdapter();
+        const outboundContextMetadataKey = protocolSwitch ? outboundHooks.contextMetadataKey : hooks.contextMetadataKey;
+        const outboundContextSnapshot = undefined;
+        const outboundRecorder = this.maybeCreateStageRecorder(outboundAdapterContext, normalized.entryEndpoint, {
+            disableSnapshots: normalized.disableSnapshots === true
+        });
+        const outboundStart = Date.now();
+        let providerPayload;
+        const outboundStage1 = await runReqOutboundStage1SemanticMap({
+            request: workingRequest,
+            adapterContext: outboundAdapterContext,
+            semanticMapper: outboundSemanticMapper,
+            contextSnapshot: outboundContextSnapshot,
+            contextMetadataKey: outboundContextMetadataKey,
+            stageRecorder: outboundRecorder
+        });
+        let formattedPayload = await runReqOutboundStage2FormatBuild({
+            formatEnvelope: outboundStage1.formatEnvelope,
+            adapterContext: outboundAdapterContext,
+            formatAdapter: outboundFormatAdapter,
+            stageRecorder: outboundRecorder
+        });
+        formattedPayload = await runReqOutboundStage3Compat({
+            payload: formattedPayload,
+            adapterContext: outboundAdapterContext,
+            stageRecorder: outboundRecorder
+        });
+        // Phase 0/1: observe + enforce provider outbound policy and tool surface (same as inbound path).
+        const effectivePolicy = normalized.policyOverride ?? this.config.policy;
+        recordHubPolicyObservation({
+            policy: effectivePolicy,
+            providerProtocol: outboundProtocol,
+            payload: formattedPayload,
+            stageRecorder: outboundRecorder,
+            requestId: normalized.id
+        });
+        providerPayload = applyHubProviderOutboundPolicy({
+            policy: effectivePolicy,
+            providerProtocol: outboundProtocol,
+            payload: formattedPayload,
+            stageRecorder: outboundRecorder,
+            requestId: normalized.id
+        });
+        providerPayload = applyProviderOutboundToolSurface({
+            config: this.config.toolSurface,
+            providerProtocol: outboundProtocol,
+            payload: providerPayload,
+            stageRecorder: outboundRecorder,
+            requestId: normalized.id
+        });
+        recordHubPolicyObservation({
+            policy: effectivePolicy,
+            providerProtocol: outboundProtocol,
+            payload: providerPayload,
+            stageRecorder: outboundRecorder,
+            requestId: normalized.id
+        });
+        const outboundEnd = Date.now();
+        nodeResults.push({
+            id: 'req_outbound',
+            success: true,
+            metadata: {
+                node: 'req_outbound',
+                executionTime: outboundEnd - outboundStart,
+                startTime: outboundStart,
+                endTime: outboundEnd,
+                dataProcessed: {
+                    messages: workingRequest.messages.length,
+                    tools: workingRequest.tools?.length ?? 0
+                }
+            }
+        });
+        const capturedChatRequest = {
+            model: workingRequest.model,
+            messages: jsonClone(workingRequest.messages),
+            tools: workingRequest.tools ? jsonClone(workingRequest.tools) : workingRequest.tools,
+            parameters: workingRequest.parameters ? jsonClone(workingRequest.parameters) : workingRequest.parameters
+        };
+        const metadata = {
+            ...normalized.metadata,
+            ...(hasImageAttachment ? { hasImageAttachment: true } : {}),
+            capturedChatRequest,
+            entryEndpoint: normalized.entryEndpoint,
+            providerProtocol: outboundProtocol,
+            stream: normalized.stream,
+            processMode: normalized.processMode,
+            routeHint: normalized.routeHint,
+            target: routing.target,
+            ...(typeof outboundStream === 'boolean' ? { providerStream: outboundStream } : {})
+        };
+        return {
+            requestId: normalized.id,
+            providerPayload,
+            standardizedRequest,
+            processedRequest,
+            routingDecision: routing.decision,
+            routingDiagnostics: routing.diagnostics,
+            target: routing.target,
+            metadata,
+            nodeResults
+        };
+    }
+    async execute(request) {
+        const normalized = await this.normalizeRequest(request);
+        if (normalized.direction === 'request' && normalized.hubEntryMode === 'chat_process') {
+            return await this.executeChatProcessEntryPipeline(normalized);
+        }
+        const hooks = this.resolveProtocolHooks(normalized.providerProtocol);
+        if (!hooks) {
+            throw new Error(`Unsupported provider protocol for hub pipeline: ${normalized.providerProtocol}`);
+        }
+        return await this.executeRequestStagePipeline(normalized, hooks);
+    }
+    captureAnthropicAliasMap(normalized, adapterContext, chatEnvelope) {
+        if (!this.shouldCaptureAnthropicAlias(normalized.entryEndpoint)) {
+            return;
+        }
+        const aliasMap = this.resolveAliasMapFromSources(adapterContext, chatEnvelope);
+        if (!aliasMap) {
+            return;
+        }
+        // A1: tool name alias map is mappable semantics and must live in chat.semantics (never metadata).
+        try {
+            if (!chatEnvelope.semantics || typeof chatEnvelope.semantics !== 'object' || Array.isArray(chatEnvelope.semantics)) {
+                chatEnvelope.semantics = {};
+            }
+            const semantics = chatEnvelope.semantics;
+            if (!semantics.tools || !isJsonObject(semantics.tools)) {
+                semantics.tools = {};
+            }
+            const toolsNode = semantics.tools;
+            if (!isJsonObject(toolsNode.toolNameAliasMap) && !isJsonObject(toolsNode.toolAliasMap)) {
+                toolsNode.toolNameAliasMap = jsonClone(aliasMap);
+            }
+        }
+        catch {
+            // best-effort: never block request handling due to alias map propagation failures
+        }
+    }
+    shouldCaptureAnthropicAlias(endpoint) {
+        return typeof endpoint === 'string' && endpoint.toLowerCase().includes('/v1/messages');
+    }
+    resolveAliasMapFromSources(adapterContext, chatEnvelope) {
+        const fromContext = coerceAliasMap(adapterContext.anthropicToolNameMap);
+        if (fromContext) {
+            return fromContext;
+        }
+        const metadataNode = chatEnvelope.metadata;
+        const direct = metadataNode ? coerceAliasMap(metadataNode.anthropicToolNameMap) : undefined;
+        if (direct) {
+            return direct;
+        }
+        const contextNode = metadataNode && metadataNode.context && typeof metadataNode.context === 'object'
+            ? metadataNode.context
+            : undefined;
+        const fromContextNode = coerceAliasMap(contextNode?.anthropicToolNameMap);
+        if (fromContextNode) {
+            return fromContextNode;
+        }
+        return readAliasMapFromSemantics(chatEnvelope);
+    }
+    resolveProtocolHooks(protocol) {
+        switch (protocol) {
+            case 'openai-chat':
+                return {
+                    createFormatAdapter: () => new ChatFormatAdapter(),
+                    createSemanticMapper: () => new ChatSemanticMapper(),
+                    captureContext: (options) => runChatContextCapture(options),
+                    contextMetadataKey: 'chatContext'
+                };
+            case 'openai-responses':
+                return {
+                    createFormatAdapter: () => new ResponsesFormatAdapter(),
+                    createSemanticMapper: () => new ResponsesSemanticMapper(),
+                    captureContext: createResponsesContextCapture(captureResponsesContextSnapshot),
+                    contextMetadataKey: 'responsesContext'
+                };
+            case 'anthropic-messages':
+                return {
+                    createFormatAdapter: () => new AnthropicFormatAdapter(),
+                    createSemanticMapper: () => new AnthropicSemanticMapper(),
+                    captureContext: (options) => runChatContextCapture(options),
+                    contextMetadataKey: 'anthropicContext'
+                };
+            case 'gemini-chat':
+                return {
+                    createFormatAdapter: () => new GeminiFormatAdapter(),
+                    createSemanticMapper: () => new GeminiSemanticMapper(),
+                    captureContext: createNoopContextCapture('gemini-chat')
+                };
+            default:
+                return undefined;
+        }
+    }
+    buildAdapterContext(normalized, target) {
+        const metadata = normalized.metadata || {};
+        const providerProtocol = target?.outboundProfile || normalized.providerProtocol;
+        const providerId = (target?.providerKey || metadata.providerKey);
+        const routeId = metadata.routeName;
+        const profileId = (target?.providerKey || metadata.pipelineId);
+        const compatibilityProfile = typeof target?.compatibilityProfile === 'string' && target.compatibilityProfile.trim()
+            ? target.compatibilityProfile.trim()
+            : typeof metadata.compatibilityProfile === 'string'
+                ? String(metadata.compatibilityProfile).trim()
+                : undefined;
+        const streamingHint = normalized.stream === true ? 'force' : normalized.stream === false ? 'disable' : 'auto';
+        const toolCallIdStyle = normalizeToolCallIdStyleCandidate(metadata.toolCallIdStyle);
+        const adapterContext = {
+            requestId: normalized.id,
+            entryEndpoint: normalized.entryEndpoint || '/v1/chat/completions',
+            providerProtocol,
+            providerId,
+            routeId,
+            profileId,
+            streamingHint,
+            toolCallIdStyle,
+            ...(compatibilityProfile ? { compatibilityProfile } : {})
+        };
+        const runtime = metadata.runtime;
+        if (runtime && typeof runtime === 'object' && !Array.isArray(runtime)) {
+            adapterContext.runtime = jsonClone(runtime);
+        }
+        const clientRequestId = typeof metadata.clientRequestId === 'string'
+            ? metadata.clientRequestId.trim()
+            : '';
+        if (clientRequestId) {
+            adapterContext.clientRequestId = clientRequestId;
+        }
+        const groupRequestId = typeof metadata.groupRequestId === 'string'
+            ? metadata.groupRequestId.trim()
+            : '';
+        if (groupRequestId) {
+            adapterContext.groupRequestId = groupRequestId;
+        }
+        if (typeof metadata.originalModelId === 'string') {
+            adapterContext.originalModelId = metadata.originalModelId;
+        }
+        if (typeof metadata.clientModelId === 'string') {
+            adapterContext.clientModelId = metadata.clientModelId;
+        }
+        if (typeof metadata.assignedModelId === 'string') {
+            adapterContext.modelId = metadata.assignedModelId;
+        }
+        const rt = cloneRuntimeMetadata(metadata);
+        if (rt) {
+            adapterContext.__rt = rt;
+        }
+        const sessionId = typeof metadata.sessionId === 'string'
+            ? metadata.sessionId.trim()
+            : '';
+        if (sessionId) {
+            adapterContext.sessionId = sessionId;
+        }
+        const conversationId = typeof metadata.conversationId === 'string'
+            ? metadata.conversationId.trim()
+            : '';
+        if (conversationId) {
+            adapterContext.conversationId = conversationId;
+        }
+        const clientConnectionState = metadata.clientConnectionState;
+        if (clientConnectionState && typeof clientConnectionState === 'object' && !Array.isArray(clientConnectionState)) {
+            const stateRecord = clientConnectionState;
+            adapterContext.clientConnectionState = clientConnectionState;
+            if (typeof stateRecord.disconnected === 'boolean') {
+                adapterContext.clientDisconnected = stateRecord.disconnected;
+            }
+        }
+        const clientDisconnectedRaw = metadata.clientDisconnected;
+        if (clientDisconnectedRaw === true ||
+            (typeof clientDisconnectedRaw === 'string' && clientDisconnectedRaw.trim().toLowerCase() === 'true')) {
+            adapterContext.clientDisconnected = true;
+        }
+        if (target?.compatibilityProfile && typeof target.compatibilityProfile === 'string') {
+            adapterContext.compatibilityProfile = target.compatibilityProfile;
+        }
+        return adapterContext;
+    }
+    maybeCreateStageRecorder(context, endpoint, options) {
+        if (options?.disableSnapshots === true) {
+            return undefined;
+        }
+        if (!shouldRecordSnapshots()) {
+            return undefined;
+        }
+        const effectiveEndpoint = endpoint || context.entryEndpoint || '/v1/chat/completions';
+        try {
+            return createSnapshotRecorder(context, effectiveEndpoint);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    asJsonObject(value) {
+        if (!value || typeof value !== 'object') {
+            throw new Error('Responses pipeline requires JSON object payload');
+        }
+        return value;
+    }
+    async normalizeRequest(request) {
+        if (!request || typeof request !== 'object') {
+            throw new Error('HubPipeline requires request payload');
+        }
+        const id = request.id || `req_${Date.now()}`;
+        const endpoint = normalizeEndpoint(request.endpoint);
+        const metadataRecord = {
+            ...(request.metadata ?? {})
+        };
+        const policyOverride = extractHubPolicyOverride(metadataRecord);
+        if (Object.prototype.hasOwnProperty.call(metadataRecord, '__hubPolicyOverride')) {
+            delete metadataRecord.__hubPolicyOverride;
+        }
+        const shadowCompare = extractHubShadowCompareConfig(metadataRecord);
+        if (Object.prototype.hasOwnProperty.call(metadataRecord, '__hubShadowCompare')) {
+            delete metadataRecord.__hubShadowCompare;
+        }
+        const disableSnapshots = metadataRecord.__disableHubSnapshots === true;
+        if (Object.prototype.hasOwnProperty.call(metadataRecord, '__disableHubSnapshots')) {
+            delete metadataRecord.__disableHubSnapshots;
+        }
+        const hubEntryRaw = typeof metadataRecord.__hubEntry === 'string'
+            ? String(metadataRecord.__hubEntry).trim().toLowerCase()
+            : '';
+        const hubEntryMode = hubEntryRaw === 'chat_process' || hubEntryRaw === 'chat-process' || hubEntryRaw === 'chatprocess'
+            ? 'chat_process'
+            : undefined;
+        if (Object.prototype.hasOwnProperty.call(metadataRecord, '__hubEntry')) {
+            delete metadataRecord.__hubEntry;
+        }
+        const entryEndpoint = typeof metadataRecord.entryEndpoint === 'string'
+            ? normalizeEndpoint(metadataRecord.entryEndpoint)
+            : endpoint;
+        const providerProtocol = resolveProviderProtocol(metadataRecord.providerProtocol);
+        const processMode = metadataRecord.processMode === 'passthrough' ? 'passthrough' : 'chat';
+        const direction = metadataRecord.direction === 'response' ? 'response' : 'request';
+        const stage = metadataRecord.stage === 'outbound' ? 'outbound' : 'inbound';
+        const resolvedReadable = this.unwrapReadable(request.payload);
+        const stream = Boolean(metadataRecord.stream ||
+            resolvedReadable ||
+            (request.payload && typeof request.payload === 'object' && request.payload.stream));
+        const payload = await this.materializePayload(request.payload, {
+            requestId: id,
+            entryEndpoint,
+            providerProtocol,
+            metadata: metadataRecord
+        }, resolvedReadable);
+        const normalizedMetadata = {
+            ...metadataRecord,
+            entryEndpoint,
+            providerProtocol,
+            processMode,
+            direction,
+            stage,
+            stream
+        };
+        const routeHint = typeof metadataRecord.routeHint === 'string' ? metadataRecord.routeHint : undefined;
+        if (routeHint) {
+            normalizedMetadata.routeHint = routeHint;
+        }
+        return {
+            id,
+            endpoint,
+            entryEndpoint,
+            providerProtocol,
+            payload,
+            metadata: normalizedMetadata,
+            policyOverride: policyOverride ?? undefined,
+            shadowCompare: shadowCompare ?? undefined,
+            disableSnapshots,
+            processMode,
+            direction,
+            stage,
+            stream,
+            routeHint,
+            ...(hubEntryMode ? { hubEntryMode } : {})
+        };
+    }
+    convertProcessNodeResult(id, result) {
+        return {
+            id,
+            success: result.success,
+            metadata: result.metadata,
+            error: result.error
+                ? {
+                    code: result.error.code ?? 'hub_chat_process_error',
+                    message: result.error.message,
+                    details: result.error.details
+                }
+                : undefined
+        };
+    }
+    async materializePayload(payload, context, resolvedStream) {
+        const stream = resolvedStream ?? this.unwrapReadable(payload);
+        if (stream) {
+            return await this.convertSsePayload(stream, context);
+        }
+        if (!payload || typeof payload !== 'object') {
+            throw new Error('HubPipeline requires JSON object payload');
+        }
+        return payload;
+    }
+    unwrapReadable(payload) {
+        if (!payload) {
+            return null;
+        }
+        if (payload instanceof Readable) {
+            return payload;
+        }
+        if (payload && typeof payload === 'object' && 'readable' in payload) {
+            const candidate = payload.readable;
+            if (candidate instanceof Readable) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+    async convertSsePayload(stream, context) {
+        const protocol = this.resolveSseProtocol(context);
+        const codec = defaultSseCodecRegistry.get(protocol);
+        try {
+            const result = await codec.convertSseToJson(stream, {
+                requestId: context.requestId,
+                model: this.extractModelHint(context.metadata),
+                direction: 'request'
+            });
+            if (!result || typeof result !== 'object') {
+                throw new Error('SSE conversion returned empty payload');
+            }
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error ?? 'Unknown error');
+            throw new Error(`Failed to convert SSE payload for protocol ${protocol}: ${message}`);
+        }
+    }
+    resolveSseProtocol(context) {
+        const explicitProtocol = resolveSseProtocolFromMetadata(context.metadata);
+        if (explicitProtocol) {
+            return explicitProtocol;
+        }
+        return context.providerProtocol;
+    }
+    extractModelHint(metadata) {
+        if (typeof metadata.model === 'string' && metadata.model.trim()) {
+            return metadata.model;
+        }
+        const provider = metadata.provider;
+        const candidates = [
+            provider?.model,
+            provider?.modelId,
+            provider?.defaultModel
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === 'string' && candidate.trim()) {
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+    resolveOutboundStreamIntent(providerPreference) {
+        if (providerPreference === 'always') {
+            return true;
+        }
+        if (providerPreference === 'never') {
+            return false;
+        }
+        return undefined;
+    }
+    applyOutboundStreamPreference(request, stream) {
+        if (!request || typeof request !== 'object') {
+            return request;
+        }
+        const ops = [];
+        if (typeof stream === 'boolean') {
+            ops.push({ op: 'set_request_parameter_fields', fields: { stream } });
+            ops.push({ op: 'set_request_metadata_fields', fields: { outboundStream: stream } });
+        }
+        else {
+            ops.push({ op: 'unset_request_parameter_keys', keys: ['stream'] });
+            ops.push({ op: 'unset_request_metadata_keys', keys: ['outboundStream'] });
+        }
+        return applyHubOperations(request, ops);
+    }
+}
+function normalizeToolCallIdStyleCandidate(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'fc') {
+        return 'fc';
+    }
+    if (normalized === 'preserve') {
+        return 'preserve';
+    }
+    return undefined;
+}
+function normalizeEndpoint(endpoint) {
+    if (!endpoint)
+        return '/v1/chat/completions';
+    const trimmed = endpoint.trim();
+    if (!trimmed)
+        return '/v1/chat/completions';
+    const normalized = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return normalized.replace(/\/{2,}/g, '/');
+}
+function resolveProviderProtocol(value) {
+    if (typeof value !== 'string' || !value.trim()) {
+        return 'openai-chat';
+    }
+    const normalized = value.trim().toLowerCase();
+    const mapped = PROVIDER_PROTOCOL_ALIASES[normalized];
+    if (mapped) {
+        return mapped;
+    }
+    throw new Error(`[HubPipeline] Unsupported providerProtocol "${value}". Configure a valid protocol (openai-chat|openai-responses|anthropic-messages|gemini-chat).`);
+}
+const PROVIDER_PROTOCOL_ALIASES = {
+    'openai-chat': 'openai-chat',
+    openai: 'openai-chat',
+    chat: 'openai-chat',
+    'responses': 'openai-responses',
+    'openai-responses': 'openai-responses',
+    'anthropic': 'anthropic-messages',
+    'anthropic-messages': 'anthropic-messages',
+    'messages': 'anthropic-messages',
+    'gemini': 'gemini-chat',
+    'google-gemini': 'gemini-chat',
+    'gemini-chat': 'gemini-chat'
+};
+function resolveEndpointForProviderProtocol(protocol) {
+    if (!protocol) {
+        return undefined;
+    }
+    const value = protocol.toLowerCase();
+    if (value === 'openai-responses')
+        return '/v1/responses';
+    if (value === 'openai-chat')
+        return '/v1/chat/completions';
+    if (value === 'anthropic-messages' || value === 'anthropic')
+        return '/v1/messages';
+    if (value === 'gemini-chat' || value === 'gemini' || value === 'google-gemini')
+        return '/v1/responses';
+    return undefined;
+}
+function resolveSseProtocolFromMetadata(metadata) {
+    const candidate = metadata.sseProtocol ?? metadata.clientSseProtocol ?? metadata.routeSseProtocol;
+    if (typeof candidate !== 'string' || !candidate.trim()) {
+        return undefined;
+    }
+    return resolveProviderProtocol(candidate);
+}
+function coerceAliasMap(candidate) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+        return undefined;
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(candidate)) {
+        if (typeof key !== 'string' || typeof value !== 'string') {
+            continue;
+        }
+        const trimmedKey = key.trim();
+        const trimmedValue = value.trim();
+        if (!trimmedKey.length || !trimmedValue.length) {
+            continue;
+        }
+        normalized[trimmedKey] = trimmedValue;
+    }
+    return Object.keys(normalized).length ? normalized : undefined;
+}
+function readAliasMapFromSemantics(chatEnvelope) {
+    if (!chatEnvelope?.semantics || typeof chatEnvelope.semantics !== 'object') {
+        return undefined;
+    }
+    const node = chatEnvelope.semantics.tools;
+    if (!node || !isJsonObject(node)) {
+        return undefined;
+    }
+    const candidate = node.toolNameAliasMap ??
+        node.toolAliasMap;
+    return coerceAliasMap(candidate);
+}
+function assertNoMappableSemanticsInMetadata(metadata, scope) {
+    if (!metadata || typeof metadata !== 'object') {
+        return;
+    }
+    const banned = [
+        'responsesResume',
+        'responses_resume',
+        'clientToolsRaw',
+        'client_tools_raw',
+        'anthropicToolNameMap',
+        'anthropic_tool_name_map',
+        // Responses semantics must be stored in chat.semantics.responses.context, not metadata.
+        'responsesContext',
+        'responses_context',
+        'responseFormat',
+        'response_format',
+        // OpenAI Chat legacy semantics must be stored in chat.semantics (system/tools/providerExtras), not metadata.
+        'systemInstructions',
+        'system_instructions',
+        'toolsFieldPresent',
+        'tools_field_present',
+        'extraFields',
+        'extra_fields'
+    ];
+    const present = banned.filter((k) => Object.prototype.hasOwnProperty.call(metadata, k));
+    if (present.length) {
+        throw new Error(`[HubPipeline][semantic_gate] Mappable semantics must not be stored in metadata (${scope}): ${present.join(', ')}`);
     }
 }