@volter/twin-fireworks 0.1.0

package/src/fireworks-types.ts

@@ -0,0 +1,165 @@
+// Fireworks wire shapes, typed narrowly — the subsets of the vendor's real response shapes this
+// pack reads and writes, grounded in the first-party OpenAPI specs (see specSource in index.ts).
+// Where Fireworks differs from OpenAI the difference is NAMED here, not papered over.
+
+// ── Inference plane (OpenAI-compatible, at /inference/v1) ────────────────────────────────────
+
+/** One message in a chat request. `reasoning_content` on assistant messages is a Fireworks
+ *  extension (reasoning models return it; `reasoning_history` controls whether it is replayed). */
+export type FireworksMessageParam = {
+  role: string;
+  content?: unknown;
+  name?: string;
+  tool_call_id?: string;
+  tool_calls?: Array<{ id: string; type: 'function'; function: { name: string; arguments: string } }>;
+  reasoning_content?: string | null;
+};
+
+/** The `service_tier` enum is Fireworks' own; only 'priority' is honored — every other value is
+ *  treated as 'default' (documented; NOT an error). */
+export type FireworksServiceTier = 'auto' | 'default' | 'flex' | 'priority';
+/** Fireworks' documented OpenAI difference: the default is `truncate`, not `error`. */
+export type FireworksContextLengthExceededBehavior = 'error' | 'truncate';
+
+export type FireworksChatRequest = {
+  model: string;
+  messages: FireworksMessageParam[];
+  temperature?: number | null;
+  top_p?: number | null;
+  top_k?: number | null;
+  frequency_penalty?: number | null;
+  presence_penalty?: number | null;
+  max_tokens?: number | null;
+  max_completion_tokens?: number | null;
+  n?: number | null;
+  stop?: string | string[] | null;
+  stream?: boolean | null;
+  stream_options?: { include_usage?: boolean; buffer_tokens?: number; buffer_ms?: number; buffer_mode?: string } | null;
+  tools?: Array<Record<string, unknown>>;
+  tool_choice?: unknown;
+  parallel_tool_calls?: boolean | null;
+  response_format?: Record<string, unknown> | null;
+  reasoning_effort?: string | number | boolean | null;
+  reasoning_history?: 'disabled' | 'interleaved' | 'preserved' | null;
+  service_tier?: FireworksServiceTier | null;
+  context_length_exceeded_behavior?: FireworksContextLengthExceededBehavior | null;
+  seed?: number | null;
+  user?: string | null;
+  echo?: boolean | null;
+  logprobs?: boolean | null;
+  top_logprobs?: number | null;
+  logit_bias?: Record<string, number> | null;
+  metadata?: Record<string, unknown> | null;
+};
+
+export type FireworksChatMessage = {
+  role: 'assistant';
+  content: string | null;
+  reasoning_content?: string | null;
+  tool_calls?: Array<{ id: string; type: 'function'; function: { name: string; arguments: string } }>;
+};
+
+/** The response envelope: `usage` is nullable on chat (absent when `echo`/logprobs paths skip it),
+ *  unlike `Completion` below where the spec marks it required. */
+export type FireworksChatCompletion = {
+  id: string;
+  object: 'chat.completion';
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: FireworksChatMessage;
+    finish_reason: string | null;
+    logprobs?: unknown | null;
+    token_ids?: number[] | null;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    total_tokens: number;
+    completion_tokens: number;
+  } | null;
+};
+
+/** Legacy `/v1/completions`: the spec marks `usage` REQUIRED here (chat's is nullable). */
+export type FireworksCompletion = {
+  id: string;
+  object: 'text_completion';
+  created: number;
+  model: string;
+  choices: Array<{ index: number; text: string; finish_reason: string | null; logprobs?: unknown | null }>;
+  usage: { prompt_tokens: number; total_tokens: number; completion_tokens: number };
+};
+
+/** The Responses API (`/v1/responses`): `id` is nullable when `store=false` (the vendor's own
+ *  contract — a non-stored response has no id to retrieve later). */
+export type FireworksResponseObject = {
+  id: string | null;
+  object: 'response';
+  created_at: number;
+  status: 'completed' | 'in_progress' | 'incomplete' | 'failed' | 'cancelled';
+  model: string;
+  output: Array<FireworksResponseOutputItem>;
+  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number } | null;
+  error?: unknown | null;
+  incomplete_details?: unknown | null;
+  instructions?: unknown | null;
+  max_output_tokens?: number | null;
+  metadata?: Record<string, unknown> | null;
+  parallel_tool_calls?: boolean | null;
+  previous_response_id?: string | null;
+  reasoning?: unknown | null;
+  store?: boolean | null;
+  temperature?: number | null;
+  text?: unknown | null;
+  tool_choice?: unknown;
+  tools?: Array<Record<string, unknown>> | null;
+  top_p?: number | null;
+  truncation?: string | null;
+  user?: string | null;
+};
+
+export type FireworksResponseOutputItem =
+  | { type: 'message'; id: string; role: 'assistant'; status: 'in_progress' | 'completed'; content: Array<{ type: string; text?: string }> }
+  | { type: 'function_call'; id: string; call_id: string; name: string; arguments: string; status?: string }
+  | { type: 'function_call_output'; tool_call_id: string; output: unknown };
+
+/** Anthropic-compatible `/v1/messages`: the response `content` is an array of typed blocks, and
+ *  `stop_reason` is Anthropic's enum (never OpenAI's `finish_reason`). */
+export type FireworksAnthropicMessage = {
+  id: string;
+  type: 'message';
+  role: 'assistant';
+  content: Array<FireworksAnthropicContentBlock>;
+  model: string;
+  stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal' | null;
+  stop_sequence: string | null;
+  usage?: { input_tokens: number; output_tokens: number };
+};
+
+export type FireworksAnthropicContentBlock =
+  | { type: 'text'; text: string; citations?: unknown[] | null }
+  | { type: 'thinking'; thinking: string; signature: string }
+  | { type: 'redacted_thinking'; data: string }
+  | { type: 'tool_use'; id: string; name: string; input: unknown };
+
+/** The Anthropic error envelope: `{ type: 'error', error: { type, message }, request_id? }` — a
+ *  DIFFERENT envelope from the OpenAI-compat plane's `{ error: { … } }`. */
+export type FireworksAnthropicErrorType =
+  | 'invalid_request_error' | 'authentication_error' | 'billing_error' | 'permission_error'
+  | 'not_found_error' | 'rate_limit_error' | 'timeout_error' | 'api_error' | 'overloaded_error';
+
+// ── Control plane (Gateway REST API, at /v1/accounts/{account_id}) ───────────────────────────
+
+/** google.rpc-style status, embedded on every resource as `status` and (per the vendor's own
+ *  comment) mimicking google/rpc/status.proto. */
+export type FireworksGatewayStatus = { code: FireworksGatewayCode; message?: string } | null;
+
+/** The gatewayCode enum — the gRPC canonical codes, as strings. */
+export type FireworksGatewayCode =
+  | 'OK' | 'CANCELLED' | 'UNKNOWN' | 'INVALID_ARGUMENT' | 'DEADLINE_EXCEEDED' | 'NOT_FOUND'
+  | 'ALREADY_EXISTS' | 'PERMISSION_DENIED' | 'UNAUTHENTICATED' | 'RESOURCE_EXHAUSTED'
+  | 'FAILED_PRECONDITION' | 'ABORTED' | 'OUT_OF_RANGE' | 'UNIMPLEMENTED' | 'INTERNAL'
+  | 'UNAVAILABLE' | 'DATA_LOSS';
+
+/** The list envelope every Gateway list operation answers. */
+export type FireworksListEnvelope<T> = { items?: never } & { [K in string]: T[] } & { nextPageToken?: string | null; totalSize?: number | null };

package/src/index.ts

@@ -0,0 +1,134 @@
+// @volter/twin-fireworks — the Fireworks twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. Fireworks serves TWO API planes on ONE host (api.fireworks.ai):
+//
+//   • the INFERENCE plane — `https://api.fireworks.ai/inference/v1/…`, OpenAI-compatible
+//     (chat/completions, completions, responses, embeddings, rerank) plus an Anthropic-compatible
+//     POST /v1/messages. Generative output is a labeled deterministic stub; the wire protocol and
+//     Fireworks' documented OpenAI differences are the fidelity surface.
+//   • the CONTROL plane — the Gateway REST API (`https://api.fireworks.ai/v1/accounts/{account_id}/…`):
+//     deployments, datasets, fine-tuning jobs, users/apiKeys, secrets, models, quotas — a stateful
+//     google.rpc-style surface (list envelopes {items, nextPageToken, totalSize}, verb-suffixed
+//     custom methods like `:cancel`, ids passed via query params on writes).
+//
+// THE DETERMINISTIC STUB IS THE ANSWER: the twin runs no model, so inference returns a
+// DETERMINISTIC STUB completion (clearly labeled `[twin-stub:<model>]`), never pretending to be
+// real inference. Everything around it — the wire protocol, the rejections, the state — is faithful.
+// (Conformance + capability tooling live in @volter/world-tooling, a dev dependency — NOT
+// re-exported here, per E2.)
+export { handleFireworksTwinRequest, FIREWORKS_INFERENCE_PREFIX, FIREWORKS_ACCOUNTS_PREFIX } from './fireworks-twin.ts';
+export type { FireworksRequest, FireworksResponseEnvelope } from './fireworks-twin.ts';
+export { createFireworksTwinFetch, createFireworksTwinServer, type FireworksTwinFetchOptions } from './fireworks-server.ts';
+export {
+  fullSyncFireworks,
+  fireworksRequestForAction,
+  liveFireworksExecute,
+  pullFireworksState,
+  pushFireworksAction,
+  pushPendingFireworksActions,
+  syncFireworksFromReal,
+  unpushableReason,
+} from './fireworks-connector.ts';
+export type { FireworksExecute, LiveFireworksOptions } from './fireworks-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveFireworksExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is Fireworks' DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `FireworksBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  FIREWORKS_BUDGET_CEILING,
+  FIREWORKS_BUDGET_MAX_RETRY_AFTER_S,
+  FIREWORKS_BUDGET_WINDOW_MS,
+  FIREWORKS_CALL_WEIGHTS,
+  FIREWORKS_RATE_BUDGET,
+  FireworksBudget,
+  FireworksBudgetError,
+  fireworksBudgetPath,
+  fireworksCallWeight,
+} from './fireworks-budget.ts';
+export type { FireworksBudgetErrorKind, FireworksBudgetOptions, FireworksBudgetReservation, FireworksBudgetSnapshot } from './fireworks-budget.ts';
+
+import type { TwinPack } from '@volter/world-core';
+import { FIREWORKS_RATE_BUDGET as RATE_BUDGET } from './fireworks-budget.ts';
+import { performFireworksAction, syncFireworksFromRemote } from './fireworks-connector.ts';
+
+export const pack: TwinPack = {
+  vendor: 'fireworks',
+  // The SAME object fireworks-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  // PROTOCOL 2 (pack contract Part 3): the pack is a plugin — its wire, its tree, and its half of
+  // the real state system. The control plane is the stateful surface (deployments, datasets,
+  // fine-tuning jobs, users/apiKeys, secrets); inference is generative and stores nothing.
+  protocol: '2',
+  refresh: { every: '15m', onDemand: { atMost: '60s' } },
+  stateSystem: { perform: performFireworksAction, refresh: syncFireworksFromRemote },
+  // The round trip: a chat completion — the one call every Fireworks integration makes first, and
+  // the one whose answer proves the wire is live end to end — then a DEPLOYMENT, because inference
+  // is generative and stores nothing; the control plane is what has state. The deployment carries no
+  // `deploymentId`, so the vendor mints one (the spec makes it optional) and the create repeats
+  // cleanly on a branch that inherited the first.
+  roundTrip: [
+    { method: 'POST', path: '/inference/v1/chat/completions', body: { model: 'accounts/fireworks/models/kimi-k2-instruct', messages: [{ role: 'user', content: 'round trip' }] }, headers: { authorization: 'Bearer round-trip' } },
+    { method: 'POST', path: '/v1/accounts/round-trip/deployments', body: { baseModel: 'accounts/fireworks/models/kimi-k2-instruct', displayName: 'round trip' }, headers: { authorization: 'Bearer round-trip' } },
+  ],
+  parityOrigin: 'http://twin',
+  archetype: 'generative',
+  bin: 'world-fireworks',
+  // The subject types the twin SERVES from its own state — the R2 resource-level claim. Inference
+  // (chat/completions, completions, responses, messages, embeddings, rerank) is generative and
+  // stores nothing; the control plane is what has state.
+  resources: ['deployment', 'dataset', 'batchInferenceJob', 'supervisedFineTuningJob', 'user', 'apiKey', 'secret', 'model'],
+  // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+  resourcesUnreachable: {
+    account: 'the vendor’s own account row (one per credential, not creatable through the API)',
+    quota: 'vendor-assigned limits (read-only in the API; the twin derives them from the account)',
+    serverlessModel: 'the vendor catalog (serverless models are curated by Fireworks, not created by callers)',
+  },
+  specSource:
+    'Fireworks first-party OpenAPI spec (https://docs.fireworks.ai/merged.openapi.yaml, downloaded 2026-09-16): ' +
+    'the merged Gateway REST API 5.10.0 document covering the control plane (api.fireworks.ai/v1/accounts/{account_id}/…) ' +
+    'AND the inference plane namespaces (chat/completions, completions, Responses, Anthropic-compatible messages). ' +
+    'The embeddings and rerank operations are documented on the vendor api-reference pages only ' +
+    '(docs.fireworks.ai/api-reference — post /embeddings, post /rerank), not in the merged spec. ' +
+    'The earlier cited URLs (api.fireworks.ai and app.fireworks.ai api/docs/openapi.json, the per-plane ' +
+    'api-reference *-openapi.* files) are dead (404, checked 2026-09-16). Envelope-faithful; ' +
+    'model output, embedding values and rerank scores are labeled deterministic stubs.',
+  description:
+    'Fireworks AI twin — the OpenAI-compatible inference plane (chat/completions + streaming, completions, ' +
+    'Responses API CRUD, Anthropic-compatible /v1/messages, embeddings, rerank) with Fireworks’ documented ' +
+    'OpenAI differences (usage in the final stream chunk by default, context_length_exceeded_behavior, ' +
+    "service_tier 'priority'-only), plus the stateful Gateway control plane (deployments, datasets, " +
+    'batch-inference and supervised-fine-tuning jobs, users/apiKeys, secrets, models) with google.rpc-style ' +
+    'statuses; generative output is a labeled deterministic stub.',
+  // Fireworks serves BOTH planes on ONE host: the inference plane under /inference/v1/ and the
+  // control plane under /v1/accounts/{account_id}/. `apiPathPrefix` is a single startsWith prefix,
+  // so '/v' is the narrowest value that routes BOTH surfaces to the twin.
+  browserRouting: { apiPathPrefix: '/v', loaderHost: 'https://api.fireworks.ai' },
+  // ADOPTION — how an app repo betrays that it talks to Fireworks, so `volter-world covers`/
+  // `init` can attribute the signal here. Declared ON THE DESCRIPTOR, never in the central
+  // SDK_TWINS / SDK_SCOPE_VENDORS / ENV_STEM_VENDORS / VENDOR_WORLD_IDS maps: declaring a fact in
+  // both homes THROWS (world-runtime/src/pack-facts.ts, `overlay*`). `fireworks-ai` is Fireworks'
+  // official Python client; `@ai-sdk/fireworks` is the Vercel AI SDK provider. `FIREWORKS` covers
+  // FIREWORKS_API_KEY / FIREWORKS_BASE_URL, the names both clients read.
+  adoption: {
+    pypi: ['fireworks-ai'],
+    sdks: ['@ai-sdk/fireworks'],
+    envStems: ['FIREWORKS'],
+  },
+  // INTERCEPTION: the one host both planes are addressed on (the `fireworks` Python client and
+  // @ai-sdk/fireworks both default to api.fireworks.ai; the inference base URL is
+  // https://api.fireworks.ai/inference).
+  hosts: [{ host: 'api.fireworks.ai' }],
+  // No app-read endpoint env, deliberately. The `fireworks` Python client reads FIREWORKS_BASE_URL
+  // — but the app-read table is the FALLBACK for packs the injector cannot intercept, and this pack
+  // declares `hosts`, so FIREWORKS_TWIN_URL + zero-edit interception is the better answer. Emitting
+  // both would quietly forgo interception (`init.test.ts`, "the app-read endpoint table cannot go
+  // stale behind the injector").
+  endpointEnvNone:
+    'The injector intercepts api.fireworks.ai (see `hosts`), so a world wires this pack through FIREWORKS_TWIN_URL rather than an app-read base-URL var. The `fireworks` Python client would honour FIREWORKS_BASE_URL, but @ai-sdk/fireworks — the dominant client in this repo’s demand census — takes its baseURL as a constructor option and reads no such env, so an app-read var would cover only half the traffic while disabling the interception that covers all of it.',
+};
+
+// registered at import: the kernel learns the pack's state system (protocol 2)
+import { registerPack } from '@volter/world-core';
+registerPack(pack);