@volter/twin-openrouter 0.1.0

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

@@ -0,0 +1,11 @@
+export type OpenRouterConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    violations: Array<{
+        check: string;
+        detail: string;
+    }>;
+};
+export declare function checkOpenRouterConformance(opts?: {
+    root?: string;
+}): Promise<OpenRouterConformanceReport>;

package/dist/src/openrouter-conformance.js

@@ -0,0 +1,53 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleOpenRouterTwinRequest } from "./openrouter-twin.js";
+export async function checkOpenRouterConformance(opts = {}) {
+    const root = opts.root ?? mkdtempSync(join(tmpdir(), 'openrouter-conf-'));
+    const owned = opts.root === undefined;
+    const violations = [];
+    let checksRun = 0;
+    const fail = (check, detail) => violations.push({ check, detail });
+    const h = (method, path, body, sseSink) => handleOpenRouterTwinRequest({ method, path, body: body === undefined ? undefined : JSON.stringify(body), root, ...(sseSink ? { sseSink } : {}) });
+    try {
+        checksRun++;
+        const chat = await h('POST', '/api/v1/chat/completions', { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'hello' }] });
+        const cb = chat.body;
+        if (chat.status !== 200 || cb.object !== 'chat.completion' || cb.choices?.[0]?.message?.role !== 'assistant')
+            fail('chat.envelope', 'invalid chat completion envelope');
+        if (typeof cb.usage?.cost !== 'number')
+            fail('chat.usage', 'OpenRouter usage cost missing');
+        checksRun++;
+        const events = [];
+        await h('POST', '/api/v1/chat/completions', { model: 'openai/gpt-4o', 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', '/api/v1/models');
+        if (!Array.isArray(models.body.data) || models.body.data.length === 0)
+            fail('models.list', 'missing models data');
+        const one = await h('GET', '/api/v1/models/openai/gpt-4o');
+        if (one.body.data?.id !== 'openai/gpt-4o')
+            fail('models.retrieve', 'missing model');
+        checksRun++;
+        const gen = await h('GET', `/api/v1/generation?id=${encodeURIComponent(cb.id)}`);
+        if (gen.body.data?.model !== 'openai/gpt-4o')
+            fail('generation.stats', 'generation lookup failed');
+        checksRun++;
+        const bad = await h('POST', '/api/v1/chat/completions', { model: 'openai/gpt-4o', messages: [] });
+        if (bad.status !== 400 || !bad.body.error)
+            fail('error.envelope', 'bad chat request did not return error envelope');
+        checksRun++;
+        const resp = await h('POST', '/api/v1/responses', { model: 'openai/gpt-4o', input: 'hi' });
+        if (resp.status !== 200 || resp.body.object !== 'response')
+            fail('responses.create', 'responses envelope invalid');
+        const embed = await h('POST', '/api/v1/embeddings', { model: 'm', input: 'hi' });
+        if (embed.status !== 200 || !Array.isArray(embed.body.data?.[0]?.embedding))
+            fail('embeddings.create', 'embeddings envelope invalid');
+    }
+    finally {
+        if (owned)
+            rmSync(root, { recursive: true, force: true });
+    }
+    return { ok: violations.length === 0, checksRun, violations };
+}

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

@@ -0,0 +1,90 @@
+import type { PerformContext, PushOutcome, RemoteExecute, TwinAction } from '@volter/world-core';
+import { OpenRouterBudget, type OpenRouterBudgetOptions } from './openrouter-budget.js';
+export type OpenRouterExecute = (req: {
+    method: string;
+    path: string;
+    body?: unknown;
+}) => Promise<{
+    status: number;
+    data: unknown;
+}>;
+/** The real OpenRouter API host. The ONLY place this pack names it as a target. */
+export declare const OPENROUTER_API_BASE = "https://openrouter.ai";
+/**
+ * THE CHOKE POINT — the one place this pack builds an `OpenRouterExecute` that really reaches
+ * openrouter.ai, and therefore the one place the rate budget has to be enforced.
+ *
+ * Reads the API key from `OPENROUTER_API_KEY` (never a literal, never a credentials file) and sends it
+ * as `Authorization: Bearer …`, which is how OpenRouter authenticates its OpenAI-compatible surface.
+ *
+ * EVERY request is guarded: the budget is charged BEFORE it goes out (`checkBudget`, which THROWS
+ * instead of returning once the ceiling or a persisted cooldown says stop) and the response is fed
+ * back (`recordCall`) so a `Retry-After` / 429 / rate-limit-exhaustion signal becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching OpenRouter. There is deliberately
+ * NO option to disable the guard.
+ *
+ * No vendor SDK is imported: real-transport `fetch` keeps this pack SDK-free at runtime, which the
+ * architecture guardrail requires.
+ */
+export declare function liveOpenRouterExecute(opts?: {
+    apiKey?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executes. Omit and one is constructed. Cannot be null. */
+    budget?: OpenRouterBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: OpenRouterBudgetOptions;
+}): OpenRouterExecute;
+export declare function pullOpenRouterState(execute: OpenRouterExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<void>;
+/**
+ * D7 consumer-facing pull entry point: gather all OpenRouter domains (the model catalog and the account's provisioning keys) and
+ * fold them into the twin as ONE observation, returning the standard result shape. Idempotent:
+ * a re-pull of identical state appends no new deltas.
+ */
+export declare function syncOpenRouterFromReal(execute: OpenRouterExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+export declare function openRouterRequestForAction(action: TwinAction): {
+    method: string;
+    path: string;
+    body?: unknown;
+} | null;
+export declare function pushOpenRouterAction(action: TwinAction, execute: OpenRouterExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<boolean>;
+export declare function pushPendingOpenRouterActions(execute: OpenRouterExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<number>;
+/**
+ * An `OpenRouterExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ * credential over these headers (executor.ts); at the twin's own wire any credential is one.
+ *
+ * The paths carry OpenRouter's `/api` prefix, which `collectOpenRouterState` already uses and the
+ * twin's own router accepts alongside the bare `/v1` form.
+ */
+export declare function openRouterExecuteOver(execute: RemoteExecute): OpenRouterExecute;
+/** The refresh adapter: pull the account's state through the executor and fold it into the root. */
+export declare function syncOpenRouterFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * The perform adapter. OpenRouter's provisioning surface is what a world can really write:
+ * `pushOpenRouterAction` maps the one crossing operation it models and answers `false` for the
+ * rest, which are the twin's OWN record (a generation is a completion this twin produced; there is
+ * nothing at OpenRouter to create). Saying so is the honest outcome, never a silent success.
+ */
+export declare function performOpenRouterAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;

package/dist/src/openrouter-connector.js

@@ -0,0 +1,245 @@
+// OpenRouter CONNECTOR — pull/push against an INJECTED `OpenRouterExecute`, so every test and every
+// capability verify runs offline against a deterministic fake.
+//
+// `liveOpenRouterExecute` below is the pack's ONE construction site for a real, network-calling
+// execute — the choke point the rate budget sits inside. Before it existed there was nowhere for a
+// guard to live: the pack only ever received an execute, so a budget could only be something the
+// caller remembered to opt into, and "the caller remembered" is exactly the assumption that cost a
+// ~4.5-day Figma token lockout (2026-07-25). See `openrouter-budget.ts` for the numbers, and for the
+// honest statement that none of OpenRouter's published figures governs this connector exactly.
+//
+// The injected contract is UNCHANGED: everything below still takes a plain `OpenRouterExecute`.
+import { confirmAction, deployableEntries, observeResources } from '@volter/world-core';
+import { OpenRouterBudget, OpenRouterBudgetError, openRouterCallWeight } from "./openrouter-budget.js";
+const DEFAULT_OCCURRED_AT = '1970-01-01T00:00:00.000Z';
+/** The real OpenRouter API host. The ONLY place this pack names it as a target. */
+export const OPENROUTER_API_BASE = 'https://openrouter.ai';
+/**
+ * THE CHOKE POINT — the one place this pack builds an `OpenRouterExecute` that really reaches
+ * openrouter.ai, and therefore the one place the rate budget has to be enforced.
+ *
+ * Reads the API key from `OPENROUTER_API_KEY` (never a literal, never a credentials file) and sends it
+ * as `Authorization: Bearer …`, which is how OpenRouter authenticates its OpenAI-compatible surface.
+ *
+ * EVERY request is guarded: the budget is charged BEFORE it goes out (`checkBudget`, which THROWS
+ * instead of returning once the ceiling or a persisted cooldown says stop) and the response is fed
+ * back (`recordCall`) so a `Retry-After` / 429 / rate-limit-exhaustion signal becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching OpenRouter. There is deliberately
+ * NO option to disable the guard.
+ *
+ * No vendor SDK is imported: real-transport `fetch` keeps this pack SDK-free at runtime, which the
+ * architecture guardrail requires.
+ */
+export function liveOpenRouterExecute(opts = {}) {
+    const apiKey = opts.apiKey ?? process.env.OPENROUTER_API_KEY ?? '';
+    if (!apiKey)
+        throw new Error('OPENROUTER_API_KEY is not set — the live OpenRouter client needs an API key');
+    const baseUrl = opts.baseUrl ?? OPENROUTER_API_BASE;
+    const doFetch = opts.fetchImpl ?? fetch;
+    // There is no value a caller can pass to end up with an unguarded execute. `null`/`undefined` (or
+    // omitting it) build the default budget; anything that is not a REAL `OpenRouterBudget` is refused
+    // loudly rather than trusted — a duck-typed stand-in with a no-op `checkBudget` would otherwise be
+    // the one clean way around the guard.
+    if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof OpenRouterBudget)) {
+        throw new Error('liveOpenRouterExecute: `budget` must be an OpenRouterBudget — refusing to build a live OpenRouter client around an unverified rate guard');
+    }
+    // The default ledger is keyed by a hash of THIS key — OpenRouter's limits are per key / per
+    // account, so a cwd-scoped ledger would hand the same key a fresh allowance per checkout/CI leg.
+    const budget = opts.budget instanceof OpenRouterBudget
+        ? opts.budget
+        : new OpenRouterBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+    return async (req) => {
+        requireVendorPath(req.path);
+        const method = (req.method || 'GET').toUpperCase();
+        const weight = openRouterCallWeight(method, req.path);
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(new URL(req.path, baseUrl).toString(), {
+            method,
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                Accept: 'application/json',
+                ...(req.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            },
+            ...(req.body === undefined ? {} : { body: JSON.stringify(req.body) }),
+        });
+        const headers = lowerCasedHeaders(res.headers);
+        const text = await res.text();
+        let data = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = { raw: text };
+        }
+        // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+        // Retry-After beyond the cap is not something to sleep off) — the cooldown is persisted first
+        // either way, so the refusal survives the throw.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer OpenRouter ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, headers, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof OpenRouterBudgetError) || !res.ok)
+                throw error;
+        }
+        return { status: res.status, data };
+    };
+}
+/**
+ * Refuse a `path` that is not a same-origin ABSOLUTE PATH.
+ *
+ * `new URL(path, base)` treats `https://evil.test/x` AND the protocol-relative `//evil.test/x` as
+ * absolute and silently retargets the host — and this factory attaches the credential
+ * unconditionally, so a caller-supplied absolute path would exfiltrate it to an arbitrary server.
+ * Figma's guarded client sidesteps this by concatenating rather than resolving; this execute takes an
+ * arbitrary `{ path }` from its caller, so it validates instead. (§9 finding, 2026-07-26.)
+ *
+ * `/twin/...` is refused for a different reason: those are the twin's OWN seed routes
+ * (`*RequestForAction` builds them), which the real vendor has never heard of. Sending one live is a
+ * guaranteed 404 that still burns budget and puts the live credential on the wire for nothing.
+ */
+function requireVendorPath(path) {
+    if (typeof path !== 'string' || !/^\/(?!\/)/.test(path)) {
+        throw new Error(`liveOpenRouterExecute: path must be a same-origin absolute path beginning with a single "/" (got ${String(path)}) — refusing to let a caller-supplied absolute URL retarget the host with the credential attached`);
+    }
+    if (path === '/twin' || path.startsWith('/twin/')) {
+        throw new Error(`liveOpenRouterExecute: refusing to send the twin-only path ${path} to real OpenRouter — that route exists only in the local twin`);
+    }
+}
+/** Response headers as a plain lower-cased record — what the kernel's back-off reader expects. */
+function lowerCasedHeaders(h) {
+    const out = {};
+    h.forEach((v, k) => { out[k.toLowerCase()] = v; });
+    return out;
+}
+/** Fetch OpenRouter's model catalog and provisioning keys through the injected client, mapped to SyncResource[] (no fold). */
+async function collectOpenRouterState(execute) {
+    const resources = [];
+    const models = await execute({ method: 'GET', path: '/api/v1/models' });
+    const catalog = models.data.data ?? [];
+    for (const model of catalog) {
+        if (typeof model.id === 'string')
+            resources.push({ type: 'model', id: `model_${model.id}`, fields: model });
+    }
+    // The PROVISIONING keys (`GET /api/v1/keys`) — the one part of an OpenRouter account a world both
+    // WRITES and can read back, so it is the pull that makes the mirror a mirror rather than a
+    // catalog copy. The vendor addresses a key by its `hash` and never returns the prefixed form, so
+    // the subject id is rebuilt exactly as `createApiKey` mints it.
+    const keys = await execute({ method: 'GET', path: '/api/v1/keys' });
+    for (const key of keys.data.data ?? []) {
+        const hash = typeof key.hash === 'string' ? key.hash : typeof key.id === 'string' ? key.id : null;
+        if (!hash)
+            continue;
+        resources.push({ type: 'api_key', id: `key_${hash}`, fields: { ...key, id: `key_${hash}`, hash } });
+    }
+    return resources;
+}
+export async function pullOpenRouterState(execute, opts = {}) {
+    const resources = await collectOpenRouterState(execute);
+    const at = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+    observeResources('openrouter', resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:openrouter:${at}` });
+}
+/**
+ * D7 consumer-facing pull entry point: gather all OpenRouter domains (the model catalog and the account's provisioning keys) and
+ * fold them into the twin as ONE observation, returning the standard result shape. Idempotent:
+ * a re-pull of identical state appends no new deltas.
+ */
+export async function syncOpenRouterFromReal(execute, opts = {}) {
+    const resources = await collectOpenRouterState(execute);
+    const at = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+    const result = observeResources('openrouter', resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:openrouter:${at}` });
+    return { observed: resources.length, deltasAppended: result.appended };
+}
+export function openRouterRequestForAction(action) {
+    if (action.operation === 'generation.record') {
+        const stat = action.fields;
+        return { method: 'GET', path: `/api/v1/generation?id=${encodeURIComponent(stat.id.replace(/^generation_/, ''))}` };
+    }
+    return null;
+}
+export async function pushOpenRouterAction(action, execute, opts = {}) {
+    const req = openRouterRequestForAction(action);
+    if (!req)
+        return false;
+    const result = await execute(req);
+    if (result.status < 200 || result.status >= 300)
+        return false;
+    // The vendor's OWN id for the subject, and the receipt that says the crossing happened — protocol
+    // 2's confirmation carries both, so a later read can tell a deployed subject from a local one.
+    const answered = result.data?.data;
+    const vendorSubjectId = typeof answered?.id === 'string' ? answered.id : action.subject.id;
+    confirmAction({
+        service: 'openrouter',
+        actionId: action.id,
+        subject: action.subject,
+        fields: action.fields ?? {},
+        occurredAt: opts.occurredAt ?? DEFAULT_OCCURRED_AT,
+        vendorSubjectId,
+        receipt: { status: 'deployed' },
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    return true;
+}
+export async function pushPendingOpenRouterActions(execute, opts = {}) {
+    let pushed = 0;
+    for (const action of deployableEntries('openrouter', opts.root)) {
+        if (await pushOpenRouterAction(action, execute, opts))
+            pushed++;
+    }
+    return pushed;
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/**
+ * An `OpenRouterExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ * credential over these headers (executor.ts); at the twin's own wire any credential is one.
+ *
+ * The paths carry OpenRouter's `/api` prefix, which `collectOpenRouterState` already uses and the
+ * twin's own router accepts alongside the bare `/v1` form.
+ */
+export function openRouterExecuteOver(execute) {
+    return async (req) => {
+        const res = await execute({
+            method: req.method,
+            path: req.path,
+            headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer twin' },
+            ...(req.body === undefined ? {} : { body: JSON.stringify(req.body) }),
+        });
+        let data = {};
+        try {
+            data = JSON.parse(res.body || '{}');
+        }
+        catch {
+            data = {};
+        }
+        return { status: res.status, data };
+    };
+}
+/** The refresh adapter: pull the account's state through the executor and fold it into the root. */
+export async function syncOpenRouterFromRemote(execute, opts = {}) {
+    return syncOpenRouterFromReal(openRouterExecuteOver(execute), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        occurredAt: opts.occurredAt ?? new Date().toISOString(),
+    });
+}
+/**
+ * The perform adapter. OpenRouter's provisioning surface is what a world can really write:
+ * `pushOpenRouterAction` maps the one crossing operation it models and answers `false` for the
+ * rest, which are the twin's OWN record (a generation is a completion this twin produced; there is
+ * nothing at OpenRouter to create). Saying so is the honest outcome, never a silent success.
+ */
+export async function performOpenRouterAction(execute, action, _ctx) {
+    const client = openRouterExecuteOver(execute);
+    const req = openRouterRequestForAction(action);
+    if (!req) {
+        const op = action.operation ?? `${action.subject.type}.update`;
+        return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record — nothing at OpenRouter to write` } };
+    }
+    const result = await client(req);
+    if (result.status < 200 || result.status >= 300) {
+        throw new Error(`openrouter ${req.method} ${req.path} refused: HTTP ${result.status}`);
+    }
+    return { externalId: action.subject.id, data: (result.data ?? {}) };
+}

package/dist/src/openrouter-local-generation.d.ts

@@ -0,0 +1,17 @@
+/** Optional pack-owned transport to a separately World-owned loopback generation service. */
+export declare const LOCAL_GENERATION_BODY_LIMIT: number;
+export type LocalGenerationFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export declare function localGenerationOrigin(value: string): string;
+/** Read only the opt-in generation request body; ordinary twin routes retain their old path. */
+export declare function readLocalGenerationBody(request: Request): Promise<{
+    bytes: Uint8Array<ArrayBuffer>;
+    text: string;
+}>;
+/** One pull from the caller means at most one read from the local response. */
+export declare function forwardLocalGeneration(args: {
+    origin: string;
+    request: Request;
+    pathname: string;
+    body: Uint8Array<ArrayBuffer>;
+    fetchImpl?: LocalGenerationFetch;
+}): Promise<Response>;