@volter/twin-openrouter 0.1.0

package/dist/src/openrouter-local-generation.js

@@ -0,0 +1,271 @@
+/** Optional pack-owned transport to a separately World-owned loopback generation service. */
+export const LOCAL_GENERATION_BODY_LIMIT = 8 * 1024 * 1024;
+export function localGenerationOrigin(value) {
+    const match = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})\/?$/.exec(value);
+    const port = match ? Number(match[1]) : 0;
+    if (!port || port > 65535) {
+        throw new Error('local_generation_url_invalid: expected http://127.0.0.1:<nonzero-port> with no credentials, path, query, or fragment');
+    }
+    return `http://127.0.0.1:${port}`;
+}
+/** Read only the opt-in generation request body; ordinary twin routes retain their old path. */
+export async function readLocalGenerationBody(request) {
+    request.signal.throwIfAborted();
+    const reader = request.body?.getReader();
+    if (!reader)
+        return { bytes: new Uint8Array(0), text: '' };
+    const parts = [];
+    let length = 0;
+    let readFailed = false;
+    let done = false;
+    let primary;
+    let failed = false;
+    let cleanupFailure;
+    let cleanupFailed = false;
+    let result;
+    let abortCleanup;
+    const onAbort = () => {
+        abortCleanup ??= reader.cancel(request.signal.reason);
+        // The request's finally block observes the same promise even if cancellation rejects first.
+        void abortCleanup.catch(() => { });
+    };
+    request.signal.addEventListener('abort', onAbort, { once: true });
+    if (request.signal.aborted)
+        onAbort();
+    try {
+        while (true) {
+            request.signal.throwIfAborted();
+            let part;
+            try {
+                part = await reader.read();
+            }
+            catch (error) {
+                readFailed = true;
+                throw error;
+            }
+            request.signal.throwIfAborted();
+            if (part.done) {
+                done = true;
+                break;
+            }
+            length += part.value.byteLength;
+            if (length > LOCAL_GENERATION_BODY_LIMIT)
+                throw new Error('local_generation_body_too_large: 8 MiB limit');
+            parts.push(part.value);
+        }
+        const bytes = new Uint8Array(length);
+        let offset = 0;
+        for (const part of parts) {
+            bytes.set(part, offset);
+            offset += part.byteLength;
+        }
+        try {
+            result = { bytes, text: new TextDecoder('utf-8', { fatal: true }).decode(bytes) };
+        }
+        catch (error) {
+            throw new Error('local_generation_invalid_utf8: request body is not valid UTF-8', { cause: error });
+        }
+    }
+    catch (error) {
+        primary = error;
+        failed = true;
+    }
+    finally {
+        request.signal.removeEventListener('abort', onAbort);
+        if (!done && (!readFailed || abortCleanup)) {
+            try {
+                await (abortCleanup ?? reader.cancel(primary));
+            }
+            catch (cleanup) {
+                cleanupFailure = cleanup;
+                cleanupFailed = true;
+            }
+        }
+        try {
+            reader.releaseLock();
+        }
+        catch (cleanup) {
+            cleanupFailure = cleanupFailed ? new AggregateError([cleanupFailure, cleanup], 'local_generation_body_cleanup_failed') : cleanup;
+            cleanupFailed = true;
+        }
+    }
+    if (cleanupFailed)
+        throw new AggregateError(failed ? [primary, cleanupFailure] : [cleanupFailure], 'local_generation_body_cleanup_failed');
+    if (failed)
+        throw primary;
+    if (!result)
+        throw new Error('local_generation_body_read_failed: no completed body');
+    return result;
+}
+function localError(status, code, message) {
+    return Response.json({ error: { message, type: 'local_generation_error', code } }, { status });
+}
+/** One pull from the caller means at most one read from the local response. */
+export async function forwardLocalGeneration(args) {
+    const relay = new AbortController();
+    const abort = () => relay.abort(args.request.signal.reason);
+    args.request.signal.addEventListener('abort', abort, { once: true });
+    if (args.request.signal.aborted)
+        abort();
+    const headers = new Headers();
+    for (const key of ['content-type', 'accept']) {
+        const value = args.request.headers.get(key);
+        if (value !== null)
+            headers.set(key, value);
+    }
+    let upstream;
+    try {
+        upstream = await (args.fetchImpl ?? fetch)(`${args.origin}${args.pathname}`, {
+            method: 'POST', headers, body: args.body, redirect: 'manual', signal: relay.signal,
+        });
+    }
+    catch (error) {
+        args.request.signal.removeEventListener('abort', abort);
+        if (args.request.signal.aborted)
+            throw error;
+        return localError(503, 'local_generation_unavailable', `Local generation service unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (upstream.status >= 300 && upstream.status < 400) {
+        try {
+            await upstream.body?.cancel();
+        }
+        catch (error) {
+            args.request.signal.removeEventListener('abort', abort);
+            return localError(502, 'local_generation_cleanup_failed', `Local generation redirect body cleanup failed: ${String(error)}`);
+        }
+        args.request.signal.removeEventListener('abort', abort);
+        return localError(502, 'local_generation_redirect_refused', 'Local generation service redirect refused');
+    }
+    if (args.request.signal.aborted) {
+        args.request.signal.removeEventListener('abort', abort);
+        try {
+            await upstream.body?.cancel(args.request.signal.reason);
+        }
+        catch (cleanup) {
+            throw new AggregateError([args.request.signal.reason, cleanup], 'local_generation_cleanup_failed');
+        }
+        throw args.request.signal.reason;
+    }
+    const responseHeaders = new Headers();
+    for (const key of ['content-type', 'retry-after', 'retry-after-ms']) {
+        const value = upstream.headers.get(key);
+        if (value !== null)
+            responseHeaders.set(key, value);
+    }
+    if (!upstream.body) {
+        args.request.signal.removeEventListener('abort', abort);
+        return new Response(null, { status: upstream.status, headers: responseHeaders });
+    }
+    const reader = upstream.body.getReader();
+    let terminal = false;
+    let cancelPromise;
+    let failure;
+    let abortCleanup;
+    let streamController;
+    let readerTerminal = 'pending';
+    void reader.closed.then(() => { readerTerminal = 'closed'; }, () => { readerTerminal = 'errored'; });
+    const cancelReader = (reason) => {
+        if (cancelPromise)
+            return cancelPromise;
+        cancelPromise = (async () => {
+            let primary;
+            let failed = false;
+            await Promise.resolve();
+            if (readerTerminal === 'pending') {
+                try {
+                    await reader.cancel(reason);
+                }
+                catch (error) {
+                    primary = error;
+                    failed = true;
+                }
+            }
+            try {
+                reader.releaseLock();
+            }
+            catch (cleanup) {
+                primary = failed ? new AggregateError([primary, cleanup], 'local_generation_cleanup_failed') : cleanup;
+                failed = true;
+            }
+            if (failed)
+                throw primary;
+        })();
+        return cancelPromise;
+    };
+    const finish = () => {
+        if (terminal)
+            return;
+        terminal = true;
+        args.request.signal.removeEventListener('abort', onAbort);
+    };
+    const onAbort = () => {
+        relay.abort(args.request.signal.reason);
+        failure = args.request.signal.reason;
+        abortCleanup = cancelReader(failure);
+        void abortCleanup.then(() => { finish(); try {
+            streamController?.error(failure);
+        }
+        catch { /* an active pull already reported the abort */ } }, (cleanup) => {
+            failure = new AggregateError([failure, cleanup], 'local_generation_cleanup_failed');
+            finish();
+            try {
+                streamController?.error(failure);
+            }
+            catch { /* an active pull already reported the failure */ }
+        });
+    };
+    args.request.signal.removeEventListener('abort', abort);
+    args.request.signal.addEventListener('abort', onAbort, { once: true });
+    if (args.request.signal.aborted)
+        onAbort();
+    const body = new ReadableStream({
+        start(controller) {
+            streamController = controller;
+            if (failure !== undefined && !abortCleanup)
+                controller.error(failure);
+        },
+        async pull(controller) {
+            if (failure !== undefined) {
+                if (abortCleanup)
+                    await abortCleanup.then(() => { }, () => { });
+                finish();
+                try {
+                    controller.error(failure);
+                }
+                catch { /* abort callback already reported it */ }
+                return;
+            }
+            try {
+                const part = await reader.read();
+                if (abortCleanup) {
+                    await abortCleanup.then(() => { }, () => { });
+                    throw failure;
+                }
+                if (part.done) {
+                    finish();
+                    reader.releaseLock();
+                    controller.close();
+                }
+                else
+                    controller.enqueue(part.value);
+            }
+            catch (error) {
+                finish();
+                try {
+                    reader.releaseLock();
+                }
+                catch { /* read/cancel race; retain original stream error */ }
+                try {
+                    controller.error(failure ?? error);
+                }
+                catch { /* already errored by abort callback */ }
+            }
+        },
+        async cancel(reason) {
+            finish();
+            relay.abort(reason);
+            await cancelReader(reason);
+        },
+    }, { highWaterMark: 0 });
+    return new Response(body, { status: upstream.status, headers: responseHeaders });
+}

package/dist/src/openrouter-mirror-ui.d.ts

@@ -0,0 +1,12 @@
+export declare function buildOpenRouterMirrorClient(): Promise<string>;
+export declare function createOpenRouterMirrorServer(options?: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+export declare function openrouterMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function openrouterMirrorStyles(): Promise<string>;

package/dist/src/openrouter-mirror-ui.js

@@ -0,0 +1,78 @@
+// OpenRouter MIRROR UI — a models/playground/generations console served as a React/TSX app
+// (bundled by Bun).
+//
+// PURE FRONTEND (R3): the mirror imports no handler module and no twin internals — it MOUNTS the
+// pack's OWN fetch adapter (`createOpenRouterTwinFetch`) as its API backend and reads every byte of
+// state back over the wire. The client fetches OPENROUTER'S REAL VENDOR PATHS (`/api/v1/models`,
+// `/api/v1/chat/completions`, `/api/v1/generations`, `/api/v1/generation?id=…`) on the same origin,
+// so there is exactly ONE serving code path and API<->UI parity cannot drift: the screen shows real
+// twin state or nothing. Mounting the adapter also hands the mirror the streaming lane, the world
+// clock and an honorable `readOnly` for free — the hand-rolled dispatch this replaced used
+// `new Date()` and ignored `readOnly` (the airtable §9 round-two finding 13 drift, verbatim).
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createOpenRouterTwinFetch } from "./openrouter-server.js";
+const CLIENT_ENTRY = () => new URL('../client/openrouter-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/openrouter-mirror.css', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>OpenRouter (twin)</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+let clientBundle = null;
+export function buildOpenRouterMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY())
+            .catch((error) => {
+            clientBundle = null;
+            throw error;
+        });
+    }
+    return clientBundle;
+}
+export async function createOpenRouterMirrorServer(options = {}) {
+    // Built ONCE, above the socket — never per request: the adapter is a closure over the twin's
+    // options and is the very same one `createOpenRouterTwinServer` serves.
+    const twin = createOpenRouterTwinFetch(options);
+    const server = await serveHttp({
+        // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+        // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+        // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+        // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+        // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+        // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+        // on loopback, so the verify's fetches deterministically reach THIS server.
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        async fetch(request) {
+            const url = new URL(request.url);
+            if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+                try {
+                    return new Response(await buildOpenRouterMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+                }
+                catch (error) {
+                    return new Response(String(error), { status: 500 });
+                }
+            }
+            if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+                return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+            }
+            if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+                return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+            }
+            // everything else -> the twin's OWN FETCH ADAPTER (composition, R2/R3). That includes the
+            // uniform `GET /twin` door and the SSE lane; nothing about the mirror port may differ from
+            // the API port.
+            return twin(request);
+        },
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+export function openrouterMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function openrouterMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

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

@@ -0,0 +1,39 @@
+export type OpenRouterModel = {
+    id: string;
+    name: string;
+    created: number;
+    description: string;
+    context_length: number;
+    architecture: {
+        modality: string;
+        tokenizer: string;
+        instruct_type: string | null;
+        input_modalities: string[];
+        output_modalities: string[];
+    };
+    pricing: {
+        prompt: string;
+        completion: string;
+        image: string;
+        request: string;
+    };
+    top_provider: {
+        context_length: number;
+        max_completion_tokens: number;
+        is_moderated: boolean;
+    };
+    per_request_limits: Record<string, unknown> | null;
+};
+export declare const OPENROUTER_MODELS: OpenRouterModel[];
+export declare function findOpenRouterModel(id: string): OpenRouterModel | undefined;
+export type OpenRouterProvider = {
+    name: string;
+    slug: string;
+    privacy_policy_url: string | null;
+    terms_of_service_url: string | null;
+    status_page_url: string | null;
+    may_log_prompts: boolean;
+    may_train_on_data: boolean;
+    moderated_by_openrouter: boolean;
+};
+export declare const OPENROUTER_PROVIDERS: OpenRouterProvider[];

package/dist/src/openrouter-models.js

@@ -0,0 +1,78 @@
+export const OPENROUTER_MODELS = [
+    {
+        id: 'openai/gpt-4o',
+        name: 'OpenAI: GPT-4o',
+        created: 1715731200,
+        description: 'Deterministic local catalog entry for GPT-4o.',
+        context_length: 128000,
+        architecture: {
+            modality: 'text+image->text',
+            tokenizer: 'GPT',
+            instruct_type: 'chatml',
+            input_modalities: ['text', 'image'],
+            output_modalities: ['text'],
+        },
+        pricing: { prompt: '0.0000025', completion: '0.00001', image: '0', request: '0' },
+        top_provider: { context_length: 128000, max_completion_tokens: 16384, is_moderated: true },
+        per_request_limits: null,
+    },
+    {
+        id: 'anthropic/claude-sonnet-4.5',
+        name: 'Anthropic: Claude Sonnet 4.5',
+        created: 1759449600,
+        description: 'Deterministic local catalog entry for Claude Sonnet.',
+        context_length: 200000,
+        architecture: {
+            modality: 'text+image->text',
+            tokenizer: 'Claude',
+            instruct_type: null,
+            input_modalities: ['text', 'image'],
+            output_modalities: ['text'],
+        },
+        pricing: { prompt: '0.000003', completion: '0.000015', image: '0', request: '0' },
+        top_provider: { context_length: 200000, max_completion_tokens: 64000, is_moderated: true },
+        per_request_limits: null,
+    },
+    {
+        id: 'google/gemini-2.5-flash',
+        name: 'Google: Gemini 2.5 Flash',
+        created: 1747267200,
+        description: 'Deterministic local catalog entry for Gemini 2.5 Flash.',
+        context_length: 1000000,
+        architecture: {
+            modality: 'text+image+audio->text',
+            tokenizer: 'Gemini',
+            instruct_type: null,
+            input_modalities: ['text', 'image', 'audio'],
+            output_modalities: ['text'],
+        },
+        pricing: { prompt: '0.0000003', completion: '0.0000025', image: '0', request: '0' },
+        top_provider: { context_length: 1000000, max_completion_tokens: 8192, is_moderated: true },
+        per_request_limits: null,
+    },
+    {
+        id: 'google/gemini-3-flash-preview',
+        name: 'Google: Gemini 3 Flash Preview',
+        created: 1763424000,
+        description: 'Deterministic local catalog entry for Gemini Flash.',
+        context_length: 1000000,
+        architecture: {
+            modality: 'text+image+audio->text',
+            tokenizer: 'Gemini',
+            instruct_type: null,
+            input_modalities: ['text', 'image', 'audio'],
+            output_modalities: ['text'],
+        },
+        pricing: { prompt: '0.0000005', completion: '0.000003', image: '0', request: '0' },
+        top_provider: { context_length: 1000000, max_completion_tokens: 8192, is_moderated: true },
+        per_request_limits: null,
+    },
+];
+export function findOpenRouterModel(id) {
+    return OPENROUTER_MODELS.find((model) => model.id === id);
+}
+export const OPENROUTER_PROVIDERS = [
+    { name: 'OpenAI', slug: 'openai', privacy_policy_url: 'https://openai.com/policies/privacy-policy', terms_of_service_url: 'https://openai.com/policies/terms-of-use', status_page_url: 'https://status.openai.com', may_log_prompts: false, may_train_on_data: false, moderated_by_openrouter: false },
+    { name: 'Anthropic', slug: 'anthropic', privacy_policy_url: 'https://www.anthropic.com/legal/privacy', terms_of_service_url: 'https://www.anthropic.com/legal/commercial-terms', status_page_url: 'https://status.anthropic.com', may_log_prompts: false, may_train_on_data: false, moderated_by_openrouter: false },
+    { name: 'Google AI Studio', slug: 'google-ai-studio', privacy_policy_url: 'https://policies.google.com/privacy', terms_of_service_url: 'https://ai.google.dev/gemini-api/terms', status_page_url: null, may_log_prompts: true, may_train_on_data: false, moderated_by_openrouter: false },
+];

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

@@ -0,0 +1,36 @@
+import { type PackScenarioAdapter, type ScenarioDocument, ScenarioEngine } from '@volter/world-core';
+import type { ChatMessage } from './openrouter-types.js';
+/** The request slice the scenario system sees — built by the chat route from validated args. */
+export type OpenRouterScenarioRequest = {
+    model: string;
+    messages: ChatMessage[];
+    tools?: unknown;
+};
+export type OpenRouterScenarioEngine = ScenarioEngine<OpenRouterScenarioRequest>;
+/** A scripted tool call — the arguments object is emitted verbatim as the JSON string the
+ *  OpenAI-shaped wire carries. */
+export type ScenarioToolCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+    id?: string;
+};
+export type OpenRouterScenarioRespond = {
+    text?: string;
+    toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+    finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+/** What a fired handler yields — the assistant turn plus the finish_reason for the envelope. */
+export type ScriptedResult = {
+    text: string | null;
+    toolCalls: Array<Record<string, unknown>>;
+    finishReason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+export declare const openrouterScenarioAdapter: PackScenarioAdapter<OpenRouterScenarioRequest>;
+/** Load + strictly validate a handlers document (handlers/openrouter.json). A broken file fails
+ *  server construction loudly; it never falls back or misfires silently. */
+export declare function loadOpenRouterScenarioDocument(path: string): ScenarioDocument;
+export declare function createOpenRouterScenarioEngine(document?: ScenarioDocument): OpenRouterScenarioEngine;
+/** Realize a fired handler's respond payload into the OpenAI-shaped assistant turn. Scripted
+ *  tool-call ids are DERIVED from the call itself (name + arguments), never a counter: two
+ *  identical worlds replaying the same script mint the same id (R9). */
+export declare function realizeOpenRouterRespond(respond: OpenRouterScenarioRespond): ScriptedResult;

package/dist/src/openrouter-scenario.js

@@ -0,0 +1,145 @@
+// The openrouter pack's HALF of the scenario system, on the kernel's ONE engine (@volter/world-core
+// scenario.ts). The GRAMMAR (ordering, once/scope/phase, extractors, strict parsing, miss
+// records, twin.use) is the kernel's and identical for every vendor; this module declares only
+// the VOCABULARY:
+//   • the `on` keys a handler may match (model / last-user text / any text / tools / tool
+//     results) — OpenRouter's wire is the OpenAI chat-completions shape, so the vocabulary is
+//     that shape's, deliberately the same words the openai pack uses,
+//   • what a `respond` payload may contain ({ text | toolCalls, finishReason? }),
+//   • how a fired handler REALIZES into an assistant turn (content or tool_calls + the
+//     finish_reason the envelope reports).
+// The engine is consulted ONCE per generation request (chat completions and the Responses beta,
+// which share `buildChoice`); a miss leaves the pack's labeled deterministic stub in place and
+// is inspectable at GET /twin/scenario. The handler FILE (handlers/openrouter.json in a world
+// dir) is the only write surface — there is no runtime write door.
+import { getActiveWorldStore, parseScenarioDocument, ScenarioError, ScenarioEngine } from '@volter/world-core';
+import { contentToText, lastUserText, stableHash } from "./openrouter-stub.js";
+const RESPOND_KEYS = new Set(['text', 'toolCalls', 'finishReason']);
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls', 'content_filter']);
+const nonEmptyString = (cond) => typeof cond === 'string' && cond.length > 0;
+/** The tool NAMES the trailing `role:"tool"` message answers, resolved through the tool_call ids
+ *  of earlier assistant turns. */
+function lastToolResultNames(messages) {
+    const names = new Set();
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string')
+        return names;
+    for (const m of messages) {
+        const am = m;
+        if (am.role !== 'assistant' || !Array.isArray(am.tool_calls))
+            continue;
+        for (const tc of am.tool_calls) {
+            if (tc?.id === last.tool_call_id && typeof tc?.function?.name === 'string')
+                names.add(tc.function.name);
+        }
+    }
+    return names;
+}
+function toolNames(tools) {
+    if (!Array.isArray(tools))
+        return [];
+    return tools
+        .map((t) => (typeof t?.function?.name === 'string' ? t.function.name : typeof t?.name === 'string' ? t.name : null))
+        .filter((n) => n !== null);
+}
+export const openrouterScenarioAdapter = {
+    vendor: 'openrouter',
+    features: (req) => ({
+        model: req.model,
+        lastUserText: lastUserText(req.messages).slice(0, 300),
+        tools: toolNames(req.tools),
+        lastMessageIsToolResult: req.messages[req.messages.length - 1]?.role === 'tool',
+        toolResultFor: [...lastToolResultNames(req.messages)],
+    }),
+    matchers: {
+        // The routed model id as the caller asked for it, with OpenRouter's `:online` suffix already
+        // stripped by the chat route (the suffix selects the web plugin, not a different model).
+        modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+        userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages).toLowerCase().includes(cond.toLowerCase()),
+        anyTextIncludes: (req, cond) => nonEmptyString(cond) && req.messages.map((m) => contentToText(m.content)).join('\n').toLowerCase().includes(cond.toLowerCase()),
+        lastMessageIsToolResult: (req, cond) => typeof cond === 'boolean' && (req.messages[req.messages.length - 1]?.role === 'tool') === cond,
+        toolResultFor: (req, cond) => nonEmptyString(cond) && lastToolResultNames(req.messages).has(cond),
+        hasTool: (req, cond) => nonEmptyString(cond) && toolNames(req.tools).includes(cond),
+    },
+    text: (req) => req.messages.map((m) => contentToText(m.content)).join('\n'),
+    validateOn: (on) => {
+        for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool']) {
+            if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k]))
+                return `on.${k} is a non-empty string`;
+        }
+        if (on.lastMessageIsToolResult !== undefined && typeof on.lastMessageIsToolResult !== 'boolean')
+            return 'on.lastMessageIsToolResult is a boolean';
+        return null;
+    },
+    validateRespond: (respond) => {
+        if (typeof respond !== 'object' || respond === null || Array.isArray(respond))
+            return 'respond is an object { text?, toolCalls?, finishReason? }';
+        const r = respond;
+        for (const k of Object.keys(r))
+            if (!RESPOND_KEYS.has(k))
+                return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+        if (r.text !== undefined && typeof r.text !== 'string')
+            return 'respond.text is a string';
+        if (r.finishReason !== undefined && (typeof r.finishReason !== 'string' || !FINISH_REASONS.has(r.finishReason)))
+            return `respond.finishReason is one of ${[...FINISH_REASONS].join(', ')}`;
+        if (r.toolCalls !== undefined) {
+            for (const tc of Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+                const t = tc;
+                if (!t || typeof t !== 'object' || Array.isArray(t))
+                    return 'respond.toolCalls entries are objects';
+                if (typeof t.name !== 'string' || !t.name)
+                    return 'respond.toolCalls[].name is a non-empty string';
+                if (!t.arguments || typeof t.arguments !== 'object' || Array.isArray(t.arguments))
+                    return 'respond.toolCalls[].arguments is an object';
+                if (t.id !== undefined && typeof t.id !== 'string')
+                    return 'respond.toolCalls[].id is a string';
+            }
+        }
+        if (r.text === undefined && r.toolCalls === undefined)
+            return 'respond needs text or toolCalls';
+        return null;
+    },
+    renderFault: (fault) => ({
+        body: { error: { message: fault.message ?? `twin fault: ${fault.status}`, type: 'twin_fault', code: 'twin_fault' } },
+    }),
+};
+/** Load + strictly validate a handlers document (handlers/openrouter.json). A broken file fails
+ *  server construction loudly; it never falls back or misfires silently. */
+export function loadOpenRouterScenarioDocument(path) {
+    let parsed;
+    try {
+        // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract R12b):
+        // the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world serves ITS
+        // OWN scenario instead of whatever happens to sit on the host disk — and the serve path
+        // stays workerd-clean.
+        const raw = getActiveWorldStore().read(path);
+        if (raw === null)
+            throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new ScenarioError(`openrouter scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return parseScenarioDocument(parsed, openrouterScenarioAdapter);
+}
+export function createOpenRouterScenarioEngine(document) {
+    return new ScenarioEngine(openrouterScenarioAdapter, document);
+}
+/** Realize a fired handler's respond payload into the OpenAI-shaped assistant turn. Scripted
+ *  tool-call ids are DERIVED from the call itself (name + arguments), never a counter: two
+ *  identical worlds replaying the same script mint the same id (R9). */
+export function realizeOpenRouterRespond(respond) {
+    const toolCalls = [];
+    for (const tc of respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : []) {
+        toolCalls.push({
+            id: tc.id ?? `call_scripted_${stableHash({ name: tc.name, arguments: tc.arguments }).slice(0, 8)}`,
+            type: 'function',
+            function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+        });
+    }
+    return {
+        text: respond.text ?? (toolCalls.length ? null : ''),
+        toolCalls,
+        finishReason: respond.finishReason ?? (toolCalls.length ? 'tool_calls' : 'stop'),
+    };
+}