@volter/twin-ai-gateway 0.1.0

package/src/ai-gateway-types.ts

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

package/src/ai-gateway-v3.ts

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

package/src/cli.ts

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

package/src/index.ts

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