@volter/twin-ai-gateway 0.1.0

package/dist/src/ai-gateway-types.d.ts

@@ -0,0 +1,94 @@
+export type SseEvent = {
+    data?: Record<string, unknown>;
+    done?: boolean;
+};
+export type SseSink = (event: SseEvent) => void;
+import type { AiGatewayScenarioEngine } from './ai-gateway-scenario.js';
+export type AiGatewayRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    /** Lower-cased request headers. The AI SDK gateway protocol (/v3/ai) carries its call
+     *  configuration in headers (`ai-language-model-id`, `ai-language-model-streaming`,
+     *  `ai-language-model-specification-version`); the /v1 surface ignores them. */
+    headers?: Record<string, string>;
+    root?: string;
+    readOnly?: boolean;
+    occurredAt?: string;
+    sseSink?: SseSink;
+    /** Optional scenario-scripting session (ai-gateway-scenario.ts): when set, POST
+     *  /v1/chat/completions first consults the scenario's ordered rules and serves a scripted
+     *  completion on a match (protocol envelope stays vendor-faithful). Test scaffolding — NOT
+     *  part of the vendor surface and excluded from the capability manifest. */
+    scenarioEngine?: AiGatewayScenarioEngine;
+};
+export type AiGatewayResponse = {
+    status: number;
+    body: unknown;
+};
+export type ChatMessage = {
+    role: string;
+    content?: unknown;
+    tool_calls?: unknown;
+    tool_call_id?: unknown;
+    cache_control?: unknown;
+};
+/** One provider attempt inside routing metadata (providerMetadata.gateway.routing). */
+export type ProviderAttempt = {
+    provider: string;
+    providerApiModelId: string;
+    credentialType: 'system' | 'byok';
+    success: boolean;
+    error?: string;
+    startTime: number;
+    endTime: number;
+};
+export type ModelAttempt = {
+    modelId: string;
+    canonicalSlug: string;
+    success: boolean;
+    providerAttemptCount: number;
+    providerAttempts: ProviderAttempt[];
+};
+export type GatewayRouting = {
+    originalModelId: string;
+    resolvedProvider: string;
+    resolvedProviderApiModelId: string;
+    fallbacksAvailable: string[];
+    planningReasoning: string;
+    canonicalSlug: string;
+    finalProvider: string;
+    modelAttemptCount: number;
+    modelAttempts: ModelAttempt[];
+    totalProviderAttemptCount: number;
+    sort?: {
+        option: string;
+        executionOrder: string[];
+        metrics: Record<string, number | null>;
+        deprioritizedProviders: string[];
+    };
+};
+/** The locally recorded generation row — the shape GET /v1/generation serves (REST API docs,
+ *  "Look up a generation"), folded into the kernel projection on every chat completion. */
+export type GenerationRecord = {
+    id: string;
+    total_cost: number;
+    upstream_inference_cost: number;
+    usage: number;
+    created_at: string;
+    model: string;
+    is_byok: boolean;
+    provider_name: string;
+    streamed: boolean;
+    finish_reason: string;
+    latency: number;
+    generation_time: number;
+    tokens_prompt: number;
+    tokens_completion: number;
+    native_tokens_prompt: number;
+    native_tokens_completion: number;
+    native_tokens_reasoning: number;
+    native_tokens_cached: number;
+    native_tokens_cache_creation: number;
+    billable_web_search_calls: number;
+};

package/dist/src/ai-gateway-types.js

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

package/dist/src/ai-gateway-v3.d.ts

@@ -0,0 +1,5 @@
+import type { AiGatewayRequest, AiGatewayResponse } from './ai-gateway-types.js';
+type ChatFn = (req: AiGatewayRequest, params: Record<string, unknown>) => Promise<AiGatewayResponse>;
+export declare function v3Config(): AiGatewayResponse;
+export declare function handleV3LanguageModel(req: AiGatewayRequest, chat: ChatFn): Promise<AiGatewayResponse>;
+export {};

package/dist/src/ai-gateway-v3.js

@@ -0,0 +1,367 @@
+// AI SDK gateway protocol (/v3/ai) — the surface `@ai-sdk/gateway` (and therefore the `ai`
+// package's `createGateway`, the AI SDK's default provider) actually speaks. This is a DIFFERENT
+// wire protocol from the OpenAI-compatible /v1 surface: the SDK's GatewayLanguageModel POSTs the
+// raw LanguageModelV3 call options to `{baseURL}/language-model` with the model id carried in the
+// `ai-language-model-id` header (plus `ai-language-model-specification-version: 3` and
+// `ai-language-model-streaming`), and expects a LanguageModelV3 generate result (content parts /
+// finishReason {unified,raw} / nested usage) back — or an SSE stream of LanguageModelV3 stream
+// parts. `GET {baseURL}/config` serves the model/provider config document `getAvailableModels()`
+// consumes. Protocol derived from the shipped SDK itself (@ai-sdk/gateway dist:
+// gateway-language-model.ts getUrl()/getModelConfigHeaders(), gateway-fetch-metadata.ts
+// gatewayAvailableModelsResponseSchema, and @ai-sdk/provider's LanguageModelV3 types) — there is
+// no separately published wire spec.
+//
+// Design rule: this module is a TRANSLATION layer only. A /v3/ai language-model call is mapped
+// onto the twin's existing deterministic chat machinery (`chatCompletion`, injected as `chat` to
+// avoid an import cycle) so accounting/generation records flow through the SAME kernel fold as
+// /v1 chats — one generation log, one credits/report surface, whichever protocol the consumer
+// speaks.
+import { AI_GATEWAY_CATALOG } from "./ai-gateway-models.js";
+const FIXED_NOW = '1970-01-01T00:00:00.000Z';
+function nowIso(occurredAt) {
+    return new Date(Date.parse(occurredAt ?? FIXED_NOW)).toISOString();
+}
+// Same vendor error envelope as /v1 — the SDK's createGatewayErrorFromResponse parses
+// { error: { message, type, param, code } } (param may be an OBJECT for model_not_found).
+function v3Error(status, message, opts = {}) {
+    return {
+        status,
+        body: {
+            error: {
+                message,
+                type: opts.type ?? 'invalid_request_error',
+                ...(opts.param !== undefined ? { param: opts.param } : {}),
+                ...(opts.code !== undefined ? { code: opts.code } : {}),
+            },
+        },
+    };
+}
+// ── GET /v3/ai/config ─────────────────────────────────────────────────────────────────────
+// The config document `provider.getAvailableModels()` fetches. Shape per the SDK's
+// gatewayAvailableModelsResponseSchema: models[] with id/name/description, decimal-string
+// pricing, a v3 specification block, and modelType.
+export function v3Config() {
+    return {
+        status: 200,
+        body: {
+            models: AI_GATEWAY_CATALOG.map(({ model }) => ({
+                id: model.id,
+                name: model.name,
+                description: model.description,
+                pricing: {
+                    input: model.pricing.input,
+                    output: model.pricing.output ?? '0',
+                    ...(model.pricing.input_cache_read ? { input_cache_read: model.pricing.input_cache_read } : {}),
+                    ...(model.pricing.input_cache_write ? { input_cache_write: model.pricing.input_cache_write } : {}),
+                },
+                specification: {
+                    specificationVersion: 'v3',
+                    provider: model.owned_by,
+                    modelId: model.id,
+                },
+                modelType: model.type,
+            })),
+        },
+    };
+}
+// ── LanguageModelV3 prompt → OpenAI-compatible messages ──────────────────────────────────
+function toolResultOutputText(output) {
+    switch (output.type) {
+        case 'text':
+        case 'error-text':
+            return String(output.value ?? '');
+        case 'json':
+        case 'error-json':
+            return JSON.stringify(output.value ?? null);
+        case 'execution-denied':
+            return output.reason ? `execution denied: ${String(output.reason)}` : 'execution denied';
+        case 'content':
+            return (Array.isArray(output.value) ? output.value : [])
+                .map((p) => (p?.type === 'text' ? String(p.text ?? '') : ''))
+                .filter(Boolean)
+                .join(' ');
+        default:
+            return JSON.stringify(output);
+    }
+}
+function filePartToOpenAi(part) {
+    const mediaType = typeof part.mediaType === 'string' ? part.mediaType : 'application/octet-stream';
+    const data = part.data;
+    // Over the wire the SDK sends file data as a string: base64, or a URL (the client's
+    // maybeEncodeFileParts converts Uint8Array → data: URL; URL objects JSON-serialize to strings).
+    if (typeof data !== 'string' || !data)
+        return { error: 'file parts must carry string data (base64 or URL) over the wire' };
+    const url = data.startsWith('http://') || data.startsWith('https://') || data.startsWith('data:')
+        ? data
+        : `data:${mediaType};base64,${data}`;
+    if (mediaType.startsWith('image/'))
+        return { part: { type: 'image_url', image_url: { url } } };
+    return { part: { type: 'file', file: { data: url, media_type: mediaType, ...(typeof part.filename === 'string' ? { filename: part.filename } : {}) } } };
+}
+function translatePrompt(prompt) {
+    if (!Array.isArray(prompt) || prompt.length === 0) {
+        return { response: v3Error(400, 'prompt must be a non-empty array of LanguageModelV3 messages', { param: 'prompt' }) };
+    }
+    const messages = [];
+    for (const raw of prompt) {
+        if (!raw || typeof raw !== 'object')
+            return { response: v3Error(400, 'each prompt message must be an object', { param: 'prompt' }) };
+        const message = raw;
+        const role = message.role;
+        if (role === 'system') {
+            messages.push({ role: 'system', content: String(message.content ?? '') });
+            continue;
+        }
+        if (role === 'user') {
+            const parts = Array.isArray(message.content) ? message.content : [];
+            const content = [];
+            for (const part of parts) {
+                if (part?.type === 'text')
+                    content.push({ type: 'text', text: String(part.text ?? '') });
+                else if (part?.type === 'file') {
+                    const mapped = filePartToOpenAi(part);
+                    if ('error' in mapped)
+                        return { response: v3Error(400, mapped.error, { param: 'prompt' }) };
+                    content.push(mapped.part);
+                }
+                else
+                    return { response: v3Error(400, `unsupported user content part type: ${String(part?.type)}`, { param: 'prompt' }) };
+            }
+            messages.push({ role: 'user', content });
+            continue;
+        }
+        if (role === 'assistant') {
+            const parts = Array.isArray(message.content) ? message.content : [];
+            const text = parts.filter((p) => p?.type === 'text').map((p) => String(p.text ?? '')).join('');
+            const toolCalls = parts.filter((p) => p?.type === 'tool-call').map((p) => ({
+                id: String(p.toolCallId ?? ''),
+                type: 'function',
+                function: {
+                    name: String(p.toolName ?? ''),
+                    arguments: typeof p.input === 'string' ? p.input : JSON.stringify(p.input ?? {}),
+                },
+            }));
+            // Reasoning parts in the history contribute nothing the stub needs; they are dropped
+            // (the OpenAI-compat machinery has no assistant-reasoning input field either).
+            messages.push({
+                role: 'assistant',
+                content: text || (toolCalls.length > 0 ? null : text),
+                ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+            });
+            continue;
+        }
+        if (role === 'tool') {
+            const parts = Array.isArray(message.content) ? message.content : [];
+            for (const part of parts) {
+                if (part?.type !== 'tool-result')
+                    continue; // tool-approval-response: provider-executed tools are not modeled (open todo)
+                messages.push({
+                    role: 'tool',
+                    tool_call_id: String(part.toolCallId ?? ''),
+                    content: toolResultOutputText((part.output ?? {})),
+                });
+            }
+            continue;
+        }
+        return { response: v3Error(400, `unsupported prompt message role: ${String(role)}`, { param: 'prompt' }) };
+    }
+    return { messages };
+}
+// ── LanguageModelV3 call options → OpenAI-compatible chat params ─────────────────────────
+function translateCallOptions(modelId, streaming, options) {
+    const translated = translatePrompt(options.prompt);
+    if ('response' in translated)
+        return translated;
+    const params = { model: modelId, messages: translated.messages, stream: streaming };
+    if (options.maxOutputTokens !== undefined)
+        params.max_tokens = options.maxOutputTokens;
+    if (options.temperature !== undefined)
+        params.temperature = options.temperature;
+    if (options.topP !== undefined)
+        params.top_p = options.topP;
+    if (options.frequencyPenalty !== undefined)
+        params.frequency_penalty = options.frequencyPenalty;
+    if (options.presencePenalty !== undefined)
+        params.presence_penalty = options.presencePenalty;
+    if (options.stopSequences !== undefined)
+        params.stop = options.stopSequences;
+    if (options.tools !== undefined) {
+        if (!Array.isArray(options.tools))
+            return { response: v3Error(400, 'tools must be an array', { param: 'tools' }) };
+        const tools = [];
+        for (const raw of options.tools) {
+            if (raw?.type === 'function') {
+                tools.push({
+                    type: 'function',
+                    function: {
+                        name: String(raw.name ?? ''),
+                        ...(raw.description !== undefined ? { description: raw.description } : {}),
+                        parameters: raw.inputSchema ?? {},
+                    },
+                });
+            }
+            else {
+                // Provider-executed tools (gateway.parallel_search / gateway.perplexity_search) are not
+                // modeled yet — fail loudly rather than silently dropping the tool (open todo:
+                // ai-gateway.v3.provider_tools).
+                return { response: v3Error(400, `provider-executed tools are not modeled by the twin yet: ${String(raw?.id ?? raw?.name)}`, { param: 'tools', code: 'not_found' }) };
+            }
+        }
+        params.tools = tools;
+    }
+    const tc = options.toolChoice;
+    if (tc !== undefined) {
+        if (tc?.type === 'auto' || tc?.type === 'none' || tc?.type === 'required')
+            params.tool_choice = tc.type;
+        else if (tc?.type === 'tool' && typeof tc.toolName === 'string')
+            params.tool_choice = { type: 'function', function: { name: tc.toolName } };
+        else
+            return { response: v3Error(400, 'toolChoice must be auto/none/required or { type: "tool", toolName }', { param: 'toolChoice' }) };
+    }
+    const rf = options.responseFormat;
+    if (rf !== undefined && rf?.type === 'json') {
+        // V3's { type:'json', schema? } maps onto the gateway's legacy json response_format, which
+        // the chat machinery already synthesizes schema-conformant output for.
+        params.response_format = { type: 'json', ...(rf.schema !== undefined ? { schema: rf.schema } : {}) };
+    }
+    // providerOptions.gateway (order/only/sort/models/byok/caching) flows through verbatim — the
+    // chat machinery already parses exactly this shape.
+    if (options.providerOptions !== undefined)
+        params.providerOptions = options.providerOptions;
+    return { params };
+}
+// ── OpenAI-compatible chat body → LanguageModelV3 generate result ────────────────────────
+function mapFinishReason(raw) {
+    const unified = raw === 'tool_calls' ? 'tool-calls' : raw === 'stop' || raw === 'length' ? raw : 'other';
+    return { unified, raw };
+}
+function mapUsage(usage) {
+    const prompt = Number(usage.prompt_tokens ?? 0);
+    const completion = Number(usage.completion_tokens ?? 0);
+    const cached = Number(usage.prompt_tokens_details?.cached_tokens ?? 0);
+    const reasoning = Number(usage.completion_tokens_details?.reasoning_tokens ?? 0);
+    return {
+        inputTokens: { total: prompt, noCache: prompt - cached, cacheRead: cached, cacheWrite: 0 },
+        outputTokens: { total: completion, text: completion - reasoning, reasoning },
+        raw: usage,
+    };
+}
+function contentParts(message) {
+    const parts = [];
+    if (typeof message.reasoning === 'string')
+        parts.push({ type: 'reasoning', text: message.reasoning });
+    if (Array.isArray(message.tool_calls)) {
+        for (const call of message.tool_calls) {
+            const fn = (call.function ?? {});
+            parts.push({ type: 'tool-call', toolCallId: String(call.id ?? ''), toolName: String(fn.name ?? ''), input: String(fn.arguments ?? '{}') });
+        }
+    }
+    else {
+        parts.push({ type: 'text', text: String(message.content ?? '') });
+    }
+    return parts;
+}
+function v3GenerateBody(chatBody, occurredAt) {
+    const choice = chatBody.choices[0];
+    const message = choice.message;
+    return {
+        content: contentParts(message),
+        finishReason: mapFinishReason(String(choice.finish_reason)),
+        usage: mapUsage((chatBody.usage ?? {})),
+        ...(chatBody.providerMetadata !== undefined ? { providerMetadata: chatBody.providerMetadata } : {}),
+        response: { id: chatBody.id, modelId: chatBody.model, timestamp: nowIso(occurredAt) },
+        warnings: [],
+    };
+}
+// SSE stream of LanguageModelV3 stream parts: response-metadata first (the generation id rides
+// on it), reasoning-start/-delta/-end, then text-start/-delta/-end OR
+// tool-input-start/-delta/-end + a tool-call part, a finish part carrying finishReason + usage
+// (+ providerMetadata.gateway), and `data: [DONE]`.
+function streamV3(chatBody, sink, occurredAt) {
+    const choice = chatBody.choices[0];
+    const message = choice.message;
+    sink({ data: { type: 'response-metadata', id: chatBody.id, modelId: chatBody.model, timestamp: nowIso(occurredAt) } });
+    if (typeof message.reasoning === 'string') {
+        const reasoning = message.reasoning;
+        sink({ data: { type: 'reasoning-start', id: 'reasoning-0' } });
+        for (let i = 0; i < reasoning.length; i += 48) {
+            sink({ data: { type: 'reasoning-delta', id: 'reasoning-0', delta: reasoning.slice(i, i + 48) } });
+        }
+        sink({ data: { type: 'reasoning-end', id: 'reasoning-0' } });
+    }
+    if (Array.isArray(message.tool_calls)) {
+        for (const call of message.tool_calls) {
+            const fn = (call.function ?? {});
+            const id = String(call.id ?? '');
+            const args = String(fn.arguments ?? '{}');
+            sink({ data: { type: 'tool-input-start', id, toolName: String(fn.name ?? '') } });
+            sink({ data: { type: 'tool-input-delta', id, delta: args } });
+            sink({ data: { type: 'tool-input-end', id } });
+            sink({ data: { type: 'tool-call', toolCallId: id, toolName: String(fn.name ?? ''), input: args } });
+        }
+    }
+    else {
+        const text = String(message.content ?? '');
+        sink({ data: { type: 'text-start', id: 'text-0' } });
+        for (let i = 0; i < text.length; i += 24) {
+            sink({ data: { type: 'text-delta', id: 'text-0', delta: text.slice(i, i + 24) } });
+        }
+        sink({ data: { type: 'text-end', id: 'text-0' } });
+    }
+    sink({
+        data: {
+            type: 'finish',
+            finishReason: mapFinishReason(String(choice.finish_reason)),
+            usage: mapUsage((chatBody.usage ?? {})),
+            ...(chatBody.providerMetadata !== undefined ? { providerMetadata: chatBody.providerMetadata } : {}),
+        },
+    });
+    sink({ done: true });
+}
+// ── POST /v3/ai/language-model ────────────────────────────────────────────────────────────
+export async function handleV3LanguageModel(req, chat) {
+    const headers = req.headers ?? {};
+    const modelId = headers['ai-language-model-id'];
+    if (!modelId) {
+        return v3Error(400, "Invalid request: missing required header 'ai-language-model-id'", { param: 'ai-language-model-id', code: 'missing_parameter' });
+    }
+    const specVersion = headers['ai-language-model-specification-version'];
+    if (specVersion !== undefined && specVersion !== '3') {
+        return v3Error(400, `Unsupported ai-language-model-specification-version: ${specVersion} (the twin models specification version 3)`, { param: 'ai-language-model-specification-version' });
+    }
+    const streaming = headers['ai-language-model-streaming'] === 'true';
+    let options = {};
+    if (req.body?.trim()) {
+        try {
+            const parsed = JSON.parse(req.body);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                options = parsed;
+        }
+        catch {
+            return v3Error(400, 'request body must be a JSON object of LanguageModelV3 call options');
+        }
+    }
+    const translated = translateCallOptions(modelId, streaming, options);
+    if ('response' in translated)
+        return translated.response;
+    // Run the SAME chat machinery/kernel fold as /v1 (validation, routing, scenario scripting,
+    // generation record, credits) — but WITHOUT the OpenAI SSE sink: the v3 stream shape is
+    // emitted below from the unary body.
+    const { sseSink: _sseSink, ...chatReq } = req;
+    const result = await chat(chatReq, translated.params);
+    if (result.status !== 200) {
+        const errorBody = result.body;
+        const err = (errorBody?.error ?? {});
+        // The /v1 surface reports unknown models OpenAI-style (type invalid_request_error, code
+        // model_not_found); the AI SDK protocol's typed errors key on error.type, with the model id
+        // in an OBJECT param — remap so the SDK surfaces GatewayModelNotFoundError.
+        if (result.status === 404 && err.code === 'model_not_found') {
+            return v3Error(404, String(err.message ?? 'Model not found'), { type: 'model_not_found', param: { modelId } });
+        }
+        return result; // same { error: { message, type, param, code } } envelope the SDK parses
+    }
+    const chatBody = result.body;
+    if (streaming && req.sseSink)
+        streamV3(chatBody, req.sseSink, req.occurredAt);
+    return { status: 200, body: v3GenerateBody(chatBody, req.occurredAt) };
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createAiGatewayTwinServer } from "./ai-gateway-server.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+const scenario = optionValue(rest, '--scenario') || undefined; // scripted completions (JSON scenario file)
+if (cmd === 'serve') {
+    const server = await createAiGatewayTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+    process.stdout.write(`ai-gateway twin (deterministic stub output)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} at http://127.0.0.1:${server.port}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    const { checkAiGatewayConformance } = await import("./ai-gateway-conformance.js"); // lazy — dev-only
+    const report = await checkAiGatewayConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-ai-gateway serve|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+export { handleAiGatewayTwinRequest } from './ai-gateway-twin.js';
+export type { AiGatewayRequest, AiGatewayResponse, SseEvent, SseSink, GenerationRecord, GatewayRouting, ModelAttempt, ProviderAttempt } from './ai-gateway-types.js';
+export { createAiGatewayTwinFetch, createAiGatewayTwinServer, type AiGatewayTwinFetchOptions } from './ai-gateway-server.js';
+export { AI_GATEWAY_CATALOG, AI_GATEWAY_MODELS, findAiGatewayModel } from './ai-gateway-models.js';
+export type { AiGatewayModel, AiGatewayCatalogEntry } from './ai-gateway-models.js';
+export { contentToText, countPromptTokens, estimateTokens, lastUserText, stableHash, stubAssistantText, synthesizeJsonSchemaValue } from './ai-gateway-stub.js';
+export { aiGatewayScenarioAdapter, createAiGatewayScenarioEngine, loadAiGatewayScenarioDocument, realizeAiGatewayRespond } from './ai-gateway-scenario.js';
+export type { AiGatewayScenarioEngine, AiGatewayScenarioRequest, AiGatewayScenarioRespond, ScenarioToolCall, ScriptedResult } from './ai-gateway-scenario.js';
+export { aiGatewayRequestForAction, pullAiGatewayState, pushAiGatewayAction, syncAiGatewayFromReal, } from './ai-gateway-connector.js';
+export type { AiGatewayExecute } from './ai-gateway-connector.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,54 @@
+export { handleAiGatewayTwinRequest } from "./ai-gateway-twin.js";
+export { createAiGatewayTwinFetch, createAiGatewayTwinServer } from "./ai-gateway-server.js";
+export { AI_GATEWAY_CATALOG, AI_GATEWAY_MODELS, findAiGatewayModel } from "./ai-gateway-models.js";
+export { contentToText, countPromptTokens, estimateTokens, lastUserText, stableHash, stubAssistantText, synthesizeJsonSchemaValue } from "./ai-gateway-stub.js";
+export { aiGatewayScenarioAdapter, createAiGatewayScenarioEngine, loadAiGatewayScenarioDocument, realizeAiGatewayRespond } from "./ai-gateway-scenario.js";
+export { aiGatewayRequestForAction, pullAiGatewayState, pushAiGatewayAction, syncAiGatewayFromReal, } from "./ai-gateway-connector.js";
+import { registerPack } from '@volter/world-core';
+import { performAiGatewayAction, syncAiGatewayFromRemote } from "./ai-gateway-connector.js";
+export const pack = {
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+    // state system. Moved 2026-09-08. The gateway has NO write API: inference is the only "write", and
+    // replaying one would spend real money — so a recorded generation is RECONCILED against the gateway
+    // rather than written, and everything else settles with that reason.
+    protocol: '2',
+    refresh: { every: '15m', onDemand: { atMost: '60s' } },
+    stateSystem: { perform: performAiGatewayAction, refresh: syncAiGatewayFromRemote },
+    // the round trip: a chat completion — the twin records the generation it answered, which is the row a
+    // caller makes here, and a fresh one each time
+    roundTrip: { method: 'POST', path: '/v1/chat/completions', body: { model: 'openai/gpt-5', messages: [{ role: 'user', content: 'round trip' }] }, headers: { authorization: 'Bearer round-trip' } },
+    parityOrigin: 'http://twin',
+    vendor: 'ai-gateway',
+    transport: 'rest',
+    archetype: 'generative',
+    bin: 'world-ai-gateway',
+    // The subject types the twin SERVES from its own state — the R2 resource-level claim.
+    // `model` and `credits` are deliberately NOT here: both are connector-side projections
+    // that only `pullAiGatewayState` / `syncAiGatewayFromReal` fold in from a real gateway
+    // through an injected client, and no route reads either back — GET /v1/models serves the
+    // static AI_GATEWAY_MODELS catalog and GET /v1/credits a balance DERIVED from the
+    // generation rows, neither from a stored subject.
+    resources: ['generation'],
+    specSource: 'Vercel AI Gateway docs (OpenAI-compatible Chat Completions/Embeddings + REST API Reference: models/credits/generation/report) + the shipped @ai-sdk/gateway SDK for the /v3/ai AI SDK gateway protocol (config + language-model); model output is a deterministic stub',
+    description: 'Vercel AI Gateway twin — OpenAI-compatible chat completions/streaming with faithful provider-routing metadata, the AI SDK gateway protocol (/v3/ai: config + language-model for `createGateway`), models catalog with per-provider endpoints, billed embeddings, credits/generation/report surfaces; generative output is a labeled deterministic stub.',
+    // The gateway serves TWO API prefixes on one host: '/v1/' (OpenAI-compat + REST reference)
+    // and '/v3/ai' (the AI SDK gateway protocol `createGateway` speaks). `apiPathPrefix` is a
+    // single startsWith prefix (control-plane VendorRoute), so '/v' is the narrowest value that
+    // routes BOTH surfaces to the twin.
+    browserRouting: { apiPathPrefix: '/v', loaderHost: 'https://ai-gateway.vercel.sh' },
+    // INTERCEPTION RULING — hostsNone, the pack's own home for it: SDK is base-URL-configured
+    // (@ai-sdk/gateway baseURL / AI_GATEWAY_BASE_URL) — worlds wire the twin through explicit
+    // endpoint config; no injector entry grounded yet.
+    hostsNone: "SDK is base-URL-configured (@ai-sdk/gateway baseURL / AI_GATEWAY_BASE_URL) — worlds wire the twin through explicit endpoint config; no injector entry grounded yet",
+    // Adoption, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31).
+    adoption: {
+        // No Python distribution: Vercel's AI Gateway is addressed through the TypeScript AI SDK
+        // (`@ai-sdk/gateway`); a Python caller points an OpenAI-compatible client at the gateway base
+        // URL, and that distribution (`openai`) belongs to the openai pack.
+        pypi: [],
+        sdks: ['@ai-sdk/gateway'], envStems: ['AIGATEWAY'],
+    },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@volter/twin-ai-gateway",
+  "version": "0.1.0",
+  "description": "Local Vercel AI Gateway twin — a faithful, stateful local AI Gateway (ai-gateway.vercel.sh) your SDK talks to unmodified, over both wire protocols: the AI SDK gateway protocol at /v3/ai (createGateway / @ai-sdk/gateway) and the OpenAI-compatible /v1 surface. Chat completions/streaming/tool calls return deterministic labeled stubs with faithful provider-routing metadata; models, credits, generation lookup, and spend reporting are local. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "sdk",
+    "api",
+    "vercel",
+    "ai-gateway",
+    "llm"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/ai-gateway"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/ai-gateway#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-ai-gateway": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@ai-sdk/openai": "^3.0.29",
+    "ai": "^6.0.86",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}