@jsonstudio/llms 0.4.3 → 0.4.5

package/dist/conversion/pipeline/codecs/v2/openai-openai-pipeline.js

@@ -0,0 +1,174 @@
+import { ProtocolConversionPipeline } from '../../index.js';
+import { buildAdapterContextFromPipeline } from '../../hooks/adapter-context.js';
+import { chatEnvelopeToStandardized } from '../../../hub/standardized-bridge.js';
+import { ChatFormatAdapter } from '../../../hub/format-adapters/chat-format-adapter.js';
+import { ChatSemanticMapper } from '../../../hub/semantic-mappers/chat-mapper.js';
+import { runStandardChatRequestFilters } from '../../../index.js';
+import { canonicalizeOpenAIChatResponse, convertStandardizedToOpenAIChat as convertCanonicalToOpenAIChat, DEFAULT_OPENAI_ENDPOINT, OPENAI_PROTOCOL } from './shared/openai-chat-helpers.js';
+function assertJsonObject(value, stage) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`OpenAI pipeline codec requires JSON payload at ${stage}`);
+    }
+    return value;
+}
+function restoreToolCallIndexes(targetMessages, sourceMessages) {
+    if (!Array.isArray(targetMessages) || !Array.isArray(sourceMessages)) {
+        return;
+    }
+    const sourceIndexMap = new Map();
+    for (const message of sourceMessages) {
+        if (!message || typeof message !== 'object')
+            continue;
+        const toolCalls = message.tool_calls;
+        if (!Array.isArray(toolCalls))
+            continue;
+        toolCalls.forEach((toolCall) => {
+            if (!toolCall || typeof toolCall !== 'object')
+                return;
+            const id = typeof toolCall.id === 'string'
+                ? String(toolCall.id)
+                : undefined;
+            if (!id || sourceIndexMap.has(id))
+                return;
+            const idxValue = toolCall.index;
+            if (typeof idxValue !== 'number')
+                return;
+            sourceIndexMap.set(id, idxValue);
+        });
+    }
+    for (const message of targetMessages) {
+        if (!message || typeof message !== 'object')
+            continue;
+        const toolCalls = message.tool_calls;
+        if (!Array.isArray(toolCalls))
+            continue;
+        toolCalls.forEach((toolCall) => {
+            if (!toolCall || typeof toolCall !== 'object')
+                return;
+            const id = typeof toolCall.id === 'string'
+                ? String(toolCall.id)
+                : undefined;
+            if (!id)
+                return;
+            const sourceIndex = sourceIndexMap.get(id);
+            if (sourceIndex === undefined)
+                return;
+            toolCall.index = sourceIndex;
+        });
+    }
+}
+function createOpenAIHooks() {
+    const formatAdapter = new ChatFormatAdapter();
+    const semanticMapper = new ChatSemanticMapper();
+    return {
+        id: 'openai-openai-v2',
+        protocol: OPENAI_PROTOCOL,
+        inbound: {
+            parse: async ({ wire, context }) => {
+                const adapterContext = buildAdapterContextFromPipeline(context, {
+                    defaultEntryEndpoint: DEFAULT_OPENAI_ENDPOINT,
+                    overrideProtocol: OPENAI_PROTOCOL
+                });
+                const formatEnvelope = await formatAdapter.parseRequest(wire, adapterContext);
+                const chatEnvelope = await semanticMapper.toChat(formatEnvelope, adapterContext);
+                const canonical = chatEnvelopeToStandardized(chatEnvelope, {
+                    adapterContext,
+                    endpoint: adapterContext.entryEndpoint ?? DEFAULT_OPENAI_ENDPOINT,
+                    requestId: adapterContext.requestId
+                });
+                return { canonical };
+            }
+        },
+        outbound: {
+            serialize: async ({ canonical }) => {
+                return { payload: assertJsonObject(canonical, 'openai_outbound_serialize') };
+            }
+        }
+    };
+}
+function buildPipelineContext(profile, context) {
+    return {
+        requestId: context.requestId,
+        entryEndpoint: context.entryEndpoint ?? context.endpoint ?? DEFAULT_OPENAI_ENDPOINT,
+        providerProtocol: profile.incomingProtocol ?? context.targetProtocol ?? OPENAI_PROTOCOL,
+        targetProtocol: profile.outgoingProtocol ?? context.targetProtocol ?? OPENAI_PROTOCOL,
+        profileId: profile.id,
+        stream: context.stream,
+        metadata: context.metadata
+    };
+}
+export class OpenAIOpenAIPipelineCodec {
+    id = 'openai-openai-v2';
+    pipeline;
+    requestMetaStore = new Map();
+    initialized = false;
+    constructor() {
+        this.pipeline = new ProtocolConversionPipeline(createOpenAIHooks());
+    }
+    async initialize() {
+        this.initialized = true;
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('OpenAIOpenAIPipelineCodec must be initialized before use');
+        }
+    }
+    stashMeta(requestId, bag) {
+        this.requestMetaStore.set(requestId, bag.snapshot());
+    }
+    consumeMeta(requestId) {
+        const stored = this.requestMetaStore.get(requestId);
+        if (stored) {
+            this.requestMetaStore.delete(requestId);
+            return stored;
+        }
+        return undefined;
+    }
+    async convertRequest(payload, profile, context) {
+        this.ensureInitialized();
+        const inboundContext = buildPipelineContext(profile, context);
+        const requestId = context.requestId ?? inboundContext.requestId ?? `req_${Date.now()}`;
+        inboundContext.requestId = requestId;
+        const inboundPayload = assertJsonObject(payload, 'openai_inbound_request');
+        const inboundOptions = {
+            payload: inboundPayload,
+            context: inboundContext
+        };
+        const inbound = await this.pipeline.convertInbound(inboundOptions);
+        this.stashMeta(requestId, inbound.meta);
+        const openaiPayload = await convertCanonicalToOpenAIChat(inbound.canonical, inbound.context);
+        if (!Array.isArray(openaiPayload.tools) && Array.isArray(inboundPayload.tools)) {
+            openaiPayload.tools = inboundPayload.tools;
+        }
+        if (openaiPayload.tool_choice === undefined &&
+            inboundPayload.tool_choice !== undefined) {
+            openaiPayload.tool_choice = inboundPayload.tool_choice;
+        }
+        const filterContext = {
+            ...context,
+            requestId,
+            entryEndpoint: context.entryEndpoint ?? DEFAULT_OPENAI_ENDPOINT,
+            endpoint: context.endpoint ?? DEFAULT_OPENAI_ENDPOINT
+        };
+        const filtered = await runStandardChatRequestFilters(openaiPayload, profile, filterContext);
+        if (filtered && typeof filtered === 'object') {
+            restoreToolCallIndexes(filtered.messages, inboundPayload.messages);
+        }
+        return filtered;
+    }
+    async convertResponse(payload, profile, context) {
+        this.ensureInitialized();
+        const pipelineContext = buildPipelineContext(profile, context);
+        const requestId = context.requestId ?? pipelineContext.requestId ?? `req_${Date.now()}`;
+        pipelineContext.requestId = requestId;
+        const storedMeta = this.consumeMeta(requestId);
+        const sanitized = await canonicalizeOpenAIChatResponse(assertJsonObject(payload, 'openai_chat_response'), context);
+        const outboundOptions = {
+            canonical: sanitized,
+            context: pipelineContext,
+            meta: storedMeta
+        };
+        const outbound = await this.pipeline.convertOutbound(outboundOptions);
+        return outbound.payload;
+    }
+}

package/dist/conversion/pipeline/codecs/v2/responses-openai-pipeline.d.ts

@@ -0,0 +1,14 @@
+import type { ConversionCodec, ConversionContext, ConversionProfile } from '../../../types.js';
+import type { JsonObject } from '../../../hub/types/json.js';
+export declare class ResponsesOpenAIPipelineCodec implements ConversionCodec {
+    readonly id = "responses-openai-v2";
+    private readonly pipeline;
+    private readonly requestMetaStore;
+    private initialized;
+    constructor();
+    initialize(): Promise<void>;
+    private ensureInitialized;
+    private stashMeta;
+    convertRequest(payload: unknown, profile: ConversionProfile, context: ConversionContext): Promise<JsonObject>;
+    convertResponse(payload: unknown, profile: ConversionProfile, context: ConversionContext): Promise<JsonObject>;
+}

package/dist/conversion/pipeline/codecs/v2/responses-openai-pipeline.js

@@ -0,0 +1,166 @@
+import { ProtocolConversionPipeline } from '../../index.js';
+import { chatEnvelopeToStandardized } from '../../../hub/standardized-bridge.js';
+import { ResponsesFormatAdapter } from '../../../hub/format-adapters/responses-format-adapter.js';
+import { ResponsesSemanticMapper } from '../../../hub/semantic-mappers/responses-mapper.js';
+import { captureResponsesContext, buildChatRequestFromResponses, buildResponsesPayloadFromChat } from '../../../responses/responses-openai-bridge.js';
+import { buildAdapterContextFromPipeline } from '../../hooks/adapter-context.js';
+import { runStandardChatRequestFilters } from '../../../index.js';
+import { canonicalizeOpenAIChatResponse, convertStandardizedToOpenAIChat as convertCanonicalToOpenAIChat, OPENAI_PROTOCOL } from './shared/openai-chat-helpers.js';
+const DEFAULT_RESPONSES_ENDPOINT = '/v1/responses';
+const RESPONSES_PROTOCOL = 'openai-responses';
+function assertJsonObject(value, stage) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Responses pipeline codec requires JSON payload at ${stage}`);
+    }
+    return value;
+}
+function cloneResponsesContext(context) {
+    try {
+        return JSON.parse(JSON.stringify(context ?? {}));
+    }
+    catch {
+        return {};
+    }
+}
+function restoreResponsesContext(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    return value;
+}
+function captureToolResults(payload) {
+    const results = [];
+    const inputArr = Array.isArray(payload?.input) ? payload.input : [];
+    for (const it of inputArr) {
+        if (!it || typeof it !== 'object')
+            continue;
+        const t = String(it.type || '').toLowerCase();
+        if (t === 'tool_result' || t === 'tool_message' || t === 'function_call_output') {
+            const tool_call_id = it.tool_call_id || it.call_id || it.tool_use_id;
+            let output = undefined;
+            const rawOut = it.output;
+            if (typeof rawOut === 'string')
+                output = rawOut;
+            else if (rawOut && typeof rawOut === 'object') {
+                try {
+                    output = JSON.stringify(rawOut);
+                }
+                catch { /* ignore */ }
+            }
+            results.push({ tool_call_id, output });
+        }
+    }
+    return results;
+}
+function createResponsesHooks() {
+    const formatAdapter = new ResponsesFormatAdapter();
+    const semanticMapper = new ResponsesSemanticMapper();
+    return {
+        id: 'responses-openai-v2',
+        protocol: RESPONSES_PROTOCOL,
+        inbound: {
+            parse: async ({ wire, context, meta }) => {
+                const adapterContext = buildAdapterContextFromPipeline(context, {
+                    defaultEntryEndpoint: DEFAULT_RESPONSES_ENDPOINT,
+                    overrideProtocol: RESPONSES_PROTOCOL
+                });
+                const formatEnvelope = await formatAdapter.parseRequest(wire, adapterContext);
+                const chatEnvelope = await semanticMapper.toChat(formatEnvelope, adapterContext);
+                const canonical = chatEnvelopeToStandardized(chatEnvelope, {
+                    adapterContext,
+                    endpoint: adapterContext.entryEndpoint,
+                    requestId: adapterContext.requestId
+                });
+                // Capture Responses-specific context for outbound mapping parity
+                const responsesContext = captureResponsesContext(wire, { route: { requestId: adapterContext.requestId } });
+                const built = buildChatRequestFromResponses(wire, responsesContext);
+                if (built.toolsNormalized) {
+                    responsesContext.toolsNormalized = built.toolsNormalized;
+                }
+                const captured = captureToolResults(wire);
+                if (captured.length) {
+                    responsesContext.__captured_tool_results = captured;
+                }
+                meta.set('responsesContext', cloneResponsesContext(responsesContext));
+                return { canonical };
+            }
+        },
+        outbound: {
+            serialize: async ({ canonical, meta }) => {
+                const stored = meta.consume('responsesContext');
+                const responsesContext = restoreResponsesContext(stored);
+                const payload = buildResponsesPayloadFromChat(canonical, responsesContext);
+                return { payload: assertJsonObject(payload, 'responses_outbound_serialize') };
+            }
+        }
+    };
+}
+function buildPipelineContext(profile, context) {
+    return {
+        requestId: context.requestId,
+        entryEndpoint: context.entryEndpoint ?? context.endpoint ?? DEFAULT_RESPONSES_ENDPOINT,
+        providerProtocol: profile.incomingProtocol ?? RESPONSES_PROTOCOL,
+        targetProtocol: profile.outgoingProtocol ?? context.targetProtocol ?? OPENAI_PROTOCOL,
+        profileId: profile.id,
+        stream: context.stream,
+        metadata: context.metadata
+    };
+}
+export class ResponsesOpenAIPipelineCodec {
+    id = 'responses-openai-v2';
+    pipeline;
+    requestMetaStore = new Map();
+    initialized = false;
+    constructor() {
+        this.pipeline = new ProtocolConversionPipeline(createResponsesHooks());
+    }
+    async initialize() {
+        this.initialized = true;
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('ResponsesOpenAIPipelineCodec must be initialized before use');
+        }
+    }
+    stashMeta(requestId, bag) {
+        this.requestMetaStore.set(requestId, bag.snapshot());
+    }
+    async convertRequest(payload, profile, context) {
+        this.ensureInitialized();
+        const inboundContext = buildPipelineContext(profile, context);
+        const requestId = context.requestId ?? inboundContext.requestId ?? `req_${Date.now()}`;
+        inboundContext.requestId = requestId;
+        const inboundOptions = {
+            payload: assertJsonObject(payload, 'responses_inbound_request'),
+            context: inboundContext
+        };
+        const inbound = await this.pipeline.convertInbound(inboundOptions);
+        this.stashMeta(requestId, inbound.meta);
+        const openaiPayload = await convertCanonicalToOpenAIChat(inbound.canonical, inbound.context);
+        const filterContext = {
+            ...context,
+            requestId,
+            entryEndpoint: context.entryEndpoint ?? DEFAULT_RESPONSES_ENDPOINT,
+            endpoint: context.endpoint ?? DEFAULT_RESPONSES_ENDPOINT
+        };
+        return runStandardChatRequestFilters(openaiPayload, profile, filterContext);
+    }
+    async convertResponse(payload, profile, context) {
+        this.ensureInitialized();
+        const pipelineContext = buildPipelineContext(profile, context);
+        const requestId = context.requestId ?? pipelineContext.requestId ?? `req_${Date.now()}`;
+        pipelineContext.requestId = requestId;
+        const storedMeta = this.requestMetaStore.get(requestId);
+        if (storedMeta) {
+            this.requestMetaStore.delete(requestId);
+        }
+        const sanitized = await canonicalizeOpenAIChatResponse(assertJsonObject(payload, 'responses_openai_response'), context);
+        const outboundOptions = {
+            canonical: sanitized,
+            context: pipelineContext,
+            meta: storedMeta
+        };
+        const outbound = await this.pipeline.convertOutbound(outboundOptions);
+        return outbound.payload;
+    }
+}

package/dist/conversion/pipeline/codecs/v2/shared/openai-chat-helpers.d.ts

@@ -0,0 +1,13 @@
+import type { JsonObject } from '../../../../hub/types/json.js';
+import type { ConversionContext } from '../../../../types.js';
+import type { CanonicalChatRequest } from '../../../schema/index.js';
+import type { ProtocolPipelineContext } from '../../../hooks/protocol-hooks.js';
+export declare const DEFAULT_OPENAI_ENDPOINT = "/v1/chat/completions";
+export declare const OPENAI_PROTOCOL = "openai-chat";
+export declare function convertStandardizedToOpenAIChat(standardized: CanonicalChatRequest, context: ProtocolPipelineContext, options?: {
+    defaultEndpoint?: string;
+}): Promise<JsonObject>;
+export declare function canonicalizeOpenAIChatResponse(payload: JsonObject, context: ConversionContext, options?: {
+    defaultEndpoint?: string;
+    profile?: string;
+}): Promise<JsonObject>;

package/dist/conversion/pipeline/codecs/v2/shared/openai-chat-helpers.js

@@ -0,0 +1,66 @@
+import { standardizedToChatEnvelope } from '../../../../hub/standardized-bridge.js';
+import { buildAdapterContextFromPipeline } from '../../../hooks/adapter-context.js';
+import { ChatFormatAdapter } from '../../../../hub/format-adapters/chat-format-adapter.js';
+import { ChatSemanticMapper } from '../../../../hub/semantic-mappers/chat-mapper.js';
+import { FilterEngine, ResponseToolTextCanonicalizeFilter, ResponseToolArgumentsStringifyFilter, ResponseFinishInvariantsFilter } from '../../../../../filters/index.js';
+import { normalizeChatResponseReasoningTools } from '../../../../shared/reasoning-tool-normalizer.js';
+export const DEFAULT_OPENAI_ENDPOINT = '/v1/chat/completions';
+export const OPENAI_PROTOCOL = 'openai-chat';
+const sharedChatFormatAdapter = new ChatFormatAdapter();
+const sharedChatSemanticMapper = new ChatSemanticMapper();
+function ensureJsonObject(value, stage) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`OpenAI chat helper requires JSON object payload at ${stage}`);
+    }
+    return value;
+}
+export async function convertStandardizedToOpenAIChat(standardized, context, options) {
+    const adapterContext = buildAdapterContextFromPipeline(context, {
+        defaultEntryEndpoint: options?.defaultEndpoint ?? DEFAULT_OPENAI_ENDPOINT,
+        overrideProtocol: OPENAI_PROTOCOL
+    });
+    const chatEnvelope = standardizedToChatEnvelope(standardized, { adapterContext });
+    const formatEnvelope = await sharedChatSemanticMapper.fromChat(chatEnvelope, adapterContext);
+    const payload = await sharedChatFormatAdapter.buildRequest(formatEnvelope, adapterContext);
+    return ensureJsonObject(payload, 'openai_request_build');
+}
+export async function canonicalizeOpenAIChatResponse(payload, context, options) {
+    const dto = {
+        data: payload,
+        metadata: {
+            requestId: context.requestId ?? `req_${Date.now()}`,
+            pipelineId: context.metadata?.pipelineId ?? 'conversion-router',
+            processingTime: 0,
+            stages: []
+        }
+    };
+    const filterContext = {
+        requestId: dto.metadata.requestId,
+        model: typeof payload.model === 'string' ? payload.model : undefined,
+        endpoint: context.entryEndpoint ?? context.endpoint ?? options?.defaultEndpoint ?? DEFAULT_OPENAI_ENDPOINT,
+        profile: options?.profile ?? OPENAI_PROTOCOL,
+        debug: { emit: () => { } }
+    };
+    const engine = new FilterEngine();
+    engine.registerFilter(new ResponseToolTextCanonicalizeFilter());
+    try {
+        const { ResponseToolArgumentsToonDecodeFilter } = await import('../../../../../filters/index.js');
+        engine.registerFilter(new ResponseToolArgumentsToonDecodeFilter());
+    }
+    catch {
+        // optional decode filter
+    }
+    engine.registerFilter(new ResponseToolArgumentsStringifyFilter());
+    engine.registerFilter(new ResponseFinishInvariantsFilter());
+    const stage1 = await engine.run('response_pre', dto.data, filterContext);
+    const stage2 = await engine.run('response_map', stage1, filterContext);
+    const stage3 = await engine.run('response_post', stage2, filterContext);
+    const normalized = ensureJsonObject(stage3, 'openai_response_filters');
+    try {
+        normalizeChatResponseReasoningTools(normalized, { idPrefixBase: 'reasoning_choice' });
+    }
+    catch {
+        // reasoning normalization best-effort
+    }
+    return normalized;
+}

package/dist/conversion/pipeline/hooks/adapter-context.d.ts

@@ -0,0 +1,7 @@
+import type { AdapterContext } from '../../hub/types/chat-envelope.js';
+import type { ProtocolPipelineContext } from './protocol-hooks.js';
+export interface AdapterContextOptions {
+    defaultEntryEndpoint?: string;
+    overrideProtocol?: string;
+}
+export declare function buildAdapterContextFromPipeline(context: ProtocolPipelineContext, options?: AdapterContextOptions): AdapterContext;

package/dist/conversion/pipeline/hooks/adapter-context.js

@@ -0,0 +1,18 @@
+export function buildAdapterContextFromPipeline(context, options) {
+    const requestId = context.requestId ?? `req_${Date.now()}`;
+    const entryEndpoint = options?.defaultEntryEndpoint ??
+        context.entryEndpoint ??
+        '/v1/chat/completions';
+    const providerProtocol = options?.overrideProtocol ??
+        context.providerProtocol ??
+        context.targetProtocol ??
+        'openai-chat';
+    const streamingHint = context.stream === true ? 'force' : context.stream === false ? 'disable' : 'auto';
+    return {
+        requestId,
+        entryEndpoint,
+        providerProtocol,
+        profileId: context.profileId,
+        streamingHint
+    };
+}

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

@@ -0,0 +1,67 @@
+import type { JsonObject } from '../../hub/types/json.js';
+import type { CanonicalChatRequest, CanonicalChatResponse } from '../schema/index.js';
+import type { ConversionMetaBag, ConversionMetaRecord } from '../meta/meta-bag.js';
+export interface ProtocolPipelineContext {
+    requestId?: string;
+    entryEndpoint?: string;
+    profileId?: string;
+    providerProtocol?: string;
+    targetProtocol?: string;
+    stream?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface InboundHookArgs<TWire = JsonObject> {
+    wire: TWire;
+    meta: ConversionMetaBag;
+    context: ProtocolPipelineContext;
+}
+export interface CanonicalHookArgs<TCanonical> {
+    canonical: TCanonical;
+    meta: ConversionMetaBag;
+    context: ProtocolPipelineContext;
+}
+export interface OutboundWireHookArgs<TWire = JsonObject> {
+    wire: TWire;
+    meta: ConversionMetaBag;
+    context: ProtocolPipelineContext;
+}
+export interface CanonicalParseResult<TCanonical> {
+    canonical: TCanonical;
+    meta?: ConversionMetaRecord;
+}
+export type ProtocolParserHook<TWire, TCanonical> = (args: InboundHookArgs<TWire>) => Promise<CanonicalParseResult<TCanonical>> | CanonicalParseResult<TCanonical>;
+export type ProtocolCleanupHook<TCanonical> = (args: CanonicalHookArgs<TCanonical>) => Promise<void> | void;
+export interface ProtocolSerializationResult<TWire> {
+    payload: TWire;
+    meta?: ConversionMetaRecord;
+}
+export type ProtocolSerializerHook<TCanonical, TWire> = (args: CanonicalHookArgs<TCanonical>) => Promise<ProtocolSerializationResult<TWire>> | ProtocolSerializationResult<TWire>;
+export type ProtocolAugmentationHook<TCanonical> = (args: CanonicalHookArgs<TCanonical>) => Promise<void> | void;
+export interface ProtocolValidationErrorDetail {
+    path?: string;
+    message: string;
+    code?: string;
+}
+export interface ProtocolValidationResult {
+    ok: boolean;
+    errors?: ProtocolValidationErrorDetail[];
+}
+export type ProtocolValidationHook<TArgs> = (args: TArgs) => Promise<void | ProtocolValidationResult> | void | ProtocolValidationResult;
+export type InboundValidationHook<TWire> = ProtocolValidationHook<InboundHookArgs<TWire>>;
+export type OutboundValidationHook<TWire> = ProtocolValidationHook<OutboundWireHookArgs<TWire>>;
+export interface ProtocolInboundHooks<TInboundWire = JsonObject, TCanonical = CanonicalChatRequest> {
+    preValidate?: InboundValidationHook<TInboundWire>;
+    parse: ProtocolParserHook<TInboundWire, TCanonical>;
+    cleanup?: ProtocolCleanupHook<TCanonical>;
+}
+export interface ProtocolOutboundHooks<TCanonical = CanonicalChatResponse, TOutboundWire = JsonObject> {
+    augment?: ProtocolAugmentationHook<TCanonical>;
+    serialize: ProtocolSerializerHook<TCanonical, TOutboundWire>;
+    postValidate?: OutboundValidationHook<TOutboundWire>;
+}
+export interface ProtocolPipelineHooks<TInboundWire = JsonObject, TOutboundWire = JsonObject, TCanonicalInbound = CanonicalChatRequest, TCanonicalOutbound = CanonicalChatResponse> {
+    id: string;
+    protocol: string;
+    inbound: ProtocolInboundHooks<TInboundWire, TCanonicalInbound>;
+    outbound: ProtocolOutboundHooks<TCanonicalOutbound, TOutboundWire>;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/conversion/pipeline/index.d.ts

@@ -0,0 +1,35 @@
+import { type CanonicalChatRequest, type CanonicalChatResponse } from './schema/index.js';
+import { type ProtocolPipelineHooks, type ProtocolPipelineContext, type ProtocolValidationErrorDetail } from './hooks/protocol-hooks.js';
+import { ConversionMetaBag, type ConversionMetaInput } from './meta/meta-bag.js';
+export interface ProtocolInboundPipelineOptions<TWire> {
+    payload: TWire;
+    context?: ProtocolPipelineContext;
+    meta?: ConversionMetaInput;
+}
+export interface ProtocolOutboundPipelineOptions<TCanonical> {
+    canonical: TCanonical;
+    context?: ProtocolPipelineContext;
+    meta?: ConversionMetaInput;
+}
+export interface ProtocolInboundPipelineResult<TCanonical> {
+    canonical: TCanonical;
+    meta: ConversionMetaBag;
+    context: ProtocolPipelineContext;
+}
+export interface ProtocolOutboundPipelineResult<TWire> {
+    payload: TWire;
+    meta: ConversionMetaBag;
+    context: ProtocolPipelineContext;
+}
+export declare class PipelineValidationError extends Error {
+    readonly stage: string;
+    readonly errors: ProtocolValidationErrorDetail[];
+    constructor(stage: string, errors: ProtocolValidationErrorDetail[]);
+}
+export declare class ProtocolConversionPipeline<TInboundWire = Record<string, unknown>, TOutboundWire = Record<string, unknown>, TCanonicalInbound = CanonicalChatRequest, TCanonicalOutbound = CanonicalChatResponse> {
+    private readonly hooks;
+    constructor(hooks: ProtocolPipelineHooks<TInboundWire, TOutboundWire, TCanonicalInbound, TCanonicalOutbound>);
+    convertInbound(options: ProtocolInboundPipelineOptions<TInboundWire>): Promise<ProtocolInboundPipelineResult<TCanonicalInbound>>;
+    convertOutbound(options: ProtocolOutboundPipelineOptions<TCanonicalOutbound>): Promise<ProtocolOutboundPipelineResult<TOutboundWire>>;
+    private runValidation;
+}

package/dist/conversion/pipeline/index.js

@@ -0,0 +1,103 @@
+import { ConversionMetaBag } from './meta/meta-bag.js';
+export class PipelineValidationError extends Error {
+    stage;
+    errors;
+    constructor(stage, errors) {
+        super(errors[0]?.message ?? `Validation failed during ${stage}`);
+        this.name = 'PipelineValidationError';
+        this.stage = stage;
+        this.errors = errors;
+    }
+}
+function normalizeContext(hooks, ctx) {
+    return {
+        profileId: ctx?.profileId ?? hooks.id,
+        providerProtocol: ctx?.providerProtocol ?? hooks.protocol,
+        targetProtocol: ctx?.targetProtocol ?? ctx?.providerProtocol ?? hooks.protocol,
+        entryEndpoint: ctx?.entryEndpoint,
+        requestId: ctx?.requestId,
+        stream: ctx?.stream,
+        metadata: ctx?.metadata ?? {}
+    };
+}
+function ingestMeta(target, incoming) {
+    if (!incoming) {
+        return;
+    }
+    target.ingest(incoming);
+}
+export class ProtocolConversionPipeline {
+    hooks;
+    constructor(hooks) {
+        if (!hooks?.inbound?.parse) {
+            throw new Error('ProtocolConversionPipeline requires an inbound.parse hook');
+        }
+        if (!hooks?.outbound?.serialize) {
+            throw new Error('ProtocolConversionPipeline requires an outbound.serialize hook');
+        }
+        this.hooks = hooks;
+    }
+    async convertInbound(options) {
+        const context = normalizeContext(this.hooks, options.context);
+        const meta = new ConversionMetaBag(options.meta);
+        await this.runValidation('inbound.preValidate', this.hooks.inbound.preValidate, {
+            wire: options.payload,
+            meta,
+            context
+        });
+        const parseResult = await this.hooks.inbound.parse({
+            wire: options.payload,
+            meta,
+            context
+        });
+        ingestMeta(meta, parseResult.meta);
+        const canonical = parseResult.canonical;
+        if (!canonical) {
+            throw new Error('ProtocolConversionPipeline inbound.parse returned an empty canonical payload');
+        }
+        if (this.hooks.inbound.cleanup) {
+            await this.hooks.inbound.cleanup({
+                canonical,
+                meta,
+                context
+            });
+        }
+        return { canonical, meta, context };
+    }
+    async convertOutbound(options) {
+        const context = normalizeContext(this.hooks, options.context);
+        const meta = new ConversionMetaBag(options.meta);
+        if (this.hooks.outbound.augment) {
+            await this.hooks.outbound.augment({
+                canonical: options.canonical,
+                meta,
+                context
+            });
+        }
+        const serialized = await this.hooks.outbound.serialize({
+            canonical: options.canonical,
+            meta,
+            context
+        });
+        ingestMeta(meta, serialized.meta);
+        await this.runValidation('outbound.postValidate', this.hooks.outbound.postValidate, {
+            wire: serialized.payload,
+            meta,
+            context
+        });
+        return { payload: serialized.payload, meta, context };
+    }
+    async runValidation(stage, hook, args) {
+        if (!hook) {
+            return;
+        }
+        const result = await hook(args);
+        if (!result) {
+            return;
+        }
+        const errors = result.errors ?? [];
+        if (result.ok === false || errors.length > 0) {
+            throw new PipelineValidationError(stage, errors.length ? errors : [{ message: 'Unknown validation error' }]);
+        }
+    }
+}