@volter/twin-openrouter 0.1.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@volter/twin-openrouter",
+  "version": "0.1.0",
+  "description": "Local OpenRouter twin — a faithful, stateful local OpenRouter API your OpenAI-compatible SDK talks to unmodified. Chat completions and streaming return deterministic labeled stubs, generation stats and key/credits/model surfaces are local. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "sdk",
+    "api",
+    "openrouter",
+    "llm"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/openrouter"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/openrouter#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-openrouter": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "openai": "^6.16.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createOpenRouterTwinServer } from './openrouter-server.ts';
+import { createOpenRouterMirrorServer } from './openrouter-mirror-ui.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const scenario = optionValue(rest, '--scenario') || undefined;
+const localGenerationUrl = hasFlag(rest, '--local-generation-url') ? optionValue(rest, '--local-generation-url') : undefined;
+const readOnly = hasFlag(rest, '--read-only');
+
+if (cmd === 'serve') {
+  const server = await createOpenRouterTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}), ...(localGenerationUrl !== undefined ? { localGenerationUrl } : {}) });
+  process.stdout.write(`openrouter twin (${localGenerationUrl !== undefined || process.env.TWIN_OPENROUTER_LOCAL_GENERATION_URL !== undefined ? 'optional local generation' : 'deterministic stub output'})${readOnly ? ' [read-only]' : ''}${scenario ? ' [scenario]' : ''} at http://127.0.0.1:${server.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'mirror') {
+  const server = await createOpenRouterMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`openrouter mirror UI at http://127.0.0.1:${server.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkOpenRouterConformance } = await import('./openrouter-conformance.ts');
+  const report = await checkOpenRouterConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-openrouter serve|mirror|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE] [--local-generation-url http://127.0.0.1:PORT]\n');
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+export { handleOpenRouterTwinRequest } from './openrouter-twin.ts';
+export type { OpenRouterRequest, OpenRouterResponse, SseEvent, SseSink, GenerationStat } from './openrouter-types.ts';
+export { createOpenRouterTwinFetch, createOpenRouterTwinServer, type OpenRouterTwinFetchOptions } from './openrouter-server.ts';
+export { OPENROUTER_MODELS, OPENROUTER_PROVIDERS, findOpenRouterModel } from './openrouter-models.ts';
+export type { OpenRouterModel, OpenRouterProvider } from './openrouter-models.ts';
+export { contentToText, countPromptTokens, estimateTokens, lastUserText, stableHash, stubAssistantText } from './openrouter-stub.ts';
+// The pack's HALF of the scenario system (the grammar is the kernel's ONE engine). Exported so a
+// test can build an engine and `use()` handlers in-process, and so the fetch adapter can mount it.
+export {
+  createOpenRouterScenarioEngine,
+  loadOpenRouterScenarioDocument,
+  openrouterScenarioAdapter,
+  realizeOpenRouterRespond,
+} from './openrouter-scenario.ts';
+export type {
+  OpenRouterScenarioEngine,
+  OpenRouterScenarioRequest,
+  OpenRouterScenarioRespond,
+  ScenarioToolCall,
+} from './openrouter-scenario.ts';
+export { buildOpenRouterMirrorClient, createOpenRouterMirrorServer, openrouterMirrorHtml } from './openrouter-mirror-ui.ts';
+export {
+  OPENROUTER_API_BASE,
+  liveOpenRouterExecute,
+  openRouterRequestForAction,
+  pullOpenRouterState,
+  pushOpenRouterAction,
+  pushPendingOpenRouterActions,
+  syncOpenRouterFromReal,
+} from './openrouter-connector.ts';
+export type { OpenRouterExecute } from './openrouter-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveOpenRouterExecute` routes every live
+// request through. The mechanism is the kernel's (`@volter/world-core` -> rateBudget.ts); these are this
+// vendor's numbers and the typed bindings around them.
+export {
+  OPENROUTER_BUDGET_CEILING,
+  OPENROUTER_BUDGET_MAX_RETRY_AFTER_S,
+  OPENROUTER_BUDGET_WINDOW_MS,
+  OPENROUTER_CALL_WEIGHTS,
+  OPENROUTER_RATE_BUDGET,
+  OpenRouterBudget,
+  OpenRouterBudgetError,
+  openRouterBudgetPath,
+  openRouterCallWeight,
+  splitOpenRouterPath,
+} from './openrouter-budget.ts';
+export type {
+  OpenRouterBudgetErrorKind,
+  OpenRouterBudgetOptions,
+  OpenRouterBudgetReservation,
+  OpenRouterBudgetSnapshot,
+} from './openrouter-budget.ts';
+
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performOpenRouterAction, syncOpenRouterFromRemote } from './openrouter-connector.ts';
+import { OPENROUTER_RATE_BUDGET as RATE_BUDGET } from './openrouter-budget.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.
+  protocol: '2',
+  // OpenRouter publishes no webhooks for the provisioning surface, so the refresh is a poll. Five
+  // minutes is the catalog's cadence, and the pull is two calls (the model catalog, the account's
+  // keys) which the rate budget counts as two.
+  refresh: { every: '5m', webhook: false, onDemand: { atMost: '30s' } },
+  stateSystem: { perform: performOpenRouterAction, refresh: syncOpenRouterFromRemote },
+  // The round trip is a provisioning-key create — OpenRouter's own write, and the ONE part of an
+  // account this twin both writes and reads back (`GET /api/v1/keys` is the pull's second domain).
+  // The key's hash is minted from the name AND the write's instant, so a second send on a branch
+  // is a second key rather than a refused duplicate.
+  roundTrip: { method: 'POST', path: '/api/v1/keys', body: { name: 'round trip' }, headers: { authorization: 'Bearer round-trip' } },
+  parityOrigin: 'http://twin',
+  vendor: 'openrouter',
+  // The SAME object openrouter-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector arm identical numbers.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'generative',
+  bin: 'world-openrouter',
+  // The subject types the twin SERVES from its own state — the R2 resource-level claim.
+  // `model` is deliberately NOT here: it is a connector-side projection that only
+  // `pullOpenRouterState` folds in from a real OpenRouter through an injected client, and no
+  // route reads it back — `GET /v1/models`, `/v1/models/count`, `/v1/models/:id` and
+  // `/:id/endpoints` all serve the static OPENROUTER_MODELS catalog (openrouter-models.ts),
+  // never a stored subject (the ai-gateway `model`/`credits` precedent).
+  resources: ['generation', 'api_key', 'byok', 'preset'],
+  specSource: 'OpenRouter API reference (OpenAI-compatible chat completions + API Reference surfaces; model output is a deterministic stub)',
+  description: 'OpenRouter API twin — OpenAI-compatible chat completions/streaming, models, key/credits/generation stats; generative output is a labeled deterministic stub.',
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31).
+  adoption: {
+    // OpenRouter's official Python SDK (OpenRouterTeam/python-sdk). An `openai` client pointed at
+    // openrouter.ai is NOT claimed here - that distribution is the openai pack's, and
+    // OPENROUTER_BASE_URL is what routes it.
+    pypi: ['openrouter'],
+    sdks: ['@openrouter/ai-sdk-provider'],
+    scopes: ['@openrouter/'],
+    // 'OR' — OpenRouter's own documented short prefix, the trio LiteLLM ships in its .env.example
+    // under a literal `# OpenRouter` heading (OR_SITE_URL / OR_APP_NAME / OR_API_KEY). Only a var
+    // whose WHOLE prefix is `OR` reaches this stem, the same narrowness that lets the github pack
+    // claim 'GH' (ladder classification 2026-09-02: litellm detected no openrouter without it).
+    envStems: ['OPENROUTER', 'OR'],
+  },
+  hosts: [{ host: 'openrouter.ai' }],
+  browserRouting: { apiPathPrefix: '/api/v1/', loaderHost: 'https://openrouter.ai' },
+};
+
+registerPack(pack);

package/src/openrouter-budget.ts

@@ -0,0 +1,159 @@
+// OpenRouter's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveOpenRouterExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger — lives
+// ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's header
+// for the full rationale AND for the honest list of what the guard does not guarantee (an injected
+// clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS: THE MISSING CHOKE POINT ─────────────────────────────────────────────────
+// A ~4.5-day Figma token lockout (2026-07-25) came from a burst of raw vendor calls made OUTSIDE any
+// guarded client. The lesson generalized: a pack with no single construction site for its live client
+// is a pack that CANNOT be protected, because there is nowhere for a guard to sit.
+//
+// This connector took an INJECTED `OpenRouterExecute` and nothing more. Excellent for testing — every
+// verify runs offline against a fake — but it meant the pack never built a network-calling execute, so
+// a rate budget could only ever be something the CALLER opted into. `liveOpenRouterExecute` (in
+// `openrouter-connector.ts`) is the choke point that fixes that: the ONE place in this pack that turns
+// a credential into a function that really talks to openrouter.ai, with this budget charged BEFORE
+// every request goes out. The injected-function contract is untouched — the factory is an ADDITION.
+//
+// ── HOW THE CEILING WAS CHOSEN, AND WHAT IS HONESTLY UNKNOWN ──────────────────────────────────
+// OpenRouter publishes three figures (openrouter.ai/docs/api_reference/limits and the endpoint docs):
+//   • a 200 requests/SECOND account surge cap, for every user, as DoS defence;
+//   • 20 requests/minute for `:free` model variants, plus a daily cap that depends on how much credit
+//     has been purchased (the published daily figure has moved; only the 20/minute is used below);
+//   • 30 requests/minute per key + 500/day per account on data API endpoints (e.g. app rankings).
+//
+// NONE of them governs this connector exactly. It calls no inference endpoint (so the `:free` limit is
+// not its limit) and not the dataset endpoint (so the 30/minute figure is not its limit either), and
+// OpenRouter publishes no per-minute figure for `/api/v1/models` or `/api/v1/generation`. That is
+// stated plainly rather than papered over.
+//
+// Given no governing figure, the budget adopts the TIGHTEST documented per-minute number wholesale:
+// 20 weighted units per 60s at 1 per call. That is under both published per-minute limits, four
+// orders of magnitude under the surge cap, and far more than the connector's real workload (a catalog
+// pull is ONE call; a push is one call per pending action). If a future caller needs more, the pack
+// declares more — with the figure that justifies it.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN ──────────────────────────────────────────────────────────────
+// OpenRouter counts REQUESTS, so weight 1 is the faithful price and the catalog pull gets it.
+// `/api/v1/generation` costs 2 — not because OpenRouter charges more (it does not) but because it is
+// the only endpoint here whose call count is UNBOUNDED IN THE CALLER'S DATA: `pushPendingOpenRouterActions`
+// issues one per pending `generation.record` action, so a backlog turns into a burst. Doubling its
+// price halves the depth at which that runaway is stopped. A judgement call, not a published cost.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'openrouter';
+
+/** Rolling window, in ms. Matches the per-MINUTE shape of every figure OpenRouter publishes. */
+export const OPENROUTER_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 20 calls/60s — the tightest per-minute figure OpenRouter
+ * documents anywhere, adopted wholesale because none of its published figures governs this connector.
+ */
+export const OPENROUTER_BUDGET_CEILING = 20;
+
+/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly. */
+export const OPENROUTER_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by the `<METHOD> <path>` this connector is about to request. See the header. */
+export const OPENROUTER_CALL_WEIGHTS = {
+  /** `GET /api/v1/generation?id=…` — one per pending action, so unbounded in the caller's backlog. */
+  generation: 2,
+  /** Every other modeled call, including the `/api/v1/models` catalog pull. */
+  other: 1,
+} as const;
+
+/**
+ * THE PACK'S DECLARATION — pure data, the only OpenRouter-specific thing in the whole budget. Rules
+ * are ordered and first-match-wins, and they are keyed on `"<METHOD> <pathname>"`.
+ *
+ * Also exported as `pack.rateBudget` (see index.ts), so `registerPack` arms it too.
+ */
+export const OPENROUTER_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: OPENROUTER_BUDGET_WINDOW_MS,
+  ceiling: OPENROUTER_BUDGET_CEILING,
+  defaultWeight: OPENROUTER_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: OPENROUTER_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^[A-Z]+ /api/v1/generation', weight: OPENROUTER_CALL_WEIGHTS.generation },
+  ],
+  reason:
+    'OpenRouter documents a 200 requests/SECOND account surge cap, 20 requests/minute for :free model ' +
+    'variants (plus a credit-dependent daily cap, whose published figure has moved and is deliberately not ' +
+    'restated here), and 30 requests/minute per key on its data API endpoints. NONE governs this ' +
+    'connector exactly — it calls no inference endpoint and not the dataset endpoint, and OpenRouter ' +
+    'publishes no per-minute figure for /api/v1/models or /api/v1/generation. Rather than invent one, this ' +
+    'adopts the tightest documented per-minute figure wholesale: 20 units / 60s at 1 per call, under both ' +
+    'published per-minute limits. /api/v1/generation costs 2 because push issues one per pending action, so ' +
+    'its call count is unbounded in the caller\'s backlog — a judgement call, not a published cost.',
+};
+
+// Declared at module load, so merely importing this module (which `openrouter-connector.ts` does) is
+// enough to arm the real ceiling. A budget constructed BEFORE this runs falls back to the kernel's
+// DEFAULT_RATE_BUDGET, whose ceiling (60) is HIGHER than this one — so here the fallback is genuinely
+// looser, not merely differently-priced. `RateBudget` reads its policy live precisely so this
+// declaration takes effect the moment it lands, and constructing through the subclass below (which
+// imports this module) is what makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, OPENROUTER_RATE_BUDGET);
+
+/** Split a connector path (which carries its own query string) into pathname + parsed query. */
+export function splitOpenRouterPath(path: string): { pathname: string; query: Record<string, string> } {
+  const q = path.indexOf('?');
+  if (q < 0) return { pathname: path, query: {} };
+  const query: Record<string, string> = {};
+  for (const [k, v] of new URLSearchParams(path.slice(q + 1))) query[k] = v;
+  return { pathname: path.slice(0, q), query };
+}
+
+/**
+ * Price one call. Keyed off the request the connector is ABOUT to make, so an unclassified endpoint
+ * still costs `defaultWeight` — an unknown endpoint must never be free.
+ */
+export function openRouterCallWeight(method: string, path: string): number {
+  const { pathname, query } = splitOpenRouterPath(path);
+  return rateBudgetWeight(VENDOR, `${(method || 'GET').toUpperCase()} ${pathname}`, query);
+}
+
+/** Where OpenRouter's ledger lives. Key-keyed and cwd-independent by default (limits are per key /
+ *  per account, so a cwd-scoped ledger would hand the same key a fresh allowance in every checkout,
+ *  worktree and CI matrix leg); pass `root` to opt into world-scoped accounting instead. */
+export function openRouterBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger to
+  // another vendor's file.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for OpenRouter's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type OpenRouterBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * OpenRouter's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof OpenRouterBudget` in `liveOpenRouterExecute` still means "a
+ * budget that accounts against OPENROUTER's ledger under OPENROUTER's ceiling": another vendor's
+ * `RateBudget` (with its own, almost certainly larger, ceiling) is NOT assignable there.
+ */
+export class OpenRouterBudget extends RateBudget {
+  constructor(opts: OpenRouterBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as OpenRouterBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as OpenRouterBudgetErrorKind } from '@volter/world-core';
+export type OpenRouterBudgetReservation = RateBudgetReservation;
+export type OpenRouterBudgetSnapshot = RateBudgetSnapshot;