@volter/twin-fireworks 0.1.0

package/src/fireworks-models.ts

@@ -0,0 +1,63 @@
+// Fireworks model catalog — the static slice the twin's INFERENCE plane accepts, on groq's
+// method (groq-models.ts): a static table with provenance comments, merged over any PULLED
+// control-plane model rows (a pulled row of the same id overrides the static one).
+//
+// WHY A CATALOG AT ALL: real Fireworks answers 404 "Model id not found" for an unknown model id
+// (the vendor's own error table: 404 covers "the model doesn't exist, the model is not deployed,
+// or you don't have permission to access it"). A twin that answered 200 for ANY string was a
+// fake success the vendor's own clients would never see.
+//
+// PROVENANCE (what is sourced, and what is not):
+//   • the chat ids are the serverless serving paths Fireworks documents (docs.fireworks.ai
+//     serverless serving paths + fireconnect model tables, read 2026-09-16): short aliases
+//     (`glm-5p2`, `kimi-latest`) and full resource names (`accounts/fireworks/models/…`) are
+//     BOTH documented spellings, so both are accepted.
+//   • the embedding ids are the Qwen3 Embedding table (docs.fireworks.ai "Generating
+//     embeddings": `fireworks/qwen3-embedding-8b` serverless; 4B/0.6B dedicated) — the twin
+//     serves the serverless one.
+//   • the rerank id is the Qwen3 Reranker table (docs.fireworks.ai "Reranking documents":
+//     `fireworks/qwen3-reranker-8b` serverless).
+//   • context windows are NOT sourced per-id here (the stub does not model context limits per
+//     model — the stub context is fixed at 8192 tokens, documented in fireworks-twin.ts); no
+//     capability asserts a per-model window. The catalog's job is the 404 REFUSAL, not metadata.
+// A model absent from this table is deliberately unknown: the honest gap is the catalog's
+// COVERAGE, filed as the fireworks.models.catalog_coverage todo — not a silent 200.
+
+/** One catalog row: the id the inference plane accepts. */
+export type FireworksCatalogModel = {
+  id: string;
+  /** Which inference endpoint families accept it. */
+  kind: 'chat' | 'embeddings' | 'rerank';
+};
+
+export const FIREWORKS_MODELS: FireworksCatalogModel[] = [
+  // Serverless chat — documented serving paths (short aliases + full resource names).
+  { id: 'kimi-latest', kind: 'chat' },
+  { id: 'kimi-fast-latest', kind: 'chat' },
+  { id: 'glm-latest', kind: 'chat' },
+  { id: 'glm-fast-latest', kind: 'chat' },
+  { id: 'glm-5p2', kind: 'chat' },
+  { id: 'glm-5p3-flash', kind: 'chat' },
+  { id: 'kimi-k2-instruct', kind: 'chat' },
+  { id: 'accounts/fireworks/models/kimi-k2-instruct', kind: 'chat' },
+  { id: 'accounts/fireworks/models/kimi-k2-instruct-0905', kind: 'chat' },
+  { id: 'accounts/fireworks/models/llama-v3p1-8b-instruct', kind: 'chat' },
+  // Serverless embeddings + rerank — the Qwen3 tables (the 4B/0.6B tiers are dedicated-only),
+  // plus the legacy Hugging-Face-style embedder the docs name explicitly ("These models are not
+  // in the Model Library … they still work on serverless if you pass the exact Hugging Face
+  // style id"). The earlier `accounts/fireworks/models/nomic-embed-text-v1_5` spelling this
+  // pack first used was never a vendor id — the sourced id is the one below.
+  { id: 'fireworks/qwen3-embedding-8b', kind: 'embeddings' },
+  { id: 'accounts/fireworks/models/qwen3-embedding-8b', kind: 'embeddings' },
+  { id: 'nomic-ai/nomic-embed-text-v1.5', kind: 'embeddings' },
+  { id: 'fireworks/qwen3-reranker-8b', kind: 'rerank' },
+  { id: 'accounts/fireworks/models/qwen3-reranker-8b', kind: 'rerank' },
+];
+
+/** The static ids, for the refusal check. */
+export const FIREWORKS_MODEL_IDS = new Set(FIREWORKS_MODELS.map((m) => m.id));
+
+/** Which endpoint family a static model id belongs to (undefined = not a chat id). */
+export function catalogKind(id: string): FireworksCatalogModel['kind'] | undefined {
+  return FIREWORKS_MODELS.find((m) => m.id === id)?.kind;
+}

package/src/fireworks-scenario.ts

@@ -0,0 +1,191 @@
+// The fireworks pack's scenario system on the kernel's ONE engine (@volter/world-core scenario.ts):
+// Fireworks chat-completions vocabulary + the scripted-turn respond shape. THE KERNEL ENGINE IS NOT
+// RE-IMPLEMENTED HERE — this file is only the pack's adapter (features, matchers, load
+// validation) plus the realizer that turns a validated `respond` into Fireworks' own envelope.
+//
+// The handler FILE (handlers/fireworks.json in a world dir) is the only write surface; the doors
+// (`GET /twin`, `GET /twin/scenario`) are read-only. Scenario support is twin-only scaffolding
+// for eval worlds, NOT vendor surface, so it is deliberately absent from the capability
+// manifest (ADDING_A_TWIN.md §6, "Scenario scripting") and gated by fireworks-scenario.test.ts.
+import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+import { contentToText, lastUserText } from './fireworks-stub.ts';
+import type { FireworksMessageParam } from './fireworks-types.ts';
+
+export type FireworksScenarioRequest = {
+  model: string;
+  messages: FireworksMessageParam[];
+  tools?: unknown;
+  /** Fireworks-specific: 'auto' | 'default' | 'flex' | 'priority' — only 'priority' is honored
+   *  by the vendor; the rest behave as 'default'. Scriptable so a world can pin behavior per tier. */
+  serviceTier?: string;
+};
+export type FireworksScenarioEngine = ScenarioEngine<FireworksScenarioRequest>;
+
+export type ScenarioToolCall = { name: string; arguments: Record<string, unknown>; id?: string };
+
+/**
+ * What a fireworks handler may script. `reasoning` is Fireworks-specific (the separate
+ * `reasoning_content` field its reasoning models answer with). A scripted FAILURE is not
+ * vocabulary of its own — it is the kernel fault grammar (`fault: { kind: 'status', … }`,
+ * R15), rendered into Fireworks' envelope by the adapter's renderFault below.
+ */
+export type FireworksScenarioRespond = {
+  text?: string;
+  reasoning?: string;
+  toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+  finishReason?: 'stop' | 'length' | 'tool_calls';
+};
+
+export type ScriptedResult = {
+  text: string | null;
+  reasoning: string | null;
+  toolCalls: Array<{ id: string; type: 'function'; function: { name: string; arguments: string } }>;
+  finishReason: 'stop' | 'length' | 'tool_calls';
+};
+
+const RESPOND_KEYS = new Set(['text', 'reasoning', 'toolCalls', 'finishReason']);
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls']);
+const SERVICE_TIERS = new Set(['auto', 'default', 'flex', 'priority']);
+const nonEmptyString = (cond: unknown): cond is string => typeof cond === 'string' && cond.length > 0;
+
+function lastToolResultNames(messages: FireworksMessageParam[]): 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?: Array<{ id?: unknown; function?: { name?: unknown } }> };
+    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: 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 fireworksScenarioAdapter: PackScenarioAdapter<FireworksScenarioRequest> = {
+  vendor: 'fireworks',
+  // R15 — a status fault in THIS vendor's envelope: the same `{error:{message, code, type}}`
+  // OpenAI-compat shape fireworks-twin.ts serves for its own refusals. The vendor's error table
+  // (docs.fireworks.ai/api-reference, "Common error codes") keys the type on the status: 429 is
+  // the serverless rate limit / deployment-capacity signal, ≥500 is the vendor's server-side
+  // family. The kernel adds the `retry-after` header when the fault carries retryAfterSeconds —
+  // renderFault must not add it itself.
+  renderFault: (f) => ({
+    body: {
+      error: {
+        message: f.message ?? (f.status === 429
+          ? 'Rate limit exceeded. Please retry your request.'
+          : f.status >= 500
+            ? 'Internal Server Error'
+            : 'The request was refused by a scripted fault.'),
+        code: f.status,
+        type: f.status === 429 ? 'rate_limit_exceeded' : f.status >= 500 ? 'internal_server_error' : 'invalid_request_error',
+      },
+    },
+  }),
+  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)],
+    serviceTier: req.serviceTier ?? 'default',
+  }),
+  matchers: {
+    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),
+    // Fireworks-specific: script behaviour per service tier ('priority' is the only honored one).
+    serviceTierEquals: (req, cond) => nonEmptyString(cond) && (req.serviceTier ?? 'default') === 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';
+    if (on.serviceTierEquals !== undefined) {
+      if (typeof on.serviceTierEquals !== 'string' || !SERVICE_TIERS.has(on.serviceTierEquals)) {
+        return `on.serviceTierEquals is one of ${[...SERVICE_TIERS].join(', ')}`;
+      }
+    }
+    return null;
+  },
+  validateRespond: (respond) => {
+    if (typeof respond !== 'object' || respond === null || Array.isArray(respond)) return 'respond is an object { text?, reasoning?, 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.reasoning !== undefined && typeof r.reasoning !== 'string') return 'respond.reasoning 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;
+  },
+};
+
+/** Load + STRICTLY validate a scenario document. A malformed file throws at load with what is
+ *  wrong — never a silent ignore-and-stub (a mis-typed rule falling back is a fake success). */
+export function loadFireworksScenarioDocument(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. A missing document keeps the historical ENOENT wording,
+    // so the loud load-time failure reads byte-identically to the read it replaces.
+    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(`fireworks scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parseScenarioDocument(parsed, fireworksScenarioAdapter);
+}
+
+export function createFireworksScenarioEngine(document?: ScenarioDocument): FireworksScenarioEngine {
+  return new ScenarioEngine(fireworksScenarioAdapter, document);
+}
+
+/**
+ * Turn a validated `respond` into the pack's own faithful assistant turn.
+ *
+ * The tool-call id is derived from the scripted call's own content and its position in the
+ * handler (never a module-level counter), exactly as the non-scenario path derives its ids — a
+ * serve-path determinism requirement: a served response is a pure function of (request, stored
+ * state), so two identical scripted requests in one process must answer identically.
+ */
+export function realizeFireworksRespond(respond: FireworksScenarioRespond): ScriptedResult {
+  const toolCalls: ScriptedResult['toolCalls'] = [];
+  const scripted = respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : [];
+  scripted.forEach((tc, index) => {
+    const seed = `${index}:${tc.name}:${JSON.stringify(tc.arguments)}`;
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++) { h ^= seed.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+    toolCalls.push({ id: tc.id ?? `call_scripted_${(h >>> 0).toString(36)}`, type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } });
+  });
+  return {
+    text: respond.text ?? (toolCalls.length ? null : ''),
+    reasoning: respond.reasoning ?? null,
+    toolCalls,
+    finishReason: respond.finishReason ?? (toolCalls.length ? 'tool_calls' : 'stop'),
+  };
+}

package/src/fireworks-server.ts

@@ -0,0 +1,153 @@
+// Fireworks twin HTTP server — serve the full Fireworks twin handler over HTTP so the real
+// `fireworks` Python SDK (pointed at `base_url: http://127.0.0.1:<port>/inference/v1`), the
+// `@ai-sdk/fireworks` provider and plain OpenAI clients (pointed at
+// `http://127.0.0.1:<port>/inference/v1`) work UNMODIFIED, and the Gateway control plane answers
+// at `/v1/accounts/{account_id}/…`. JSON bodies pass straight through. Writable by default; pass
+// readOnly to reject mutations (D3).
+//
+// Streaming: when a streamable request body has `"stream": true`, the server constructs a REAL SSE
+// response by feeding the handler an sseSink that writes each chunk in the `data: <json>\n\n` wire
+// format, ending with `data: [DONE]\n\n` on the OpenAI-compat paths (the Anthropic-compat
+// /v1/messages ends with its `message_stop` event — no [DONE] sentinel; that is the vendor's own
+// shape). The handler itself stays socket-free — the sink is the only place a socket is touched,
+// on the live HTTP path.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createFireworksTwinFetch` and the
+// SERVER is one line of `serveHttp` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): SSE streaming on THREE paths (chat/completions, completions,
+// messages) genuinely exceeds the common shape — groq-server.ts is the reference.
+import { serveHttp, twinManifest, worldNow } from '@volter/world-core';
+import { createFireworksScenarioEngine, type FireworksScenarioEngine, loadFireworksScenarioDocument } from './fireworks-scenario.ts';
+import { FIREWORKS_INFERENCE_PREFIX, handleFireworksTwinRequest } from './fireworks-twin.ts';
+import type { SseEvent } from './fireworks-twin.ts';
+
+function wantsStream(body: string): boolean {
+  if (!body) return false;
+  try {
+    return (JSON.parse(body) as { stream?: unknown })?.stream === true;
+  } catch {
+    return false;
+  }
+}
+
+function encodeSse(event: SseEvent): string {
+  if (event.done) return 'data: [DONE]\n\n';
+  return `data: ${JSON.stringify(event.data)}\n\n`;
+}
+
+// The three inference paths Fireworks streams. The Anthropic-compat /v1/messages streams in the
+// SAME SSE transport but with its own event vocabulary — and the handler already ends its sequence
+// with `message_stop`, so the [DONE] sentinel must NOT be appended there (Anthropic streams do not
+// carry one; appending one would be a wire lie the official clients parse as an unknown event).
+const STREAMABLE = new Set([
+  `${FIREWORKS_INFERENCE_PREFIX}/chat/completions`,
+  `${FIREWORKS_INFERENCE_PREFIX}/completions`,
+  `${FIREWORKS_INFERENCE_PREFIX}/messages`,
+]);
+
+/** Options every Fireworks-twin HTTP surface needs, independent of who owns the socket. */
+export interface FireworksTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  scenarioPath?: string;
+}
+
+export function createFireworksTwinFetch(options: FireworksTwinFetchOptions): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  // Scenario scripting (fireworks-scenario.ts): a JSON scenario file — via the scenarioPath option
+  // or the TWIN_FIREWORKS_SCENARIO env var — scripts chat completions. Loaded ONCE at startup (a
+  // malformed file fails loudly here, never silently).
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_FIREWORKS_SCENARIO;
+  const scenarioEngine: FireworksScenarioEngine | undefined = scenarioPath ? createFireworksScenarioEngine(loadFireworksScenarioDocument(scenarioPath)) : undefined;
+  return async function fireworksTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, read-only.
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(twinManifest({
+        vendor: 'fireworks',
+        twinOf: 'Fireworks AI API (inference plane at /inference/v1, Gateway control plane at /v1/accounts/{account_id})',
+        stateSentence: 'Seed control-plane state through the ordinary Gateway API (POST /v1/accounts/{account_id}/deployments?deploymentId=…) with any key.',
+        behaviorSentence: "Chat completions are scripted by MSW-shaped handlers in the world dir (handlers/fireworks.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|lastMessageIsToolResult|serviceTierEquals|nthCall}, respond:{text|reasoning, finishReason?} | fault:{kind:'status'|'slow'|'drop', ...}, once?, phase?}. Unmatched requests answer a labeled stub naming this door.",
+        exampleHandler: { on: { userTextIncludes: 'summarize' }, respond: { text: 'Scripted summary.' }, once: true },
+        engine: scenarioEngine as never,
+      }));
+    }
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin/scenario') {
+      return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'fireworks', handlers: [], misses: 0, recentMisses: [] });
+    }
+
+    const path = url.pathname + (url.search || '');
+    const cleanPath = url.pathname.replace(/\/+$/, '');
+    const passHeaders: Record<string, string> = {};
+    for (const k of ['authorization', 'anthropic-version']) {
+      const v = request.headers.get(k);
+      if (v !== null) passHeaders[k] = v;
+    }
+
+    let body = '';
+    if (request.method !== 'GET') body = await request.text();
+
+    // 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 (validation 422/400, auth 401,
+    // rate-limit 429) 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. Fireworks rejects a bad request BEFORE opening the event
+    // stream; this twin decides every refusal before the first chunk.
+    if (!readOnly && request.method.toUpperCase() === 'POST' && STREAMABLE.has(cleanPath) && wantsStream(body)) {
+      const events: SseEvent[] = [];
+      const { status, body: out, headers: errHeaders } = await handleFireworksTwinRequest({
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+        method: request.method, path, body, readOnly, occurredAt: worldNow(), headers: passHeaders,
+        ...(options.root !== undefined ? { root: options.root } : {}), sseSink: (e: SseEvent) => events.push(e),
+      });
+      if (status >= 400) {
+        return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin', ...(errHeaders ?? {}) } });
+      }
+      // /v1/messages ends with its own message_stop; the OpenAI-compat paths end with [DONE].
+      const anthropicStream = cleanPath === `${FIREWORKS_INFERENCE_PREFIX}/messages`;
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const enc = new TextEncoder();
+          for (const e of events) {
+            if (e.done && anthropicStream) continue; // no [DONE] on the Anthropic surface
+            controller.enqueue(enc.encode(encodeSse(e)));
+          }
+          controller.close();
+        },
+      });
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', 'x-request-id': 'req_twin' } });
+    }
+
+    // Defensive: a handler throw must become a vendor-shaped 500, never an escaped exception
+    // (ADDING_A_TWIN.md §8, "In-process server harnesses … contain handler errors").
+    let status: number;
+    let out: unknown;
+    let outHeaders: Record<string, string> | undefined;
+    try {
+      const res = await handleFireworksTwinRequest({
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+        method: request.method, path, body, readOnly,
+        occurredAt: worldNow(), headers: passHeaders,
+        ...(options.root !== undefined ? { root: options.root } : {}),
+      });
+      status = res.status; out = res.body; outHeaders = res.headers;
+    } catch (err) {
+      return new Response(JSON.stringify({ error: { message: `twin handler error: ${err instanceof Error ? err.message : String(err)}`, code: 500 } }), {
+        status: 500, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin' },
+      });
+    }
+
+    return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'x-request-id': 'req_twin', ...(outHeaders ?? {}) } });
+  };
+}
+
+export async function createFireworksTwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createFireworksTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/src/fireworks-stub.ts

@@ -0,0 +1,83 @@
+// Fireworks stub core — the deterministic-content primitives shared by the inference handlers.
+// Mirrors groq-stub.ts / ai-gateway-stub.ts: NO model runs here, so generated content is a
+// DETERMINISTIC, clearly-labeled function of the prompt — never pretending to be real inference.
+// Everything AROUND the stub (the envelope, the field names, the rejections) is vendor-faithful.
+
+/** A cheap stable hash (FNV-1a, 32-bit) — the same primitive the sibling packs use. */
+export function fnv1a(text: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** Flatten message/prompt content to plain text (strings joined; content blocks' text parts taken). */
+export function contentToText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => (typeof part === 'string' ? part : typeof (part as { text?: unknown })?.text === 'string' ? ((part as { text: string }).text) : ''))
+      .join(' ');
+  }
+  return '';
+}
+
+/** ~1 token per 4 characters — the same rough estimate the sibling packs use. */
+export function estimateTokens(text: string): number {
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+export function countPromptTokens(messages: Array<{ content?: unknown }>): number {
+  return messages.reduce((sum, m) => sum + estimateTokens(contentToText(m.content)), 0);
+}
+
+export function lastUserText(messages: Array<{ role?: string; content?: unknown }>): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === 'user') return contentToText(messages[i].content);
+  }
+  return '';
+}
+
+/** THE LABEL. Every generated completion carries it, so nothing can be mistaken for real output. */
+export function stubAssistantText(model: string, prompt: string): string {
+  const h = fnv1a(`${model}\0${prompt}`);
+  return `[twin-stub:${model}] Deterministic response to: ${prompt.slice(0, 120) || '(empty prompt)'} (hash ${h.toString(16)})`;
+}
+
+/** Deterministic reasoning content, for reasoning_effort on supported models. */
+export function stubReasoningText(model: string, prompt: string): string {
+  const h = fnv1a(`reasoning\0${model}\0${prompt}`);
+  return `[twin-stub:${model}] reasoning trace (hash ${h.toString(16)})`;
+}
+
+/** Deterministic pseudo-embedding: L2-normalized, derived from the input hash. `dimensions` must
+ *  already be a validated positive integer — the twin's handler refuses anything else BEFORE
+ *  calling this (a client-sized allocation from an unvalidated number is a one-request DoS). The
+ *  guard here is the class-level backstop: NO array in this pack is ever sized from a request
+ *  value without a bound. */
+export function pseudoEmbedding(text: string, dimensions: number): number[] {
+  if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 4096) {
+    throw new RangeError(`pseudoEmbedding: dimensions must be an integer in [1, 4096], got ${dimensions}`);
+  }
+  const vec = new Array<number>(dimensions);
+  let h = fnv1a(text);
+  for (let i = 0; i < dimensions; i++) {
+    h = Math.imul(h ^ (i + 1), 0x01000193) >>> 0;
+    vec[i] = (h / 0xffffffff) * 2 - 1;
+  }
+  const norm = Math.hypot(...vec) || 1;
+  return vec.map((v) => v / norm);
+}
+
+/** Deterministic relevance score in [0, 1] for rerank, biased by shared-token overlap so the
+ *  ORDER of results responds to the query (a constant ordering would be a fake). */
+export function stubRelevanceScore(query: string, document: string): number {
+  const q = new Set(query.toLowerCase().split(/\W+/).filter(Boolean));
+  const d = new Set(document.toLowerCase().split(/\W+/).filter(Boolean));
+  let overlap = 0;
+  for (const t of q) if (d.has(t)) overlap++;
+  const base = (fnv1a(`${query}\0${document}`) % 1000) / 10000; // 0..0.1 jitter
+  return Math.min(1, overlap / Math.max(1, q.size) + base);
+}