@volter/twin-ai-gateway 0.1.0

package/src/ai-gateway-twin.ts

@@ -0,0 +1,1068 @@
+// 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_CATALOG, AI_GATEWAY_MODELS, findAiGatewayModel, type AiGatewayCatalogEntry } from './ai-gateway-models.ts';
+import {
+  buildToolCall,
+  contentToText,
+  countPromptTokens,
+  estimateTokens,
+  lastUserText,
+  normalizeTool,
+  stableHash,
+  stubAssistantText,
+  synthesizeJsonSchemaValue,
+} from './ai-gateway-stub.ts';
+import { type AiGatewayScenarioRespond, realizeAiGatewayRespond, type ScriptedResult } from './ai-gateway-scenario.ts';
+import { handleV3LanguageModel, v3Config } from './ai-gateway-v3.ts';
+import type {
+  AiGatewayRequest,
+  AiGatewayResponse,
+  ChatMessage,
+  GatewayRouting,
+  GenerationRecord,
+  ModelAttempt,
+  SseEvent,
+} from './ai-gateway-types.ts';
+
+const SERVICE = 'ai-gateway';
+const FIXED_NOW = '1970-01-01T00:00:00.000Z';
+const STARTING_CREDITS = 100;
+
+function nowEpoch(occurredAt?: string): number {
+  return Math.floor(Date.parse(occurredAt ?? FIXED_NOW) / 1000);
+}
+
+function nowIso(occurredAt?: string): string {
+  return new Date(Date.parse(occurredAt ?? FIXED_NOW)).toISOString();
+}
+
+function parseJson(body?: string): Record<string, unknown> {
+  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: number, message: string, opts: { type?: string; param?: string; code?: string } = {}): AiGatewayResponse {
+  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: string): AiGatewayResponse {
+  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(): AiGatewayResponse {
+  return error(405, 'This AI Gateway twin was started read-only; local writes are disabled.', { code: 'read_only' });
+}
+
+function rowsOfType(type: string, root?: string): Record<string, unknown>[] {
+  return projectResources(SERVICE, root)
+    .filter((r) => r.type === type)
+    .map((r) => {
+      const { type: _type, updatedAt: _updatedAt, ...rest } = r;
+      return rest as Record<string, unknown>;
+    });
+}
+
+function generationRows(root?: string): GenerationRecord[] {
+  return rowsOfType('generation', root) as unknown as GenerationRecord[];
+}
+
+// ── gateway routing options (providerOptions.gateway + top-level shorthands) ─────────────
+
+type GatewayOptions = {
+  order?: string[];
+  only?: string[];
+  sort?: 'cost' | 'ttft' | 'tps';
+  models?: string[];
+  byok?: Record<string, unknown>;
+  caching?: 'auto';
+};
+
+function parseStringArray(raw: unknown, name: string): { value?: string[] } | { error: AiGatewayResponse } {
+  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 as string[] };
+}
+
+const SORT_OPTIONS = new Set(['cost', 'ttft', 'tps']);
+
+function parseGatewayOptions(params: Record<string, unknown>): { value: GatewayOptions } | { error: AiGatewayResponse } {
+  const out: GatewayOptions = {};
+
+  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 as Record<string, unknown>).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 ?? {}) as Record<string, unknown>;
+
+  for (const [key, name] of [['order', 'providerOptions.gateway.order'], ['only', 'providerOptions.gateway.only']] as const) {
+    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 as GatewayOptions['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 as Record<string, unknown>).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 as GatewayOptions['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 as Record<string, unknown>)) {
+      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 as Record<string, unknown>;
+  }
+
+  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: string, option: 'cost' | 'ttft' | 'tps'): number {
+  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
+}
+
+type ResolvedRouting = { entry: AiGatewayCatalogEntry; routing: GatewayRouting; credentialType: 'system' | 'byok' };
+
+function resolveRouting(modelId: string, opts: GatewayOptions, occurredAt?: string): ResolvedRouting | { response: AiGatewayResponse } {
+  const startMs = Date.parse(occurredAt ?? FIXED_NOW);
+  const modelAttempts: ModelAttempt[] = [];
+
+  // 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: AiGatewayCatalogEntry | undefined;
+  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: Record<string, number | null> | undefined;
+  if (opts.sort) {
+    const metrics: Record<string, number | null> = {};
+    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: GatewayRouting['sort'] = opts.sort && sortMetrics
+    ? { option: opts.sort, executionOrder: [...allowed], metrics: sortMetrics, deprioritizedProviders: [] }
+    : undefined;
+
+  const resolvedProvider = allowed[0]!;
+  const credentialType: 'system' | 'byok' = opts.byok && Object.prototype.hasOwnProperty.call(opts.byok, resolvedProvider) ? 'byok' : 'system';
+  const providerApiModelId = resolvedModelId.slice(resolvedModelId.indexOf('/') + 1);
+
+  const routing: GatewayRouting = {
+    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 };
+}
+
+// ── chat completions ──────────────────────────────────────────────────────────────────────
+
+type ReasoningConfig = { enabled?: boolean; max_tokens?: number; effort?: string; exclude?: boolean };
+
+type ChatArgs = {
+  model: string;
+  messages: ChatMessage[];
+  stream: boolean;
+  n: number;
+  maxTokens?: number;
+  tools?: unknown[];
+  toolChoice?: unknown;
+  responseFormat?: Record<string, unknown>;
+  reasoning?: ReasoningConfig;
+  cachedTokens: number;
+  gateway: GatewayOptions;
+};
+
+const MESSAGE_ROLES = new Set(['system', 'developer', 'user', 'assistant', 'tool']);
+const CONTENT_PART_TYPES = new Set(['text', 'image_url', 'file']);
+
+function validateMessages(raw: unknown): { messages: ChatMessage[] } | { response: AiGatewayResponse } {
+  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 as ChatMessage).role !== 'string') {
+      return { response: error(400, 'each message must include a role', { param: 'messages' }) };
+    }
+    const message = m as ChatMessage;
+    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 as { type?: unknown })?.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 as { image_url?: { url?: unknown } }).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 as { file?: { data?: unknown } }).file;
+          if (!file || typeof file !== 'object' || typeof (file as { data?: unknown }).data !== 'string') {
+            return { response: error(400, 'file parts must include file.data', { param: 'messages' }) };
+          }
+        }
+      }
+    }
+  }
+  return { messages: raw as ChatMessage[] };
+}
+
+function validateSampling(params: Record<string, unknown>): AiGatewayResponse | null {
+  const inRange = (v: unknown, min: number, max: number) => 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: unknown): { value?: Record<string, unknown> } | { error: AiGatewayResponse } {
+  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 as Record<string, unknown>;
+  // 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 as Record<string, unknown>).name !== 'string') {
+      return { error: error(400, 'response_format.json_schema requires a name', { param: 'response_format' }) };
+    }
+  }
+  return { value: rf };
+}
+
+const EFFORTS: Record<string, number> = { none: 0, minimal: 0.1, low: 0.2, medium: 0.5, high: 0.8, xhigh: 0.95 };
+
+function parseReasoning(raw: unknown): { value?: ReasoningConfig } | { error: AiGatewayResponse } {
+  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 as Record<string, unknown>;
+  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 as number) < 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: ChatArgs): number {
+  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: ChatArgs): boolean {
+  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: ChatMessage[]): number {
+  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 as object)));
+    if (marked) cached += estimateTokens(`${message.role}: ${contentToText(message.content)}`);
+  }
+  return cached;
+}
+
+function validateChat(params: Record<string, unknown>): { args: ChatArgs } | { response: AiGatewayResponse } {
+  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 as number) < 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 as number) < 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 as unknown[]) {
+      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 as Record<string, unknown>).type === 'function' &&
+      typeof ((tc as Record<string, unknown>).function as Record<string, unknown> | undefined)?.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 as unknown[] } : {}),
+      ...(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: ChatArgs): { tool: ReturnType<typeof normalizeTool> } | { none: true } | { response: AiGatewayResponse } {
+  if (!args.tools || args.tools.length === 0 || args.toolChoice === 'none') return { none: true };
+  if (args.toolChoice && typeof args.toolChoice === 'object') {
+    const wanted = ((args.toolChoice as Record<string, unknown>).function as Record<string, unknown>).name as string;
+    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: ChatArgs): string | null {
+  const rf = args.responseFormat;
+  if (!rf || rf.type === 'text') return null;
+  if (rf.type === 'json_schema') {
+    const js = rf.json_schema as Record<string, unknown>;
+    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: string, text: string): Array<Record<string, unknown>> {
+  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 }];
+}
+
+type BuiltChoice = { message: Record<string, unknown>; finishReason: string; completionTokens: number; reasoningTokenCount: number };
+
+function buildChoiceMessage(args: ChatArgs, resolvedModelId: string, scripted: ScriptedResult | null): BuiltChoice | { response: AiGatewayResponse } {
+  const message: Record<string, unknown> = { role: 'assistant' };
+  let finishReason = 'stop';
+  let completionTokens = 0;
+  let reasoningText: string | null = 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: number): string {
+  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: AiGatewayCatalogEntry, promptTokens: number, completionTokens: number): number {
+  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: unknown, seq: number): string {
+  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: GenerationRecord,
+  root?: string,
+  occurredAt?: string,
+): Promise<void> {
+  await applyTwinWrite(SERVICE, {
+    operation: 'generation.record',
+    subjectType: 'generation',
+    subjectId: record.id,
+    fields: record as unknown as Record<string, unknown>,
+    occurredAt: occurredAt ?? FIXED_NOW,
+    actor: { kind: 'system' },
+  }, root);
+}
+
+async function chatCompletion(req: AiGatewayRequest, params: Record<string, unknown>): Promise<AiGatewayResponse> {
+  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 as AiGatewayScenarioRespond);
+        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 as { content: string }).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: Record<string, unknown> = {
+    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: Record<string, unknown> = {
+    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: Record<string, unknown>, sink: (event: SseEvent) => void): void {
+  const base = { id: body.id, object: 'chat.completion.chunk', created: body.created, model: body.model };
+  const choices = body.choices as Array<Record<string, unknown>>;
+  choices.forEach((choice, choiceIndex) => {
+    const message = choice.message as Record<string, unknown>;
+    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 as Array<Record<string, unknown>>).forEach((call, index) => {
+        const fn = call.function as Record<string, unknown>;
+        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: string, dim: number): number[] {
+  // 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: AiGatewayRequest, params: Record<string, unknown>): Promise<AiGatewayResponse> {
+  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 as number) < 1 || (params.dimensions as number) > 4096) {
+      return error(400, 'dimensions must be an integer between 1 and 4096', { param: 'dimensions' });
+    }
+    dim = params.dimensions as number;
+  }
+  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 as string), 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: AiGatewayCatalogEntry): AiGatewayResponse {
+  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?: string): AiGatewayResponse {
+  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: AiGatewayRequest, url: URL): AiGatewayResponse {
+  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: AiGatewayRequest, url: URL): AiGatewayResponse {
+  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: GenerationRecord): string | null => {
+    // 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
+  };
+  type Row = {
+    total_cost: number; market_cost: number; surcharge_cost: number; gateway_cost: number;
+    input_tokens: number; output_tokens: number; cached_input_tokens: number;
+    cache_creation_input_tokens: number; reasoning_tokens: number; request_count: number;
+  };
+  const groups = new Map<string, Row>();
+  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: Array<Record<string, unknown>> = [...groups.entries()]
+    .map(([key, value]): Record<string, unknown> => ({ [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: AiGatewayRequest): Promise<AiGatewayResponse> {
+  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' });
+}