@volter/twin-ai-gateway 0.1.0

package/src/ai-gateway-conformance.ts

@@ -0,0 +1,77 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleAiGatewayTwinRequest } from './ai-gateway-twin.ts';
+import type { SseEvent } from './ai-gateway-types.ts';
+
+export type AiGatewayConformanceReport = {
+  ok: boolean;
+  checksRun: number;
+  violations: Array<{ check: string; detail: string }>;
+};
+
+type Body = Record<string, any>;
+
+export async function checkAiGatewayConformance(opts: { root?: string } = {}): Promise<AiGatewayConformanceReport> {
+  const root = opts.root ?? mkdtempSync(join(tmpdir(), 'ai-gateway-conf-'));
+  const owned = opts.root === undefined;
+  const violations: Array<{ check: string; detail: string }> = [];
+  let checksRun = 0;
+  const fail = (check: string, detail: string) => violations.push({ check, detail });
+  const h = (method: string, path: string, body?: unknown, sseSink?: (event: SseEvent) => void) =>
+    handleAiGatewayTwinRequest({ method, path, body: body === undefined ? undefined : JSON.stringify(body), root, ...(sseSink ? { sseSink } : {}) });
+
+  try {
+    checksRun++;
+    const chat = await h('POST', '/v1/chat/completions', { model: 'anthropic/claude-sonnet-4.6', messages: [{ role: 'user', content: 'hello' }] });
+    const cb = chat.body as Body;
+    if (chat.status !== 200 || cb.object !== 'chat.completion' || cb.choices?.[0]?.message?.role !== 'assistant') fail('chat.envelope', 'invalid chat completion envelope');
+    if (!String(cb.id).startsWith('gen_')) fail('chat.generation_id', 'chat completion id is not a gen_ generation id');
+    if (typeof cb.providerMetadata?.gateway?.cost !== 'string' || cb.providerMetadata?.gateway?.routing?.finalProvider !== 'anthropic') {
+      fail('chat.provider_metadata', 'providerMetadata.gateway routing/cost missing');
+    }
+
+    checksRun++;
+    const events: SseEvent[] = [];
+    await h('POST', '/v1/chat/completions', { model: 'anthropic/claude-sonnet-4.6', stream: true, messages: [{ role: 'user', content: 'stream' }] }, (event) => events.push(event));
+    if (!events.some((event) => event.data?.object === 'chat.completion.chunk') || events.at(-1)?.done !== true) fail('streaming', 'missing chunk or [DONE]');
+
+    checksRun++;
+    const models = await h('GET', '/v1/models');
+    if ((models.body as Body).object !== 'list' || !Array.isArray((models.body as Body).data) || (models.body as Body).data.length === 0) fail('models.list', 'missing models data');
+    const one = await h('GET', '/v1/models/anthropic/claude-sonnet-4.6');
+    if ((one.body as Body).id !== 'anthropic/claude-sonnet-4.6') fail('models.retrieve', 'missing model');
+
+    checksRun++;
+    const gen = await h('GET', `/v1/generation?id=${encodeURIComponent(cb.id)}`);
+    if ((gen.body as Body).data?.model !== 'anthropic/claude-sonnet-4.6') fail('generation.lookup', 'generation lookup failed');
+    const creditsRes = await h('GET', '/v1/credits');
+    if (typeof (creditsRes.body as Body).balance !== 'string' || typeof (creditsRes.body as Body).total_used !== 'string') fail('credits', 'credits shape invalid');
+
+    checksRun++;
+    const bad = await h('POST', '/v1/chat/completions', { model: 'anthropic/claude-sonnet-4.6', messages: [] });
+    if (bad.status !== 400 || (bad.body as Body).error?.type !== 'invalid_request_error') fail('error.envelope', 'bad chat request did not return the vendor error envelope');
+
+    checksRun++;
+    const embed = await h('POST', '/v1/embeddings', { model: 'openai/text-embedding-3-small', input: 'hi' });
+    if (embed.status !== 200 || !Array.isArray((embed.body as Body).data?.[0]?.embedding)) fail('embeddings.create', 'embeddings envelope invalid');
+    if (!String((embed.body as Body).providerMetadata?.gateway?.generationId ?? '').startsWith('gen_')) fail('embeddings.accounting', 'embeddings call did not record a billed generation');
+
+    checksRun++;
+    const v3 = await handleAiGatewayTwinRequest({
+      method: 'POST',
+      path: '/v3/ai/language-model',
+      headers: { 'ai-language-model-id': 'anthropic/claude-sonnet-4.6', 'ai-language-model-streaming': 'false' },
+      body: JSON.stringify({ prompt: [{ role: 'user', content: [{ type: 'text', text: 'v3 conformance' }] }] }),
+      root,
+    });
+    const vb = v3.body as Body;
+    if (v3.status !== 200 || (vb.finishReason as Body)?.unified !== 'stop' || !Array.isArray(vb.content)) fail('v3.language_model', 'AI SDK gateway protocol generate result invalid');
+    const config = await h('GET', '/v3/ai/config');
+    if (config.status !== 200 || !Array.isArray((config.body as Body).models)) fail('v3.config', 'AI SDK gateway config document invalid');
+  } finally {
+    if (owned) rmSync(root, { recursive: true, force: true });
+  }
+
+  return { ok: violations.length === 0, checksRun, violations };
+}

package/src/ai-gateway-connector.ts

@@ -0,0 +1,100 @@
+// Connector: pull/push against the REAL AI Gateway over an INJECTED client (the real fetch-based
+// executor in prod, a fake in tests). No other module may reach the live vendor — the vendor's
+// read surface here is the unauthenticated model catalog (GET /v1/models) plus the team's
+// credits balance (GET /v1/credits).
+import { observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import type { GenerationRecord } from './ai-gateway-types.ts';
+
+export type AiGatewayExecute = (req: { method: string; path: string; body?: unknown }) => Promise<{ status: number; data: unknown }>;
+const DEFAULT_OCCURRED_AT = '1970-01-01T00:00:00.000Z';
+
+/** Fetch the gateway's model catalog + credits through the injected client and map to
+ *  SyncResource[] (no fold). */
+async function collectAiGatewayState(execute: AiGatewayExecute): Promise<SyncResource[]> {
+  const resources: SyncResource[] = [];
+  const models = await execute({ method: 'GET', path: '/v1/models' });
+  const data = (models.data as { data?: Array<Record<string, unknown>> }).data ?? [];
+  for (const model of data) {
+    if (typeof model.id === 'string') resources.push({ type: 'model', id: `model_${model.id}`, fields: model });
+  }
+  const credits = await execute({ method: 'GET', path: '/v1/credits' });
+  if (credits.status >= 200 && credits.status < 300 && credits.data && typeof credits.data === 'object') {
+    resources.push({ type: 'credits', id: 'credits_account', fields: credits.data as Record<string, unknown> });
+  }
+  return resources;
+}
+
+/** One fold onto the head: protocol 2's observe, one batch, one instant. */
+function fold(resources: SyncResource[], opts: { root?: string; occurredAt?: string }) {
+  const at = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+  return observeResources('ai-gateway', resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:ai-gateway:${at}`,
+  });
+}
+
+export async function pullAiGatewayState(execute: AiGatewayExecute, opts: { root?: string; occurredAt?: string } = {}): Promise<void> {
+  const resources = await collectAiGatewayState(execute);
+  fold(resources, opts);
+}
+
+/**
+ * D7 consumer-facing pull entry point: gather all AI Gateway read domains (model catalog +
+ * credits) and fold them into the twin through a SINGLE observed batch, returning the standard result
+ * shape. Idempotent: a re-pull of identical state appends no new deltas.
+ */
+export async function syncAiGatewayFromReal(
+  execute: AiGatewayExecute,
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const resources = await collectAiGatewayState(execute);
+  const result = fold(resources, opts);
+  return { observed: result.observed, deltasAppended: result.appended };
+}
+
+/** Map a local twin action to the real-gateway request that CONFIRMS it. The gateway exposes no
+ *  write API (inference is the only "write", and replaying it against the live vendor would
+ *  spend real money) — so push means reconciliation: verify a locally recorded generation
+ *  exists upstream via GET /v1/generation. Unknown operation types return null (unpushable). */
+export function aiGatewayRequestForAction(action: TwinAction): { method: string; path: string; body?: unknown } | null {
+  if (action.operation === 'generation.record') {
+    const record = action.fields as unknown as GenerationRecord;
+    return { method: 'GET', path: `/v1/generation?id=${encodeURIComponent(record.id)}` };
+  }
+  return null;
+}
+
+export async function pushAiGatewayAction(action: TwinAction, execute: AiGatewayExecute): Promise<boolean> {
+  const req = aiGatewayRequestForAction(action);
+  if (!req) return false;
+  const result = await execute(req);
+  return result.status >= 200 && result.status < 300;
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's. */
+export function aiGatewayExecuteOver(execute: RemoteExecute): AiGatewayExecute {
+  return async ({ method, path, body }) => {
+    const res = await execute({ method, path, headers: { accept: 'application/json', authorization: 'Bearer twin', ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    let data: unknown = {};
+    if (res.body) { try { data = JSON.parse(res.body); } catch { data = { error: res.body.slice(0, 200) }; } }
+    return { status: res.status, data };
+  };
+}
+/** The refresh adapter: pull the gateway's model catalogue and the account's credits. */
+export async function syncAiGatewayFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<{ observed: number; deltasAppended: number }> {
+  return syncAiGatewayFromReal(aiGatewayExecuteOver(execute), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}),
+  });
+}
+/** The perform adapter. The gateway exposes NO write API — inference is the only "write", and replaying
+ *  one against the live vendor would spend real money. So a recorded generation is RECONCILED rather than
+ *  written: the head asks the gateway whether it has that generation, and a refusal is heard as one. */
+export async function performAiGatewayAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  const req = aiGatewayRequestForAction(action);
+  if (!req) return { externalId: action.subject.id, data: { performed: false, reason: `${action.operation ?? action.subject.type} is the twin's own record — the AI Gateway has no write API` } };
+  const ok = await pushAiGatewayAction(action, aiGatewayExecuteOver(execute));
+  if (!ok) throw new Error(`ai-gateway perform ${action.operation ?? action.subject.type} refused: the gateway does not hold that generation`);
+  return { externalId: action.subject.id, data: { performed: false, reason: 'reconciled against the gateway rather than written — inference is the only write, and replaying it would spend real money' } };
+}

package/src/ai-gateway-models.ts

@@ -0,0 +1,105 @@
+// Deterministic local model catalog for the AI Gateway twin. The SERVED shape follows the
+// documented GET /v1/models response (OpenAI models format + gateway fields: name, description,
+// context_window, max_tokens, type, tags, pricing — see Vercel "REST API Reference", List models).
+// Model ids are `creator/model` slugs, exactly how the real gateway addresses models.
+//
+// `providers` is twin-internal routing data (which provider endpoints can serve the model, in
+// default preference order) — it is NOT part of the served /v1/models row (the real gateway
+// exposes per-provider data only via GET /v1/models/{creator}/{model}/endpoints).
+
+export type AiGatewayModel = {
+  id: string;
+  object: 'model';
+  created: number;
+  released: number;
+  owned_by: string;
+  name: string;
+  description: string;
+  context_window: number;
+  max_tokens: number;
+  type: 'language' | 'embedding' | 'reranking' | 'image' | 'video';
+  tags: string[];
+  pricing: {
+    input: string;
+    output?: string;
+    input_cache_read?: string;
+    input_cache_write?: string;
+  };
+};
+
+export type AiGatewayCatalogEntry = {
+  model: AiGatewayModel;
+  /** Provider slugs able to serve this model, in the gateway's default preference order. */
+  providers: string[];
+};
+
+const lang = (
+  id: string,
+  ownedBy: string,
+  name: string,
+  contextWindow: number,
+  maxTokens: number,
+  input: string,
+  output: string,
+  providers: string[],
+  tags: string[] = ['tool-use', 'reasoning'],
+): AiGatewayCatalogEntry => ({
+  model: {
+    id,
+    object: 'model',
+    created: 1755815280,
+    released: 1755815280,
+    owned_by: ownedBy,
+    name,
+    description: `Deterministic local catalog entry for ${name}.`,
+    context_window: contextWindow,
+    max_tokens: maxTokens,
+    type: 'language',
+    tags,
+    pricing: {
+      input,
+      output,
+      input_cache_read: '0.0000001',
+      input_cache_write: input,
+    },
+  },
+  providers,
+});
+
+export const AI_GATEWAY_CATALOG: AiGatewayCatalogEntry[] = [
+  lang('anthropic/claude-sonnet-4.6', 'anthropic', 'Claude Sonnet 4.6', 1_000_000, 64_000, '0.000003', '0.000015', ['anthropic', 'bedrock', 'vertex'], ['tool-use', 'reasoning', 'vision', 'file-input']),
+  lang('anthropic/claude-opus-4.8', 'anthropic', 'Claude Opus 4.8', 1_000_000, 64_000, '0.000005', '0.000025', ['anthropic', 'bedrock', 'vertex'], ['tool-use', 'reasoning', 'vision', 'file-input']),
+  lang('openai/gpt-5', 'openai', 'GPT-5', 400_000, 128_000, '0.00000125', '0.00001', ['openai', 'azure'], ['tool-use', 'reasoning', 'vision', 'file-input']),
+  lang('openai/gpt-5.2', 'openai', 'GPT-5.2', 400_000, 128_000, '0.00000125', '0.00001', ['openai', 'azure'], ['tool-use', 'reasoning', 'vision', 'file-input']),
+  lang('xai/grok-4-1', 'xai', 'Grok 4.1', 256_000, 64_000, '0.000003', '0.000015', ['xai'], ['tool-use', 'reasoning']),
+  lang('groq/llama-3.3-70b-versatile', 'groq', 'Llama 3.3 70B Versatile', 131_072, 32_768, '0.00000059', '0.00000079', ['groq'], ['tool-use']),
+  lang('zai/glm-4.6', 'zai', 'GLM 4.6', 200_000, 128_000, '0.0000006', '0.0000022', ['zai', 'novita'], ['tool-use', 'reasoning']),
+  lang('zai/glm-4.5-air', 'zai', 'GLM 4.5 Air', 128_000, 96_000, '0.0000002', '0.0000011', ['zai', 'novita'], ['tool-use', 'reasoning']),
+  lang('openai/gpt-oss-120b', 'openai', 'GPT OSS 120B', 131_072, 32_768, '0.0000001', '0.0000005', ['groq', 'cerebras', 'fireworks'], ['tool-use', 'reasoning']),
+  lang('openai/gpt-oss-20b', 'openai', 'GPT OSS 20B', 131_072, 32_768, '0.00000005', '0.0000002', ['groq', 'cerebras'], ['tool-use', 'reasoning']),
+  lang('minimax/minimax-m2', 'minimax', 'MiniMax M2', 200_000, 128_000, '0.0000003', '0.0000012', ['minimax', 'novita'], ['tool-use', 'reasoning']),
+  lang('google/gemini-3.1-pro-preview', 'google', 'Gemini 3.1 Pro Preview', 1_000_000, 64_000, '0.000002', '0.000012', ['google', 'vertex'], ['tool-use', 'reasoning', 'vision', 'file-input']),
+  {
+    model: {
+      id: 'openai/text-embedding-3-small',
+      object: 'model',
+      created: 1755815280,
+      released: 1755815280,
+      owned_by: 'openai',
+      name: 'Text Embedding 3 Small',
+      description: 'Deterministic local catalog entry for Text Embedding 3 Small.',
+      context_window: 8_191,
+      max_tokens: 0,
+      type: 'embedding',
+      tags: [],
+      pricing: { input: '0.00000002' },
+    },
+    providers: ['openai', 'azure'],
+  },
+];
+
+export const AI_GATEWAY_MODELS: AiGatewayModel[] = AI_GATEWAY_CATALOG.map((entry) => entry.model);
+
+export function findAiGatewayModel(id: string): AiGatewayCatalogEntry | undefined {
+  return AI_GATEWAY_CATALOG.find((entry) => entry.model.id === id);
+}

package/src/ai-gateway-perform-harness.ts

@@ -0,0 +1,17 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). Not on the serve path.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { pushAiGatewayAction, type AiGatewayExecute } from './ai-gateway-connector.ts';
+
+export async function performPending(execute: AiGatewayExecute, opts: { root?: string; occurredAt?: string } = {}): Promise<number> {
+  let pushed = 0;
+  for (const entry of deployableEntries('ai-gateway', opts.root)) {
+    if (!(await pushAiGatewayAction(entry, execute))) continue;
+    confirmAction({
+      service: 'ai-gateway', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+      occurredAt: opts.occurredAt ?? worldNow(), receipt: { status: 'deployed' },
+      ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    pushed += 1;
+  }
+  return pushed;
+}

package/src/ai-gateway-scenario.ts

@@ -0,0 +1,137 @@
+// The ai-gateway pack's HALF of the scenario system on the kernel's ONE engine (@volter/world-core
+// scenario.ts): the OpenAI-compat chat vocabulary + the scripted-turn respond shape the
+// envelope builder consumes. The handler FILE (handlers/ai-gateway.json in a world dir) is
+// the only write surface.
+import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+import { contentToText, lastUserText } from './ai-gateway-stub.ts';
+import type { ChatMessage } from './ai-gateway-types.ts';
+
+export type AiGatewayScenarioRequest = { model: string; messages: ChatMessage[]; tools?: unknown };
+export type AiGatewayScenarioEngine = ScenarioEngine<AiGatewayScenarioRequest>;
+
+/** A scripted tool call — the full arguments payload is emitted verbatim (and streamed as
+ *  tool_calls argument deltas on the streaming path). */
+export type ScenarioToolCall = { name: string; arguments: Record<string, unknown>; id?: string };
+
+/** What the assistant says when a handler fires: any combination of reasoning/text/toolCalls
+ *  (emitted in the vendor's field ordering). */
+export type AiGatewayScenarioRespond = {
+  reasoning?: string;
+  text?: string;
+  toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+  /** Defaults to 'tool_calls' when any tool call is present, else 'stop'. */
+  finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+
+/** What a fired handler yields — the scripted assistant turn for the envelope builder. */
+export type ScriptedResult = {
+  text: string | null;
+  reasoning: string | null;
+  toolCalls: ScenarioToolCall[];
+  finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+
+const RESPOND_KEYS = new Set(['reasoning', 'text', 'toolCalls', 'finishReason']);
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls', 'content_filter']);
+const nonEmptyString = (cond: unknown): cond is string => typeof cond === 'string' && cond.length > 0;
+
+/** The function names the last message's tool results answer: resolve each `tool` message's
+ *  tool_call_id against the tool_calls of earlier assistant turns. */
+function lastToolResultNames(messages: ChatMessage[]): Set<string> {
+  const last = messages[messages.length - 1];
+  const names = new Set<string>();
+  if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string') return names;
+  for (const m of messages) {
+    if (m.role !== 'assistant' || !Array.isArray(m.tool_calls)) continue;
+    for (const tc of m.tool_calls) {
+      const call = tc as { id?: unknown; function?: { name?: unknown } };
+      if (call?.id === last.tool_call_id && typeof call?.function?.name === 'string') names.add(call.function.name);
+    }
+  }
+  return names;
+}
+
+function toolNames(tools: unknown): string[] {
+  if (!Array.isArray(tools)) return [];
+  return tools.map((t) => {
+    const fn = t as { function?: { name?: unknown }; name?: unknown };
+    return typeof fn?.function?.name === 'string' ? fn.function.name : typeof fn?.name === 'string' ? fn.name : null;
+  }).filter((n): n is string => n !== null);
+}
+
+export const aiGatewayScenarioAdapter: PackScenarioAdapter<AiGatewayScenarioRequest> = {
+  vendor: 'ai-gateway',
+  features: (req): ScenarioFeatures => ({
+    model: req.model,
+    lastUserText: lastUserText(req.messages).slice(0, 300),
+    tools: toolNames(req.tools),
+    lastMessageHasToolResult: req.messages[req.messages.length - 1]?.role === 'tool',
+    toolResultFor: [...lastToolResultNames(req.messages)],
+  }),
+  matchers: {
+    modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+    userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages).toLowerCase().includes(cond.toLowerCase()),
+    anyTextIncludes: (req, cond) => nonEmptyString(cond) && req.messages.map((m) => contentToText(m.content)).join('\n').toLowerCase().includes(cond.toLowerCase()),
+    lastMessageHasToolResult: (req, cond) => typeof cond === 'boolean' && (req.messages[req.messages.length - 1]?.role === 'tool') === cond,
+    toolResultFor: (req, cond) => nonEmptyString(cond) && lastToolResultNames(req.messages).has(cond),
+    hasTool: (req, cond) => nonEmptyString(cond) && toolNames(req.tools).includes(cond),
+  },
+  text: (req) => req.messages.map((m) => contentToText(m.content)).join('\n'),
+  validateOn: (on) => {
+    for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool'] as const) if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k])) return `on.${k} is a non-empty string`;
+    for (const k of ['lastMessageHasToolResult'] as const) if (on[k] !== undefined && typeof on[k] !== 'boolean') return `on.${k} is a boolean`;
+    return null;
+  },
+  validateRespond: (respond) => {
+    if (typeof respond !== 'object' || respond === null || Array.isArray(respond)) return 'respond is an object { reasoning?, text?, toolCalls?, finishReason? }';
+    const r = respond as Record<string, unknown>;
+    for (const k of Object.keys(r)) if (!RESPOND_KEYS.has(k)) return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+    if (r.text !== undefined && typeof r.text !== 'string') return 'respond.text is a string';
+    if (r.reasoning !== undefined && typeof r.reasoning !== 'string') return 'respond.reasoning is a string';
+    if (r.finishReason !== undefined && (typeof r.finishReason !== 'string' || !FINISH_REASONS.has(r.finishReason))) return `respond.finishReason is one of ${[...FINISH_REASONS].join(', ')}`;
+    if (r.toolCalls !== undefined) {
+      for (const tc of Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+        const t = tc as Record<string, unknown>;
+        if (!t || typeof t !== 'object' || Array.isArray(t)) return 'respond.toolCalls entries are objects';
+        if (typeof t.name !== 'string' || !t.name) return 'respond.toolCalls[].name is a non-empty string';
+        if (!t.arguments || typeof t.arguments !== 'object' || Array.isArray(t.arguments)) return 'respond.toolCalls[].arguments is an object';
+        if (t.id !== undefined && typeof t.id !== 'string') return 'respond.toolCalls[].id is a string';
+      }
+    }
+    const hasAny = r.text !== undefined || r.reasoning !== undefined || r.toolCalls !== undefined;
+    if (!hasAny) return 'respond needs text, reasoning, or toolCalls';
+    return null;
+  },
+};
+
+export function loadAiGatewayScenarioDocument(path: string): ScenarioDocument {
+  let parsed: unknown;
+  try {
+    // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract
+    // R12b): the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world
+    // serves ITS OWN scenario instead of whatever happens to sit on the host disk — and the
+    // serve path stays workerd-clean. A missing document keeps the historical ENOENT wording,
+    // so the loud load-time failure reads byte-identically to the read it replaces.
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new ScenarioError(`ai-gateway scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parseScenarioDocument(parsed, aiGatewayScenarioAdapter);
+}
+
+export function createAiGatewayScenarioEngine(document?: ScenarioDocument): AiGatewayScenarioEngine {
+  return new ScenarioEngine(aiGatewayScenarioAdapter, document);
+}
+
+/** Realize a fired handler's respond into the envelope builder's scripted-turn shape. */
+export function realizeAiGatewayRespond(respond: AiGatewayScenarioRespond): ScriptedResult {
+  const toolCalls = respond.toolCalls === undefined ? [] : Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls];
+  return {
+    text: respond.text ?? null,
+    reasoning: respond.reasoning ?? null,
+    toolCalls,
+    finishReason: respond.finishReason ?? (toolCalls.length > 0 ? 'tool_calls' : 'stop'),
+  };
+}

package/src/ai-gateway-server.ts

@@ -0,0 +1,122 @@
+// Vercel AI Gateway twin HTTP server.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createAiGatewayTwinFetch` and
+// the SERVER is one line of `Bun.serve` around it, so the standalone (R1) and hosted lanes execute
+// identical serving bytes. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): the SSE streaming lane below genuinely exceeds the common shape
+// — openai-server.ts is the reference for that.
+import { serveHttp } from '@volter/world-core';
+import { handleAiGatewayTwinRequest } from './ai-gateway-twin.ts';
+import { twinManifest, worldNow } from '@volter/world-core';
+import { createAiGatewayScenarioEngine, type AiGatewayScenarioEngine, loadAiGatewayScenarioDocument } from './ai-gateway-scenario.ts';
+import type { SseEvent } from './ai-gateway-types.ts';
+
+function wantsStream(body: string): boolean {
+  try {
+    return JSON.parse(body || '{}')?.stream === true;
+  } catch {
+    return false;
+  }
+}
+
+function encodeSse(event: SseEvent): string {
+  return event.done ? 'data: [DONE]\n\n' : `data: ${JSON.stringify(event.data)}\n\n`;
+}
+
+/** Options every AI Gateway-twin HTTP surface needs, independent of who owns the socket. */
+export interface AiGatewayTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  scenarioPath?: string;
+}
+
+export function createAiGatewayTwinFetch(options: AiGatewayTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  // Scenario scripting (ai-gateway-scenario.ts): a JSON scenario file — via the scenarioPath
+  // option or the TWIN_AI_GATEWAY_SCENARIO env var — scripts deterministic completions for
+  // POST /v1/chat/completions. A malformed scenario throws here, failing construction loudly.
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_AI_GATEWAY_SCENARIO;
+  const scenarioEngine: AiGatewayScenarioEngine | undefined = scenarioPath ? createAiGatewayScenarioEngine(loadAiGatewayScenarioDocument(scenarioPath)) : undefined;
+  return async function aiGatewayTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, read-only.
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(twinManifest({
+        vendor: 'ai-gateway',
+        twinOf: 'Vercel AI Gateway (OpenAI-compat chat completions)',
+        stateSentence: 'Seed nothing — generations/credits accrue from ordinary API use with any key.',
+        behaviorSentence: 'Completions are scripted by MSW-shaped handlers in the world dir (handlers/ai-gateway.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|hasTool|toolResultFor|lastMessageHasToolResult|nthCall}, respond:{text|reasoning|toolCalls, finishReason?}, once?, phase?}. Unmatched requests answer a labeled stub naming this door.',
+        exampleHandler: { on: { userTextIncludes: 'plan', hasTool: 'proposePlan' }, respond: { toolCalls: { name: 'proposePlan', arguments: { steps: 3 } } }, once: true },
+        engine: scenarioEngine as never,
+      }));
+    }
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin/scenario') {
+      return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'ai-gateway', handlers: [], misses: 0, recentMisses: [] });
+    }
+    const path = url.pathname + url.search;
+    const body = request.method === 'GET' ? '' : await request.text();
+    const headers = Object.fromEntries(request.headers.entries());
+
+    // Streaming is signaled in the BODY on the OpenAI-compat surface (`stream: true`) and in a
+    // HEADER on the AI SDK gateway protocol (`ai-language-model-streaming: true`).
+    const isStreamingRequest = !readOnly && request.method.toUpperCase() === 'POST' && (
+      (url.pathname === '/v1/chat/completions' && wantsStream(body)) ||
+      (url.pathname === '/v3/ai/language-model' && request.headers.get('ai-language-model-streaming') === 'true')
+    );
+
+    if (isStreamingRequest) {
+      // Buffer the handler's SSE events first: a request that FAILS validation/routing must
+      // get its real 4xx status + JSON error body on the wire (never a 200 SSE stream
+      // wrapping an error — that would be a fake success).
+      const events: SseEvent[] = [];
+      const result = await handleAiGatewayTwinRequest({
+        method: request.method,
+        path,
+        body,
+        headers,
+        readOnly,
+        occurredAt: worldNow(),
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+        sseSink: (event) => events.push(event),
+      });
+      if (result.status >= 400) {
+        return new Response(JSON.stringify(result.body), { status: result.status, headers: { 'content-type': 'application/json' } });
+      }
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const encoder = new TextEncoder();
+          for (const event of events) controller.enqueue(encoder.encode(encodeSse(event)));
+          controller.close();
+        },
+      });
+      return new Response(stream, {
+        headers: {
+          'content-type': 'text/event-stream; charset=utf-8',
+          'cache-control': 'no-cache',
+        },
+      });
+    }
+
+    const result = await handleAiGatewayTwinRequest({
+      method: request.method,
+      path,
+      body,
+      headers,
+      readOnly,
+      occurredAt: worldNow(),
+      ...(options.root !== undefined ? { root: options.root } : {}),
+      ...(scenarioEngine ? { scenarioEngine } : {}),
+    });
+    return new Response(JSON.stringify(result.body), { status: result.status, headers: { 'content-type': 'application/json' } });
+  };
+}
+
+export async function createAiGatewayTwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createAiGatewayTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}