@volter/twin-ai-gateway 0.1.0

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

@@ -0,0 +1,994 @@
+// Vercel AI Gateway twin — request handler. Routes the gateway's OpenAI-compatible surface
+// (POST /v1/chat/completions incl. SSE streaming/tools/structured outputs/reasoning/provider
+// routing, POST /v1/embeddings, GET /v1/models[...]) plus the gateway REST surface
+// (GET /v1/credits, GET /v1/generation, GET /v1/report) AND the AI SDK gateway protocol
+// (`@ai-sdk/gateway` / the `ai` package's `createGateway`: GET /v3/ai/config,
+// POST /v3/ai/language-model — see ai-gateway-v3.ts) onto the shared @volter/world-core kernel.
+// Model output is a deterministic, clearly-labeled stub; the protocol envelope — including
+// providerMetadata.gateway routing/cost metadata — is vendor-faithful per Vercel's docs
+// (docs/ai-gateway: "OpenAI Chat Completions API", "Advanced Configuration",
+// "Provider Filtering, Ordering & Sorting", "REST API Reference") and, for /v3/ai, per the
+// shipped @ai-sdk/gateway SDK itself.
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { AI_GATEWAY_MODELS, findAiGatewayModel } from "./ai-gateway-models.js";
+import { buildToolCall, contentToText, countPromptTokens, estimateTokens, lastUserText, normalizeTool, stableHash, stubAssistantText, synthesizeJsonSchemaValue, } from "./ai-gateway-stub.js";
+import { realizeAiGatewayRespond } from "./ai-gateway-scenario.js";
+import { handleV3LanguageModel, v3Config } from "./ai-gateway-v3.js";
+const SERVICE = 'ai-gateway';
+const FIXED_NOW = '1970-01-01T00:00:00.000Z';
+const STARTING_CREDITS = 100;
+function nowEpoch(occurredAt) {
+    return Math.floor(Date.parse(occurredAt ?? FIXED_NOW) / 1000);
+}
+function nowIso(occurredAt) {
+    return new Date(Date.parse(occurredAt ?? FIXED_NOW)).toISOString();
+}
+function parseJson(body) {
+    if (!body?.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(body);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+// Vendor error envelope: { error: { message, type, param?, code? } } — the documented AI
+// Gateway error response format (OpenAI-compatible docs, "Error handling").
+function error(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 } : {}),
+            },
+        },
+    };
+}
+function modelNotFound(model) {
+    return error(404, `The model '${model}' does not exist or you do not have access to it.`, { code: 'model_not_found', param: 'model' });
+}
+function readOnlyRejected() {
+    return error(405, 'This AI Gateway twin was started read-only; local writes are disabled.', { code: 'read_only' });
+}
+function rowsOfType(type, root) {
+    return projectResources(SERVICE, root)
+        .filter((r) => r.type === type)
+        .map((r) => {
+        const { type: _type, updatedAt: _updatedAt, ...rest } = r;
+        return rest;
+    });
+}
+function generationRows(root) {
+    return rowsOfType('generation', root);
+}
+function parseStringArray(raw, name) {
+    if (raw === undefined)
+        return {};
+    if (!Array.isArray(raw) || raw.some((s) => typeof s !== 'string' || !s)) {
+        return { error: error(400, `${name} must be an array of non-empty strings`, { param: name }) };
+    }
+    return { value: raw };
+}
+const SORT_OPTIONS = new Set(['cost', 'ttft', 'tps']);
+function parseGatewayOptions(params) {
+    const out = {};
+    const po = params.providerOptions;
+    if (po !== undefined && (!po || typeof po !== 'object' || Array.isArray(po))) {
+        return { error: error(400, 'providerOptions must be an object', { param: 'providerOptions' }) };
+    }
+    const gw = po ? po.gateway : undefined;
+    if (gw !== undefined && (!gw || typeof gw !== 'object' || Array.isArray(gw))) {
+        return { error: error(400, 'providerOptions.gateway must be an object', { param: 'providerOptions.gateway' }) };
+    }
+    const g = (gw ?? {});
+    for (const [key, name] of [['order', 'providerOptions.gateway.order'], ['only', 'providerOptions.gateway.only']]) {
+        const parsed = parseStringArray(g[key], name);
+        if ('error' in parsed)
+            return parsed;
+        if (parsed.value)
+            out[key] = parsed.value;
+    }
+    if (g.sort !== undefined) {
+        if (typeof g.sort !== 'string' || !SORT_OPTIONS.has(g.sort)) {
+            return { error: error(400, "providerOptions.gateway.sort must be one of 'cost', 'ttft', 'tps'", { param: 'providerOptions.gateway.sort' }) };
+        }
+        out.sort = g.sort;
+    }
+    // Model fallbacks: top-level `models` (Option 1) or providerOptions.gateway.models (Option 2).
+    const topModels = parseStringArray(params.models, 'models');
+    if ('error' in topModels)
+        return topModels;
+    const gwModels = parseStringArray(g.models, 'providerOptions.gateway.models');
+    if ('error' in gwModels)
+        return gwModels;
+    if (topModels.value && gwModels.value && JSON.stringify(topModels.value) !== JSON.stringify(gwModels.value)) {
+        return { error: error(400, 'models and providerOptions.gateway.models must resolve to the same value') };
+    }
+    const models = topModels.value ?? gwModels.value;
+    if (models)
+        out.models = models;
+    // Top-level `provider` shorthand — documented to support `sort`, equivalent to
+    // providerOptions.gateway.sort; conflicting values fail the request.
+    if (params.provider !== undefined) {
+        const p = params.provider;
+        if (!p || typeof p !== 'object' || Array.isArray(p)) {
+            return { error: error(400, 'provider must be an object', { param: 'provider' }) };
+        }
+        const sort = p.sort;
+        if (sort !== undefined) {
+            if (typeof sort !== 'string' || !SORT_OPTIONS.has(sort)) {
+                return { error: error(400, "provider.sort must be one of 'cost', 'ttft', 'tps'", { param: 'provider.sort' }) };
+            }
+            if (out.sort !== undefined && out.sort !== sort) {
+                return { error: error(400, 'provider.sort and providerOptions.gateway.sort must resolve to the same value') };
+            }
+            out.sort = sort;
+        }
+    }
+    if (g.byok !== undefined) {
+        const byok = g.byok;
+        if (!byok || typeof byok !== 'object' || Array.isArray(byok)) {
+            return { error: error(400, 'providerOptions.gateway.byok must be a record of provider slug to credential arrays', { param: 'providerOptions.gateway.byok' }) };
+        }
+        for (const [slug, creds] of Object.entries(byok)) {
+            if (!Array.isArray(creds) || creds.length === 0 || creds.some((c) => !c || typeof c !== 'object' || Array.isArray(c))) {
+                return { error: error(400, `providerOptions.gateway.byok.${slug} must be a non-empty array of credential objects`, { param: 'providerOptions.gateway.byok' }) };
+            }
+        }
+        out.byok = byok;
+    }
+    if (g.caching !== undefined) {
+        if (g.caching !== 'auto') {
+            return { error: error(400, "providerOptions.gateway.caching must be 'auto'", { param: 'providerOptions.gateway.caching' }) };
+        }
+        out.caching = 'auto';
+    }
+    return { value: out };
+}
+// Deterministic per-provider routing metric (twin simulation of the gateway's live cost/latency/
+// throughput telemetry — stable across runs, seeded from the provider slug).
+function providerMetric(provider, option) {
+    const seed = parseInt(stableHash(`${option}:${provider}`).slice(0, 6), 16);
+    if (option === 'cost')
+        return Number((0.001 + (seed % 500) / 100000).toFixed(6));
+    if (option === 'ttft')
+        return 200 + (seed % 800);
+    return 20 + (seed % 120); // tps
+}
+function resolveRouting(modelId, opts, occurredAt) {
+    const startMs = Date.parse(occurredAt ?? FIXED_NOW);
+    const modelAttempts = [];
+    // Model fallback chain: primary first, then the `models` fallbacks in order. In the twin the
+    // deterministic failure mode for a model attempt is "not in the catalog".
+    const chain = [modelId, ...(opts.models ?? [])];
+    let entry;
+    let resolvedModelId = modelId;
+    for (const candidate of chain) {
+        const found = findAiGatewayModel(candidate);
+        if (found) {
+            entry = found;
+            resolvedModelId = candidate;
+            break;
+        }
+        modelAttempts.push({ modelId: candidate, canonicalSlug: candidate, success: false, providerAttemptCount: 0, providerAttempts: [] });
+    }
+    if (!entry)
+        return { response: modelNotFound(modelId) };
+    let allowed = [...entry.providers];
+    if (opts.only) {
+        allowed = allowed.filter((p) => opts.only.includes(p));
+        if (allowed.length === 0) {
+            return {
+                response: error(400, `No allowed providers are available for model '${resolvedModelId}'. Allowed providers: ${opts.only.join(', ')}. Providers serving this model: ${entry.providers.join(', ')}.`, { code: 'no_available_providers' }),
+            };
+        }
+    }
+    let sortMetrics;
+    if (opts.sort) {
+        const metrics = {};
+        for (const p of allowed)
+            metrics[p] = providerMetric(p, opts.sort);
+        const dir = opts.sort === 'tps' ? -1 : 1; // tps: highest first; cost/ttft: lowest first
+        allowed = [...allowed].sort((a, b) => dir * ((metrics[a] ?? 0) - (metrics[b] ?? 0)) || a.localeCompare(b));
+        sortMetrics = metrics;
+    }
+    if (opts.order) {
+        // Documented combination semantics: `order` providers are promoted to the front, the rest
+        // keep the (possibly sorted) order — and `executionOrder` below reports the FINAL attempted
+        // order, promotion included.
+        const promoted = opts.order.filter((p) => allowed.includes(p));
+        allowed = [...promoted, ...allowed.filter((p) => !promoted.includes(p))];
+    }
+    const sortMeta = opts.sort && sortMetrics
+        ? { option: opts.sort, executionOrder: [...allowed], metrics: sortMetrics, deprioritizedProviders: [] }
+        : undefined;
+    const resolvedProvider = allowed[0];
+    const credentialType = opts.byok && Object.prototype.hasOwnProperty.call(opts.byok, resolvedProvider) ? 'byok' : 'system';
+    const providerApiModelId = resolvedModelId.slice(resolvedModelId.indexOf('/') + 1);
+    const routing = {
+        originalModelId: modelId,
+        resolvedProvider,
+        resolvedProviderApiModelId: providerApiModelId,
+        fallbacksAvailable: allowed.slice(1),
+        planningReasoning: `${credentialType === 'byok' ? 'BYOK' : 'System'} credentials planned for: ${resolvedProvider}. Total execution order: ${allowed.map((p) => `${p}(${opts.byok && Object.prototype.hasOwnProperty.call(opts.byok, p) ? 'byok' : 'system'})`).join(', ')}`,
+        canonicalSlug: resolvedModelId,
+        finalProvider: resolvedProvider,
+        modelAttemptCount: modelAttempts.length + 1,
+        modelAttempts: [
+            ...modelAttempts,
+            {
+                modelId: `${resolvedProvider}:${providerApiModelId}`,
+                canonicalSlug: resolvedModelId,
+                success: true,
+                providerAttemptCount: 1,
+                providerAttempts: [{
+                        provider: resolvedProvider,
+                        providerApiModelId,
+                        credentialType,
+                        success: true,
+                        startTime: startMs,
+                        endTime: startMs + 1000,
+                    }],
+            },
+        ],
+        totalProviderAttemptCount: 1,
+        ...(sortMeta ? { sort: sortMeta } : {}),
+    };
+    return { entry, routing, credentialType };
+}
+const MESSAGE_ROLES = new Set(['system', 'developer', 'user', 'assistant', 'tool']);
+const CONTENT_PART_TYPES = new Set(['text', 'image_url', 'file']);
+function validateMessages(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { response: error(400, 'messages must be a non-empty array', { param: 'messages', code: 'missing_parameter' }) };
+    }
+    for (const m of raw) {
+        if (!m || typeof m !== 'object' || typeof m.role !== 'string') {
+            return { response: error(400, 'each message must include a role', { param: 'messages' }) };
+        }
+        const message = m;
+        if (!MESSAGE_ROLES.has(message.role)) {
+            return { response: error(400, `unsupported message role: ${message.role}`, { param: 'messages' }) };
+        }
+        if (message.role === 'tool' && (typeof message.tool_call_id !== 'string' || !message.tool_call_id)) {
+            return { response: error(400, "messages with role 'tool' must include tool_call_id", { param: 'messages' }) };
+        }
+        const hasContent = typeof message.content === 'string'
+            ? true
+            : Array.isArray(message.content) ? message.content.length > 0 : message.tool_calls !== undefined;
+        if (!hasContent) {
+            return { response: error(400, 'each message must include content or tool_calls', { param: 'messages' }) };
+        }
+        if (Array.isArray(message.content)) {
+            for (const part of message.content) {
+                const type = part?.type;
+                if (typeof type !== 'string' || !CONTENT_PART_TYPES.has(type)) {
+                    return { response: error(400, `unsupported content part type: ${String(type)} (supported: text, image_url, file)`, { param: 'messages' }) };
+                }
+                if (type === 'image_url') {
+                    const url = part.image_url?.url;
+                    if (typeof url !== 'string' || !url)
+                        return { response: error(400, 'image_url parts must include image_url.url', { param: 'messages' }) };
+                }
+                if (type === 'file') {
+                    const file = part.file;
+                    if (!file || typeof file !== 'object' || typeof file.data !== 'string') {
+                        return { response: error(400, 'file parts must include file.data', { param: 'messages' }) };
+                    }
+                }
+            }
+        }
+    }
+    return { messages: raw };
+}
+function validateSampling(params) {
+    const inRange = (v, min, max) => typeof v === 'number' && v >= min && v <= max;
+    if (params.temperature !== undefined && !inRange(params.temperature, 0, 2)) {
+        return error(400, 'temperature must be a number between 0 and 2', { param: 'temperature' });
+    }
+    if (params.top_p !== undefined && !inRange(params.top_p, 0, 1)) {
+        return error(400, 'top_p must be a number between 0 and 1', { param: 'top_p' });
+    }
+    if (params.frequency_penalty !== undefined && !inRange(params.frequency_penalty, -2, 2)) {
+        return error(400, 'frequency_penalty must be a number between -2 and 2', { param: 'frequency_penalty' });
+    }
+    if (params.presence_penalty !== undefined && !inRange(params.presence_penalty, -2, 2)) {
+        return error(400, 'presence_penalty must be a number between -2 and 2', { param: 'presence_penalty' });
+    }
+    if (params.stop !== undefined && typeof params.stop !== 'string' && !(Array.isArray(params.stop) && params.stop.every((s) => typeof s === 'string'))) {
+        return error(400, 'stop must be a string or an array of strings', { param: 'stop' });
+    }
+    return null;
+}
+// response_format per the gateway docs: OpenAI json_schema format, legacy `json` format, or text.
+function parseResponseFormat(raw) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { error: error(400, 'response_format must be an object', { param: 'response_format' }) };
+    }
+    const rf = raw;
+    // The gateway implements the OpenAI Chat Completions spec ('text'/'json_object'/'json_schema')
+    // plus its own documented legacy 'json' format.
+    if (rf.type !== 'text' && rf.type !== 'json_object' && rf.type !== 'json_schema' && rf.type !== 'json') {
+        return { error: error(400, "response_format.type must be one of 'text', 'json_object', 'json_schema', 'json'", { param: 'response_format' }) };
+    }
+    if (rf.type === 'json_schema') {
+        const js = rf.json_schema;
+        if (!js || typeof js !== 'object' || typeof js.name !== 'string') {
+            return { error: error(400, 'response_format.json_schema requires a name', { param: 'response_format' }) };
+        }
+    }
+    return { value: rf };
+}
+const EFFORTS = { none: 0, minimal: 0.1, low: 0.2, medium: 0.5, high: 0.8, xhigh: 0.95 };
+function parseReasoning(raw) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { error: error(400, 'reasoning must be an object', { param: 'reasoning' }) };
+    }
+    const r = raw;
+    if (r.effort !== undefined && (typeof r.effort !== 'string' || !(r.effort in EFFORTS))) {
+        return { error: error(400, "reasoning.effort must be one of 'none', 'minimal', 'low', 'medium', 'high', 'xhigh'", { param: 'reasoning.effort' }) };
+    }
+    if (r.max_tokens !== undefined && (!Number.isInteger(r.max_tokens) || r.max_tokens < 0)) {
+        return { error: error(400, 'reasoning.max_tokens must be a non-negative integer', { param: 'reasoning.max_tokens' }) };
+    }
+    // Documented as mutually exclusive ("Advanced Configuration", reasoning parameters).
+    if (r.effort !== undefined && r.max_tokens !== undefined) {
+        return { error: error(400, 'reasoning.effort and reasoning.max_tokens are mutually exclusive', { param: 'reasoning' }) };
+    }
+    return {
+        value: {
+            ...(r.enabled !== undefined ? { enabled: r.enabled === true } : {}),
+            ...(r.max_tokens !== undefined ? { max_tokens: Number(r.max_tokens) } : {}),
+            ...(r.effort !== undefined ? { effort: String(r.effort) } : {}),
+            ...(r.exclude !== undefined ? { exclude: r.exclude === true } : {}),
+        },
+    };
+}
+function reasoningTokens(args) {
+    const r = args.reasoning;
+    if (!r)
+        return 0;
+    if (r.effort === 'none')
+        return 0;
+    if (r.max_tokens !== undefined)
+        return r.max_tokens;
+    if (r.effort !== undefined)
+        return Math.round((args.maxTokens ?? 1000) * (EFFORTS[r.effort] ?? 0));
+    return r.enabled ? 256 : 0;
+}
+function reasoningActive(args) {
+    const r = args.reasoning;
+    if (!r)
+        return false;
+    if (r.effort === 'none')
+        return false;
+    return r.enabled === true || r.effort !== undefined || r.max_tokens !== undefined;
+}
+// cache_control markers (manual prompt caching, Anthropic-style, documented in the gateway's
+// "Advanced Configuration" → Prompt caching): marked prompt tokens report as cached.
+function cachedPromptTokens(messages) {
+    let cached = 0;
+    for (const message of messages) {
+        const marked = message.cache_control !== undefined ||
+            (Array.isArray(message.content) && message.content.some((p) => p && typeof p === 'object' && 'cache_control' in p));
+        if (marked)
+            cached += estimateTokens(`${message.role}: ${contentToText(message.content)}`);
+    }
+    return cached;
+}
+function validateChat(params) {
+    if (typeof params.model !== 'string' || !params.model) {
+        return { response: error(400, "Invalid request: missing required parameter 'model'", { param: 'model', code: 'missing_parameter' }) };
+    }
+    const messages = validateMessages(params.messages);
+    if ('response' in messages)
+        return messages;
+    const sampling = validateSampling(params);
+    if (sampling)
+        return { response: sampling };
+    const rawMax = params.max_completion_tokens ?? params.max_tokens;
+    if (rawMax !== undefined && (!Number.isInteger(rawMax) || rawMax < 1)) {
+        return { response: error(400, 'max_tokens must be an integer >= 1', { param: 'max_tokens' }) };
+    }
+    if (params.n !== undefined && (!Number.isInteger(params.n) || params.n < 1)) {
+        return { response: error(400, 'n must be an integer >= 1', { param: 'n' }) };
+    }
+    if (params.tools !== undefined && !Array.isArray(params.tools)) {
+        return { response: error(400, 'tools must be an array', { param: 'tools' }) };
+    }
+    if (params.tools !== undefined) {
+        for (const tool of params.tools) {
+            if (!normalizeTool(tool))
+                return { response: error(400, 'each tool must be a function tool with a name', { param: 'tools' }) };
+        }
+    }
+    if (params.tool_choice !== undefined) {
+        const tc = params.tool_choice;
+        const isString = tc === 'auto' || tc === 'none' || tc === 'required';
+        const isFn = !!tc && typeof tc === 'object' && tc.type === 'function' &&
+            typeof tc.function?.name === 'string';
+        if (!isString && !isFn) {
+            return { response: error(400, "tool_choice must be 'auto', 'none', 'required', or a named function", { param: 'tool_choice' }) };
+        }
+    }
+    const rf = parseResponseFormat(params.response_format);
+    if ('error' in rf)
+        return { response: rf.error };
+    const reasoning = parseReasoning(params.reasoning);
+    if ('error' in reasoning)
+        return { response: reasoning.error };
+    const gateway = parseGatewayOptions(params);
+    if ('error' in gateway)
+        return { response: gateway.error };
+    const msgs = messages.messages;
+    return {
+        args: {
+            model: params.model,
+            messages: msgs,
+            stream: params.stream === true,
+            n: params.n === undefined ? 1 : Number(params.n),
+            ...(rawMax !== undefined ? { maxTokens: Number(rawMax) } : {}),
+            ...(params.tools !== undefined ? { tools: params.tools } : {}),
+            ...(params.tool_choice !== undefined ? { toolChoice: params.tool_choice } : {}),
+            ...(rf.value ? { responseFormat: rf.value } : {}),
+            ...(reasoning.value ? { reasoning: reasoning.value } : {}),
+            cachedTokens: Math.min(cachedPromptTokens(msgs), countPromptTokens(msgs)),
+            gateway: gateway.value,
+        },
+    };
+}
+function chooseTool(args) {
+    if (!args.tools || args.tools.length === 0 || args.toolChoice === 'none')
+        return { none: true };
+    if (args.toolChoice && typeof args.toolChoice === 'object') {
+        const wanted = args.toolChoice.function.name;
+        const found = args.tools.map(normalizeTool).find((t) => t?.name === wanted);
+        if (!found)
+            return { response: error(400, `tool_choice function '${wanted}' is not present in tools`, { param: 'tool_choice' }) };
+        return { tool: found };
+    }
+    return { tool: normalizeTool(args.tools[0]) };
+}
+function structuredJsonText(args) {
+    const rf = args.responseFormat;
+    if (!rf || rf.type === 'text')
+        return null;
+    if (rf.type === 'json_schema') {
+        const js = rf.json_schema;
+        return JSON.stringify(synthesizeJsonSchemaValue(js.schema));
+    }
+    // 'json_object' (OpenAI spec) and the legacy { type: 'json', schema?, name?, description? } format
+    if (rf.schema !== undefined)
+        return JSON.stringify(synthesizeJsonSchemaValue(rf.schema));
+    return JSON.stringify({ twin_stub: true, echo: lastUserText(args.messages) || 'empty prompt', model: args.model });
+}
+function reasoningDetails(modelId, text) {
+    if (modelId.startsWith('anthropic/')) {
+        return [{ type: 'reasoning.text', text, signature: `twin-signature-${stableHash(text)}`, format: 'anthropic-claude-v1', index: 0 }];
+    }
+    if (modelId.startsWith('openai/')) {
+        return [
+            { type: 'reasoning.summary', summary: text, format: 'openai-responses-v1', index: 0 },
+            { type: 'reasoning.encrypted', data: `twin-encrypted-${stableHash(text)}`, format: 'openai-responses-v1', index: 1 },
+        ];
+    }
+    return [{ type: 'reasoning.text', text, format: 'unknown', index: 0 }];
+}
+function buildChoiceMessage(args, resolvedModelId, scripted) {
+    const message = { role: 'assistant' };
+    let finishReason = 'stop';
+    let completionTokens = 0;
+    let reasoningText = null;
+    let reasoningTokenCount = 0;
+    if (scripted) {
+        if (scripted.reasoning !== null)
+            reasoningText = scripted.reasoning;
+        if (scripted.toolCalls.length > 0) {
+            message.content = scripted.text; // null unless the rule also scripts text
+            message.tool_calls = scripted.toolCalls.map((tc, i) => ({
+                id: tc.id ?? `call_twin_${stableHash(`${tc.name}:${i}`).slice(0, 8)}`,
+                type: 'function',
+                function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+            }));
+            completionTokens = estimateTokens(JSON.stringify(message.tool_calls));
+        }
+        else {
+            message.content = scripted.text ?? '';
+            completionTokens = estimateTokens(String(message.content));
+        }
+        finishReason = scripted.finishReason;
+    }
+    else {
+        const chosen = chooseTool(args);
+        if ('response' in chosen)
+            return chosen;
+        if ('tool' in chosen && chosen.tool) {
+            const call = buildToolCall(chosen.tool);
+            message.content = null;
+            message.tool_calls = [call];
+            finishReason = 'tool_calls';
+            completionTokens = estimateTokens(JSON.stringify(call));
+        }
+        else {
+            let text = structuredJsonText(args) ?? stubAssistantText(args.messages, args.model);
+            if (args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens) {
+                text = text.slice(0, args.maxTokens * 4);
+                finishReason = 'length';
+            }
+            message.content = text;
+            completionTokens = estimateTokens(text);
+        }
+        if (reasoningActive(args)) {
+            reasoningText = `[twin-stub:ai-gateway:reasoning] deterministic reasoning trace for ${args.model}`;
+            reasoningTokenCount = reasoningTokens(args);
+        }
+    }
+    if (scripted?.reasoning != null)
+        reasoningTokenCount = estimateTokens(scripted.reasoning);
+    if (reasoningText !== null && args.reasoning?.exclude !== true) {
+        message.reasoning = reasoningText;
+        message.reasoning_details = reasoningDetails(resolvedModelId, reasoningText);
+    }
+    return { message, finishReason, completionTokens, reasoningTokenCount };
+}
+function formatUsd(n) {
+    const s = n.toFixed(10).replace(/0+$/, '');
+    const [int, dec = ''] = s.split('.');
+    return `${int}.${dec.length >= 2 ? dec : (dec + '00').slice(0, 2)}`;
+}
+function generationCost(entry, promptTokens, completionTokens) {
+    const input = Number(entry.model.pricing.input);
+    const output = Number(entry.model.pricing.output ?? '0');
+    return Number((promptTokens * input + completionTokens * output).toFixed(10));
+}
+// Generation ids are UNIQUE per generation (docs: `gen_<ulid>`): the seed includes a per-root
+// monotonic sequence (the count of already-recorded generations), so identical back-to-back
+// requests still mint distinct ids and the kernel's (type, id) resolution can never return a
+// different request's record. Deterministic: same request at the same log position → same id.
+function generationId(seed, seq) {
+    const s = [seed, seq];
+    const hex = `${stableHash(s)}${stableHash([s, 'gen'])}${stableHash([s, 'id'])}${stableHash([s, 'x'])}`;
+    return `gen_${hex.toUpperCase().slice(0, 26)}`;
+}
+async function recordGeneration(record, root, occurredAt) {
+    await applyTwinWrite(SERVICE, {
+        operation: 'generation.record',
+        subjectType: 'generation',
+        subjectId: record.id,
+        fields: record,
+        occurredAt: occurredAt ?? FIXED_NOW,
+        actor: { kind: 'system' },
+    }, root);
+}
+async function chatCompletion(req, params) {
+    const validated = validateChat(params);
+    if ('response' in validated)
+        return validated.response;
+    const args = validated.args;
+    const resolved = resolveRouting(args.model, args.gateway, req.occurredAt);
+    if ('response' in resolved)
+        return resolved.response;
+    const { entry, routing, credentialType } = resolved;
+    let missTeach = '';
+    const scripted = req.scenarioEngine
+        ? (() => {
+            const decision = req.scenarioEngine.next({ model: args.model, messages: args.messages, ...(args.tools ? { tools: args.tools } : {}) });
+            if (decision.kind === 'handler')
+                return realizeAiGatewayRespond(decision.respond);
+            missTeach = `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/ai-gateway.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]`;
+            return null;
+        })()
+        : null;
+    const built = buildChoiceMessage(args, entry.model.id, scripted);
+    if ('response' in built)
+        return built.response;
+    if (missTeach && typeof built.message.content === 'string') {
+        built.message.content += missTeach;
+    }
+    const promptTokens = countPromptTokens(args.messages);
+    const perChoiceTokens = built.completionTokens + built.reasoningTokenCount;
+    const completionTokens = perChoiceTokens * args.n;
+    const marketCost = generationCost(entry, promptTokens, completionTokens);
+    // BYOK accounting per the docs: the provider bills the tokens, so the gateway's total_cost
+    // for the generation is 0.00 and the market price is reported as upstream_inference_cost.
+    const isByok = credentialType === 'byok';
+    const totalCost = isByok ? 0 : marketCost;
+    // ATOMICITY ASSUMPTION: no `await` may sit between this seq read and the recordGeneration()
+    // write below — that synchronous prefix is what makes concurrent identical requests mint
+    // unique ids (verified: 25 concurrent identical POSTs → 25 unique ids). An added await here
+    // would reintroduce the id-collision race.
+    const seq = generationRows(req.root).length;
+    const id = generationId({ args, promptTokens }, seq);
+    const usage = {
+        prompt_tokens: promptTokens,
+        completion_tokens: completionTokens,
+        total_tokens: promptTokens + completionTokens,
+        ...(args.cachedTokens > 0 ? { prompt_tokens_details: { cached_tokens: args.cachedTokens } } : {}),
+        ...(built.reasoningTokenCount > 0 ? { completion_tokens_details: { reasoning_tokens: built.reasoningTokenCount * args.n } } : {}),
+    };
+    const body = {
+        id,
+        object: 'chat.completion',
+        created: nowEpoch(req.occurredAt),
+        model: entry.model.id,
+        choices: Array.from({ length: args.n }, (_u, index) => ({ index, message: built.message, finish_reason: built.finishReason })),
+        usage,
+        providerMetadata: {
+            gateway: {
+                routing,
+                cost: formatUsd(totalCost),
+                marketCost: formatUsd(marketCost),
+                generationId: id,
+            },
+        },
+    };
+    await recordGeneration({
+        id,
+        total_cost: totalCost,
+        upstream_inference_cost: isByok ? marketCost : 0,
+        usage: totalCost,
+        created_at: nowIso(req.occurredAt),
+        model: entry.model.id,
+        is_byok: isByok,
+        provider_name: routing.finalProvider,
+        streamed: args.stream,
+        finish_reason: built.finishReason,
+        latency: 200,
+        generation_time: 1000 + completionTokens * 10,
+        tokens_prompt: promptTokens,
+        tokens_completion: completionTokens,
+        native_tokens_prompt: promptTokens,
+        native_tokens_completion: completionTokens,
+        native_tokens_reasoning: built.reasoningTokenCount * args.n,
+        native_tokens_cached: args.cachedTokens,
+        native_tokens_cache_creation: 0,
+        billable_web_search_calls: 0,
+    }, req.root, req.occurredAt);
+    if (args.stream && req.sseSink)
+        streamChat(body, req.sseSink);
+    return { status: 200, body };
+}
+// SSE streaming: OpenAI chat.completion.chunk envelope; the generation id rides on every chunk
+// starting with the FIRST (the gateway documents injecting the generation id into the first
+// content chunk); reasoning streams via delta.reasoning (+ delta.reasoning_details); ends with
+// a finish_reason + usage chunk and `data: [DONE]`. EVERY choice streams (OpenAI semantics:
+// each chunk carries one element of `choices` with its own index), so streaming with n>1 emits
+// the same n choices the unary body carries and bills — not just index 0. The final chunk (the
+// last choice's finish) carries the n-scaled usage.
+function streamChat(body, sink) {
+    const base = { id: body.id, object: 'chat.completion.chunk', created: body.created, model: body.model };
+    const choices = body.choices;
+    choices.forEach((choice, choiceIndex) => {
+        const message = choice.message;
+        sink({ data: { ...base, choices: [{ index: choiceIndex, delta: { role: 'assistant' }, finish_reason: null }] } });
+        if (typeof message.reasoning === 'string') {
+            const reasoning = message.reasoning;
+            for (let i = 0; i < reasoning.length; i += 48) {
+                const slice = reasoning.slice(i, i + 48);
+                sink({ data: { ...base, choices: [{ index: choiceIndex, delta: { reasoning: slice, ...(i === 0 && message.reasoning_details ? { reasoning_details: message.reasoning_details } : {}) }, finish_reason: null }] } });
+            }
+        }
+        if (Array.isArray(message.tool_calls)) {
+            message.tool_calls.forEach((call, index) => {
+                const fn = call.function;
+                sink({ data: { ...base, choices: [{ index: choiceIndex, delta: { tool_calls: [{ index, id: call.id, type: 'function', function: { name: fn.name, arguments: '' } }] }, finish_reason: null }] } });
+                sink({ data: { ...base, choices: [{ index: choiceIndex, delta: { tool_calls: [{ index, function: { arguments: fn.arguments } }] }, finish_reason: null }] } });
+            });
+        }
+        else {
+            const text = String(message.content ?? '');
+            for (let i = 0; i < text.length; i += 24) {
+                sink({ data: { ...base, choices: [{ index: choiceIndex, delta: { content: text.slice(i, i + 24) }, finish_reason: null }] } });
+            }
+        }
+        const isLast = choiceIndex === choices.length - 1;
+        sink({ data: { ...base, choices: [{ index: choiceIndex, delta: {}, finish_reason: choice.finish_reason }], ...(isLast ? { usage: body.usage } : {}) } });
+    });
+    sink({ done: true });
+}
+// ── embeddings ────────────────────────────────────────────────────────────────────────────
+// Matches the real default dimension of openai/text-embedding-3-small, so client code that
+// sizes buffers/vector columns off the twin doesn't break against the vendor.
+const DEFAULT_EMBED_DIM = 1536;
+function embedVector(text, dim) {
+    // Deterministic pseudo-embedding seeded from the text hash; L2-normalized.
+    const seed = parseInt(stableHash(text), 16) || 1;
+    let x = seed;
+    const raw = Array.from({ length: dim }, () => {
+        x = (Math.imul(x, 1103515245) + 12345) & 0x7fffffff;
+        return (x / 0x7fffffff) * 2 - 1;
+    });
+    const norm = Math.sqrt(raw.reduce((s, v) => s + v * v, 0)) || 1;
+    return raw.map((v) => Number((v / norm).toFixed(6)));
+}
+async function createEmbeddings(req, params) {
+    if (typeof params.model !== 'string' || !params.model) {
+        return error(400, "Invalid request: missing required parameter 'model'", { param: 'model', code: 'missing_parameter' });
+    }
+    const entry = findAiGatewayModel(params.model);
+    if (!entry)
+        return modelNotFound(params.model);
+    if (entry.model.type !== 'embedding') {
+        return error(400, `The model '${params.model}' is not an embedding model.`, { param: 'model' });
+    }
+    if (params.input === undefined)
+        return error(400, 'input is required', { param: 'input', code: 'missing_parameter' });
+    const inputs = Array.isArray(params.input) ? params.input : [params.input];
+    if (inputs.length === 0 || inputs.some((i) => typeof i !== 'string')) {
+        return error(400, 'input must be a non-empty string or array of strings', { param: 'input' });
+    }
+    let dim = DEFAULT_EMBED_DIM;
+    if (params.dimensions !== undefined) {
+        if (!Number.isInteger(params.dimensions) || params.dimensions < 1 || params.dimensions > 4096) {
+            return error(400, 'dimensions must be an integer between 1 and 4096', { param: 'dimensions' });
+        }
+        dim = params.dimensions;
+    }
+    const gateway = parseGatewayOptions(params);
+    if ('error' in gateway)
+        return gateway.error;
+    const resolved = resolveRouting(entry.model.id, gateway.value, req.occurredAt);
+    if ('response' in resolved)
+        return resolved.response;
+    const data = inputs.map((text, index) => ({ object: 'embedding', index, embedding: embedVector(`${text}:${dim}`, dim) }));
+    const promptTokens = inputs.reduce((s, t) => s + estimateTokens(t), 0);
+    const marketCost = Number((promptTokens * Number(entry.model.pricing.input)).toFixed(10));
+    // The real gateway BILLS embeddings — so the twin records a generation for every embeddings
+    // call through the same kernel fold as chat: credits (/v1/credits), the spend report
+    // (/v1/report), and generation lookup (/v1/generation?id) all move. Same BYOK rule as chat:
+    // BYOK requests record total_cost 0 with the market price as upstream_inference_cost.
+    const isByok = resolved.credentialType === 'byok';
+    const totalCost = isByok ? 0 : marketCost;
+    // Same ATOMICITY rule as chatCompletion: no `await` between this seq read and the
+    // recordGeneration() write, so concurrent identical requests still mint unique ids.
+    const seq = generationRows(req.root).length;
+    const id = generationId({ embeddings: { model: entry.model.id, inputs, dim }, promptTokens }, seq);
+    await recordGeneration({
+        id,
+        total_cost: totalCost,
+        upstream_inference_cost: isByok ? marketCost : 0,
+        usage: totalCost,
+        created_at: nowIso(req.occurredAt),
+        model: entry.model.id,
+        is_byok: isByok,
+        provider_name: resolved.routing.finalProvider,
+        streamed: false,
+        finish_reason: 'stop',
+        latency: 200,
+        generation_time: 100 + promptTokens,
+        tokens_prompt: promptTokens,
+        tokens_completion: 0,
+        native_tokens_prompt: promptTokens,
+        native_tokens_completion: 0,
+        native_tokens_reasoning: 0,
+        native_tokens_cached: 0,
+        native_tokens_cache_creation: 0,
+        billable_web_search_calls: 0,
+    }, req.root, req.occurredAt);
+    return {
+        status: 200,
+        body: {
+            object: 'list',
+            data,
+            model: entry.model.id,
+            usage: { prompt_tokens: promptTokens, total_tokens: promptTokens },
+            providerMetadata: { gateway: { routing: resolved.routing, cost: formatUsd(totalCost), marketCost: formatUsd(marketCost), generationId: id } },
+        },
+    };
+}
+// ── models / credits / generation / report ────────────────────────────────────────────────
+function modelEndpoints(entry) {
+    const m = entry.model;
+    return {
+        status: 200,
+        body: {
+            data: {
+                id: m.id,
+                name: m.name,
+                created: m.created,
+                released: m.released,
+                description: m.description,
+                architecture: {
+                    tokenizer: null,
+                    instruct_type: null,
+                    modality: m.tags.includes('vision') ? 'text+image→text' : 'text→text',
+                    input_modalities: m.tags.includes('vision') ? ['text', 'image'] : ['text'],
+                    output_modalities: ['text'],
+                },
+                endpoints: entry.providers.map((provider) => ({
+                    name: `${provider} | ${m.id}`,
+                    model_name: m.name,
+                    context_length: m.context_window,
+                    pricing: {
+                        prompt: m.pricing.input,
+                        completion: m.pricing.output ?? '0',
+                        ...(m.pricing.input_cache_read ? { input_cache_read: m.pricing.input_cache_read } : {}),
+                        ...(m.pricing.input_cache_write ? { input_cache_write: m.pricing.input_cache_write } : {}),
+                    },
+                    provider_name: provider,
+                    max_completion_tokens: m.max_tokens,
+                    supported_parameters: ['max_tokens', 'temperature', 'tools', 'reasoning'],
+                    status: 0,
+                    uptime_last_15m: 100,
+                    uptime_last_1h: 100,
+                    uptime_last_1d: 100,
+                    throughput_last_1h: { p50: providerMetric(provider, 'tps'), p95: providerMetric(provider, 'tps') + 5 },
+                    latency_last_1h: { p50: providerMetric(provider, 'ttft'), p95: providerMetric(provider, 'ttft') + 200 },
+                    supports_implicit_caching: false,
+                })),
+            },
+        },
+    };
+}
+function credits(root) {
+    const used = generationRows(root).reduce((sum, g) => sum + g.total_cost, 0);
+    return {
+        status: 200,
+        body: { balance: formatUsd(STARTING_CREDITS - used), total_used: formatUsd(used) },
+    };
+}
+function generationLookup(req, url) {
+    const id = url.searchParams.get('id');
+    if (!id)
+        return error(400, "Invalid request: missing required parameter 'id'", { param: 'id', code: 'missing_parameter' });
+    const found = generationRows(req.root).find((g) => g.id === id);
+    if (!found)
+        return error(404, `Generation '${id}' not found.`, { code: 'not_found' });
+    return { status: 200, body: { data: found } };
+}
+// Spend report (GET /v1/report), per the documented Custom Reporting response format: a
+// `results` array whose rows carry the grouping field (day/model/provider/credential_type/…)
+// plus the metric fields (total_cost/market_cost/surcharge_cost/gateway_cost, token counts,
+// request_count). The twin records no per-request user/tag/api-key attribution yet (see the
+// `ai-gateway.chat.reporting_tags` / `ai-gateway.report.attribution_groupings` todos), so
+// attribution-keyed groupings and filters resolve to empty result sets rather than fabricating
+// attribution that was never recorded.
+const REPORT_GROUP_BY = new Set(['day', 'user', 'model', 'tag', 'provider', 'credential_type', 'zero_data_retention', 'api_key_name']);
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function spendReport(req, url) {
+    const q = url.searchParams;
+    const start = q.get('start_date');
+    const end = q.get('end_date');
+    if (!start || !DATE_RE.test(start))
+        return error(400, 'start_date is required in YYYY-MM-DD format', { param: 'start_date' });
+    if (!end || !DATE_RE.test(end))
+        return error(400, 'end_date is required in YYYY-MM-DD format', { param: 'end_date' });
+    const groupBy = q.get('group_by') ?? 'day';
+    if (!REPORT_GROUP_BY.has(groupBy)) {
+        return error(400, `group_by must be one of ${[...REPORT_GROUP_BY].join(', ')}`, { param: 'group_by' });
+    }
+    const datePart = q.get('date_part') ?? 'day';
+    if (datePart !== 'day' && datePart !== 'hour') {
+        return error(400, "date_part must be 'day' or 'hour'", { param: 'date_part' });
+    }
+    const credentialType = q.get('credential_type');
+    if (credentialType !== null && credentialType !== 'byok' && credentialType !== 'system') {
+        return error(400, "credential_type must be 'byok' or 'system'", { param: 'credential_type' });
+    }
+    const zdr = q.get('zero_data_retention');
+    if (zdr !== null && zdr !== 'true' && zdr !== 'false') {
+        return error(400, 'zero_data_retention must be true or false', { param: 'zero_data_retention' });
+    }
+    const tagsMatch = q.get('tags_match') ?? 'any';
+    if (tagsMatch !== 'any' && tagsMatch !== 'all') {
+        return error(400, "tags_match must be 'any' or 'all'", { param: 'tags_match' });
+    }
+    let rows = generationRows(req.root).filter((g) => {
+        const day = g.created_at.slice(0, 10);
+        return day >= start && day <= end;
+    });
+    const model = q.get('model');
+    if (model)
+        rows = rows.filter((g) => g.model === model);
+    const provider = q.get('provider');
+    if (provider)
+        rows = rows.filter((g) => g.provider_name === provider);
+    if (credentialType)
+        rows = rows.filter((g) => (g.is_byok ? 'byok' : 'system') === credentialType);
+    // No generation ever requests ZDR / carries user or tag attribution in the twin yet:
+    if (zdr === 'true')
+        rows = [];
+    if (q.get('user_id') || q.get('tags'))
+        rows = [];
+    const keyOf = (g) => {
+        // date_part=hour buckets are `YYYY-MM-DDTHH` under the `hour` grouping field (docs).
+        if (groupBy === 'day')
+            return datePart === 'hour' ? g.created_at.slice(0, 13) : g.created_at.slice(0, 10);
+        if (groupBy === 'model')
+            return g.model;
+        if (groupBy === 'provider')
+            return g.provider_name;
+        if (groupBy === 'credential_type')
+            return g.is_byok ? 'byok' : 'system';
+        if (groupBy === 'zero_data_retention')
+            return 'false'; // no ZDR requests recorded
+        return null; // user/tag/api_key_name: no attribution recorded
+    };
+    const groups = new Map();
+    for (const g of rows) {
+        const key = keyOf(g);
+        if (key === null)
+            continue;
+        const cur = groups.get(key) ?? {
+            total_cost: 0, market_cost: 0, surcharge_cost: 0, gateway_cost: 0,
+            input_tokens: 0, output_tokens: 0, cached_input_tokens: 0,
+            cache_creation_input_tokens: 0, reasoning_tokens: 0, request_count: 0,
+        };
+        cur.total_cost = Number((cur.total_cost + g.total_cost).toFixed(10));
+        // market_cost includes both BYOK and non-BYOK cost; gateway_cost is the gateway's OWN cost
+        // separate from the provider rate — 0 here ("no markup on tokens", matching the docs sample).
+        cur.market_cost = Number((cur.market_cost + g.total_cost + g.upstream_inference_cost).toFixed(10));
+        cur.input_tokens += g.tokens_prompt;
+        cur.output_tokens += g.tokens_completion;
+        cur.cached_input_tokens += g.native_tokens_cached;
+        cur.cache_creation_input_tokens += g.native_tokens_cache_creation;
+        cur.reasoning_tokens += g.native_tokens_reasoning;
+        cur.request_count += 1;
+        groups.set(key, cur);
+    }
+    const field = groupBy === 'day' ? (datePart === 'hour' ? 'hour' : 'day') : groupBy;
+    const results = [...groups.entries()]
+        .map(([key, value]) => ({ [field]: key, ...value }))
+        .sort((a, b) => (String(a[field]) < String(b[field]) ? -1 : 1));
+    return { status: 200, body: { results } };
+}
+// ── router ────────────────────────────────────────────────────────────────────────────────
+export async function handleAiGatewayTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    const url = new URL(req.path, 'http://twin.local');
+    const path = url.pathname;
+    if (method === 'GET' && path === '/v1/models') {
+        return { status: 200, body: { object: 'list', data: AI_GATEWAY_MODELS } };
+    }
+    if (method === 'GET' && path.startsWith('/v1/models/') && path.endsWith('/endpoints')) {
+        const id = decodeURIComponent(path.slice('/v1/models/'.length, -'/endpoints'.length));
+        const entry = findAiGatewayModel(id);
+        return entry ? modelEndpoints(entry) : modelNotFound(id);
+    }
+    if (method === 'GET' && path.startsWith('/v1/models/')) {
+        const id = decodeURIComponent(path.slice('/v1/models/'.length));
+        const entry = findAiGatewayModel(id);
+        return entry ? { status: 200, body: entry.model } : modelNotFound(id);
+    }
+    if (method === 'GET' && path === '/v1/credits')
+        return credits(req.root);
+    if (method === 'GET' && path === '/v1/generation')
+        return generationLookup(req, url);
+    if (method === 'GET' && path === '/v1/report')
+        return spendReport(req, url);
+    if (method === 'POST' && path === '/v1/chat/completions') {
+        if (req.readOnly)
+            return readOnlyRejected();
+        return chatCompletion(req, parseJson(req.body));
+    }
+    if (method === 'POST' && path === '/v1/embeddings') {
+        if (req.readOnly)
+            return readOnlyRejected();
+        return createEmbeddings(req, parseJson(req.body));
+    }
+    // ── AI SDK gateway protocol (/v3/ai) — what `createGateway` (the `ai` package /
+    // @ai-sdk/gateway) actually speaks; see ai-gateway-v3.ts. Language-model calls run through
+    // the SAME chatCompletion fold as /v1, so accounting is one surface across both protocols.
+    if (method === 'GET' && path === '/v3/ai/config')
+        return v3Config();
+    if (method === 'POST' && path === '/v3/ai/language-model') {
+        if (req.readOnly)
+            return readOnlyRejected();
+        return handleV3LanguageModel(req, chatCompletion);
+    }
+    if (path.startsWith('/v3/ai/')) {
+        // embedding-model / image-model / video-model are real /v3/ai sub-surfaces the twin does
+        // not model yet — honest 404s (open todos in the capability manifest), never fake success.
+        return error(404, `AI SDK gateway protocol operation not modeled: ${method} ${path} (modeled: GET /v3/ai/config, POST /v3/ai/language-model)`, { code: 'not_found' });
+    }
+    return error(404, `AI Gateway operation not modeled: ${method} ${path}`, { code: 'not_found' });
+}