@volter/twin-openrouter 0.1.0

package/dist/src/openrouter-budget.js

@@ -0,0 +1,133 @@
+// 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, } 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,
+};
+/**
+ * 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 = {
+    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) {
+    const q = path.indexOf('?');
+    if (q < 0)
+        return { pathname: path, query: {} };
+    const query = {};
+    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, path) {
+    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 = {}) {
+    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 });
+}
+/**
+ * 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 = {}) {
+        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';

package/dist/src/openrouter-capabilities.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const OPENROUTER_CAPABILITIES: CapabilitySpec[];
+export declare function openrouterCapabilities(): Promise<CapabilityReport>;