@volter/twin-openrouter 0.1.0

package/dist/client/openrouter-mirror.css

@@ -0,0 +1,131 @@
+:root {
+  --bg: #f6f6f3;
+  --panel: #ffffff;
+  --ink: #171717;
+  --muted: #6b6f76;
+  --line: #deded8;
+  --accent: #256f63;
+  --accent-dark: #174c45;
+  --warn-bg: #fff4dc;
+  --warn: #8f5a00;
+  --bad-bg: #fee8e7;
+  --bad: #b3261e;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--ink);
+  font: 14px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+.app { min-height: 100vh; padding: 28px; }
+header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 22px;
+}
+h1 { margin: 0; font-size: 28px; letter-spacing: 0; }
+p { margin: 4px 0 0; color: var(--muted); }
+button {
+  border: 0;
+  border-radius: 7px;
+  background: var(--accent);
+  color: white;
+  padding: 8px 14px;
+  font-weight: 650;
+  cursor: pointer;
+}
+button:hover { background: var(--accent-dark); }
+button:disabled { opacity: .65; cursor: default; }
+
+.grid {
+  display: grid;
+  grid-template-columns: minmax(300px, 420px) minmax(0, 1fr);
+  gap: 18px;
+  align-items: start;
+}
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 16px;
+}
+.generations-panel { grid-column: 2; }
+h2 { margin: 0 0 12px; font-size: 17px; letter-spacing: 0; }
+label { display: block; margin-bottom: 12px; }
+label span { display: block; margin-bottom: 4px; color: var(--muted); font-size: 12px; font-weight: 650; }
+input, textarea {
+  width: 100%;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  padding: 8px 10px;
+  font: inherit;
+}
+.rows { display: flex; flex-direction: column; gap: 8px; }
+.row {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  gap: 14px;
+  align-items: center;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  padding: 10px 12px;
+}
+button.row {
+  background: var(--panel);
+  color: var(--ink);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+button.row:hover { background: #f0f5f3; }
+.row strong, .row span { display: block; min-width: 0; overflow-wrap: anywhere; }
+
+.detail {
+  margin-top: 18px;
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 16px;
+}
+.detail-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 10px; }
+.detail-head h3 { margin: 0; font-size: 16px; }
+.detail-body h4 { margin: 14px 0 6px; font-size: 13px; color: var(--muted); }
+.kv { display: flex; justify-content: space-between; padding: 4px 0; border-bottom: 1px solid var(--line); }
+.endpoint-row { margin-top: 6px; }
+.mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; color: var(--muted); }
+.empty { color: var(--muted); padding: 18px 4px; }
+.error {
+  background: var(--bad-bg);
+  color: var(--bad);
+  border-radius: 7px;
+  padding: 10px 12px;
+  margin: 12px 0;
+}
+.stub-output { margin-top: 14px; }
+.stub-banner {
+  background: var(--warn-bg);
+  color: var(--warn);
+  border-radius: 7px;
+  padding: 8px 10px;
+  font-weight: 650;
+}
+pre {
+  margin: 10px 0 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  background: #fafaf8;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  padding: 12px;
+}
+
+@media (max-width: 850px) {
+  .app { padding: 18px; }
+  .grid { grid-template-columns: 1fr; }
+  .generations-panel { grid-column: auto; }
+}

package/dist/client/openrouter-mirror.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client/openrouter-mirror.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative, as
+// before); served under a path prefix with a <base> tag every read and write resolves inside that
+// prefix instead of escaping it.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+async function json(path, init) {
+    const response = await fetch(`${WIRE_BASE}${path}`, init);
+    const body = await response.json();
+    if (!response.ok)
+        throw new Error(body?.error?.message ?? `request failed: ${response.status}`);
+    return body;
+}
+function ModelDetail({ model, onClose }) {
+    const [detail, setDetail] = useState(null);
+    const [error, setError] = useState('');
+    useEffect(() => {
+        void json(`/api/v1/models/${model}/endpoints`)
+            .then((body) => setDetail(body.data))
+            .catch((err) => setError(err instanceof Error ? err.message : String(err)));
+    }, [model]);
+    return (_jsxs("div", { className: "detail model-detail", children: [_jsxs("div", { className: "detail-head", children: [_jsx("h3", { children: "Model detail" }), _jsx("button", { onClick: onClose, children: "Close" })] }), error ? _jsx("div", { className: "error", children: error }) : null, detail ? (_jsxs("div", { className: "detail-body", children: [_jsx("div", { className: "mono", children: detail.id }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Context" }), _jsx("span", { className: "mono", children: detail.context_length.toLocaleString() })] }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Prompt $/tok" }), _jsx("span", { className: "mono", children: detail.pricing?.prompt ?? '-' })] }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Completion $/tok" }), _jsx("span", { className: "mono", children: detail.pricing?.completion ?? '-' })] }), _jsx("h4", { children: "Endpoints" }), (detail.endpoints ?? []).map((endpoint) => (_jsxs("div", { className: "row endpoint-row", children: [_jsx("span", { children: endpoint.name }), _jsx("span", { className: "mono", children: endpoint.provider_name }), _jsxs("span", { className: "mono", children: [endpoint.context_length.toLocaleString(), " ctx"] })] }, endpoint.provider_name)))] })) : (error ? null : _jsx("div", { className: "empty", children: "Loading\u2026" }))] }));
+}
+function Models({ models, onSelect }) {
+    return (_jsxs("section", { className: "panel models-panel", children: [_jsx("h2", { children: "Models" }), _jsx("div", { className: "rows", children: models.map((model) => (_jsxs("button", { className: "row model-row", onClick: () => onSelect(model.id), children: [_jsxs("div", { children: [_jsx("strong", { children: model.name }), _jsx("span", { className: "mono", children: model.id })] }), _jsx("span", { children: model.architecture?.modality ?? 'text->text' }), _jsxs("span", { className: "mono", children: [model.context_length.toLocaleString(), " ctx"] })] }, model.id))) })] }));
+}
+function GenerationDetail({ id, onClose }) {
+    const [detail, setDetail] = useState(null);
+    const [error, setError] = useState('');
+    useEffect(() => {
+        void json(`/api/v1/generation?id=${encodeURIComponent(id)}`)
+            .then((body) => setDetail(body.data))
+            .catch((err) => setError(err instanceof Error ? err.message : String(err)));
+    }, [id]);
+    return (_jsxs("div", { className: "detail generation-detail", children: [_jsxs("div", { className: "detail-head", children: [_jsx("h3", { children: "Generation detail" }), _jsx("button", { onClick: onClose, children: "Close" })] }), error ? _jsx("div", { className: "error", children: error }) : null, detail ? (_jsxs("div", { className: "detail-body", children: [_jsx("div", { className: "mono", children: detail.id }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Model" }), _jsx("span", { className: "mono", children: detail.model })] }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Provider" }), _jsx("span", { className: "mono", children: detail.provider_name ?? 'twin' })] }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Finish" }), _jsx("span", { className: "mono", children: detail.finish_reason ?? '-' })] }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Prompt tokens" }), _jsx("span", { className: "mono", children: detail.tokens_prompt })] }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Completion tokens" }), _jsx("span", { className: "mono", children: detail.tokens_completion })] }), _jsxs("div", { className: "kv", children: [_jsx("span", { children: "Total cost" }), _jsxs("span", { className: "mono", children: ["$", detail.total_cost.toFixed(8)] })] })] })) : (error ? null : _jsx("div", { className: "empty", children: "Loading\u2026" }))] }));
+}
+function Generations({ generations, onSelect }) {
+    return (_jsxs("section", { className: "panel generations-panel", children: [_jsx("h2", { children: "Generations" }), _jsxs("div", { className: "rows", children: [generations.length === 0 ? _jsx("div", { className: "empty", children: "No generations yet." }) : null, generations.map((generation) => (_jsxs("button", { className: "row generation-row", onClick: () => onSelect(generation.id), children: [_jsxs("div", { children: [_jsx("strong", { children: generation.model }), _jsx("span", { className: "mono", children: generation.id })] }), _jsx("span", { children: generation.streamed ? 'streamed' : 'standard' }), _jsxs("span", { className: "mono", children: ["$", generation.total_cost.toFixed(8)] })] }, generation.id)))] })] }));
+}
+function Playground({ onComplete }) {
+    const [model, setModel] = useState('google/gemini-3-flash-preview');
+    const [prompt, setPrompt] = useState('Summarize the OpenRouter twin.');
+    const [result, setResult] = useState('');
+    const [error, setError] = useState('');
+    const [busy, setBusy] = useState(false);
+    async function send() {
+        setBusy(true);
+        setError('');
+        setResult('');
+        try {
+            const body = await json('/api/v1/chat/completions', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }] }),
+            });
+            setResult(body.choices?.[0]?.message?.content ?? '');
+            onComplete();
+        }
+        catch (err) {
+            setError(err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    return (_jsxs("section", { className: "panel playground-panel", children: [_jsx("h2", { children: "Playground" }), _jsxs("label", { children: [_jsx("span", { children: "Model" }), _jsx("input", { value: model, onChange: (event) => setModel(event.target.value) })] }), _jsxs("label", { children: [_jsx("span", { children: "Prompt" }), _jsx("textarea", { rows: 4, value: prompt, onChange: (event) => setPrompt(event.target.value) })] }), _jsx("button", { onClick: send, disabled: busy, children: busy ? 'Sending...' : 'Send' }), error ? _jsx("div", { className: "error", children: error }) : null, result ? (_jsxs("div", { className: "stub-output", children: [_jsx("div", { className: "stub-banner", children: "Stub completion: deterministic twin output, no provider model was run." }), _jsx("pre", { children: result })] })) : null] }));
+}
+function App() {
+    const [models, setModels] = useState([]);
+    const [generations, setGenerations] = useState([]);
+    const [loadError, setLoadError] = useState('');
+    const [selectedModel, setSelectedModel] = useState('');
+    const [selectedGeneration, setSelectedGeneration] = useState('');
+    async function load() {
+        try {
+            const [modelsBody, generationBody] = await Promise.all([
+                json('/api/v1/models'),
+                json('/api/v1/generations'),
+            ]);
+            setModels(modelsBody.data);
+            setGenerations(generationBody.data);
+        }
+        catch (err) {
+            setLoadError(err instanceof Error ? err.message : String(err));
+        }
+    }
+    useEffect(() => {
+        void load();
+    }, []);
+    return (_jsxs("main", { className: "app openrouter-mirror", children: [_jsxs("header", { children: [_jsxs("div", { children: [_jsx("h1", { children: "OpenRouter Twin" }), _jsx("p", { children: "OpenAI-compatible API simulation with deterministic stub output." })] }), _jsx("button", { onClick: () => void load(), children: "Refresh" })] }), loadError ? _jsx("div", { className: "error", children: loadError }) : null, _jsxs("div", { className: "grid", children: [_jsx(Playground, { onComplete: () => void load() }), _jsx(Models, { models: models, onSelect: setSelectedModel }), _jsx(Generations, { generations: generations, onSelect: setSelectedGeneration })] }), selectedModel ? _jsx(ModelDetail, { model: selectedModel, onClose: () => setSelectedModel('') }) : null, selectedGeneration ? _jsx(GenerationDetail, { id: selectedGeneration, onClose: () => setSelectedGeneration('') }) : null] }));
+}
+const root = document.getElementById('root');
+if (root)
+    createRoot(root).render(_jsx(App, {}));

package/dist/client/openrouter-mirror.tsx

@@ -0,0 +1,221 @@
+import React, { useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative, as
+// before); served under a path prefix with a <base> tag every read and write resolves inside that
+// prefix instead of escaping it.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+
+type Model = { id: string; name: string; context_length: number; architecture?: { modality?: string }; pricing?: { prompt?: string; completion?: string } };
+type ModelEndpoints = Model & { endpoints?: Array<{ name: string; provider_name: string; context_length: number }> };
+type Generation = { id: string; model: string; created_at: string; total_cost: number; tokens_prompt: number; tokens_completion: number; streamed: boolean; provider_name?: string; finish_reason?: string };
+
+async function json<T>(path: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(`${WIRE_BASE}${path}`, init);
+  const body = await response.json();
+  if (!response.ok) throw new Error(body?.error?.message ?? `request failed: ${response.status}`);
+  return body as T;
+}
+
+function ModelDetail({ model, onClose }: { model: string; onClose: () => void }) {
+  const [detail, setDetail] = useState<ModelEndpoints | null>(null);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    void json<{ data: ModelEndpoints }>(`/api/v1/models/${model}/endpoints`)
+      .then((body) => setDetail(body.data))
+      .catch((err) => setError(err instanceof Error ? err.message : String(err)));
+  }, [model]);
+  return (
+    <div className="detail model-detail">
+      <div className="detail-head">
+        <h3>Model detail</h3>
+        <button onClick={onClose}>Close</button>
+      </div>
+      {error ? <div className="error">{error}</div> : null}
+      {detail ? (
+        <div className="detail-body">
+          <div className="mono">{detail.id}</div>
+          <div className="kv"><span>Context</span><span className="mono">{detail.context_length.toLocaleString()}</span></div>
+          <div className="kv"><span>Prompt $/tok</span><span className="mono">{detail.pricing?.prompt ?? '-'}</span></div>
+          <div className="kv"><span>Completion $/tok</span><span className="mono">{detail.pricing?.completion ?? '-'}</span></div>
+          <h4>Endpoints</h4>
+          {(detail.endpoints ?? []).map((endpoint) => (
+            <div className="row endpoint-row" key={endpoint.provider_name}>
+              <span>{endpoint.name}</span>
+              <span className="mono">{endpoint.provider_name}</span>
+              <span className="mono">{endpoint.context_length.toLocaleString()} ctx</span>
+            </div>
+          ))}
+        </div>
+      ) : (error ? null : <div className="empty">Loading…</div>)}
+    </div>
+  );
+}
+
+function Models({ models, onSelect }: { models: Model[]; onSelect: (id: string) => void }) {
+  return (
+    <section className="panel models-panel">
+      <h2>Models</h2>
+      <div className="rows">
+        {models.map((model) => (
+          <button className="row model-row" key={model.id} onClick={() => onSelect(model.id)}>
+            <div>
+              <strong>{model.name}</strong>
+              <span className="mono">{model.id}</span>
+            </div>
+            <span>{model.architecture?.modality ?? 'text->text'}</span>
+            <span className="mono">{model.context_length.toLocaleString()} ctx</span>
+          </button>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function GenerationDetail({ id, onClose }: { id: string; onClose: () => void }) {
+  const [detail, setDetail] = useState<Generation | null>(null);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    void json<{ data: Generation }>(`/api/v1/generation?id=${encodeURIComponent(id)}`)
+      .then((body) => setDetail(body.data))
+      .catch((err) => setError(err instanceof Error ? err.message : String(err)));
+  }, [id]);
+  return (
+    <div className="detail generation-detail">
+      <div className="detail-head">
+        <h3>Generation detail</h3>
+        <button onClick={onClose}>Close</button>
+      </div>
+      {error ? <div className="error">{error}</div> : null}
+      {detail ? (
+        <div className="detail-body">
+          <div className="mono">{detail.id}</div>
+          <div className="kv"><span>Model</span><span className="mono">{detail.model}</span></div>
+          <div className="kv"><span>Provider</span><span className="mono">{detail.provider_name ?? 'twin'}</span></div>
+          <div className="kv"><span>Finish</span><span className="mono">{detail.finish_reason ?? '-'}</span></div>
+          <div className="kv"><span>Prompt tokens</span><span className="mono">{detail.tokens_prompt}</span></div>
+          <div className="kv"><span>Completion tokens</span><span className="mono">{detail.tokens_completion}</span></div>
+          <div className="kv"><span>Total cost</span><span className="mono">${detail.total_cost.toFixed(8)}</span></div>
+        </div>
+      ) : (error ? null : <div className="empty">Loading…</div>)}
+    </div>
+  );
+}
+
+function Generations({ generations, onSelect }: { generations: Generation[]; onSelect: (id: string) => void }) {
+  return (
+    <section className="panel generations-panel">
+      <h2>Generations</h2>
+      <div className="rows">
+        {generations.length === 0 ? <div className="empty">No generations yet.</div> : null}
+        {generations.map((generation) => (
+          <button className="row generation-row" key={generation.id} onClick={() => onSelect(generation.id)}>
+            <div>
+              <strong>{generation.model}</strong>
+              <span className="mono">{generation.id}</span>
+            </div>
+            <span>{generation.streamed ? 'streamed' : 'standard'}</span>
+            <span className="mono">${generation.total_cost.toFixed(8)}</span>
+          </button>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function Playground({ onComplete }: { onComplete: () => void }) {
+  const [model, setModel] = useState('google/gemini-3-flash-preview');
+  const [prompt, setPrompt] = useState('Summarize the OpenRouter twin.');
+  const [result, setResult] = useState('');
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState(false);
+
+  async function send() {
+    setBusy(true);
+    setError('');
+    setResult('');
+    try {
+      const body = await json<any>('/api/v1/chat/completions', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }] }),
+      });
+      setResult(body.choices?.[0]?.message?.content ?? '');
+      onComplete();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <section className="panel playground-panel">
+      <h2>Playground</h2>
+      <label>
+        <span>Model</span>
+        <input value={model} onChange={(event) => setModel(event.target.value)} />
+      </label>
+      <label>
+        <span>Prompt</span>
+        <textarea rows={4} value={prompt} onChange={(event) => setPrompt(event.target.value)} />
+      </label>
+      <button onClick={send} disabled={busy}>{busy ? 'Sending...' : 'Send'}</button>
+      {error ? <div className="error">{error}</div> : null}
+      {result ? (
+        <div className="stub-output">
+          <div className="stub-banner">Stub completion: deterministic twin output, no provider model was run.</div>
+          <pre>{result}</pre>
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+function App() {
+  const [models, setModels] = useState<Model[]>([]);
+  const [generations, setGenerations] = useState<Generation[]>([]);
+  const [loadError, setLoadError] = useState('');
+  const [selectedModel, setSelectedModel] = useState('');
+  const [selectedGeneration, setSelectedGeneration] = useState('');
+
+  async function load() {
+    try {
+      const [modelsBody, generationBody] = await Promise.all([
+        json<{ data: Model[] }>('/api/v1/models'),
+        json<{ data: Generation[] }>('/api/v1/generations'),
+      ]);
+      setModels(modelsBody.data);
+      setGenerations(generationBody.data);
+    } catch (err) {
+      setLoadError(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  useEffect(() => {
+    void load();
+  }, []);
+
+  return (
+    <main className="app openrouter-mirror">
+      <header>
+        <div>
+          <h1>OpenRouter Twin</h1>
+          <p>OpenAI-compatible API simulation with deterministic stub output.</p>
+        </div>
+        <button onClick={() => void load()}>Refresh</button>
+      </header>
+      {loadError ? <div className="error">{loadError}</div> : null}
+      <div className="grid">
+        <Playground onComplete={() => void load()} />
+        <Models models={models} onSelect={setSelectedModel} />
+        <Generations generations={generations} onSelect={setSelectedGeneration} />
+      </div>
+      {selectedModel ? <ModelDetail model={selectedModel} onClose={() => setSelectedModel('')} /> : null}
+      {selectedGeneration ? <GenerationDetail id={selectedGeneration} onClose={() => setSelectedGeneration('')} /> : null}
+    </main>
+  );
+}
+
+const root = document.getElementById('root');
+if (root) createRoot(root).render(<App />);

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createOpenRouterTwinServer } from "./openrouter-server.js";
+import { createOpenRouterMirrorServer } from "./openrouter-mirror-ui.js";
+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.js");
+    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/dist/src/index.d.ts

@@ -0,0 +1,15 @@
+export { handleOpenRouterTwinRequest } from './openrouter-twin.js';
+export type { OpenRouterRequest, OpenRouterResponse, SseEvent, SseSink, GenerationStat } from './openrouter-types.js';
+export { createOpenRouterTwinFetch, createOpenRouterTwinServer, type OpenRouterTwinFetchOptions } from './openrouter-server.js';
+export { OPENROUTER_MODELS, OPENROUTER_PROVIDERS, findOpenRouterModel } from './openrouter-models.js';
+export type { OpenRouterModel, OpenRouterProvider } from './openrouter-models.js';
+export { contentToText, countPromptTokens, estimateTokens, lastUserText, stableHash, stubAssistantText } from './openrouter-stub.js';
+export { createOpenRouterScenarioEngine, loadOpenRouterScenarioDocument, openrouterScenarioAdapter, realizeOpenRouterRespond, } from './openrouter-scenario.js';
+export type { OpenRouterScenarioEngine, OpenRouterScenarioRequest, OpenRouterScenarioRespond, ScenarioToolCall, } from './openrouter-scenario.js';
+export { buildOpenRouterMirrorClient, createOpenRouterMirrorServer, openrouterMirrorHtml } from './openrouter-mirror-ui.js';
+export { OPENROUTER_API_BASE, liveOpenRouterExecute, openRouterRequestForAction, pullOpenRouterState, pushOpenRouterAction, pushPendingOpenRouterActions, syncOpenRouterFromReal, } from './openrouter-connector.js';
+export type { OpenRouterExecute } from './openrouter-connector.js';
+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.js';
+export type { OpenRouterBudgetErrorKind, OpenRouterBudgetOptions, OpenRouterBudgetReservation, OpenRouterBudgetSnapshot, } from './openrouter-budget.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,66 @@
+export { handleOpenRouterTwinRequest } from "./openrouter-twin.js";
+export { createOpenRouterTwinFetch, createOpenRouterTwinServer } from "./openrouter-server.js";
+export { OPENROUTER_MODELS, OPENROUTER_PROVIDERS, findOpenRouterModel } from "./openrouter-models.js";
+export { contentToText, countPromptTokens, estimateTokens, lastUserText, stableHash, stubAssistantText } from "./openrouter-stub.js";
+// 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.js";
+export { buildOpenRouterMirrorClient, createOpenRouterMirrorServer, openrouterMirrorHtml } from "./openrouter-mirror-ui.js";
+export { OPENROUTER_API_BASE, liveOpenRouterExecute, openRouterRequestForAction, pullOpenRouterState, pushOpenRouterAction, pushPendingOpenRouterActions, syncOpenRouterFromReal, } from "./openrouter-connector.js";
+// 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.js";
+import { registerPack } from '@volter/world-core';
+import { performOpenRouterAction, syncOpenRouterFromRemote } from "./openrouter-connector.js";
+import { OPENROUTER_RATE_BUDGET as RATE_BUDGET } from "./openrouter-budget.js";
+export const pack = {
+    // 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/dist/src/openrouter-budget.d.ts

@@ -0,0 +1,58 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Matches the per-MINUTE shape of every figure OpenRouter publishes. */
+export declare const OPENROUTER_BUDGET_WINDOW_MS = 60000;
+/**
+ * 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 declare const OPENROUTER_BUDGET_CEILING = 20;
+/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly. */
+export declare 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 declare const OPENROUTER_CALL_WEIGHTS: {
+    /** `GET /api/v1/generation?id=…` — one per pending action, so unbounded in the caller's backlog. */
+    readonly generation: 2;
+    /** Every other modeled call, including the `/api/v1/models` catalog pull. */
+    readonly 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 declare const OPENROUTER_RATE_BUDGET: RateBudgetDeclaration;
+/** Split a connector path (which carries its own query string) into pathname + parsed query. */
+export declare function splitOpenRouterPath(path: string): {
+    pathname: string;
+    query: Record<string, string>;
+};
+/**
+ * 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 declare function openRouterCallWeight(method: string, path: string): number;
+/** 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 declare function openRouterBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** 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 declare class OpenRouterBudget extends RateBudget {
+    constructor(opts?: OpenRouterBudgetOptions);
+}
+/** 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;