@volter/twin-openrouter 0.1.0

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

@@ -0,0 +1,20 @@
+import { type LocalGenerationFetch } from './openrouter-local-generation.js';
+/** Options every OpenRouter-twin HTTP surface needs, independent of who owns the socket. */
+export interface OpenRouterTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    /** Path to the world dir's handlers/openrouter.json — read ONCE, at construction, through the
+     *  active WorldStore. Absent → no engine, and the labeled deterministic stub answers. */
+    scenarioPath?: string;
+    /** Explicitly selected World-owned loopback service. Absent means deterministic twin output. */
+    localGenerationUrl?: string;
+    /** Injectable transport for deterministic pack tests; the production default is global fetch. */
+    localGenerationFetch?: LocalGenerationFetch;
+}
+export declare function createOpenRouterTwinFetch(options: OpenRouterTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createOpenRouterTwinServer(options?: OpenRouterTwinFetchOptions & {
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/openrouter-server.js

@@ -0,0 +1,144 @@
+// OpenRouter twin HTTP server.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createOpenRouterTwinFetch` and
+// the SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): the SSE streaming lane genuinely exceeds the common shape —
+// openai-server.ts is the reference for it. The two READ DOORS it serves are the same ones that
+// adapter provides (runtime contract R5): keyless `GET /twin` and `GET /twin/scenario`.
+//
+// SCENARIO scripting (openrouter-scenario.ts): pass `scenarioPath` (or set the
+// TWIN_OPENROUTER_SCENARIO env var) to script chat-completion turns. A malformed scenario throws
+// at construction — loudly, never a silent fallback.
+import { serveHttp } from '@volter/world-core';
+import { handleOpenRouterTwinRequest, handleOpenRouterTwinRequestWithGeneration } from "./openrouter-twin.js";
+import { worldNow, twinManifest } from '@volter/world-core';
+import { createOpenRouterScenarioEngine, loadOpenRouterScenarioDocument } from "./openrouter-scenario.js";
+import { forwardLocalGeneration, localGenerationOrigin, readLocalGenerationBody } from "./openrouter-local-generation.js";
+function wantsStream(body) {
+    try {
+        return JSON.parse(body || '{}')?.stream === true;
+    }
+    catch {
+        return false;
+    }
+}
+function encodeSse(event) {
+    return event.done ? 'data: [DONE]\n\n' : `data: ${JSON.stringify(event.data)}\n\n`;
+}
+export function createOpenRouterTwinFetch(options) {
+    const readOnly = options.readOnly ?? false;
+    const scenarioPath = options.scenarioPath ?? process.env.TWIN_OPENROUTER_SCENARIO;
+    const scenarioEngine = scenarioPath ? createOpenRouterScenarioEngine(loadOpenRouterScenarioDocument(scenarioPath)) : undefined;
+    const selectedUrl = options.localGenerationUrl !== undefined ? options.localGenerationUrl : process.env.TWIN_OPENROUTER_LOCAL_GENERATION_URL;
+    const localOrigin = selectedUrl === undefined ? undefined : localGenerationOrigin(selectedUrl);
+    return async function openRouterTwinFetch(request) {
+        const url = new URL(request.url);
+        // THE READ DOORS (runtime contract R5, TWIN-PROGRAMMING-MODEL): discovery + inspection,
+        // keyless and read-only. They answer BEFORE any vendor routing, so a door is never an
+        // authenticated vendor route.
+        if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+            return Response.json(twinManifest({
+                vendor: 'openrouter',
+                twinOf: 'the OpenRouter API',
+                stateSentence: localOrigin
+                    ? 'Stored twin resources and scripted chat generations use the ordinary twin log. Forwarded local generations belong only to the local service ledger; twin generation and analytics routes do not include them.'
+                    : 'Stateful where it stores: seed keys, BYOK credentials, presets and generation stats through the ordinary API with any credential. Generations are recorded as you make them.',
+                behaviorSentence: `Chat completions (and the Responses beta) are scripted by MSW-shaped handlers in the world dir (handlers/openrouter.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|hasTool|toolResultFor|lastMessageIsToolResult|nthCall}, respond:{text|toolCalls, finishReason?}, once?, phase?}. ${localOrigin ? 'Only unmatched supported generation requests are handed to an explicitly selected World-owned local service; this opt-in output is nondeterministic and is not replayable twin state.' : 'Unmatched requests answer the labeled deterministic stub naming this door.'}`,
+                exampleHandler: { on: { userTextIncludes: 'summarize' }, respond: { text: 'Scripted summary.' } },
+                engine: scenarioEngine,
+            }));
+        }
+        if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin/scenario') {
+            return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'openrouter', handlers: [], misses: 0, recentMisses: [] });
+        }
+        const path = url.pathname + url.search;
+        const normalizedPath = url.pathname.replace(/^\/api\/v1/, '/v1');
+        const localRoute = localOrigin !== undefined && request.method.toUpperCase() === 'POST'
+            && (normalizedPath === '/v1/chat/completions' || normalizedPath === '/v1/responses');
+        if (localRoute && readOnly) {
+            const refusal = await handleOpenRouterTwinRequest({ method: request.method, path, readOnly });
+            return new Response(JSON.stringify(refusal.body), { status: refusal.status, headers: { 'content-type': 'application/json' } });
+        }
+        let body;
+        let localBytes;
+        if (localRoute) {
+            try {
+                const bounded = await readLocalGenerationBody(request);
+                body = bounded.text;
+                localBytes = bounded.bytes;
+            }
+            catch (error) {
+                if (request.signal.aborted)
+                    throw error;
+                const message = error instanceof Error ? error.message : String(error);
+                const status = message.startsWith('local_generation_body_too_large') ? 413 : message.startsWith('local_generation_invalid_utf8') ? 400 : 500;
+                return Response.json({ error: { message, type: 'local_generation_error', code: status === 413 ? 'local_generation_body_too_large' : status === 400 ? 'invalid_utf8' : 'local_generation_body_read_failed' } }, { status });
+            }
+        }
+        else
+            body = request.method === 'GET' ? '' : await request.text();
+        const events = [];
+        const streamChat = request.method.toUpperCase() === 'POST' && normalizedPath === '/v1/chat/completions' && wantsStream(body);
+        const twinRequest = {
+            method: request.method,
+            path,
+            body,
+            readOnly,
+            signal: request.signal,
+            occurredAt: worldNow(),
+            ...(options.root !== undefined ? { root: options.root } : {}),
+            ...(scenarioEngine ? { scenarioEngine } : {}),
+            ...(streamChat ? { sseSink: (event) => events.push(event) } : {}),
+        };
+        const result = localRoute && localOrigin && localBytes
+            ? await handleOpenRouterTwinRequestWithGeneration(twinRequest, () => forwardLocalGeneration({
+                origin: localOrigin, request, pathname: url.pathname, body: localBytes,
+                ...(options.localGenerationFetch ? { fetchImpl: options.localGenerationFetch } : {}),
+            }))
+            : await handleOpenRouterTwinRequest(twinRequest);
+        if (result instanceof Response)
+            return result;
+        // Streaming POST → a real text/event-stream response built from the sink.
+        //
+        // Events are COLLECTED first, then framed. The handler is synchronous-fast, so buffering
+        // costs nothing — and it is what lets a PRE-STREAM failure answer with its REAL status and
+        // the vendor's JSON error envelope. Emitting the refusal as a lone `data:` frame inside a
+        // 200 text/event-stream was a FAKE SUCCESS the in-process path could not see:
+        // `handleOpenRouterTwinRequest` returns 404 for an unknown model and 400 for a body with
+        // no `messages`, while the wire returned 200 in both cases — so every verify asserting
+        // those statuses asserted something the socket never carried. OpenRouter rejects a bad
+        // request BEFORE opening the event stream; this twin decides every refusal before the
+        // first chunk.
+        if (!readOnly && streamChat) {
+            if (result.status >= 400) {
+                return new Response(JSON.stringify(result.body), {
+                    status: result.status,
+                    headers: { 'content-type': 'application/json', ...result.headers },
+                });
+            }
+            const stream = new ReadableStream({
+                start(controller) {
+                    const encoder = new TextEncoder();
+                    for (const event of events)
+                        controller.enqueue(encoder.encode(encodeSse(event)));
+                    controller.close();
+                },
+            });
+            return new Response(stream, {
+                headers: {
+                    'content-type': 'text/event-stream; charset=utf-8',
+                    'cache-control': 'no-cache',
+                },
+            });
+        }
+        return new Response(JSON.stringify(result.body), { status: result.status, headers: { 'content-type': 'application/json', ...result.headers } });
+    };
+}
+export async function createOpenRouterTwinServer(options = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createOpenRouterTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

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

@@ -0,0 +1,8 @@
+import type { ChatMessage } from './openrouter-types.js';
+export declare function contentToText(content: unknown): string;
+export declare function lastUserText(messages: ChatMessage[]): string;
+export declare function estimateTokens(input: string): number;
+export declare function countPromptTokens(messages: ChatMessage[]): number;
+export declare function stubAssistantText(messages: ChatMessage[], model: string): string;
+export declare function stableHash(value: unknown): string;
+export declare function firstToolCall(tools: unknown): Record<string, unknown> | null;

package/dist/src/openrouter-stub.js

@@ -0,0 +1,58 @@
+export function contentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content.map((part) => {
+            if (typeof part === 'string')
+                return part;
+            if (part && typeof part === 'object' && 'text' in part)
+                return String(part.text ?? '');
+            return '';
+        }).filter(Boolean).join(' ');
+    }
+    return '';
+}
+export function lastUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]?.role === 'user')
+            return contentToText(messages[i]?.content);
+    }
+    return '';
+}
+export function estimateTokens(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return 0;
+    return Math.max(1, Math.ceil(trimmed.length / 4));
+}
+export function countPromptTokens(messages) {
+    return messages.reduce((sum, message) => sum + estimateTokens(`${message.role}: ${contentToText(message.content)}`), 0);
+}
+export function stubAssistantText(messages, model) {
+    const text = lastUserText(messages) || 'empty prompt';
+    return `[twin-stub:openrouter:${model}] Echoing the last user message for deterministic simulation: ${text}`;
+}
+export function stableHash(value) {
+    const s = JSON.stringify(value);
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+export function firstToolCall(tools) {
+    if (!Array.isArray(tools) || tools.length === 0)
+        return null;
+    const tool = tools[0];
+    const fn = tool.function && typeof tool.function === 'object' ? tool.function : tool;
+    const name = typeof fn.name === 'string' ? fn.name : 'tool';
+    return {
+        id: `call_twin_${stableHash(name).slice(0, 8)}`,
+        type: 'function',
+        function: {
+            name,
+            arguments: JSON.stringify({ twin: true, input: 'deterministic tool arguments' }),
+        },
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { OpenRouterRequest, OpenRouterResponse } from './openrouter-types.js';
+/** The legacy handler remains JSON-shaped; only the fetch adapter can select a local handoff. */
+export declare function handleOpenRouterTwinRequest(req: OpenRouterRequest): Promise<OpenRouterResponse>;
+export declare function handleOpenRouterTwinRequestWithGeneration(req: OpenRouterRequest, localGeneration?: () => Promise<Response>): Promise<OpenRouterResponse | Response>;