@jsonstudio/llms 0.6.1172 → 0.6.1397

package/dist/conversion/hub/pipeline/hub-pipeline/execute-request-stage.js

@@ -0,0 +1,390 @@
+import { jsonClone } from '../../types/json.js';
+import { ensureRuntimeMetadata, readRuntimeMetadata } from '../../../shared/runtime-metadata.js';
+import { computeRequestTokens } from '../../../../router/virtual-router/token-estimator.js';
+import { isCompactionRequest } from '../../../shared/compaction-detect.js';
+import { recordHubPolicyObservation, applyHubProviderOutboundPolicy } from '../../policy/policy-engine.js';
+import { applyProviderOutboundToolSurface } from '../../tool-surface/tool-surface-engine.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 { 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 { runReqOutboundStage2ThoughtSignatureInject } from '../stages/req_outbound/req_outbound_stage2_thought_signature_inject/index.js';
+import { runReqOutboundStage3Compat } from '../stages/req_outbound/req_outbound_stage3_compat/index.js';
+import { extractSessionIdentifiersFromMetadata } from '../session-identifiers.js';
+import { buildAdapterContext, maybeCreateStageRecorder, resolveOutboundStreamIntent, applyOutboundStreamPreference } from './adapter-context.js';
+import { resolveClientProtocolFromEntryEndpoint } from './protocol.js';
+import { assertNoMappableSemanticsInMetadata } from './semantic-gate.js';
+import { convertProcessNodeResult } from './node-results.js';
+import { resolveApplyPatchToolModeFromEnv, resolveApplyPatchToolModeFromTools } from './apply-patch-tool-mode.js';
+import { injectServerToolRuntimeConfig } from './servertool-runtime-config.js';
+function asJsonObject(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Responses pipeline requires JSON object payload');
+    }
+    return value;
+}
+function readResponsesResumeFromSemantics(request) {
+    try {
+        const semantics = request?.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;
+    }
+}
+export async function executeRequestStagePipeline(options) {
+    const { config, routerEngine, normalized, hooks } = options;
+    const formatAdapter = hooks.createFormatAdapter();
+    const semanticMapper = hooks.createSemanticMapper();
+    const rawRequest = 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 ?? config.policy;
+    const shadowCompareBaselineMode = normalized.shadowCompare?.baselineMode;
+    const inboundAdapterContext = buildAdapterContext(normalized);
+    const inboundRecorder = maybeCreateStageRecorder(inboundAdapterContext, normalized.entryEndpoint, {
+        disableSnapshots: normalized.disableSnapshots === true
+    });
+    const inboundStart = Date.now();
+    recordHubPolicyObservation({
+        policy: effectivePolicy,
+        providerProtocol: resolveClientProtocolFromEntryEndpoint(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
+    });
+    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
+            }
+        }
+    });
+    const metaBase = {
+        ...(normalized.metadata ?? {})
+    };
+    injectServerToolRuntimeConfig(config, metaBase);
+    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;
+        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(convertProcessNodeResult('chat_process.req.stage4.tool_governance', processResult.nodeResult));
+        }
+    }
+    let workingRequest = processedRequest ?? standardizedRequest;
+    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;
+    const responsesResume = readResponsesResumeFromSemantics(workingRequest);
+    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 shadowCompareForcedProviderKey = normalizedMeta && typeof normalizedMeta.__shadowCompareForcedProviderKey === 'string'
+        ? String(normalizedMeta.__shadowCompareForcedProviderKey)
+        : '';
+    const disabledProviderKeyAliases = normalizedMeta && Array.isArray(normalizedMeta.disabledProviderKeyAliases)
+        ? normalizedMeta.disabledProviderKeyAliases
+        : null;
+    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 } : {}),
+        ...(shadowCompareForcedProviderKey.trim().length
+            ? { __shadowCompareForcedProviderKey: shadowCompareForcedProviderKey.trim() }
+            : {}),
+        ...(disabledProviderKeyAliases && disabledProviderKeyAliases.length
+            ? { disabledProviderKeyAliases: disabledProviderKeyAliases }
+            : {})
+    };
+    const routing = runReqProcessStage2RouteSelect({
+        routerEngine,
+        request: workingRequest,
+        metadataInput,
+        normalizedMetadata: normalized.metadata,
+        stageRecorder: inboundRecorder
+    });
+    const stopMessageState = routerEngine.getStopMessageState(metadataInput);
+    if (stopMessageState && normalized.metadata && typeof normalized.metadata === 'object') {
+        const rt = ensureRuntimeMetadata(normalized.metadata);
+        rt.stopMessageState = stopMessageState;
+    }
+    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 = resolveOutboundStreamIntent(routing.target?.streaming);
+    workingRequest = applyOutboundStreamPreference(workingRequest, outboundStream);
+    const outboundAdapterContext = 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 ? options.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;
+    const outboundRecorder = maybeCreateStageRecorder(outboundAdapterContext, normalized.entryEndpoint, {
+        disableSnapshots: normalized.disableSnapshots === true
+    });
+    const outboundStart = Date.now();
+    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 runReqOutboundStage2ThoughtSignatureInject({
+        payload: formattedPayload,
+        adapterContext: outboundAdapterContext,
+        stageRecorder: outboundRecorder
+    });
+    formattedPayload = await runReqOutboundStage3Compat({
+        payload: formattedPayload,
+        adapterContext: outboundAdapterContext,
+        stageRecorder: outboundRecorder
+    });
+    let shadowBaselineProviderPayload;
+    if (shadowCompareBaselineMode) {
+        const baselinePolicy = {
+            ...(effectivePolicy ?? {}),
+            mode: shadowCompareBaselineMode
+        };
+        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: config.toolSurface,
+            providerProtocol: outboundProtocol,
+            payload: baselinePayload,
+            stageRecorder: undefined,
+            requestId: normalized.id
+        });
+        shadowBaselineProviderPayload = baselinePayload;
+    }
+    recordHubPolicyObservation({
+        policy: effectivePolicy,
+        providerProtocol: outboundProtocol,
+        payload: formattedPayload,
+        stageRecorder: outboundRecorder,
+        requestId: normalized.id
+    });
+    let providerPayload = applyHubProviderOutboundPolicy({
+        policy: effectivePolicy,
+        providerProtocol: outboundProtocol,
+        payload: formattedPayload,
+        stageRecorder: outboundRecorder,
+        requestId: normalized.id
+    });
+    providerPayload = applyProviderOutboundToolSurface({
+        config: 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 } : {}),
+        ...(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
+    };
+}

package/dist/conversion/hub/pipeline/hub-pipeline/node-results.d.ts

@@ -0,0 +1,3 @@
+import type { HubPipelineNodeResult } from './types.js';
+import type { HubProcessNodeResult } from '../../process/chat-process.js';
+export declare function convertProcessNodeResult(id: string, result: HubProcessNodeResult): HubPipelineNodeResult;

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

@@ -0,0 +1,14 @@
+export function 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
+    };
+}

package/dist/conversion/hub/pipeline/hub-pipeline/payload-normalize.d.ts

@@ -0,0 +1,2 @@
+import type { HubPipelineRequest, NormalizedRequest } from './types.js';
+export declare function normalizeHubPipelineRequest(request: HubPipelineRequest): Promise<NormalizedRequest>;

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

@@ -0,0 +1,144 @@
+import { Readable } from 'node:stream';
+import { defaultSseCodecRegistry } from '../../../../sse/index.js';
+import { extractHubPolicyOverride, extractHubShadowCompareConfig } from './policy.js';
+import { normalizeEndpoint, resolveProviderProtocol, resolveSseProtocolFromMetadata } from './protocol.js';
+function 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;
+}
+function resolveSseProtocol(context) {
+    const explicitProtocol = resolveSseProtocolFromMetadata(context.metadata);
+    if (explicitProtocol) {
+        return explicitProtocol;
+    }
+    return context.providerProtocol;
+}
+function 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;
+}
+async function convertSsePayload(stream, context) {
+    const protocol = resolveSseProtocol(context);
+    const codec = defaultSseCodecRegistry.get(protocol);
+    try {
+        const result = await codec.convertSseToJson(stream, {
+            requestId: context.requestId,
+            model: 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}`);
+    }
+}
+async function materializePayload(payload, context, resolvedStream) {
+    const stream = resolvedStream ?? unwrapReadable(payload);
+    if (stream) {
+        return await convertSsePayload(stream, context);
+    }
+    if (!payload || typeof payload !== 'object') {
+        throw new Error('HubPipeline requires JSON object payload');
+    }
+    return payload;
+}
+export async function normalizeHubPipelineRequest(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 = unwrapReadable(request.payload);
+    const stream = Boolean(metadataRecord.stream ||
+        resolvedReadable ||
+        (request.payload && typeof request.payload === 'object' && request.payload.stream));
+    const payload = await 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 } : {})
+    };
+}

package/dist/conversion/hub/pipeline/hub-pipeline/policy.d.ts

@@ -0,0 +1,4 @@
+import type { HubPolicyConfig } from '../../policy/policy-engine.js';
+import type { HubShadowCompareRequestConfig } from './types.js';
+export declare function extractHubPolicyOverride(metadata: Record<string, unknown> | undefined): HubPolicyConfig | undefined;
+export declare function extractHubShadowCompareConfig(metadata: Record<string, unknown> | undefined): HubShadowCompareRequestConfig | undefined;

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

@@ -0,0 +1,32 @@
+export 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 } : {})
+    };
+}
+export 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 };
+}

package/dist/conversion/hub/pipeline/hub-pipeline/protocol.d.ts

@@ -0,0 +1,8 @@
+import type { SseProtocol } from '../../../../sse/index.js';
+import type { ProviderProtocol } from './types.js';
+export declare function normalizeEndpoint(endpoint: string): string;
+export declare function resolveProviderProtocol(value: unknown): ProviderProtocol;
+export declare const PROVIDER_PROTOCOL_ALIASES: Record<string, ProviderProtocol>;
+export declare function resolveEndpointForProviderProtocol(protocol?: string): string | undefined;
+export declare function resolveSseProtocolFromMetadata(metadata: Record<string, unknown>): SseProtocol | undefined;
+export declare function resolveClientProtocolFromEntryEndpoint(entryEndpoint: string): ProviderProtocol;

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

@@ -0,0 +1,63 @@
+export 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, '/');
+}
+export 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).`);
+}
+export 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'
+};
+export 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;
+}
+export function resolveSseProtocolFromMetadata(metadata) {
+    const candidate = metadata.sseProtocol ?? metadata.clientSseProtocol ?? metadata.routeSseProtocol;
+    if (typeof candidate !== 'string' || !candidate.trim()) {
+        return undefined;
+    }
+    return resolveProviderProtocol(candidate);
+}
+export function resolveClientProtocolFromEntryEndpoint(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';
+}

package/dist/conversion/hub/pipeline/hub-pipeline/resolve-protocol-hooks.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderProtocol, RequestStageHooks } from './types.js';
+export declare function resolveProtocolHooks(protocol: ProviderProtocol): RequestStageHooks<Record<string, unknown>> | undefined;