@volter/twin-fireworks 0.1.0

package/dist/src/fireworks-models.js

@@ -0,0 +1,53 @@
+// 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.
+export const FIREWORKS_MODELS = [
+    // 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) {
+    return FIREWORKS_MODELS.find((m) => m.id === id)?.kind;
+}

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

@@ -0,0 +1,55 @@
+import { type PackScenarioAdapter, type ScenarioDocument, ScenarioEngine } from '@volter/world-core';
+import type { FireworksMessageParam } from './fireworks-types.js';
+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';
+};
+export declare const fireworksScenarioAdapter: PackScenarioAdapter<FireworksScenarioRequest>;
+/** 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 declare function loadFireworksScenarioDocument(path: string): ScenarioDocument;
+export declare function createFireworksScenarioEngine(document?: ScenarioDocument): FireworksScenarioEngine;
+/**
+ * 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 declare function realizeFireworksRespond(respond: FireworksScenarioRespond): ScriptedResult;

package/dist/src/fireworks-scenario.js

@@ -0,0 +1,171 @@
+// 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, ScenarioError, ScenarioEngine } from '@volter/world-core';
+import { contentToText, lastUserText } from "./fireworks-stub.js";
+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) => typeof cond === 'string' && cond.length > 0;
+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 fireworksScenarioAdapter = {
+    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) => ({
+        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)],
+        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]?.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']) {
+            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;
+        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;
+                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) {
+    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. 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) {
+    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) {
+    const 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/dist/src/fireworks-server.d.ts

@@ -0,0 +1,16 @@
+/** Options every Fireworks-twin HTTP surface needs, independent of who owns the socket. */
+export interface FireworksTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}
+export declare function createFireworksTwinFetch(options: FireworksTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createFireworksTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/fireworks-server.js

@@ -0,0 +1,144 @@
+// 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, loadFireworksScenarioDocument } from "./fireworks-scenario.js";
+import { FIREWORKS_INFERENCE_PREFIX, handleFireworksTwinRequest } from "./fireworks-twin.js";
+function wantsStream(body) {
+    if (!body)
+        return false;
+    try {
+        return JSON.parse(body)?.stream === true;
+    }
+    catch {
+        return false;
+    }
+}
+function encodeSse(event) {
+    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`,
+]);
+export function createFireworksTwinFetch(options) {
+    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 = scenarioPath ? createFireworksScenarioEngine(loadFireworksScenarioDocument(scenarioPath)) : undefined;
+    return async function fireworksTwinFetch(request) {
+        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,
+            }));
+        }
+        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 = {};
+        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 = [];
+            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) => 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({
+                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;
+        let out;
+        let outHeaders;
+        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) {
+    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/dist/src/fireworks-stub.d.ts

@@ -0,0 +1,26 @@
+/** A cheap stable hash (FNV-1a, 32-bit) — the same primitive the sibling packs use. */
+export declare function fnv1a(text: string): number;
+/** Flatten message/prompt content to plain text (strings joined; content blocks' text parts taken). */
+export declare function contentToText(content: unknown): string;
+/** ~1 token per 4 characters — the same rough estimate the sibling packs use. */
+export declare function estimateTokens(text: string): number;
+export declare function countPromptTokens(messages: Array<{
+    content?: unknown;
+}>): number;
+export declare function lastUserText(messages: Array<{
+    role?: string;
+    content?: unknown;
+}>): string;
+/** THE LABEL. Every generated completion carries it, so nothing can be mistaken for real output. */
+export declare function stubAssistantText(model: string, prompt: string): string;
+/** Deterministic reasoning content, for reasoning_effort on supported models. */
+export declare function stubReasoningText(model: string, prompt: string): string;
+/** 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 declare function pseudoEmbedding(text: string, dimensions: number): number[];
+/** 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 declare function stubRelevanceScore(query: string, document: string): number;

package/dist/src/fireworks-stub.js

@@ -0,0 +1,78 @@
+// 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) {
+    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) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => (typeof part === 'string' ? part : typeof part?.text === 'string' ? (part.text) : ''))
+            .join(' ');
+    }
+    return '';
+}
+/** ~1 token per 4 characters — the same rough estimate the sibling packs use. */
+export function estimateTokens(text) {
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+export function countPromptTokens(messages) {
+    return messages.reduce((sum, m) => sum + estimateTokens(contentToText(m.content)), 0);
+}
+export function lastUserText(messages) {
+    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, prompt) {
+    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, prompt) {
+    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, dimensions) {
+    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(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, document) {
+    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);
+}

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

@@ -0,0 +1,51 @@
+import type { FireworksScenarioEngine } from './fireworks-scenario.js';
+/** The inference base path. The vendor's inference server root is `https://api.fireworks.ai/inference`
+ *  and every OpenAI-compat operation hangs off `/v1/…` under it. */
+export declare const FIREWORKS_INFERENCE_PREFIX = "/inference/v1";
+/** The control-plane base path: everything Gateway REST hangs off `/v1/accounts/{account_id}/…`. */
+export declare const FIREWORKS_ACCOUNTS_PREFIX = "/v1/accounts";
+export type FireworksRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** The credential the caller presents (the SDKs' bearer `Authorization` header). When a request
+     *  carries an auth SURFACE (this field set, or `headers` present), the twin holds it to the real
+     *  vendor rule: a credential is required → 401 on missing/invalid. In-process trusted calls
+     *  (capability verify, connector) omit BOTH and are not auth-gated. */
+    apiKey?: string;
+    /** Lower-cased request headers the HTTP server passes through so the handler can model auth. */
+    headers?: Record<string, string>;
+    /** When set on a streaming POST, chunks are written here (no sockets). */
+    sseSink?: SseSink;
+    /** Scenario scripting (fireworks-scenario.ts): when set, chat completions consult the engine
+     *  first — a matching handler scripts the answer, a miss answers the labeled stub with a
+     *  pointer to the miss. Twin-only scaffolding, never vendor surface. */
+    scenarioEngine?: FireworksScenarioEngine;
+};
+export type SseEvent = {
+    data?: unknown;
+    done?: boolean;
+};
+export type SseSink = (event: SseEvent) => void;
+/** The handler response. `headers` (when present) are response headers the HTTP server should set. */
+export type FireworksResponseEnvelope = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/**
+ * Rows of `type`, SCOPED TO ONE ACCOUNT. Every control-plane resource is stored with the
+ * `accountId` it was created (or pulled) under, and every read goes through this — a resource
+ * addressed under a different account's path is invisible here, which is what makes the
+ * cross-account GET/PATCH/DELETE answer the vendor's own NOT_FOUND. `accountId === undefined`
+ * means the caller reads a plane with NO account segment (the inference plane's stored
+ * responses) — those rows are not account-scoped and the filter is skipped for them.
+ */
+/** A row is gone when the TWIN deleted it (`_deleted`, the twin's own marker) or when the
+ *  CONNECTOR observed it vanish from the vendor (`deleted`, the kernel's tombstone field).
+ *  Reading only the first served a resource the pull had correctly tombstoned (round-four review). */
+export declare function isTombstoned(r: Record<string, unknown>): boolean;
+export declare function handleFireworksTwinRequest(req: FireworksRequest): Promise<FireworksResponseEnvelope>;