@volter/twin-openrouter 0.1.0

package/src/openrouter-models.ts

@@ -0,0 +1,118 @@
+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 const OPENROUTER_MODELS: OpenRouterModel[] = [
+  {
+    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: string): OpenRouterModel | undefined {
+  return OPENROUTER_MODELS.find((model) => model.id === id);
+}
+
+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 const OPENROUTER_PROVIDERS: OpenRouterProvider[] = [
+  { 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/src/openrouter-scenario.ts

@@ -0,0 +1,156 @@
+// 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, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+import { contentToText, lastUserText, stableHash } from './openrouter-stub.ts';
+import type { ChatMessage } from './openrouter-types.ts';
+
+/** 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';
+};
+
+const RESPOND_KEYS = new Set(['text', 'toolCalls', 'finishReason']);
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls', 'content_filter']);
+const nonEmptyString = (cond: unknown): cond is string => 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: ChatMessage[]): Set<string> {
+  const names = new Set<string>();
+  const last = messages[messages.length - 1] as { role?: string; tool_call_id?: unknown } | undefined;
+  if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string') return names;
+  for (const m of messages) {
+    const am = m as { role?: string; tool_calls?: unknown };
+    if (am.role !== 'assistant' || !Array.isArray(am.tool_calls)) continue;
+    for (const tc of am.tool_calls as Array<{ id?: unknown; function?: { name?: unknown } }>) {
+      if (tc?.id === last.tool_call_id && typeof tc?.function?.name === 'string') names.add(tc.function.name);
+    }
+  }
+  return names;
+}
+
+function toolNames(tools: unknown): string[] {
+  if (!Array.isArray(tools)) return [];
+  return (tools as Array<{ function?: { name?: unknown }; name?: unknown }>)
+    .map((t) => (typeof t?.function?.name === 'string' ? t.function.name : typeof t?.name === 'string' ? t.name : null))
+    .filter((n): n is string => n !== null);
+}
+
+export const openrouterScenarioAdapter: PackScenarioAdapter<OpenRouterScenarioRequest> = {
+  vendor: 'openrouter',
+  features: (req): ScenarioFeatures => ({
+    model: req.model,
+    lastUserText: lastUserText(req.messages).slice(0, 300),
+    tools: toolNames(req.tools),
+    lastMessageIsToolResult: (req.messages[req.messages.length - 1] as { role?: string } | undefined)?.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] as { role?: string } | undefined)?.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'] as const) {
+      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 as Record<string, unknown>;
+    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 as Record<string, unknown>;
+        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: string): ScenarioDocument {
+  let parsed: unknown;
+  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?: ScenarioDocument): OpenRouterScenarioEngine {
+  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: OpenRouterScenarioRespond): ScriptedResult {
+  const toolCalls: Array<Record<string, unknown>> = [];
+  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'),
+  };
+}

package/src/openrouter-server.ts

@@ -0,0 +1,158 @@
+// 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.ts';
+import { worldNow, twinManifest } from '@volter/world-core';
+import { createOpenRouterScenarioEngine, loadOpenRouterScenarioDocument, type OpenRouterScenarioEngine } from './openrouter-scenario.ts';
+import type { SseEvent } from './openrouter-types.ts';
+import { forwardLocalGeneration, localGenerationOrigin, readLocalGenerationBody, type LocalGenerationFetch } from './openrouter-local-generation.ts';
+
+function wantsStream(body: string): boolean {
+  try {
+    return JSON.parse(body || '{}')?.stream === true;
+  } catch {
+    return false;
+  }
+}
+
+function encodeSse(event: SseEvent): string {
+  return event.done ? 'data: [DONE]\n\n' : `data: ${JSON.stringify(event.data)}\n\n`;
+}
+
+/** 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 function createOpenRouterTwinFetch(options: OpenRouterTwinFetchOptions): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_OPENROUTER_SCENARIO;
+  const scenarioEngine: OpenRouterScenarioEngine | undefined = 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: Request): Promise<Response> {
+    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 as never,
+      }));
+    }
+    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: string;
+    let localBytes: Uint8Array<ArrayBuffer> | undefined;
+    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: SseEvent[] = [];
+    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: SseEvent) => 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<Uint8Array>({
+        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: OpenRouterTwinFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {
+  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/src/openrouter-stub.ts

@@ -0,0 +1,60 @@
+import type { ChatMessage } from './openrouter-types.ts';
+
+export function contentToText(content: unknown): string {
+  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 as { text?: unknown }).text ?? '');
+      return '';
+    }).filter(Boolean).join(' ');
+  }
+  return '';
+}
+
+export function lastUserText(messages: ChatMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === 'user') return contentToText(messages[i]?.content);
+  }
+  return '';
+}
+
+export function estimateTokens(input: string): number {
+  const trimmed = input.trim();
+  if (!trimmed) return 0;
+  return Math.max(1, Math.ceil(trimmed.length / 4));
+}
+
+export function countPromptTokens(messages: ChatMessage[]): number {
+  return messages.reduce((sum, message) => sum + estimateTokens(`${message.role}: ${contentToText(message.content)}`), 0);
+}
+
+export function stubAssistantText(messages: ChatMessage[], model: string): string {
+  const text = lastUserText(messages) || 'empty prompt';
+  return `[twin-stub:openrouter:${model}] Echoing the last user message for deterministic simulation: ${text}`;
+}
+
+export function stableHash(value: unknown): string {
+  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: unknown): Record<string, unknown> | null {
+  if (!Array.isArray(tools) || tools.length === 0) return null;
+  const tool = tools[0] as Record<string, any>;
+  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' }),
+    },
+  };
+}