@jsonstudio/llms 0.6.802 → 0.6.954

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

@@ -1,5 +1,5 @@
 import { Readable } from 'node:stream';
-import { isJsonObject } from '../types/json.js';
+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 { defaultSseCodecRegistry } from '../../../sse/index.js';
@@ -25,6 +25,23 @@ import { runReqOutboundStage3Compat } from './stages/req_outbound/req_outbound_s
 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';
+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 class HubPipeline {
     routerEngine;
     config;
@@ -37,6 +54,7 @@ export class HubPipeline {
             quotaView: config.quotaView
         });
         this.routerEngine.initialize(config.virtualRouter);
+        setHubPolicyRuntimePolicy(config.policy);
         try {
             this.unsubscribeProviderErrors = providerErrorCenter.subscribe((event) => {
                 try {
@@ -97,13 +115,38 @@ export class HubPipeline {
         const formatAdapter = hooks.createFormatAdapter();
         const semanticMapper = hooks.createSemanticMapper();
         const rawRequest = this.asJsonObject(normalized.payload);
+        // Preserve the client-provided raw tool definitions (schema included) for response-side validation
+        // and protocol-correct outbound tool-call formatting. This must reflect the inbound request shape,
+        // not the governed/augmented tools.
+        try {
+            const toolsRaw = Array.isArray(rawRequest?.tools) ? rawRequest.tools : null;
+            if (toolsRaw && toolsRaw.length > 0) {
+                normalized.metadata = normalized.metadata || {};
+                normalized.metadata.clientToolsRaw = jsonClone(toolsRaw);
+            }
+        }
+        catch {
+            // best-effort: do not block request handling due to tool snapshot failures
+        }
         if (isCompactionRequest(rawRequest)) {
             normalized.metadata = normalized.metadata || {};
             normalized.metadata.compactionRequest = true;
         }
+        const effectivePolicy = normalized.policyOverride ?? this.config.policy;
         const inboundAdapterContext = this.buildAdapterContext(normalized);
-        const inboundRecorder = this.maybeCreateStageRecorder(inboundAdapterContext, normalized.entryEndpoint);
+        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,
@@ -139,20 +182,26 @@ export class HubPipeline {
                 }
             }
         });
+        // 将 VirtualRouter 层的 servertool 相关配置注入到 metadata，保证响应侧
+        // servertool（第三跳 reenter）也能访问到相同配置，即使当前 route 标记为 passthrough。
+        const metaBase = {
+            ...(normalized.metadata ?? {})
+        };
+        const webSearchConfig = this.config.virtualRouter?.webSearch;
+        if (webSearchConfig) {
+            metaBase.webSearch = webSearchConfig;
+        }
+        const execCommandGuard = this.config.virtualRouter?.execCommandGuard;
+        if (execCommandGuard) {
+            metaBase.execCommandGuard = execCommandGuard;
+        }
+        normalized.metadata = metaBase;
         let processedRequest;
         if (normalized.processMode !== 'passthrough') {
-            const processMetadata = {
-                ...(normalized.metadata ?? {})
-            };
-            const webSearchConfig = this.config.virtualRouter?.webSearch;
-            if (webSearchConfig) {
-                processMetadata.webSearch = webSearchConfig;
-            }
-            normalized.metadata = processMetadata;
             const processResult = await runReqProcessStage1ToolGovernance({
                 request: standardizedRequest,
                 rawPayload: rawRequest,
-                metadata: processMetadata,
+                metadata: metaBase,
                 entryEndpoint: normalized.entryEndpoint,
                 requestId: normalized.id,
                 stageRecorder: inboundRecorder
@@ -251,7 +300,9 @@ export class HubPipeline {
         // 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);
+        const outboundRecorder = this.maybeCreateStageRecorder(outboundAdapterContext, normalized.entryEndpoint, {
+            disableSnapshots: normalized.disableSnapshots === true
+        });
         const outboundStart = Date.now();
         let providerPayload;
         const outboundStage1 = await runReqOutboundStage1SemanticMap({
@@ -273,7 +324,20 @@ export class HubPipeline {
             adapterContext: outboundAdapterContext,
             stageRecorder: outboundRecorder
         });
-        providerPayload = formattedPayload;
+        providerPayload = applyHubProviderOutboundPolicy({
+            policy: effectivePolicy,
+            providerProtocol: outboundProtocol,
+            payload: formattedPayload,
+            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',
@@ -305,11 +369,13 @@ export class HubPipeline {
         // 对于 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: Array.isArray(workingRequest.messages) ? [...workingRequest.messages] : workingRequest.messages,
-            tools: workingRequest.tools,
-            parameters: workingRequest.parameters
+            messages: jsonClone(workingRequest.messages),
+            tools: workingRequest.tools ? jsonClone(workingRequest.tools) : workingRequest.tools,
+            parameters: workingRequest.parameters ? jsonClone(workingRequest.parameters) : workingRequest.parameters
         };
         const metadata = {
             ...normalized.metadata,
@@ -335,6 +401,14 @@ export class HubPipeline {
             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';
+    }
     async execute(request) {
         const normalized = await this.normalizeRequest(request);
         const hooks = this.resolveProtocolHooks(normalized.providerProtocol);
@@ -429,6 +503,10 @@ export class HubPipeline {
             streamingHint,
             toolCallIdStyle
         };
+        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()
             : '';
@@ -457,6 +535,11 @@ export class HubPipeline {
             adapterContext.serverToolFollowup = metadata
                 .serverToolFollowup;
         }
+        // Preserve raw client tools (schemas) for response-side validation/formatting.
+        if (Object.prototype.hasOwnProperty.call(metadata, 'clientToolsRaw')) {
+            adapterContext.clientToolsRaw = metadata
+                .clientToolsRaw;
+        }
         const sessionId = typeof metadata.sessionId === 'string'
             ? metadata.sessionId.trim()
             : '';
@@ -512,7 +595,10 @@ export class HubPipeline {
         }
         return adapterContext;
     }
-    maybeCreateStageRecorder(context, endpoint) {
+    maybeCreateStageRecorder(context, endpoint, options) {
+        if (options?.disableSnapshots === true) {
+            return undefined;
+        }
         if (!shouldRecordSnapshots()) {
             return undefined;
         }
@@ -539,6 +625,14 @@ export class HubPipeline {
         const metadataRecord = {
             ...(request.metadata ?? {})
         };
+        const policyOverride = extractHubPolicyOverride(metadataRecord);
+        if (Object.prototype.hasOwnProperty.call(metadataRecord, '__hubPolicyOverride')) {
+            delete metadataRecord.__hubPolicyOverride;
+        }
+        const disableSnapshots = metadataRecord.__disableHubSnapshots === true;
+        if (Object.prototype.hasOwnProperty.call(metadataRecord, '__disableHubSnapshots')) {
+            delete metadataRecord.__disableHubSnapshots;
+        }
         const entryEndpoint = typeof metadataRecord.entryEndpoint === 'string'
             ? normalizeEndpoint(metadataRecord.entryEndpoint)
             : endpoint;
@@ -576,6 +670,8 @@ export class HubPipeline {
             providerProtocol,
             payload,
             metadata: normalizedMetadata,
+            policyOverride: policyOverride ?? undefined,
+            disableSnapshots,
             processMode,
             direction,
             stage,

package/dist/conversion/hub/pipeline/stages/req_inbound/req_inbound_stage3_context_capture/index.js

@@ -312,9 +312,6 @@ function buildApplyPatchDiagnostics(output) {
 }
 function appendDiagnosticsToRecord(record) {
     const name = typeof record.name === 'string' ? record.name.trim() : undefined;
-    if (name !== 'apply_patch') {
-        return;
-    }
     let text;
     if (typeof record.output === 'string') {
         text = record.output;
@@ -329,6 +326,12 @@ function appendDiagnosticsToRecord(record) {
     if (!diag) {
         return;
     }
+    // Some providers / compatibility layers omit `name` on tool outputs.
+    // When the output text matches apply_patch argument-parse failures, still inject the diagnostics
+    // to keep user-visible behavior stable across modes.
+    if (name && name !== 'apply_patch') {
+        return;
+    }
     const merged = `${text}${diag}`;
     if (typeof record.output === 'string') {
         record.output = merged;

package/dist/conversion/hub/pipeline/stages/req_process/req_process_stage1_tool_governance/index.js

@@ -1,5 +1,6 @@
 import { runHubChatProcess } from '../../../../process/chat-process.js';
 import { recordStage } from '../../../stages/utils.js';
+import { captureApplyPatchExecutionFailuresFromProcessedRequest } from '../../../../../../tools/apply-patch/execution-capturer.js';
 export async function runReqProcessStage1ToolGovernance(options) {
     const result = await runHubChatProcess({
         request: options.request,
@@ -10,6 +11,9 @@ export async function runReqProcessStage1ToolGovernance(options) {
     });
     if (result.processedRequest) {
         recordStage(options.stageRecorder, 'req_process_stage1_tool_governance', result.processedRequest);
+        // Best-effort: capture apply_patch execution failures reported by tool role messages.
+        // This is for errorsamples collection only and must not affect runtime behavior.
+        captureApplyPatchExecutionFailuresFromProcessedRequest(result.processedRequest);
     }
     return result;
 }

package/dist/conversion/hub/pipeline/stages/resp_outbound/resp_outbound_stage1_client_remap/index.js

@@ -12,8 +12,10 @@ export function runRespOutboundStage1ClientRemap(options) {
         });
     }
     else {
+        const toolsRaw = resolveClientToolsRawFromContext(options.adapterContext);
         clientPayload = buildResponsesPayloadFromChat(options.payload, {
-            requestId: options.requestId
+            requestId: options.requestId,
+            ...(toolsRaw ? { toolsRaw } : {})
         });
     }
     recordStage(options.stageRecorder, 'resp_outbound_stage1_client_remap', clientPayload);
@@ -41,3 +43,23 @@ function resolveAliasMapFromContext(adapterContext) {
     }
     return Object.keys(map).length ? map : undefined;
 }
+function resolveClientToolsRawFromContext(adapterContext) {
+    if (!adapterContext) {
+        return undefined;
+    }
+    const candidate = adapterContext.clientToolsRaw;
+    if (!candidate || !Array.isArray(candidate)) {
+        return undefined;
+    }
+    const filtered = [];
+    for (const entry of candidate) {
+        if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+            const type = entry.type;
+            if (typeof type !== 'string' || !type.trim()) {
+                continue;
+            }
+            filtered.push(entry);
+        }
+    }
+    return filtered.length ? filtered : undefined;
+}

package/dist/conversion/hub/pipelines/inbound.d.ts

@@ -0,0 +1,22 @@
+import type { ChatEnvelope, AdapterContext } from '../types/chat-envelope.js';
+import type { FormatAdapter, SemanticMapper, StageRecorder } from '../format-adapters/index.js';
+import type { JsonObject } from '../types/json.js';
+export type InboundStage = 'format_parse' | 'semantic_map_to_chat' | 'inbound_passthrough';
+export interface InboundPassthroughConfig {
+    mode: 'chat';
+    factory: (raw: JsonObject, ctx: AdapterContext) => Promise<ChatEnvelope> | ChatEnvelope;
+}
+export interface InboundPlan {
+    protocol?: string;
+    stages: InboundStage[];
+    formatAdapter?: Pick<FormatAdapter, 'parseRequest'>;
+    semanticMapper?: Pick<SemanticMapper, 'toChat'>;
+    passthrough?: InboundPassthroughConfig;
+}
+export interface InboundPipelineOptions {
+    rawRequest: JsonObject;
+    context: AdapterContext;
+    plan: InboundPlan;
+    stageRecorder?: StageRecorder;
+}
+export declare function runInboundPipeline(options: InboundPipelineOptions): Promise<ChatEnvelope>;

package/dist/conversion/hub/pipelines/outbound.d.ts

@@ -0,0 +1,22 @@
+import type { ChatEnvelope, AdapterContext } from '../types/chat-envelope.js';
+import type { FormatAdapter, SemanticMapper, StageRecorder } from '../format-adapters/index.js';
+import type { JsonObject } from '../types/json.js';
+export type OutboundStage = 'semantic_map_from_chat' | 'format_build' | 'outbound_passthrough';
+export interface OutboundPassthroughConfig {
+    mode: 'protocol';
+    factory: (chat: ChatEnvelope, ctx: AdapterContext) => Promise<JsonObject> | JsonObject;
+}
+export interface OutboundPlan {
+    protocol?: string;
+    stages: OutboundStage[];
+    formatAdapter?: Pick<FormatAdapter, 'buildResponse'>;
+    semanticMapper?: Pick<SemanticMapper, 'fromChat'>;
+    passthrough?: OutboundPassthroughConfig;
+}
+export interface OutboundPipelineOptions {
+    chat: ChatEnvelope;
+    context: AdapterContext;
+    plan: OutboundPlan;
+    stageRecorder?: StageRecorder;
+}
+export declare function runOutboundPipeline(options: OutboundPipelineOptions): Promise<JsonObject>;

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

@@ -0,0 +1,46 @@
+import type { JsonObject } from '../types/json.js';
+import type { StageRecorder } from '../format-adapters/index.js';
+export type HubPolicyMode = 'off' | 'observe' | 'enforce';
+export interface HubPolicyConfig {
+    mode?: HubPolicyMode;
+    /**
+     * Optional: sampling rate in [0, 1]. When provided, observation is best-effort
+     * and may skip recording for some requests.
+     */
+    sampleRate?: number;
+}
+export interface PolicyObservation {
+    phase: 'client_inbound' | 'provider_outbound' | 'provider_inbound' | 'client_outbound';
+    providerProtocol: string;
+    violations: Array<{
+        code: 'unexpected_wrapper' | 'unexpected_field';
+        path: string;
+        detail?: string;
+    }>;
+    summary: {
+        totalViolations: number;
+        unexpectedFieldCount: number;
+    };
+}
+export interface ProviderOutboundPolicyApplyResult {
+    payload: JsonObject;
+    changed: boolean;
+    removedTopLevelKeys: string[];
+    flattenedWrappers: string[];
+}
+export declare function setHubPolicyRuntimePolicy(policy?: HubPolicyConfig): void;
+export declare function recordHubPolicyObservation(options: {
+    policy?: HubPolicyConfig;
+    phase?: PolicyObservation['phase'];
+    providerProtocol: string;
+    payload: JsonObject;
+    stageRecorder?: StageRecorder;
+    requestId?: string;
+}): void;
+export declare function applyHubProviderOutboundPolicy(options: {
+    policy?: HubPolicyConfig;
+    providerProtocol: string;
+    payload: JsonObject;
+    stageRecorder?: StageRecorder;
+    requestId?: string;
+}): JsonObject;

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

@@ -0,0 +1,176 @@
+import { resolveHubProtocolSpec } from './protocol-spec.js';
+let hubPolicyRuntime = undefined;
+export function setHubPolicyRuntimePolicy(policy) {
+    hubPolicyRuntime = policy;
+}
+function resolveEffectivePolicy(policy) {
+    return policy ?? hubPolicyRuntime;
+}
+function shouldSample(rate) {
+    if (rate === undefined)
+        return true;
+    if (!Number.isFinite(rate))
+        return true;
+    if (rate <= 0)
+        return false;
+    if (rate >= 1)
+        return true;
+    return Math.random() < rate;
+}
+function isJsonRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function applyProviderOutboundPolicy(providerProtocol, payload) {
+    const removedTopLevelKeys = [];
+    const flattenedWrappers = [];
+    const spec = resolveHubProtocolSpec(providerProtocol);
+    if (!spec.providerOutbound.enforceEnabled) {
+        return {
+            payload,
+            changed: false,
+            removedTopLevelKeys,
+            flattenedWrappers
+        };
+    }
+    let out = payload;
+    const ensureOutClone = () => {
+        if (out === payload) {
+            out = { ...payload };
+        }
+    };
+    // Reserved/private keys must never be sent upstream.
+    for (const key of Object.keys(payload)) {
+        if (spec.providerOutbound.reservedKeyPrefixes.some((prefix) => key.startsWith(prefix))) {
+            ensureOutClone();
+            delete out[key];
+            removedTopLevelKeys.push(key);
+        }
+    }
+    // Flatten accidental wrappers that have caused upstream 400s.
+    for (const rule of spec.providerOutbound.flattenWrappers) {
+        const wrapperKey = rule.wrapperKey;
+        if (!wrapperKey || typeof wrapperKey !== 'string') {
+            continue;
+        }
+        if (!isJsonRecord(out[wrapperKey])) {
+            continue;
+        }
+        ensureOutClone();
+        const inner = { ...out[wrapperKey] };
+        const alias = rule.aliasKeys || {};
+        for (const [from, to] of Object.entries(alias)) {
+            if (inner[to] === undefined && inner[from] !== undefined) {
+                inner[to] = inner[from];
+            }
+        }
+        const allow = Array.isArray(rule.allowKeys) ? new Set(rule.allowKeys) : null;
+        const onlyIfMissing = rule.onlyIfTargetMissing !== false;
+        for (const [key, value] of Object.entries(inner)) {
+            if (allow && !allow.has(key)) {
+                continue;
+            }
+            if (!onlyIfMissing || out[key] === undefined) {
+                out[key] = value;
+            }
+        }
+        delete out[wrapperKey];
+        flattenedWrappers.push(wrapperKey);
+    }
+    return {
+        payload: out,
+        changed: out !== payload || removedTopLevelKeys.length > 0 || flattenedWrappers.length > 0,
+        removedTopLevelKeys,
+        flattenedWrappers
+    };
+}
+function observeProviderOutboundPayload(providerProtocol, payload) {
+    const violations = [];
+    // V0 (observe-only): detect known "layout anti-patterns" and reserved keys.
+    // Do NOT modify payload here.
+    const spec = resolveHubProtocolSpec(providerProtocol);
+    for (const rule of spec.providerOutbound.forbidWrappers) {
+        if (rule.code !== 'forbid_wrapper') {
+            continue;
+        }
+        if (rule.path in payload && isJsonRecord(payload[rule.path])) {
+            violations.push({
+                code: 'unexpected_wrapper',
+                path: rule.path,
+                detail: rule.detail
+            });
+        }
+    }
+    // Always record unknown private wrapper keys (best-effort, conservative).
+    for (const key of Object.keys(payload)) {
+        if (spec.providerOutbound.reservedKeyPrefixes.some((prefix) => key.startsWith(prefix))) {
+            violations.push({
+                code: 'unexpected_field',
+                path: key
+            });
+        }
+    }
+    const unexpectedFieldCount = violations.filter((v) => v.code === 'unexpected_field').length;
+    return {
+        phase: 'provider_outbound',
+        providerProtocol,
+        violations,
+        summary: {
+            totalViolations: violations.length,
+            unexpectedFieldCount
+        }
+    };
+}
+export function recordHubPolicyObservation(options) {
+    if (!options.stageRecorder) {
+        return;
+    }
+    const effectivePolicy = resolveEffectivePolicy(options.policy);
+    const mode = effectivePolicy?.mode ?? 'off';
+    // Keep observing in enforce mode (best-effort) so operators can monitor
+    // violations while gradually turning enforcement on.
+    if (mode !== 'observe' && mode !== 'enforce') {
+        return;
+    }
+    if (!shouldSample(effectivePolicy?.sampleRate)) {
+        return;
+    }
+    try {
+        const phase = options.phase ?? 'provider_outbound';
+        const observation = observeProviderOutboundPayload(options.providerProtocol, options.payload);
+        observation.phase = phase;
+        if (observation.summary.totalViolations <= 0) {
+            return;
+        }
+        const stage = `hub_policy.observe.${phase}`;
+        options.stageRecorder.record(stage, {
+            requestId: options.requestId,
+            ...observation
+        });
+    }
+    catch {
+        // observe-only must never break the pipeline
+    }
+}
+export function applyHubProviderOutboundPolicy(options) {
+    const effectivePolicy = resolveEffectivePolicy(options.policy);
+    const mode = effectivePolicy?.mode ?? 'off';
+    if (mode !== 'enforce') {
+        return options.payload;
+    }
+    const result = applyProviderOutboundPolicy(options.providerProtocol, options.payload);
+    if (!result.changed) {
+        return options.payload;
+    }
+    try {
+        options.stageRecorder?.record('hub_policy.enforce.provider_outbound', {
+            requestId: options.requestId,
+            providerProtocol: options.providerProtocol,
+            removedTopLevelKeys: result.removedTopLevelKeys,
+            flattenedWrappers: result.flattenedWrappers
+        });
+    }
+    catch {
+        // policy enforcement recording must not break the pipeline
+    }
+    return result.payload;
+}

package/dist/conversion/hub/policy/protocol-spec.d.ts

@@ -0,0 +1,50 @@
+export type HubProviderProtocol = 'openai-chat' | 'openai-responses' | 'anthropic-messages' | 'gemini-chat';
+export interface ProviderOutboundLayoutRule {
+    code: 'forbid_wrapper';
+    path: string;
+    detail: string;
+}
+export interface ProviderOutboundWrapperFlattenRule {
+    wrapperKey: string;
+    /**
+     * When provided, only these keys from the wrapper are merged into top-level.
+     * When omitted, all keys are eligible.
+     */
+    allowKeys?: string[];
+    /**
+     * Key remap inside wrapper prior to merging (e.g. max_tokens -> max_output_tokens).
+     */
+    aliasKeys?: Record<string, string>;
+    /**
+     * Merge strategy: only write to target when top-level key is undefined.
+     */
+    onlyIfTargetMissing?: boolean;
+}
+export interface ProviderOutboundPolicySpec {
+    /**
+     * Whether provider outbound enforcement is enabled for this protocol.
+     * Keep this false for protocols not yet migrated, to avoid behavior changes.
+     */
+    enforceEnabled: boolean;
+    /**
+     * Reserved/private key prefixes that must not be sent upstream.
+     * (Enforced only when enforceEnabled=true.)
+     */
+    reservedKeyPrefixes: string[];
+    /**
+     * Wrappers that should not exist in provider outbound payload.
+     * observe: treat as violations; enforce: flatten/remove when configured.
+     */
+    forbidWrappers: ProviderOutboundLayoutRule[];
+    /**
+     * Best-effort fix for known wrapper anti-patterns by flattening into top-level.
+     * (Applied only when enforceEnabled=true.)
+     */
+    flattenWrappers: ProviderOutboundWrapperFlattenRule[];
+}
+export interface ProtocolSpec {
+    id: HubProviderProtocol;
+    providerOutbound: ProviderOutboundPolicySpec;
+}
+export declare const HUB_PROTOCOL_SPECS: Record<HubProviderProtocol, ProtocolSpec>;
+export declare function resolveHubProtocolSpec(protocol: string): ProtocolSpec;