@plurnk/plurnk-providers 1.3.2 → 1.3.4

package/src/OpenAICompat.ts

@@ -29,17 +29,15 @@ import { emitWarningOnce } from "./warnings.ts";
 // (canary-verified; the #32 clamp is lifted — it caused the plan-less service#331).
 export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" | "effort_explicit" | "template" | "anthropic";
 
-// How a caller-supplied GBNF grammar is carried on the wire — backends accept
-// different shapes for the SAME GBNF (probed/configured, never guessed; §13); the
-// wire shape per style lives in #grammarBody. "none" means the grammar is NOT sent
-// (never silently — so a constrained consumer can't mistake unconstrained output
-// for enforced).
-export type GrammarStyle = "none" | "llamacpp" | "response_format";
+// GBNF transport is a local llama-server capability. "none" means no
+// service-managed constrained sampling; endpoint-owned settings are not inferred.
+export type GrammarStyle = "none" | "llamacpp";
 
 export type OpenAICompatConfig = {
     model: string;
     url: string;                              // fully-resolved chat-completions URL
     fetchTimeoutMs: number;
+    streamIdleTimeoutMs?: number;             // streamed body inter-chunk deadline; zero/unset disables
     headers?: Record<string, string>;         // fully-resolved request headers (incl. auth); default {}
     fetch?: ProviderFetch;                    // per-instance request executor; default globalThis.fetch
     contextWindow?: number | null;              // default null; caller resolves-or-fails (#419), narrows to required with the interface
@@ -54,6 +52,9 @@ export type OpenAICompatConfig = {
     // false -- a backend that strict-validates unknown fields 400s, so enable only
     // where the field is accepted. Same identity that already drives slot affinity.
     promptCacheKey?: boolean;
+    // Optional provider-configured service tier. Unlike caller sampling, this is
+    // a fixed deployment choice and therefore wins on every request.
+    serviceTier?: string;
     gbnfDebug?: boolean;                        // PLURNK_PROVIDERS_GBNF_DEBUG: validate the grammar locally + throw on invalid, but DON'T transport it (run unconstrained); default false
     streaming?: boolean;                        // SSE transport (default true); false → one non-streamed JSON
     firstPartyMetadata?: boolean;              // forward per-turn attributions + client as Plurnk-* headers (plurnk only); default false
@@ -238,6 +239,7 @@ export default class OpenAICompatProvider implements Provider {
     #model: string;
     #url: string;
     #fetchTimeoutMs: number;
+    #streamIdleTimeoutMs: number | undefined;
     #headers: Record<string, string>;
     #fetch: ProviderFetch;
     #hasApiKey = false;
@@ -259,6 +261,7 @@ export default class OpenAICompatProvider implements Provider {
     #source: string;
     #grammarStyle: GrammarStyle;
     #promptCacheKey: boolean;
+    #serviceTier: string | undefined;
     #gbnfDebug: boolean;
     #streaming: boolean;
     #firstPartyMetadata: boolean;
@@ -284,6 +287,7 @@ export default class OpenAICompatProvider implements Provider {
         this.#model = config.model;
         this.#url = config.url;
         this.#fetchTimeoutMs = config.fetchTimeoutMs;
+        this.#streamIdleTimeoutMs = config.streamIdleTimeoutMs;
         this.#headers = config.headers ?? {};
         this.#fetch = config.fetch ?? ((input, init) => globalThis.fetch(input, init));
         this.#contextWindow = config.contextWindow ?? null;
@@ -309,6 +313,7 @@ export default class OpenAICompatProvider implements Provider {
         this.#source = config.source ?? "provider";
         this.#grammarStyle = config.grammarStyle ?? "none";
         this.#promptCacheKey = config.promptCacheKey ?? false;
+        this.#serviceTier = config.serviceTier;
         this.#gbnfDebug = config.gbnfDebug ?? false;
         this.#streaming = config.streaming ?? true;
         this.#firstPartyMetadata = config.firstPartyMetadata ?? false;
@@ -444,31 +449,25 @@ export default class OpenAICompatProvider implements Provider {
         return { id_slot: slot };
     }
 
-    // Grammar transport (SPEC §13): carry the caller-supplied GBNF in the shape
-    // the backend accepts. Same grammar, different wire field per backend; an
-    // unsupported/unknown backend sends NO field at all (cloud APIs 400 on
-    // unknowns, and a silent send would let a constrained consumer mistake
-    // unconstrained output for enforced).
+    // Optional local llama-server GBNF transport (SPEC §13). Unsupported
+    // backends receive no grammar-related field.
     #grammarBody(grammar: string | undefined): Record<string, unknown> {
         if (grammar === undefined) return {};
         switch (this.#grammarStyle) {
             // Greedy decoding under hard constraint loops without a repeat-penalty
-            // floor (#9, SPEC §13) — every grammar path carries it. llama.cpp spells
-            // it `repeat_penalty`; the OpenAI-compat (Fireworks) shape is `repetition_penalty`
-            // (verified honored live, #20).
+            // floor (#9, SPEC §13) — llama.cpp spells it `repeat_penalty`.
             case "llamacpp": return { grammar, repeat_penalty: this.#repeatPenalty };
-            case "response_format": return { response_format: { type: "grammar", grammar }, repetition_penalty: this.#repeatPenalty };
             case "none": return {};
         }
     }
 
     // Anti-degeneration DEFAULT on EVERY request (#426), keyed to the backend's wire
-    // convention - NOT grammar-bound. GBNF is a local rail (off for cloud), so a cloud
+    // convention - NOT grammar-bound. GBNF is a local constraint, so a cloud
     // alias runs the sampler bare: firefast (deepseek/fireworks) ran 4/86 bench turns
     // straight to the token cap on pure looped repetition (run52). Ships next to
     // temperature so caller `sampling` can tune it; the grammar path re-asserts it as a
-    // managed FLOOR in #grammarBody. Per backend: llama.cpp/response_format take the
-    // repeat_penalty MULTIPLIER; the plain cloud path ("none") can't, so it gets
+    // managed FLOOR in #grammarBody. llama.cpp takes the repeat_penalty
+    // MULTIPLIER; the plain cloud path ("none") can't, so it gets
     // frequency_penalty - OpenAI-standard, accepted by every OpenAI-compat backend (verified
     // live: together/deepinfra/fireworks; it is OpenAI's own param, so real OpenAI takes it too).
     #repetitionPenaltyBody(): Record<string, unknown> {
@@ -485,7 +484,6 @@ export default class OpenAICompatProvider implements Provider {
                     ...(this.#dryAllowedLength !== undefined ? { dry_allowed_length: this.#dryAllowedLength } : {}),
                 } : {}),
             };
-            case "response_format": return { repetition_penalty: this.#repeatPenalty };
             case "none": return this.#frequencyPenalty > 0 ? { frequency_penalty: this.#frequencyPenalty } : {};
         }
     }
@@ -620,6 +618,7 @@ export default class OpenAICompatProvider implements Provider {
             // the router's per-model tuning must not be overridden by client floors.
             ...(this.#tuningFloors ? { temperature: this.#temperature, ...this.#repetitionPenaltyBody() } : {}),
             ...this.#samplingBody(sampling),
+            ...(this.#serviceTier !== undefined ? { service_tier: this.#serviceTier } : {}),
             model: this.#model,
             messages,
             ...this.#reasoningBody(),
@@ -640,23 +639,27 @@ export default class OpenAICompatProvider implements Provider {
         // signal spans them all. Retry only the transient classifications, prefer
         // a server Retry-After over the backoff, and let the caller's abort cut
         // through both the in-flight request and the backoff sleep.
-        // Stream by default, but fall back to one non-streamed JSON for the one
-        // case it breaks: a response_format grammar (fireworks) streams its
-        // constrained output mislabeled as reasoning_content, yet returns it as
-        // content non-streamed. The atomic dump is correct either way, so the
-        // demotion is scoped to exactly that request, not the whole provider.
-        const grammarBreaksStream = sendGrammar !== undefined && this.#grammarStyle === "response_format";
-        const transport = this.#streaming && !grammarBreaksStream ? chatCompletionStream : chatCompletion;
+        const transport = this.#streaming ? chatCompletionStream : chatCompletion;
 
         // Per-request headers = static auth/routing + any first-party telemetry.
         const metaHeaders = this.#metadataHeaders(attributions, client, strikes, workerId, primaryWorkerId, workspaceId, loop, turn);
         const headers = Object.keys(metaHeaders).length > 0 ? { ...this.#headers, ...metaHeaders } : this.#headers;
+        const transportRetries: Array<{ attempt: number; kind: string; elapsedMs: number; message: string }> = [];
         let raw;
         for (let attempt = 0; ; attempt++) {
+            const attemptStarted = performance.now();
             const timeoutSignal = AbortSignal.timeout(this.#fetchTimeoutMs);
             const effectiveSignal = signal !== undefined ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
             try {
-                raw = await transport({ url: this.#url, headers, body, signal: effectiveSignal, fetch: this.#fetch, captureRawBody: this.#rawBody });
+                raw = await transport({
+                    url: this.#url,
+                    headers,
+                    body,
+                    signal: effectiveSignal,
+                    fetch: this.#fetch,
+                    captureRawBody: this.#rawBody,
+                    streamIdleTimeoutMs: this.#streamIdleTimeoutMs,
+                });
                 break;
             } catch (err) {
                 // Caller-initiated abort is cancellation — never retried or wrapped.
@@ -677,6 +680,12 @@ export default class OpenAICompatProvider implements Provider {
                     }
                     throw pe;
                 }
+                transportRetries.push({
+                    attempt: attempt + 1,
+                    kind,
+                    elapsedMs: Math.round(performance.now() - attemptStarted),
+                    message: err instanceof Error ? err.message : String(err),
+                });
                 const retryAfter = err instanceof OpenAiHttpError ? err.retryAfter : null;
                 await sleepWithAbort(retryAfter ?? this.#retryDelayMs * 2 ** attempt, signal);
             }
@@ -728,7 +737,10 @@ export default class OpenAICompatProvider implements Provider {
         }
 
         const builtMeta = this.#buildMeta(raw.chunkMetadata);
-        const meta = railsMeta !== undefined ? { ...builtMeta, ...railsMeta } : builtMeta;
+        const retryMeta = transportRetries.length > 0 ? { transportRetries } : undefined;
+        const meta = railsMeta !== undefined || retryMeta !== undefined
+            ? { ...builtMeta, ...railsMeta, ...retryMeta }
+            : builtMeta;
 
         // #36: surface per-token logprobs + their mean when the backend returned
         // them (only possible when the flag requested them). Absent otherwise —

package/src/ProviderRegistry.test.ts

@@ -14,6 +14,7 @@ const mapOf = (entries: Record<string, string>, skipped: Record<string, string>
 
 const fullEnv = Object.freeze({
     PLURNK_PROVIDERS_FETCH_TIMEOUT: "600000",
+    PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT: "0",
     PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_RETRY_DELAY: "1", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
     OPENAI_BASE_URL: "http://x",
 });
@@ -162,6 +163,34 @@ test("instantiateProvider: per-alias knobs scope through to the provider (per-al
     mock.restoreAll();
 });
 
+test("#622: two Fireworks aliases independently select default and priority service tiers", async () => {
+    const bodies: Record<string, unknown>[] = [];
+    mock.method(globalThis, "fetch", async (_url: string, init?: RequestInit) => {
+        bodies.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
+        return new Response(JSON.stringify({ choices: [{ message: { content: "ok" }, finish_reason: "stop" }] }), { status: 200, headers: { "Content-Type": "application/json" } });
+    });
+    const env = {
+        ...fullEnv,
+        FIREWORKS_BASE_URL: "https://api.fireworks.ai/inference/v1",
+        FIREWORKS_API_KEY: "fw",
+        PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192",
+        PLURNK_PROVIDERS_SERVICE_TIER_fast: "priority",
+        PLURNK_PROVIDERS_SERVICE_TIER_standard: "default",
+    };
+    const imports = async () => ({});
+    const discover = async () => ({ registry: new Map(), skipped: new Map(), attributions: new Map() });
+    const fast = await instantiateProvider("fireworks", env, "accounts/fireworks/routers/glm-5p2-fast", imports, discover, undefined, "fast");
+    const standard = await instantiateProvider("fireworks", env, "deepseek-v4-pro", imports, discover, undefined, "standard");
+    await fast.generate({ workerId: "fast-worker", messages: [] });
+    await standard.generate({ workerId: "standard-worker", messages: [] });
+    assert.deepEqual(bodies.map((body) => body.service_tier), ["priority", "default"]);
+    assert.deepEqual(bodies.map((body) => body.model), [
+        "accounts/fireworks/routers/glm-5p2-fast",
+        "accounts/fireworks/models/deepseek-v4-pro",
+    ]);
+    mock.restoreAll();
+});
+
 test("loadActiveProvider: resolves the alias cascade end-to-end via the scan", async () => {
     resetDiscoveryCache();
     const env = { ...fullEnv, PLURNK_MODEL: "opus", PLURNK_MODEL_opus: "openrouter/anthropic/claude-opus-latest" } as NodeJS.ProcessEnv;

package/src/env.test.ts

@@ -166,6 +166,14 @@ test("#399: the shipped floor activates reasoning by default (adaptive — owner
     assert.ok(!defaults.match(/^PLURNK_PROVIDERS_REASONING_BUDGET=/m), "no shipped magnitude — budget is on-mode only");
 });
 
+test("#567: the shipped DRY floor stays off while retaining the measured alias-safe shape", async () => {
+    const { readFileSync } = await import("node:fs");
+    const defaults = readFileSync(new URL("../.env.defaults", import.meta.url), "utf8");
+    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_MULTIPLIER=0$/m, "one-model tuning is not a universal sampler floor");
+    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_BASE=1\.75$/m);
+    assert.match(defaults, /^PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=32$/m, "the measured identifier-safe shape remains available for alias opt-in");
+});
+
 // -- #507: envelope reserves (owner-ruled migration from PLURNK_SERVICE_*) --
 
 test("#507 envelopeFromEnv: percentages and absolutes parse; missing/invalid fail hard", async () => {

package/src/env.ts

@@ -163,10 +163,12 @@ export const PROVIDERS_KNOBS = Object.freeze([
     "PLURNK_PROVIDERS_CONTEXT_WINDOW",
     "PLURNK_PROVIDERS_RETRY_ATTEMPTS",
     "PLURNK_PROVIDERS_FETCH_TIMEOUT",
+    "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT",
     "PLURNK_PROVIDERS_LLAMA_SERVER",
     "PLURNK_PROVIDERS_TEMPERATURE",
     "PLURNK_PROVIDERS_REPEAT_PENALTY",
     "PLURNK_PROVIDERS_FREQUENCY_PENALTY",
+    "PLURNK_PROVIDERS_SERVICE_TIER",
     "PLURNK_PROVIDERS_REPEAT_LAST_N",
     "PLURNK_PROVIDERS_DRY_MULTIPLIER",
     "PLURNK_PROVIDERS_DRY_BASE",

package/src/index.ts

@@ -36,7 +36,7 @@ export type { OpenAICompatConfig, ReasoningStyle, GrammarStyle } from "./OpenAIC
 // worker-sticky for KV-cache reuse, overflow to a healthy sibling; the blend
 // DECISION stays the consumer's, by choosing which pool to call.
 export { default as Pool } from "./Pool.ts";
-export { chatCompletionStream, chatCompletion, OpenAiHttpError } from "./openaiStream.ts";
+export { chatCompletionStream, chatCompletion, OpenAiHttpError, StreamIdleError } from "./openaiStream.ts";
 export type { StreamResponse, EncryptedReasoningItem, ProviderFetch } from "./openaiStream.ts";
 export { parseRequiredInt, parseOptionalInt, parseRequiredFloat, parseOptionalFloat, requireEnv, reasoningFromEnv, scopeEnvToAlias, dataCaptureFromEnv, contextWindowFromEnv, envelopeFromEnv, resolveReserve } from "./env.ts";
 export type { Reasoning, ReasoningMode, ReserveSpec } from "./env.ts";

package/src/openai.ts

@@ -1,6 +1,6 @@
 export { default as OpenAICompatProvider, effortFromBudget } from "./OpenAICompat.ts";
 export type { GrammarStyle, OpenAICompatConfig, ReasoningStyle } from "./OpenAICompat.ts";
-export { chatCompletion, chatCompletionStream, OpenAiHttpError } from "./openaiStream.ts";
+export { chatCompletion, chatCompletionStream, OpenAiHttpError, StreamIdleError } from "./openaiStream.ts";
 export type {
     EncryptedReasoningItem,
     ProviderFetch,

package/src/openaiStream.ts

@@ -13,6 +13,9 @@ type StreamRequest = {
     // #36: assemble the verbatim wire body onto StreamResponse.rawBody. Off by
     // default so a serving turn never pays the reassembly/retention cost.
     captureRawBody?: boolean;
+    // Maximum silence between streamed response-body chunks. Undefined/zero
+    // disables this clock; the caller's signal still owns the total deadline.
+    streamIdleTimeoutMs?: number;
 };
 
 import type { RawUsage } from "./usage.ts";
@@ -122,6 +125,15 @@ export class OpenAiHttpError extends Error {
     }
 }
 
+export class StreamIdleError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number) {
+        super(`stream received no body bytes for ${timeoutMs}ms`);
+        this.name = "StreamIdleError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+
 const parseRetryAfter = (header: string | null): number | null => {
     if (header === null) return null;
     const asInt = Number.parseInt(header, 10);
@@ -170,7 +182,7 @@ export const chatCompletion = async ({ url, headers, body, signal, fetch, captur
     };
 };
 
-export const chatCompletionStream = async ({ url, headers, body, signal, fetch, captureRawBody }: StreamRequest): Promise<StreamResponse> => {
+export const chatCompletionStream = async ({ url, headers, body, signal, fetch, captureRawBody, streamIdleTimeoutMs }: StreamRequest): Promise<StreamResponse> => {
     const requestBody = { ...body, stream: true, stream_options: { include_usage: true } };
 
     const response = await fetch(url, {
@@ -206,7 +218,23 @@ export const chatCompletionStream = async ({ url, headers, body, signal, fetch,
     let encryptedNoKey = 0;
 
     while (true) {
-        const { done, value } = await reader.read();
+        const read = reader.read();
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const idle = streamIdleTimeoutMs !== undefined && streamIdleTimeoutMs > 0
+            ? new Promise<never>((_resolve, reject) => {
+                timer = setTimeout(() => reject(new StreamIdleError(streamIdleTimeoutMs)), streamIdleTimeoutMs);
+            })
+            : null;
+        let result: Awaited<ReturnType<typeof reader.read>>;
+        try {
+            result = idle === null ? await read : await Promise.race([read, idle]);
+        } catch (err) {
+            if (err instanceof StreamIdleError) void reader.cancel(err).catch(() => undefined);
+            throw err;
+        } finally {
+            if (timer !== undefined) clearTimeout(timer);
+        }
+        const { done, value } = result;
         if (done) break;
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");

package/src/standardProviders.test.ts

@@ -6,7 +6,7 @@ import { STANDARD_PROVIDERS, isStandardProvider, standardProviderFromEnv } from
 // defaults for the providers exercised outside the coverage loop. `openai` is
 // deliberately omitted so its missing-base fail-hard test still fires.
 const baseEnv = Object.freeze({
-    PLURNK_PROVIDERS_FETCH_TIMEOUT: "600000", PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_RETRY_DELAY: "1", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
+    PLURNK_PROVIDERS_FETCH_TIMEOUT: "600000", PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT: "0", PLURNK_PROVIDERS_REASONING: "off", PLURNK_PROVIDERS_TEMPERATURE: "0.2", PLURNK_PROVIDERS_REPEAT_PENALTY: "1.15", PLURNK_PROVIDERS_FREQUENCY_PENALTY: "0.4", PLURNK_PROVIDERS_REASONING_RESERVE: "10%", PLURNK_PROVIDERS_COMPLETION_RESERVE: "25%", PLURNK_PROVIDERS_RETRY_DELAY: "1", PLURNK_PROVIDERS_PROBE_ATTEMPTS: "3", PLURNK_PROVIDERS_PROBE_DELAY: "1", PLURNK_PROVIDERS_RETRY_ATTEMPTS: "0",
     GROQ_BASE_URL: "https://api.groq.com/openai/v1",
     DEEPINFRA_BASE_URL: "https://api.deepinfra.com/v1/openai",
     FIREWORKS_BASE_URL: "https://api.fireworks.ai/inference/v1",
@@ -298,10 +298,10 @@ test("openai: a garbage PLURNK_PROVIDERS_LLAMA_SERVER value fails hard", async (
     );
 });
 
-test("constrainsOutput: fireworks (static response_format) reports true; groq reports false", async () => {
+test("constrainsOutput: cloud providers do not claim local GBNF transport", async () => {
     mockEndpoint();
     const fw = await standardProviderFromEnv("fireworks", { ...baseEnv, FIREWORKS_API_KEY: "k", PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192" }, "m");
-    assert.equal(fw!.constrainsOutput, true);
+    assert.equal(fw!.constrainsOutput, false);
     const gq = await standardProviderFromEnv("groq", { ...baseEnv, GROQ_API_KEY: "k", PLURNK_PROVIDERS_CONTEXT_WINDOW: "8192" }, "m");
     assert.equal(gq!.constrainsOutput, false);
 });
@@ -868,9 +868,7 @@ test("plurnk: reads its window from upstream but stays a plain OpenAI client —
     mock.restoreAll();
 });
 
-// — fireworks carries GBNF via response_format.grammar (cloud GBNF, #grammarStyle) —
-
-test("fireworks: a grammar transports as response_format.grammar (not the llama.cpp top-level field)", async () => {
+test("fireworks: caller GBNF is not transported to the cloud API", async () => {
     let body = "";
     mock.method(globalThis, "fetch", async (url: string, init?: RequestInit) => {
         if (String(url).endsWith("/chat/completions")) { body = String(init?.body); return new Response(JSON.stringify({ choices: [{ message: { content: "ok" }, finish_reason: "stop" }] }), { status: 200, headers: { "Content-Type": "application/json" } }); }
@@ -879,31 +877,57 @@ test("fireworks: a grammar transports as response_format.grammar (not the llama.
     const p = await standardProviderFromEnv("fireworks", { ...baseEnv, FIREWORKS_API_KEY: "fw" }, "accounts/fireworks/models/deepseek-v4-pro");
     await p!.generate({ workerId: "r", messages: [], grammar: 'root ::= "ok"' });
     const b = JSON.parse(body);
-    assert.deepEqual(b.response_format, { type: "grammar", grammar: 'root ::= "ok"' });
+    assert.equal("response_format" in b, false);
     assert.equal("grammar" in b, false);
     mock.restoreAll();
 });
 
 // — fireworks modelPrefix: the alias carries only the distinctive tail —
 
-const fireworksWireModel = async (alias: string): Promise<string> => {
+const fireworksWireBody = async (model: string, env: NodeJS.ProcessEnv = {}): Promise<Record<string, unknown>> => {
     let body = "";
     mock.method(globalThis, "fetch", async (url: string, init?: RequestInit) => {
         if (String(url).endsWith("/chat/completions")) { body = String(init?.body); return new Response(JSON.stringify({ choices: [{ message: { content: "ok" }, finish_reason: "stop" }] }), { status: 200, headers: { "Content-Type": "application/json" } }); }
         return new Response("{}", { status: 200 });
     });
-    const p = await standardProviderFromEnv("fireworks", { ...baseEnv, FIREWORKS_API_KEY: "fw" }, alias);
+    const p = await standardProviderFromEnv("fireworks", { ...baseEnv, FIREWORKS_API_KEY: "fw", ...env }, model);
     await p!.generate({ workerId: "r", messages: [] });
     mock.restoreAll();
-    return JSON.parse(body).model;
+    return JSON.parse(body) as Record<string, unknown>;
 };
 
 test("fireworks: a bare alias is prefixed with accounts/fireworks/models/ on the wire", async () => {
-    assert.equal(await fireworksWireModel("deepseek-v4-pro"), "accounts/fireworks/models/deepseek-v4-pro");
+    assert.equal((await fireworksWireBody("deepseek-v4-pro")).model, "accounts/fireworks/models/deepseek-v4-pro");
+});
+
+test("fireworks: fully qualified model and router ids are preserved verbatim", async () => {
+    assert.equal((await fireworksWireBody("accounts/fireworks/models/deepseek-v4-pro")).model, "accounts/fireworks/models/deepseek-v4-pro");
+    assert.equal((await fireworksWireBody("accounts/fireworks/routers/glm-5p2-fast")).model, "accounts/fireworks/routers/glm-5p2-fast");
+});
+
+test("fireworks: configured service tier is fixed on the wire and invalid values fail hard", async () => {
+    const body = await fireworksWireBody("deepseek-v4-pro", { PLURNK_PROVIDERS_SERVICE_TIER: "priority" });
+    assert.equal(body.service_tier, "priority");
+    assert.equal((await fireworksWireBody("deepseek-v4-pro", { PLURNK_PROVIDERS_SERVICE_TIER: "flex" })).service_tier, "flex");
+    await assert.rejects(
+        standardProviderFromEnv("fireworks", { ...baseEnv, FIREWORKS_API_KEY: "fw", PLURNK_PROVIDERS_SERVICE_TIER: "urgent" }, "deepseek-v4-pro"),
+        /PLURNK_PROVIDERS_SERVICE_TIER must be one of "auto", "default", "flex", "priority"/,
+    );
 });
 
-test("fireworks: an already-prefixed id is left unchanged (idempotent prepend)", async () => {
-    assert.equal(await fireworksWireModel("accounts/fireworks/models/deepseek-v4-pro"), "accounts/fireworks/models/deepseek-v4-pro");
+test("fireworks: configured tier wins over per-call sampling; unset retains per-call intent", async () => {
+    let bodies: Record<string, unknown>[] = [];
+    mock.method(globalThis, "fetch", async (_url: string, init?: RequestInit) => {
+        bodies.push(JSON.parse(String(init?.body)) as Record<string, unknown>);
+        return new Response(JSON.stringify({ choices: [{ message: { content: "ok" }, finish_reason: "stop" }] }), { status: 200, headers: { "Content-Type": "application/json" } });
+    });
+    const fixed = await standardProviderFromEnv("fireworks", { ...baseEnv, FIREWORKS_API_KEY: "fw", PLURNK_PROVIDERS_SERVICE_TIER: "priority" }, "deepseek-v4-pro");
+    await fixed!.generate({ workerId: "r", messages: [], sampling: { service_tier: "default" } });
+    const flexible = await standardProviderFromEnv("fireworks", { ...baseEnv, FIREWORKS_API_KEY: "fw" }, "deepseek-v4-pro");
+    await flexible!.generate({ workerId: "r", messages: [], sampling: { service_tier: "priority" } });
+    assert.deepEqual(bodies.map((body) => body.service_tier), ["priority", "priority"]);
+    bodies = [];
+    mock.restoreAll();
 });
 
 test("#518 prompt_cache_key: default-ON for a standard provider (workerId), OFF for anthropic (cache_control)", async () => {

package/src/standardProviders.ts

@@ -59,21 +59,19 @@ type StandardProviderSpec = {
     // not already include it.
     flexBaseStrip?: boolean;
     reasoningStyle: ReasoningStyle;
-    // How this backend carries a GBNF grammar (default "none" — not sent). A
-    // probeNctx entry is upgraded to "llamacpp" when the probe sees a
-    // llama-server; cloud backends that support GBNF set their shape statically
-    // (fireworks → "response_format", verified live).
-    grammarStyle?: GrammarStyle;
-    // SSE streaming (default true). The streaming transport is dropped
-    // per-request only when it would break a feature (a response_format grammar
-    // arrives mislabeled as reasoning_content under fireworks' stream); leave
-    // unset to keep streaming on for every other call. See OpenAICompat.generate.
+    // SSE streaming (default true).
     streaming?: boolean;
     // Constant model-id prefix the backend requires but the alias shouldn't
     // repeat (fireworks → "accounts/fireworks/models/", so the alias is just
     // `fireworks/deepseek-v4-pro`). Prepended idempotently to form the wire id,
     // which is ALSO the catalog key (models.dev keys fireworks-ai on the full id).
     modelPrefix?: string;
+    // A fully qualified model namespace that bypasses modelPrefix. Fireworks
+    // uses sibling models/, routers/, and deployments/ resource collections.
+    qualifiedModelPrefix?: string;
+    // Fixed request tiers supported by this provider. An unset knob means the
+    // provider default; configured values are validated and sent every call.
+    serviceTiers?: readonly string[];
     // First-party telemetry forwarding. ONLY the plurnk hosted endpoint sets
     // this — it forwards the consumer's per-turn `attributions` (contributor
     // credit) and `client` (originating frontend) as `Plurnk-Attribution` /
@@ -155,7 +153,11 @@ export const STANDARD_PROVIDERS: Readonly<Record<string, StandardProviderSpec>>
     fireworks: {
         apiKeyVar: "FIREWORKS_API_KEY", apiKeyRequired: true,
         baseUrlVar: "FIREWORKS_BASE_URL", chatPath: "/chat/completions",
-        reasoningStyle: "effort_explicit", grammarStyle: "response_format", modelPrefix: "accounts/fireworks/models/", tokenizerEnvVar: "FIREWORKS_TOKENIZER",
+        reasoningStyle: "effort_explicit",
+        modelPrefix: "accounts/fireworks/models/",
+        qualifiedModelPrefix: "accounts/fireworks/",
+        serviceTiers: ["auto", "default", "flex", "priority"],
+        tokenizerEnvVar: "FIREWORKS_TOKENIZER",
     },
     deepinfra: {
         apiKeyVar: ["DEEPINFRA_API_KEY", "DEEPINFRA_API_TOKEN", "DEEPINFRA_TOKEN"], apiKeyRequired: true,
@@ -289,7 +291,7 @@ export const STANDARD_PROVIDERS: Readonly<Record<string, StandardProviderSpec>>
         apiKeyVar: "PLURNK_API_KEY", apiKeyRequired: true,
         apiKeyMessage: "PLURNK_API_KEY not found. Acquire one at https://plurnk.ai . Plurnk also supports local models and alternative cloud provider configurations.",
         apiKeyRejectedMessage: "PLURNK_API_KEY was rejected by plurnk.ai (invalid or expired). Verify it at https://plurnk.ai .",
-        reasoningStyle: "none", grammarStyle: "none", tokenizerEnvVar: "PLURNK_TOKENIZER",
+        reasoningStyle: "none", tokenizerEnvVar: "PLURNK_TOKENIZER",
         probeNctx: true, detectLlamaServer: false, firstPartyMetadata: true, balanceMetaKey: "balance_pico", suppressTuningFloors: true,
     },
 });
@@ -417,7 +419,8 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
     // The on-the-wire model id: a backend-required constant prefix (fireworks)
     // prepended idempotently, so the operator's alias carries only the distinctive
     // tail. This id is what the backend, the probe, AND the catalog key on.
-    const wireModel = spec.modelPrefix !== undefined && !model.startsWith(spec.modelPrefix)
+    const qualified = spec.qualifiedModelPrefix !== undefined && model.startsWith(spec.qualifiedModelPrefix);
+    const wireModel = spec.modelPrefix !== undefined && !qualified && !model.startsWith(spec.modelPrefix)
         ? `${spec.modelPrefix}${model}`
         : model;
 
@@ -444,17 +447,29 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
     );
     const url = resolveUrl(spec, env, name, baseUrlOverride);
     const fetchTimeoutMs = parseRequiredInt(env.PLURNK_PROVIDERS_FETCH_TIMEOUT, "PLURNK_PROVIDERS_FETCH_TIMEOUT", name);
+    const streamIdleTimeoutMs = parseRequiredInt(env.PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT, "PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT", name);
+    const serviceTier = (() => {
+        const raw = env.PLURNK_PROVIDERS_SERVICE_TIER;
+        if (raw === undefined || raw.length === 0) return undefined;
+        if (spec.serviceTiers === undefined) {
+            throw new Error(`${name} provider: PLURNK_PROVIDERS_SERVICE_TIER is not supported`);
+        }
+        if (!spec.serviceTiers.includes(raw)) {
+            throw new Error(`${name} provider: PLURNK_PROVIDERS_SERVICE_TIER must be one of ${spec.serviceTiers.map((tier) => JSON.stringify(tier)).join(", ")} (got "${raw}")`);
+        }
+        return raw;
+    })();
 
     // The probe always runs for probeNctx specs — grammar capability must not
     // hinge on whether the operator pinned PLURNK_PROVIDERS_CONTEXT_WINDOW. For
     // contextWindow itself, explicit env still wins over the probed n_ctx.
     let contextWindow = contextWindowFromEnv(env, name);
-    // Grammar shape: a static spec choice (e.g. fireworks → "response_format"),
-    // upgraded to "llamacpp" when the probe fingerprints a llama-server. Slot
+    // GBNF transport is upgraded to "llamacpp" only when the probe fingerprints
+    // a llama-server. Slot
     // pinning is llama-server-only, so it keys on that same fingerprint. A spec
     // can opt out of the fingerprint entirely (detectLlamaServer: false → plurnk)
     // to read the window but stay a plain remote OpenAI server.
-    let grammarStyle: GrammarStyle = spec.grammarStyle ?? "none";
+    let grammarStyle: GrammarStyle = "none";
     let supportsSlotPinning = false;
     let slotCount: number | null = null;
     let eosText: string | undefined;
@@ -500,7 +515,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
             // un-upgraded, but NEVER silently (#34) — rails going dark without a
             // signal cost the consumer weeks of misattributed rambles.
             emitWarningOnce(
-                `${name} provider: llama-server detection failed after ${probeAttempts} attempts — grammar transport stays OFF (grammarStyle "none"). If this endpoint IS a llama-server, pin PLURNK_PROVIDERS_LLAMA_SERVER=1 (or its _<alias> form).`,
+                `${name} provider: llama-server detection failed after ${probeAttempts} attempts — local capabilities are unknown. If this endpoint is a llama-server, pin PLURNK_PROVIDERS_LLAMA_SERVER=1 (or its _<alias> form).`,
                 "PLURNK_PROBE_FAILED",
             );
         }
@@ -577,6 +592,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         headers,
         contextWindow,
         fetchTimeoutMs,
+        streamIdleTimeoutMs,
         reasoning,
         temperature: parseRequiredFloat(env.PLURNK_PROVIDERS_TEMPERATURE, "PLURNK_PROVIDERS_TEMPERATURE", name, 0),
         repeatPenalty: parseRequiredFloat(env.PLURNK_PROVIDERS_REPEAT_PENALTY, "PLURNK_PROVIDERS_REPEAT_PENALTY", name, 0),
@@ -607,6 +623,7 @@ export const standardProviderFromEnv = async (name: string, env: NodeJS.ProcessE
         firstPartyMetadata: spec.firstPartyMetadata,
         apiKeyRejectedMessage: spec.apiKeyRejectedMessage,
         promptCacheKey: spec.promptCacheKey ?? true, // #518: default-on for standard providers (OpenAI-standard field, 6/6 backends verified accept it); per-spec opt-out below
+        serviceTier,
         balanceMetaKey: spec.balanceMetaKey,
         supportsSlotPinning,
         slotCount,