@volter/twin-openrouter 0.1.0

package/src/openrouter-capabilities.ts

@@ -0,0 +1,861 @@
+import { createHash } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { applyTwinWrite, deployableEntries, projectResources } from '@volter/world-core';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary, isInfrastructureError, harnessError } from '@volter/world-tooling';
+import { handleOpenRouterTwinRequest } from './openrouter-twin.ts';
+import { buildOpenRouterMirrorClient, createOpenRouterMirrorServer } from './openrouter-mirror-ui.ts';
+import { pullOpenRouterState, pushPendingOpenRouterActions } from './openrouter-connector.ts';
+import type { OpenRouterResponse, SseEvent } from './openrouter-types.ts';
+
+type Body = Record<string, any>;
+type Step = { m: string; p: string; b?: unknown; sseSink?: (event: SseEvent) => void };
+
+async function withRoot(fn: (h: (step: Step) => Promise<OpenRouterResponse>) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'openrouter-cap-'));
+  const h = (step: Step) => handleOpenRouterTwinRequest({
+    method: step.m,
+    path: step.p,
+    body: step.b === undefined ? undefined : JSON.stringify(step.b),
+    root,
+    ...(step.sseSink ? { sseSink: step.sseSink } : {}),
+  });
+  try {
+    return await verifyBoundary('openrouter.withRoot', () => fn(h));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+async function handleOpenRouterTwinRequestRO(method: string, path: string, body: unknown): Promise<OpenRouterResponse> {
+  const root = mkdtempSync(join(tmpdir(), 'openrouter-cap-ro-'));
+  try {
+    return await handleOpenRouterTwinRequest({ method, path, body: JSON.stringify(body), readOnly: true, root });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'todo' });
+
+const CHAT = (extra: Record<string, unknown> = {}) => ({
+  model: 'google/gemini-3-flash-preview',
+  messages: [{ role: 'user', content: 'hello openrouter twin' }],
+  ...extra,
+});
+
+// UI verifies assert markers against the BUILT (minified) mirror bundle — the same bytes the
+// browser runs — not the .tsx source, so a marker that the bundler erases can't false-green.
+let bundle: Promise<string> | null = null;
+const mirrorBundle = (): Promise<string> => (bundle ??= buildOpenRouterMirrorClient());
+
+async function withMirror(fn: (baseUrl: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'openrouter-mirror-cap-'));
+  const server = await createOpenRouterMirrorServer({ root });
+  try {
+    return await fn(`http://127.0.0.1:${server.port}`);
+  } catch (err) {
+    if (isInfrastructureError(err)) throw harnessError('openrouter.withMirror', err);
+    return false;
+  } finally {
+    server.stop();
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+export const OPENROUTER_CAPABILITIES: CapabilitySpec[] = [
+
+  done('openrouter.chat.create', 'chat', 'Chat completions: create returns OpenAI-compatible envelope', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      const b = r.body as Body;
+      return r.status === 200 && b.object === 'chat.completion' && b.model === 'google/gemini-3-flash-preview' &&
+        typeof b.id === 'string' && b.choices?.[0]?.message?.role === 'assistant' && typeof b.usage?.cost === 'number';
+    }),
+  ),
+  done('openrouter.chat.stub_labeled', 'chat', 'Chat output is clearly labeled as a twin stub', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      const text = (r.body as Body).choices?.[0]?.message?.content as string;
+      return r.status === 200 && text.includes('[twin-stub:openrouter') && text.includes('hello openrouter twin');
+    }),
+  ),
+  done('openrouter.chat.validation', 'chat', 'Chat rejects empty or malformed messages with vendor-shaped error', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const empty = await h({ m: 'POST', p: '/api/v1/chat/completions', b: { model: 'openai/gpt-4o', messages: [] } });
+      const malformed = await h({ m: 'POST', p: '/api/v1/chat/completions', b: { model: 'openai/gpt-4o', messages: [{ content: 'x' }] } });
+      const noContent = await h({ m: 'POST', p: '/api/v1/chat/completions', b: { model: 'openai/gpt-4o', messages: [{ role: 'user' }] } });
+      const unknownModel = await h({ m: 'POST', p: '/api/v1/chat/completions', b: { model: 'not-a/provider', messages: [{ role: 'user', content: 'x' }] } });
+      return empty.status === 400 && malformed.status === 400 && noContent.status === 400 && unknownModel.status === 404 &&
+        !!(empty.body as Body).error?.code && (unknownModel.body as Body).error?.code === 'not_found';
+    }),
+  ),
+  done('openrouter.chat.default_model', 'chat', 'Chat defaults model when omitted', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: { messages: [{ role: 'user', content: 'default' }] } });
+      return r.status === 200 && (r.body as Body).model === 'openai/gpt-4o';
+    }),
+  ),
+  done('openrouter.chat.multiple_choices', 'chat', 'Chat supports n choices with stable indexes', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ n: 3 }) });
+      const choices = (r.body as Body).choices as Body[];
+      return r.status === 200 && choices.length === 3 && choices[0]!.index === 0 && choices[2]!.index === 2;
+    }),
+  ),
+  done('openrouter.chat.max_tokens', 'chat', 'Chat honors max_tokens/max_completion_tokens as a length cap', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ max_tokens: 1 }) });
+      return r.status === 200 && (r.body as Body).choices?.[0]?.finish_reason === 'length';
+    }),
+  ),
+  done('openrouter.chat.tool_calls', 'chat', 'Chat returns OpenAI-compatible tool_call envelope', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ tools: [{ type: 'function', function: { name: 'lookup' } }] }) });
+      const choice = (r.body as Body).choices?.[0];
+      return r.status === 200 && choice?.finish_reason === 'tool_calls' && choice?.message?.tool_calls?.[0]?.function?.name === 'lookup';
+    }),
+  ),
+  done('openrouter.chat.usage_details', 'chat', 'Chat usage includes OpenRouter-style cost and token detail fields', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      const usage = (r.body as Body).usage;
+      return r.status === 200 && typeof usage.cost === 'number' && usage.prompt_tokens_details.cached_tokens === 0 &&
+        usage.completion_tokens_details.reasoning_tokens === 0;
+    }),
+  ),
+  done('openrouter.chat.v1_alias', 'chat', 'Chat accepts /v1 alias as well as /api/v1', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      return r.status === 200 && (r.body as Body).object === 'chat.completion';
+    }),
+  ),
+  done('openrouter.streaming.chunks', 'streaming', 'Streaming emits chat.completion.chunk events and [DONE]', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const events: SseEvent[] = [];
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ stream: true }), sseSink: (event) => events.push(event) });
+      return r.status === 200 && events.some((event) => event.data?.object === 'chat.completion.chunk') && events.at(-1)?.done === true;
+    }),
+  ),
+  done('openrouter.streaming.reconstruct', 'streaming', 'Streaming deltas reconstruct final content', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const events: SseEvent[] = [];
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ stream: true }), sseSink: (event) => events.push(event) });
+      const streamed = events.filter((event) => event.data).map((event) => (event.data!.choices as Body[])[0]?.delta?.content ?? '').join('');
+      const full = (r.body as Body).choices?.[0]?.message?.content;
+      return streamed === full && streamed.includes('[twin-stub');
+    }),
+  ),
+  done('openrouter.streaming.usage', 'streaming', 'Final streaming chunk includes usage', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const events: SseEvent[] = [];
+      await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ stream: true }), sseSink: (event) => events.push(event) });
+      return events.some((event) => typeof (event.data as Body | undefined)?.usage?.cost === 'number');
+    }),
+  ),
+  done('openrouter.models.list', 'models', 'Models: list all models and properties', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/models' });
+      const first = (r.body as Body).data?.[0];
+      return r.status === 200 && first?.id === 'openai/gpt-4o' && typeof first?.pricing?.prompt === 'string';
+    }),
+  ),
+  done('openrouter.models.retrieve', 'models', 'Models: retrieve a model by slug', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/models/openai/gpt-4o' });
+      return r.status === 200 && (r.body as Body).data?.id === 'openai/gpt-4o';
+    }),
+  ),
+  done('openrouter.models.count', 'models', 'Models: total count endpoint', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/models/count' });
+      return r.status === 200 && (r.body as Body).data?.count >= 3;
+    }),
+  ),
+  done('openrouter.models.endpoints', 'models', 'Models: list endpoints for a model', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/models/openai/gpt-4o/endpoints' });
+      return r.status === 200 && (r.body as Body).data?.endpoints?.[0]?.provider_name === 'twin';
+    }),
+  ),
+  done('openrouter.models.not_found', 'models', 'Models: unknown model returns 404', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/models/nope/nope' });
+      return r.status === 404 && !!(r.body as Body).error;
+    }),
+  ),
+  done('openrouter.key.current', 'keys', 'Current API key metadata endpoint', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/key' });
+      return r.status === 200 && (r.body as Body).data?.label === 'twin-key';
+    }),
+  ),
+  done('openrouter.credits.get', 'credits', 'Credits: remaining credits endpoint', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/credits' });
+      return r.status === 200 && (r.body as Body).data?.total_credits === 100;
+    }),
+  ),
+  done('openrouter.generation.stats', 'generations', 'Generation stats are queryable by completion id', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const chat = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      const id = (chat.body as Body).id;
+      const stats = await h({ m: 'GET', p: `/api/v1/generation?id=${encodeURIComponent(id)}` });
+      const data = (stats.body as Body).data;
+      return stats.status === 200 && data?.model === 'google/gemini-3-flash-preview' &&
+        data?.api_type === 'chat' && data?.provider_name === 'twin' && data?.request_id === id &&
+        data?.finish_reason === 'stop' && typeof data?.usage === 'number';
+    }),
+  ),
+  done('openrouter.generation.list_local', 'generations', 'Local mirror lists recorded generations', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      const list = await h({ m: 'GET', p: '/api/v1/generations' });
+      return list.status === 200 && (list.body as Body).data?.length === 1;
+    }),
+  ),
+  done('openrouter.readonly.rejects_chat', 'honesty', 'readOnly rejects local chat writes', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'openrouter-cap-'));
+    try {
+      const r = await handleOpenRouterTwinRequest({ method: 'POST', path: '/api/v1/chat/completions', body: JSON.stringify(CHAT()), readOnly: true, root });
+      return r.status === 405;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('openrouter.unmodeled.404', 'honesty', 'Unmodeled operations fail with 404 instead of fake success', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/totally/unmodeled/op', b: { name: 'x' } });
+      return r.status === 404 && (r.body as Body).error?.code === 'not_found';
+    }),
+  ),
+  done('openrouter.ui.mirror_markers', 'ui', 'Mirror Models catalog + Generations screens read live twin APIs', 'ui', 'common', async () =>
+    await withMirror(async (baseUrl) => {
+      // (1) the built mirror renders the three panel markers served by the mirror server …
+      const js = await mirrorBundle();
+      if (!['models-panel', 'generations-panel', 'playground-panel'].every((m) => js.includes(m))) return false;
+      // the shell loads the bundle relative to its <base> (the hosted mirror mounts it under a path), and it is served
+      const shell = await fetch(`${baseUrl}/`).then((r) => r.text());
+      if (!shell.includes('src="assets/app.js"') || (await fetch(`${baseUrl}/assets/app.js`)).status !== 200) return false;
+      // (2) … AND both data panels are coupled to the SAME mirror APIs the App component fetches.
+      const models = await fetch(`${baseUrl}/api/v1/models`).then((r) => r.json()) as Body;
+      if (!(models.data?.length >= 1 && models.data?.[0]?.id === 'openai/gpt-4o')) return false;
+      const emptyRows = await fetch(`${baseUrl}/api/v1/generations`).then((r) => r.json()) as Body;
+      if (emptyRows.data?.length !== 0) return false;
+      await fetch(`${baseUrl}/api/v1/chat/completions`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(CHAT()) });
+      const rows = await fetch(`${baseUrl}/api/v1/generations`).then((r) => r.json()) as Body;
+      return rows.data?.length === 1 && rows.data?.[0]?.model === 'google/gemini-3-flash-preview';
+    }),
+  ),
+  done('openrouter.ui.stub_banner', 'ui', 'Mirror playground renders the live stub completion and labels it', 'ui', 'common', () =>
+    withRoot(async (h) => {
+      // (1) the built mirror carries the stub banner copy the Playground emits …
+      const js = await mirrorBundle();
+      if (!(js.includes('Stub completion') && js.includes('no provider model was run'))) return false;
+      // (2) … AND the playground output is data-coupled: the same chat endpoint the Send button POSTs
+      // returns the labeled stub content the <pre> renders (not hardcoded UI text).
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: 'Summarize the OpenRouter twin.' }] }) });
+      const content = (r.body as Body).choices?.[0]?.message?.content as string;
+      return r.status === 200 && content.includes('[twin-stub:openrouter') && content.includes('Summarize the OpenRouter twin.');
+    }),
+  ),
+  done('openrouter.connector.pull', 'connector', "Connector pulls the model catalog AND the account's provisioning keys through an injected client, idempotently — two domains, two calls", 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'openrouter-connector-cap-'));
+    try {
+      let calls = 0;
+      const execute = async () => {
+        calls++;
+        return { status: 200, data: { data: [{ id: 'vendor/model-a', name: 'Vendor Model A', context_length: 4096 }] } };
+      };
+      await pullOpenRouterState(execute, { root });
+      await pullOpenRouterState(execute, { root });
+      const models = projectResources('openrouter', root).filter((r) => r.type === 'model');
+      // two domains per pull, so two pulls are four calls; the fake answers both with the same page
+      return calls === 4 && models.length === 1 && models[0]?.id === 'model_vendor/model-a';
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('openrouter.connector.push', 'connector', 'Connector confirms pending generation actions through an injected client idempotently', 'connector', 'niche', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'openrouter-connector-cap-'));
+    try {
+      await applyTwinWrite('openrouter', {
+        operation: 'generation.record',
+        subjectType: 'generation',
+        subjectId: 'generation_chatcmpl-cap',
+        fields: { id: 'generation_chatcmpl-cap', object: 'generation', model: 'openai/gpt-4o' },
+        occurredAt: '1970-01-01T00:00:00.000Z',
+        actor: { kind: 'system' },
+      }, root);
+      const paths: string[] = [];
+      const execute = async (req: { path: string }) => {
+        paths.push(req.path);
+        return { status: 200, data: { ok: true } };
+      };
+      const first = await pushPendingOpenRouterActions(execute, { root });
+      const second = await pushPendingOpenRouterActions(execute, { root });
+      return first === 1 && second === 0 && deployableEntries('openrouter', root).length === 0 &&
+        paths.length === 1 && paths[0] === '/api/v1/generation?id=chatcmpl-cap';
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+
+  done('openrouter.chat.response_format', 'chat', 'Chat response_format json_object/json_schema', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const ok = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ response_format: { type: 'json_object' } }) });
+      const content = (ok.body as Body).choices?.[0]?.message?.content as string;
+      let parsed: Body | null = null;
+      try { parsed = JSON.parse(content); } catch { parsed = null; }
+      const schemaOk = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ response_format: { type: 'json_schema', json_schema: { name: 'echo', schema: { type: 'object' } } } }) });
+      const bad = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ response_format: { type: 'csv' } }) });
+      return ok.status === 200 && parsed?.twin_stub === true && schemaOk.status === 200 &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_response_format';
+    }),
+  ),
+  done('openrouter.chat.reasoning', 'chat', 'Reasoning controls surface reasoning text and reasoning_tokens', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ reasoning: { effort: 'high' } }) });
+      const msg = (r.body as Body).choices?.[0]?.message;
+      const reasoned = (r.body as Body).usage?.completion_tokens_details?.reasoning_tokens;
+      const excluded = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ reasoning: { effort: 'low', exclude: true } }) });
+      const bad = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ reasoning: { effort: 'turbo' } }) });
+      return r.status === 200 && typeof msg.reasoning === 'string' && reasoned === 256 &&
+        excluded.status === 200 && (excluded.body as Body).choices?.[0]?.message?.reasoning === undefined &&
+        (excluded.body as Body).usage?.completion_tokens_details?.reasoning_tokens === 16 &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_reasoning';
+    }),
+  ),
+  done('openrouter.chat.web_search', 'chat', 'Web search plugin/online suffix returns url_citation annotations', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const viaPlugin = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ plugins: [{ id: 'web', max_results: 2 }] }) });
+      const ann = (viaPlugin.body as Body).choices?.[0]?.message?.annotations as Body[] | undefined;
+      const viaOnline = await h({ m: 'POST', p: '/api/v1/chat/completions', b: { ...CHAT(), model: 'openai/gpt-4o:online' } });
+      const bad = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ plugins: [{ id: 'web', max_results: 0 }] }) });
+      return viaPlugin.status === 200 && ann?.length === 2 && ann[0]?.type === 'url_citation' &&
+        String(ann[0]?.url_citation?.title).includes('[twin-stub:openrouter:web_search]') &&
+        viaOnline.status === 200 && ((viaOnline.body as Body).choices?.[0]?.message?.annotations as Body[])?.length >= 1 &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_web_search';
+    }),
+  ),
+  done('openrouter.chat.cache_control', 'chat', 'Prompt cache_control marks cached_tokens in usage', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const cached = await h({ m: 'POST', p: '/api/v1/chat/completions', b: {
+        model: 'openai/gpt-4o',
+        messages: [
+          { role: 'system', content: 'You are a long cached system prompt for the twin.', cache_control: { type: 'ephemeral' } },
+          { role: 'user', content: 'hello' },
+        ],
+      } });
+      const uncached = await h({ m: 'POST', p: '/api/v1/chat/completions', b: { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'hello' }] } });
+      const cachedTokens = (cached.body as Body).usage?.prompt_tokens_details?.cached_tokens;
+      const plainTokens = (uncached.body as Body).usage?.prompt_tokens_details?.cached_tokens;
+      return cached.status === 200 && cachedTokens > 0 && plainTokens === 0;
+    }),
+  ),
+  done('openrouter.chat.provider_preferences', 'chat', 'Provider routing/preferences parameter is accepted and echoed', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ provider: { order: ['twin'], allow_fallbacks: false } }) });
+      const bad = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ provider: 'twin' }) });
+      return r.status === 200 && (r.body as Body).provider === 'twin' &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_provider';
+    }),
+  ),
+  done('openrouter.chat.transforms', 'chat', 'Prompt transforms are validated and echoed', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const ok = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ transforms: ['middle-out'] }) });
+      const bad = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ transforms: ['nope'] }) });
+      const notArray = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ transforms: 'middle-out' }) });
+      return ok.status === 200 && JSON.stringify((ok.body as Body).transforms) === JSON.stringify(['middle-out']) &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_transforms' &&
+        notArray.status === 400 && (notArray.body as Body).error?.code === 'invalid_transforms';
+    }),
+  ),
+  done('openrouter.chat.logprobs', 'chat', 'logprobs + top_logprobs return OpenAI-shaped per-token logprobs', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ logprobs: true, top_logprobs: 2 }) });
+      const lp = (r.body as Body).choices?.[0]?.logprobs;
+      const first = lp?.content?.[0];
+      const off = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      const badTop = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ logprobs: true, top_logprobs: 99 }) });
+      return r.status === 200 && Array.isArray(lp?.content) && typeof first?.logprob === 'number' &&
+        first?.top_logprobs?.length === 2 && typeof first?.top_logprobs?.[0]?.logprob === 'number' &&
+        (off.body as Body).choices?.[0]?.logprobs === undefined &&
+        badTop.status === 400 && (badTop.body as Body).error?.code === 'invalid_top_logprobs';
+    }),
+  ),
+  done('openrouter.chat.modalities', 'chat', 'Image output modality attaches a labeled stub image; bad modality rejected', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ modalities: ['text', 'image'] }) });
+      const images = (r.body as Body).choices?.[0]?.message?.images as Body[] | undefined;
+      const bad = await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT({ modalities: ['hologram'] }) });
+      const url = String(images?.[0]?.image_url?.url ?? '');
+      return r.status === 200 && images?.length === 1 && url.startsWith('data:image/png;base64,') &&
+        Buffer.from(url.split(',')[1] ?? '', 'base64').toString().includes('[twin-stub:openrouter:image]') &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_modalities';
+    }),
+  ),
+  done('openrouter.responses.create', 'responses', 'Responses API beta: create response', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/responses', b: { model: 'openai/gpt-4o', input: 'hello responses' } });
+      const b = r.body as Body;
+      const textItem = (b.output as Body[])?.find((o) => o.type === 'message');
+      const bad = await h({ m: 'POST', p: '/api/v1/responses', b: { model: 'openai/gpt-4o' } });
+      const unknown = await h({ m: 'POST', p: '/api/v1/responses', b: { model: 'no/model', input: 'x' } });
+      return r.status === 200 && b.object === 'response' && b.status === 'completed' &&
+        String(b.output_text).includes('[twin-stub:openrouter') && textItem?.content?.[0]?.type === 'output_text' &&
+        b.usage?.input_tokens > 0 && bad.status === 400 && unknown.status === 404;
+    }),
+  ),
+  done('openrouter.responses.reasoning', 'responses', 'Responses API reasoning emits a reasoning output item', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/responses', b: { model: 'openai/gpt-4o', input: 'think', reasoning: { effort: 'medium' } } });
+      const reasoningItem = ((r.body as Body).output as Body[])?.find((o) => o.type === 'reasoning');
+      const reasoned = (r.body as Body).usage?.output_tokens_details?.reasoning_tokens;
+      return r.status === 200 && reasoningItem?.summary?.[0]?.type === 'summary_text' && reasoned === 64;
+    }),
+  ),
+  done('openrouter.responses.tool_calling', 'responses', 'Responses API returns a function_call output item', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/responses', b: { model: 'openai/gpt-4o', input: 'call', tools: [{ type: 'function', name: 'lookup' }] } });
+      const fc = ((r.body as Body).output as Body[])?.find((o) => o.type === 'function_call');
+      return r.status === 200 && fc?.name === 'lookup' && typeof fc?.call_id === 'string' && fc?.status === 'completed';
+    }),
+  ),
+  done('openrouter.responses.web_search', 'responses', 'Responses API web search attaches url citations', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/responses', b: { model: 'openai/gpt-4o', input: 'find', plugins: [{ id: 'web', max_results: 2 }] } });
+      const msg = ((r.body as Body).output as Body[])?.find((o) => o.type === 'message');
+      const ann = msg?.content?.[0]?.annotations as Body[] | undefined;
+      return r.status === 200 && ann?.length === 2 && ann[0]?.type === 'url_citation';
+    }),
+  ),
+  done('openrouter.anthropic.messages', 'anthropic_messages', 'Anthropic Messages compatibility endpoint', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/messages', b: { model: 'anthropic/claude-sonnet-4.5', max_tokens: 64, messages: [{ role: 'user', content: 'hello claude' }] } });
+      const b = r.body as Body;
+      const noMax = await h({ m: 'POST', p: '/api/v1/messages', b: { model: 'anthropic/claude-sonnet-4.5', messages: [{ role: 'user', content: 'x' }] } });
+      return r.status === 200 && b.type === 'message' && b.role === 'assistant' &&
+        String(b.content?.[0]?.text).includes('[twin-stub:openrouter') && b.stop_reason === 'end_turn' &&
+        typeof b.usage?.input_tokens === 'number' && noMax.status === 400 && (noMax.body as Body).error?.code === 'invalid_max_tokens';
+    }),
+  ),
+  done('openrouter.embeddings.create', 'embeddings', 'Embeddings endpoint', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/embeddings', b: { model: 'openai/text-embedding-3-small', input: ['alpha', 'beta'] } });
+      const b = r.body as Body;
+      const first = b.data?.[0];
+      const same = await h({ m: 'POST', p: '/api/v1/embeddings', b: { model: 'openai/text-embedding-3-small', input: ['alpha'] } });
+      const deterministic = JSON.stringify((same.body as Body).data?.[0]?.embedding) === JSON.stringify(first?.embedding);
+      const bad = await h({ m: 'POST', p: '/api/v1/embeddings', b: { model: 'openai/text-embedding-3-small' } });
+      return r.status === 200 && b.object === 'list' && b.data?.length === 2 && first?.index === 0 &&
+        Array.isArray(first?.embedding) && first.embedding.length === 8 && deterministic &&
+        b.usage?.prompt_tokens > 0 && bad.status === 400;
+    }),
+  ),
+  done('openrouter.providers.list', 'providers', 'Providers: list all providers', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/providers' });
+      const data = (r.body as Body).data as Body[];
+      return r.status === 200 && data?.length >= 3 && data.some((p) => p.slug === 'anthropic' && typeof p.may_log_prompts === 'boolean');
+    }),
+  ),
+  done('openrouter.rerank.submit', 'rerank', 'Rerank: submit request returns scored results', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/rerank', b: { model: 'twin/rerank-1', query: 'orange fruit', documents: ['a green car', 'an orange fruit basket'], top_n: 2 } });
+      const results = (r.body as Body).results as Body[];
+      const bad = await h({ m: 'POST', p: '/api/v1/rerank', b: { model: 'twin/rerank-1', query: 'x' } });
+      // index 1 mentions the query terms, index 0 does not → it must rank first.
+      return r.status === 200 && results?.length === 2 && results[0]!.relevance_score >= results[1]!.relevance_score &&
+        results[0]!.index === 1 && results[1]!.index === 0 && results[0]!.relevance_score > 0 && results[1]!.relevance_score === 0 &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_documents';
+    }),
+  ),
+  done('openrouter.api_keys.list', 'api_keys', 'API keys: list keys reflects created keys', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const empty = await h({ m: 'GET', p: '/api/v1/keys' });
+      await h({ m: 'POST', p: '/api/v1/keys', b: { name: 'ci key' } });
+      const list = await h({ m: 'GET', p: '/api/v1/keys' });
+      const rows = (list.body as Body).data as Body[];
+      return empty.status === 200 && (empty.body as Body).data?.length === 0 &&
+        list.status === 200 && rows?.length === 1 && rows[0]?.name === 'ci key' && !String(rows[0]?.id).startsWith('key_');
+    }),
+  ),
+  done('openrouter.api_keys.create', 'api_keys', 'API keys: create key returns the secret once', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/keys', b: { name: 'deploy', limit: 5 } });
+      const b = (r.body as Body).data;
+      const bad = await h({ m: 'POST', p: '/api/v1/keys', b: {} });
+      const ro = await handleOpenRouterTwinRequestRO('POST', '/api/v1/keys', { name: 'x' });
+      return r.status === 200 && typeof b?.key === 'string' && b.key.startsWith('sk-or-v1-twin-') &&
+        b.limit === 5 && b.disabled === false && bad.status === 400 && ro.status === 405;
+    }),
+  ),
+  done('openrouter.api_keys.update', 'api_keys', 'API keys: update/delete key mutates persisted state', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/api/v1/keys', b: { name: 'rotate' } });
+      const hash = (created.body as Body).data?.hash;
+      const upd = await h({ m: 'PATCH', p: `/api/v1/keys/${hash}`, b: { disabled: true, name: 'rotated' } });
+      const list = await h({ m: 'GET', p: '/api/v1/keys' });
+      const after = ((list.body as Body).data as Body[])?.[0];
+      const del = await h({ m: 'DELETE', p: `/api/v1/keys/${hash}` });
+      const afterDel = ((await h({ m: 'GET', p: '/api/v1/keys' })).body as Body).data;
+      const missing = await h({ m: 'PATCH', p: '/api/v1/keys/nope', b: { name: 'x' } });
+      return upd.status === 200 && after?.disabled === true && after?.name === 'rotated' &&
+        del.status === 200 && (del.body as Body).data?.deleted === true && afterDel?.length === 0 && missing.status === 404;
+    }),
+  ),
+  done('openrouter.byok.list', 'byok', 'BYOK: list provider credentials', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const empty = await h({ m: 'GET', p: '/api/v1/keys/byok' });
+      await h({ m: 'POST', p: '/api/v1/keys/byok', b: { provider_name: 'anthropic', api_key: 'sk-ant-secret1234' } });
+      const list = await h({ m: 'GET', p: '/api/v1/keys/byok' });
+      const rows = (list.body as Body).data as Body[];
+      return empty.status === 200 && (empty.body as Body).data?.length === 0 &&
+        rows?.length === 1 && rows[0]?.provider_name === 'anthropic' && rows[0]?.api_key_preview === '...1234' &&
+        !String(rows[0]?.id).includes('sk-ant');
+    }),
+  ),
+  done('openrouter.byok.create', 'byok', 'BYOK: create provider credential validates provider', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const ok = await h({ m: 'POST', p: '/api/v1/keys/byok', b: { provider_name: 'openai', api_key: 'sk-secretkey99' } });
+      const unknown = await h({ m: 'POST', p: '/api/v1/keys/byok', b: { provider_name: 'made-up', api_key: 'x' } });
+      const missing = await h({ m: 'POST', p: '/api/v1/keys/byok', b: { provider_name: 'openai' } });
+      return ok.status === 200 && (ok.body as Body).data?.enabled === true &&
+        unknown.status === 400 && (unknown.body as Body).error?.code === 'unknown_provider' &&
+        missing.status === 400 && (missing.body as Body).error?.code === 'invalid_api_key';
+    }),
+  ),
+  done('openrouter.byok.update', 'byok', 'BYOK: update/delete provider credential', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/api/v1/keys/byok', b: { provider_name: 'openai', api_key: 'sk-orig0000' } });
+      const upd = await h({ m: 'PATCH', p: '/api/v1/keys/byok/openai', b: { enabled: false } });
+      const afterUpd = ((await h({ m: 'GET', p: '/api/v1/keys/byok' })).body as Body).data?.[0];
+      const del = await h({ m: 'DELETE', p: '/api/v1/keys/byok/openai' });
+      const afterDel = ((await h({ m: 'GET', p: '/api/v1/keys/byok' })).body as Body).data;
+      const missing = await h({ m: 'DELETE', p: '/api/v1/keys/byok/anthropic' });
+      return upd.status === 200 && afterUpd?.enabled === false && del.status === 200 &&
+        afterDel?.length === 0 && missing.status === 404;
+    }),
+  ),
+  done('openrouter.presets.list', 'presets', 'Presets: list/get presets', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/api/v1/presets', b: { name: 'My Preset', model: 'openai/gpt-4o', parameters: { temperature: 0.2 } } });
+      const slug = (created.body as Body).data?.slug;
+      const list = await h({ m: 'GET', p: '/api/v1/presets' });
+      const get = await h({ m: 'GET', p: `/api/v1/presets/${slug}` });
+      const missing = await h({ m: 'GET', p: '/api/v1/presets/nope' });
+      return list.status === 200 && (list.body as Body).data?.length === 1 && slug === 'my-preset' &&
+        get.status === 200 && (get.body as Body).data?.parameters?.temperature === 0.2 && missing.status === 404;
+    }),
+  ),
+  done('openrouter.presets.create_chat', 'presets', 'Presets: create from chat completions body', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/presets', b: { name: 'Chat Preset', model: 'openai/gpt-4o' } });
+      const b = (r.body as Body).data;
+      const badModel = await h({ m: 'POST', p: '/api/v1/presets', b: { name: 'x', model: 'no/model' } });
+      const noName = await h({ m: 'POST', p: '/api/v1/presets', b: { model: 'openai/gpt-4o' } });
+      return r.status === 200 && b?.source === 'chat' && b?.model === 'openai/gpt-4o' &&
+        badModel.status === 404 && noName.status === 400;
+    }),
+  ),
+  done('openrouter.files.upload', 'files', 'Files: upload returns a processed file object', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/files', b: { filename: 'data.jsonl', purpose: 'user_data', content: 'a\nb\nc' } });
+      const b = r.body as Body;
+      const noName = await h({ m: 'POST', p: '/api/v1/files', b: { purpose: 'user_data' } });
+      const badPurpose = await h({ m: 'POST', p: '/api/v1/files', b: { filename: 'x', purpose: 'wat' } });
+      const ro = await handleOpenRouterTwinRequestRO('POST', '/api/v1/files', { filename: 'x' });
+      return r.status === 200 && b.object === 'file' && b.filename === 'data.jsonl' && b.purpose === 'user_data' &&
+        b.bytes === 5 && b.status === 'processed' && typeof b.id === 'string' && !String(b.id).startsWith('file_') &&
+        noName.status === 400 && badPurpose.status === 400 && (badPurpose.body as Body).error?.code === 'invalid_purpose' && ro.status === 405;
+    }),
+  ),
+  done('openrouter.files.retrieve', 'files', 'Files: retrieve/list/delete reflect persisted state', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/api/v1/files', b: { filename: 'doc.txt', content: 'hello' } });
+      const id = (created.body as Body).id;
+      const list = await h({ m: 'GET', p: '/api/v1/files' });
+      const get = await h({ m: 'GET', p: `/api/v1/files/${id}` });
+      const del = await h({ m: 'DELETE', p: `/api/v1/files/${id}` });
+      const afterDel = await h({ m: 'GET', p: '/api/v1/files' });
+      const missing = await h({ m: 'GET', p: '/api/v1/files/nope' });
+      return list.status === 200 && (list.body as Body).object === 'list' && (list.body as Body).data?.length === 1 &&
+        get.status === 200 && (get.body as Body).filename === 'doc.txt' &&
+        del.status === 200 && (del.body as Body).deleted === true && (afterDel.body as Body).data?.length === 0 && missing.status === 404;
+    }),
+  ),
+  done('openrouter.oauth.authorization_code_create', 'oauth', 'OAuth: create authorization code with PKCE challenge + redirect', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/auth/authorize', b: { callback_url: 'https://app.local/cb', code_challenge: 'abc', code_challenge_method: 'S256' } });
+      const b = (r.body as Body).data;
+      const noCb = await h({ m: 'POST', p: '/api/v1/auth/authorize', b: { code_challenge: 'abc' } });
+      const noChal = await h({ m: 'POST', p: '/api/v1/auth/authorize', b: { callback_url: 'https://app.local/cb' } });
+      return r.status === 200 && typeof b?.code === 'string' && String(b?.redirect_url).startsWith('https://app.local/cb?code=') &&
+        noCb.status === 400 && (noCb.body as Body).error?.code === 'invalid_callback_url' &&
+        noChal.status === 400 && (noChal.body as Body).error?.code === 'invalid_code_challenge';
+    }),
+  ),
+  done('openrouter.oauth.exchange', 'oauth', 'OAuth: exchange code for API key validates PKCE verifier; single-use', 'api', 'common', () =>
+    withRoot(async (h) => {
+      // S256(verifier) must equal challenge. Use a known pair.
+      const verifier = 'twin-pkce-verifier-string';
+      const challenge = createHash('sha256').update(verifier).digest('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+      const auth = await h({ m: 'POST', p: '/api/v1/auth/authorize', b: { callback_url: 'https://app.local/cb', code_challenge: challenge } });
+      const code = (auth.body as Body).data?.code;
+      const wrong = await h({ m: 'POST', p: '/api/v1/auth/keys', b: { code, code_verifier: 'wrong' } });
+      const ok = await h({ m: 'POST', p: '/api/v1/auth/keys', b: { code, code_verifier: verifier } });
+      const reused = await h({ m: 'POST', p: '/api/v1/auth/keys', b: { code, code_verifier: verifier } });
+      const keys = await h({ m: 'GET', p: '/api/v1/keys' });
+      return wrong.status === 400 && (wrong.body as Body).error?.code === 'invalid_code_verifier' &&
+        ok.status === 200 && String((ok.body as Body).key).startsWith('sk-or-v1-twin-') &&
+        reused.status === 400 && (reused.body as Body).error?.code === 'code_already_used' &&
+        (keys.body as Body).data?.length === 1;
+    }),
+  ),
+  done('openrouter.speech.create', 'speech', 'Speech: returns a labeled deterministic stub audio envelope', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/audio/speech', b: { model: 'twin/tts-1', input: 'hello world', voice: 'nova' } });
+      const b = r.body as Body;
+      const decoded = Buffer.from(String(b.audio), 'base64').toString();
+      const bad = await h({ m: 'POST', p: '/api/v1/audio/speech', b: { model: 'twin/tts-1' } });
+      return r.status === 200 && b.object === 'audio.speech' && b.voice === 'nova' && b.stub === true &&
+        decoded.includes('[twin-stub:openrouter:speech]') && decoded.includes('hello world') &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_input';
+    }),
+  ),
+  done('openrouter.transcriptions.create', 'transcriptions', 'Transcriptions: returns a labeled deterministic stub transcript', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/audio/transcriptions', b: { model: 'twin/whisper-1', file: 'base64audio' } });
+      const b = r.body as Body;
+      const bad = await h({ m: 'POST', p: '/api/v1/audio/transcriptions', b: { model: 'twin/whisper-1' } });
+      return r.status === 200 && b.object === 'audio.transcription' && String(b.text).includes('[twin-stub:openrouter:transcription]') &&
+        b.stub === true && bad.status === 400 && (bad.body as Body).error?.code === 'invalid_file';
+    }),
+  ),
+  done('openrouter.analytics.activity', 'analytics', 'Analytics: activity is computed from recorded generations grouped by model', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const empty = await h({ m: 'GET', p: '/api/v1/analytics/activity' });
+      await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      await h({ m: 'POST', p: '/api/v1/chat/completions', b: { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'second' }] } });
+      const r = await h({ m: 'GET', p: '/api/v1/analytics/activity' });
+      const rows = (r.body as Body).data as Body[];
+      const gemini = rows.find((x) => x.model === 'google/gemini-3-flash-preview');
+      return empty.status === 200 && (empty.body as Body).data?.length === 0 &&
+        rows.length === 2 && gemini?.requests === 1 && gemini?.prompt_tokens > 0 && typeof gemini?.usage === 'number';
+    }),
+  ),
+  done('openrouter.analytics.query', 'analytics', 'Analytics: metric/dimension query aggregates recorded generations', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      await h({ m: 'POST', p: '/api/v1/chat/completions', b: { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'q' }] } });
+      const byModel = await h({ m: 'GET', p: '/api/v1/analytics/query?metric=requests&dimension=model' });
+      const data = (byModel.body as Body).data as Body[];
+      const post = await h({ m: 'POST', p: '/api/v1/analytics/query', b: { metric: 'total_tokens', dimension: 'date' } });
+      const bad = await h({ m: 'GET', p: '/api/v1/analytics/query?metric=bogus' });
+      return byModel.status === 200 && data.length === 2 && data.every((d) => d.requests === 1) &&
+        post.status === 200 && (post.body as Body).data?.[0]?.total_tokens > 0 &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_metric';
+    }),
+  ),
+  done('openrouter.analytics.daily_tokens', 'analytics', 'Analytics: daily token totals computed from recorded generations', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/api/v1/chat/completions', b: CHAT() });
+      await h({ m: 'POST', p: '/api/v1/chat/completions', b: { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'd' }] } });
+      const r = await h({ m: 'GET', p: '/api/v1/analytics/daily' });
+      const rows = (r.body as Body).data as Body[];
+      return r.status === 200 && rows.length === 1 && rows[0]?.requests === 2 &&
+        rows[0]?.total_tokens === rows[0]?.prompt_tokens + rows[0]?.completion_tokens && rows[0]?.total_tokens > 0;
+    }),
+  ),
+  done('openrouter.presets.create_responses', 'presets', 'Presets: create from responses body tags source=responses', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/presets/responses', b: { name: 'Resp Preset', model: 'openai/gpt-4o', parameters: { temperature: 0.5 } } });
+      const b = (r.body as Body).data;
+      const get = await h({ m: 'GET', p: `/api/v1/presets/${b?.slug}` });
+      const badModel = await h({ m: 'POST', p: '/api/v1/presets/responses', b: { name: 'x', model: 'no/model' } });
+      return r.status === 200 && b?.source === 'responses' && b?.slug === 'resp-preset' &&
+        get.status === 200 && (get.body as Body).data?.source === 'responses' && badModel.status === 404;
+    }),
+  ),
+  done('openrouter.datasets.list', 'datasets', 'Datasets: list reflects created datasets', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const empty = await h({ m: 'GET', p: '/api/v1/datasets' });
+      await h({ m: 'POST', p: '/api/v1/datasets', b: { name: 'eval set' } });
+      const list = await h({ m: 'GET', p: '/api/v1/datasets' });
+      const rows = (list.body as Body).data as Body[];
+      return empty.status === 200 && (empty.body as Body).data?.length === 0 &&
+        list.status === 200 && rows?.length === 1 && rows[0]?.name === 'eval set' && !String(rows[0]?.id).startsWith('dataset_');
+    }),
+  ),
+  done('openrouter.datasets.create', 'datasets', 'Datasets: create validates name and persists', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/datasets', b: { name: 'My Dataset', description: 'd' } });
+      const b = (r.body as Body).data;
+      const noName = await h({ m: 'POST', p: '/api/v1/datasets', b: {} });
+      const ro = await handleOpenRouterTwinRequestRO('POST', '/api/v1/datasets', { name: 'x' });
+      return r.status === 200 && b?.name === 'My Dataset' && b?.status === 'ready' && b?.row_count === 0 &&
+        noName.status === 400 && ro.status === 405;
+    }),
+  ),
+  done('openrouter.guardrails.crud', 'guardrails', 'Guardrails: create/list/get/update/delete persist through the kernel', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/api/v1/guardrails', b: { name: 'PII Filter', rules: [{ kind: 'pii' }] } });
+      const id = (created.body as Body).data?.id;
+      const list = await h({ m: 'GET', p: '/api/v1/guardrails' });
+      const upd = await h({ m: 'PATCH', p: `/api/v1/guardrails/${id}`, b: { enabled: false, name: 'PII Off' } });
+      const get = await h({ m: 'GET', p: `/api/v1/guardrails/${id}` });
+      const del = await h({ m: 'DELETE', p: `/api/v1/guardrails/${id}` });
+      const afterDel = await h({ m: 'GET', p: '/api/v1/guardrails' });
+      const noName = await h({ m: 'POST', p: '/api/v1/guardrails', b: {} });
+      return created.status === 200 && (list.body as Body).data?.length === 1 && upd.status === 200 &&
+        (get.body as Body).data?.enabled === false && (get.body as Body).data?.name === 'PII Off' &&
+        del.status === 200 && (afterDel.body as Body).data?.length === 0 && noName.status === 400;
+    }),
+  ),
+  done('openrouter.guardrails.assignments', 'guardrails', 'Guardrails: set/get key assignments persist', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/api/v1/guardrails', b: { name: 'GR' } });
+      const id = (created.body as Body).data?.id;
+      const set = await h({ m: 'PUT', p: `/api/v1/guardrails/${id}/assignments`, b: { key_hashes: ['h1', 'h2'] } });
+      const get = await h({ m: 'GET', p: `/api/v1/guardrails/${id}/assignments` });
+      const bad = await h({ m: 'PUT', p: `/api/v1/guardrails/${id}/assignments`, b: {} });
+      const missing = await h({ m: 'GET', p: '/api/v1/guardrails/nope/assignments' });
+      return set.status === 200 && JSON.stringify((get.body as Body).data?.key_hashes) === JSON.stringify(['h1', 'h2']) &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_assignments' && missing.status === 404;
+    }),
+  ),
+  done('openrouter.organization.members', 'organization', 'Organization: list members with roles', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/organization/members' });
+      const rows = (r.body as Body).data as Body[];
+      return r.status === 200 && rows?.length >= 2 && rows.some((m) => m.role === 'owner') && rows.every((m) => typeof m.email === 'string');
+    }),
+  ),
+  done('openrouter.workspaces.crud', 'workspaces', 'Workspaces: create/list/get/update/delete persist through the kernel', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/api/v1/workspaces', b: { name: 'Team A' } });
+      const id = (created.body as Body).data?.id;
+      const list = await h({ m: 'GET', p: '/api/v1/workspaces' });
+      const upd = await h({ m: 'PATCH', p: `/api/v1/workspaces/${id}`, b: { description: 'updated' } });
+      const get = await h({ m: 'GET', p: `/api/v1/workspaces/${id}` });
+      const del = await h({ m: 'DELETE', p: `/api/v1/workspaces/${id}` });
+      const afterDel = await h({ m: 'GET', p: '/api/v1/workspaces' });
+      const noName = await h({ m: 'POST', p: '/api/v1/workspaces', b: {} });
+      return created.status === 200 && (created.body as Body).data?.slug === 'team-a' && (list.body as Body).data?.length === 1 &&
+        upd.status === 200 && (get.body as Body).data?.description === 'updated' &&
+        del.status === 200 && (afterDel.body as Body).data?.length === 0 && noName.status === 400;
+    }),
+  ),
+  done('openrouter.workspaces.members', 'workspaces', 'Workspaces: bulk add/remove members mutates membership set', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/api/v1/workspaces', b: { name: 'WS' } });
+      const id = (created.body as Body).data?.id;
+      const add = await h({ m: 'POST', p: `/api/v1/workspaces/${id}/members`, b: { add: ['u1', 'u2'] } });
+      const remove = await h({ m: 'POST', p: `/api/v1/workspaces/${id}/members`, b: { remove: ['u1'] } });
+      const get = await h({ m: 'GET', p: `/api/v1/workspaces/${id}` });
+      const bad = await h({ m: 'POST', p: `/api/v1/workspaces/${id}/members`, b: {} });
+      return add.status === 200 && JSON.stringify((add.body as Body).data?.members) === JSON.stringify(['u1', 'u2']) &&
+        remove.status === 200 && JSON.stringify((remove.body as Body).data?.members) === JSON.stringify(['u2']) &&
+        JSON.stringify((get.body as Body).data?.members) === JSON.stringify(['u2']) &&
+        bad.status === 400 && (bad.body as Body).error?.code === 'invalid_members';
+    }),
+  ),
+  done('openrouter.video.submit', 'video', 'Video generation: submit returns a completed generation object', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/api/v1/video', b: { model: 'twin/video-gen-1', prompt: 'a cat surfing' } });
+      const b = r.body as Body;
+      const noPrompt = await h({ m: 'POST', p: '/api/v1/video', b: { model: 'twin/video-gen-1' } });
+      return r.status === 200 && b.object === 'video.generation' && b.status === 'completed' && b.stub === true &&
+        typeof b.id === 'string' && String(b.download_url).includes('/content') &&
+        noPrompt.status === 400 && (noPrompt.body as Body).error?.code === 'invalid_prompt';
+    }),
+  ),
+  done('openrouter.video.poll_download', 'video', 'Video generation: poll status, download labeled stub, list models', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const sub = await h({ m: 'POST', p: '/api/v1/video', b: { model: 'twin/video-gen-1', prompt: 'a dog skating' } });
+      const id = (sub.body as Body).id;
+      const poll = await h({ m: 'GET', p: `/api/v1/video/${id}` });
+      const dl = await h({ m: 'GET', p: `/api/v1/video/${id}/content` });
+      const models = await h({ m: 'GET', p: '/api/v1/video/models' });
+      const missing = await h({ m: 'GET', p: '/api/v1/video/nope' });
+      const decoded = Buffer.from(String((dl.body as Body).content), 'base64').toString();
+      return poll.status === 200 && (poll.body as Body).status === 'completed' &&
+        dl.status === 200 && decoded.includes('[twin-stub:openrouter:video]') &&
+        (models.body as Body).data?.length >= 1 && missing.status === 404;
+    }),
+  ),
+  done('openrouter.observability.destinations', 'observability', 'Observability destinations: list/create/update/delete', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const created = await h({ m: 'POST', p: '/api/v1/observability/destinations', b: { type: 'webhook', name: 'hook', config: { url: 'https://x' } } });
+      const id = (created.body as Body).data?.id;
+      const list = await h({ m: 'GET', p: '/api/v1/observability/destinations' });
+      const upd = await h({ m: 'PATCH', p: `/api/v1/observability/destinations/${id}`, b: { enabled: false } });
+      const del = await h({ m: 'DELETE', p: `/api/v1/observability/destinations/${id}` });
+      const afterDel = await h({ m: 'GET', p: '/api/v1/observability/destinations' });
+      const badType = await h({ m: 'POST', p: '/api/v1/observability/destinations', b: { type: 'carrier-pigeon' } });
+      return created.status === 200 && (created.body as Body).data?.type === 'webhook' && (list.body as Body).data?.length === 1 &&
+        upd.status === 200 && (upd.body as Body).data?.enabled === false &&
+        del.status === 200 && (afterDel.body as Body).data?.length === 0 &&
+        badType.status === 400 && (badType.body as Body).error?.code === 'invalid_type';
+    }),
+  ),
+  done('openrouter.rankings.apps', 'rankings', 'Rankings: top apps by token usage ranked descending', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/api/v1/rankings/apps' });
+      const rows = (r.body as Body).data as Body[];
+      return r.status === 200 && rows?.length >= 3 && rows[0]?.rank === 1 &&
+        rows[0]?.total_tokens >= rows[1]?.total_tokens && typeof rows[0]?.title === 'string';
+    }),
+  ),
+  done('openrouter.rankings.benchmarks', 'rankings', 'Rankings: Artificial Analysis / Design Arena benchmark catalog', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const all = await h({ m: 'GET', p: '/api/v1/rankings/benchmarks' });
+      const filtered = await h({ m: 'GET', p: '/api/v1/rankings/benchmarks?source=design-arena' });
+      const rows = (all.body as Body).data as Body[];
+      const fr = (filtered.body as Body).data as Body[];
+      return all.status === 200 && rows?.length >= 3 && rows.some((b) => b.source === 'artificial-analysis') &&
+        fr.length >= 1 && fr.every((b) => b.source === 'design-arena');
+    }),
+  ),
+  done('openrouter.ui.generation_detail', 'ui', 'Mirror generation detail view is data-coupled to the generation API', 'ui', 'common', async () =>
+    await withMirror(async (baseUrl) => {
+      // (1) the built mirror carries the generation-detail panel markers the App renders …
+      const js = await mirrorBundle();
+      if (!(js.includes('generation-detail') && js.includes('Generation detail'))) return false;
+      // (2) … AND it is coupled to the SAME single-generation API the detail view fetches.
+      const chat = await fetch(`${baseUrl}/api/v1/chat/completions`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(CHAT()) }).then((r) => r.json()) as Body;
+      const id = chat.id as string;
+      const detail = await fetch(`${baseUrl}/api/v1/generation?id=${encodeURIComponent(id)}`).then((r) => r.json()) as Body;
+      const missing = await fetch(`${baseUrl}/api/v1/generation?id=does-not-exist`);
+      return detail.data?.request_id === id && detail.data?.model === 'google/gemini-3-flash-preview' &&
+        typeof detail.data?.total_cost === 'number' && detail.data?.provider_name === 'twin' && missing.status === 404;
+    }),
+  ),
+  done('openrouter.ui.model_detail', 'ui', 'Mirror model detail view is data-coupled to the model endpoints API', 'ui', 'common', async () =>
+    await withMirror(async (baseUrl) => {
+      // (1) the built mirror carries the model-detail panel markers the App renders …
+      const js = await mirrorBundle();
+      if (!(js.includes('model-detail') && js.includes('Model detail') && js.includes('Endpoints'))) return false;
+      // (2) … AND it is coupled to the SAME model-endpoints API the detail view fetches.
+      const detail = await fetch(`${baseUrl}/api/v1/models/openai/gpt-4o/endpoints`).then((r) => r.json()) as Body;
+      const missing = await fetch(`${baseUrl}/api/v1/models/nope/nope/endpoints`);
+      return detail.data?.id === 'openai/gpt-4o' && detail.data?.endpoints?.[0]?.provider_name === 'twin' &&
+        typeof detail.data?.pricing?.prompt === 'string' && missing.status === 404;
+    }),
+  ),
+  // ── Pull-surface coverage audit gaps (TWIN-46 / G2) — filed as manifest todos, which is
+  // what the demand-ordered build list is drawn from. See pull-audit.json (repo root) for the
+  // per-pack pull-vs-read-surface evidence.
+  todo('openrouter.connector.pull_key', 'connector', 'Connector: pull current API key metadata (GET /api/v1/key) from the real account', 'connector', 'core'),
+  todo('openrouter.connector.pull_credits', 'connector', 'Connector: pull remaining credits (GET /api/v1/credits) from the real account', 'connector', 'core'),
+
+];
+
+export async function openrouterCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('openrouter', OPENROUTER_CAPABILITIES);
+}