@plurnk/plurnk-providers 1.5.0 → 1.6.0

package/.env.defaults

@@ -17,13 +17,12 @@
 # ACTIVATION and BUDGET are separate so a numeric can never silently flip wire flags.
 # off | adaptive | on. The provider maps intent to each backend's native mechanism
 # (reasoning_effort, enable_thinking, think, ...). Default ADAPTIVE (#399):
-# reasoning ACTIVE on a fresh install, each backend's own adaptive depth,
-# no shipped magnitude - a reasoning model that ships un-reasoning blind-edits and
-# declares done.
+# defer activation and depth to the backend's documented default. Use an alias-scoped
+# ON when a reasoning-capable model defaults off and the operator wants it enabled.
 PLURNK_PROVIDERS_REASONING=adaptive
-# Positive int, REQUIRED iff REASONING=on - the magnitude for tier/budget mapping.
-# On llama-server it is a request-scoped reasoning allowance and may tighten, but
-# cannot exceed, the resolved PLURNK_PROVIDERS_REASONING_RESERVE.
+# Optional positive int when REASONING=on. Without one, ON activates reasoning at
+# the adapter's ordinary enabled posture. On llama-server an explicit value is a
+# request-scoped allowance and may tighten, but cannot exceed, the resolved reserve.
 # PLURNK_PROVIDERS_REASONING_BUDGET=4096
 
 # Response-content interpretation ({§provider-tagged-reasoning}) is independent
@@ -48,10 +47,14 @@ PLURNK_PROVIDERS_FREQUENCY_PENALTY=0
 # Fixed provider service tier. Fireworks accepts auto|default|flex|priority;
 # normally set per alias so a paid routing choice is explicit.
 # PLURNK_PROVIDERS_SERVICE_TIER_myfireworks=priority
-# Compatible endpoints verified to accept the OpenAI prompt_cache_key use the
-# stable worker id for replica-local prefix affinity. Official native SDKs own
-# their cache mechanisms and do not receive this compatible extension.
-PLURNK_PROVIDERS_PROMPT_CACHE_KEY=1
+# Route adapters project the stable worker identity through only the provider's
+# documented session/cache-affinity control. Unknown compatible routes receive
+# no guessed field. Disable globally or per alias only for operational diagnosis.
+PLURNK_PROVIDERS_CACHE_AFFINITY=1
+# Explicit cache writes are distinct from affinity and may affect billing.
+# stable-system marks only the reusable system boundary on supported Claude
+# routes; off requests no explicit cache write. Provider-default lifetime is 5m.
+PLURNK_PROVIDERS_CACHE_WRITE_POLICY=stable-system
 # #567: DRY is a llama.cpp-only repeated-sequence penalty. It can reduce
 # degenerate loops, but it can also corrupt exact source, identifiers, quoted
 # evidence, and other repetition required by PLURNK operations. The portable
@@ -64,16 +67,27 @@ PLURNK_PROVIDERS_DRY_MULTIPLIER=0
 # Set it per alias only from measured model behavior.
 # PLURNK_PROVIDERS_REPEAT_LAST_N_<alias>=512
 
-# --- Transport budgets (§4, #18) ---
-# Total generation-operation timeout (ms), including retries; caller cancellation also spans the operation.
+# --- Connectivity budgets ({§provider-connectivity}, #240) ---
+# Complete logical generation deadline (ms), spanning every physical attempt
+# and retry delay. Zero disables this outer deadline; caller cancellation still
+# spans the operation. The floor leaves all four ten-minute attempts plus normal
+# backoff available under the three-retry floor.
+PLURNK_PROVIDERS_OPERATION_TIMEOUT=2700000
+# Maximum duration (ms) of one physical generation attempt. Zero disables the
+# per-attempt deadline without changing the operation deadline.
 PLURNK_PROVIDERS_FETCH_TIMEOUT=600000
-# Maximum silence (ms) between streamed response-body chunks after response
-# streaming begins. Two minutes: generous for slow local inference, fast enough
-# to catch a dead connection before the total timeout. A detected stall consumes
-# the same configured retry budget as every other retryable transport failure.
+# Maximum wait (ms) from response-stream start to first semantic model content.
+# Transport metadata and empty deltas do not satisfy it. The portable floor
+# allows endpoints that intentionally buffer a full attempt; tighten per alias
+# from measured time-to-first-content. Zero disables it.
+PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT=600000
+# Maximum silence (ms) between semantic streamed-content chunks after content
+# begins. Zero disables it. Both content deadlines consume the ordinary retry
+# budget when they expire.
 PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT=120000
 # Transient-failure retries: 0 = surface the first failure; N = retries on
-# 429/5xx/stream-idle timeout with the AI SDK's backoff (Retry-After wins).
+# network failure, 408/409/429/ordinary 5xx, or an inner deadline, with the AI
+# SDK's backoff (Retry-After wins).
 PLURNK_PROVIDERS_RETRY_ATTEMPTS=3
 # Maximum characters retained from an upstream provider diagnostic in the
 # public Problem detail. Structured failure facts are not truncated.
@@ -89,16 +103,16 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
 # Unset by default. Set per alias only for a local llama-server whose GBNF
 # transport is detected or pinned. Cloud and endpoint-managed model settings do
 # not use this knob.
-# PLURNK_PROVIDERS_GBNF=plurnk.gbnf
+# PLURNK_PROVIDERS_GBNF=plurnk.qwen.gbnf
 # Debug toggle: validate but withhold a configured local GBNF, then report the
 # unconstrained output's divergence. Development aid; leave unset in production.
 # PLURNK_PROVIDERS_GBNF_DEBUG=0
 
 # --- Window ({§model-fact-resolution}) ---
-# Physical provider context only. Unset derives from a live endpoint probe (n_ctx) or
-# models.dev, else null (surfaced once via PLURNK_CONTEXT_UNKNOWN). A configured value
-# caps detected physics or declares it when unknown. Prompt packing and model-facing
-# pressure are consumer policy, not provider configuration.
+# Effective total context envelope. Unset derives natural capacity from a live endpoint probe
+# (n_ctx) or models.dev, else null (surfaced once via PLURNK_CONTEXT_UNKNOWN). A configured
+# value is a final hard cap on known capacity or declares the envelope when unknown. Model-facing
+# prompt pressure is separate consumer policy.
 # PLURNK_PROVIDERS_CONTEXT_WINDOW=200000
 
 # --- llama-server detection pin (#34) ---

package/SPEC.md

@@ -42,24 +42,23 @@ interface Provider {
     signal?: AbortSignal,
   ): Promise<PromptTokenMeasurement>;
   tokenize?(text: string): Promise<number[]>;
-  calculateCost(usage: ProviderUsage): number;
-  calculateCharge?(usage: ProviderUsage): Exclude<ProviderCost, { kind: "authoritative" }>;
   generate(args: GenerateArgs): Promise<ProviderResponse>;
 }
 ```
 
-`contextWindow` is provider physics and resolves under
-{§model-fact-resolution}. `null` means genuinely unknown; a consumer MUST NOT
-invent a stand-in. The context-window knob never carries model-facing prompt
-policy or grinder pressure.
+`contextWindow` is the effective total context envelope resolved under
+{§model-fact-resolution}: the minimum of known model capacity and any stricter
+operator cap. `null` means genuinely unknown; a consumer MUST NOT invent a
+stand-in. The context-window knob is a hard cap, never model-facing grinder
+pressure.
 
 `PromptTokenMeasurement` is a discriminated request-level result:
 
-| `kind`        | Meaning                                                | May authorize physical admission |
-| ------------- | ------------------------------------------------------ | -------------------------------- |
-| `exact`       | Exact count for the complete provider request.         | Yes.                             |
-| `upper_bound` | Proven upper bound for the complete provider request.  | Yes.                             |
-| `estimate`    | Empirical prediction with required causal `detail`.    | No.                              |
+| `kind`        | Meaning                                                | May authorize hard context-envelope admission |
+| ------------- | ------------------------------------------------------ | --------------------------------------------- |
+| `exact`       | Exact count for the complete provider request.         | Yes.                                          |
+| `upper_bound` | Proven upper bound for the complete provider request.  | Yes.                                          |
+| `estimate`    | Empirical prediction with required causal `detail`.    | No.                                           |
 
 Every result carries a non-negative integer `tokens` and a non-empty `source`.
 `countPromptTokens` receives the same messages supplied to `generate` and may
@@ -74,45 +73,72 @@ hard; consumers do not reinterpret it as ordinary unavailability.
 endpoint exposes its real vocabulary. Content tokenization does not substitute
 for complete-request measurement.
 
-§provider-monetary-evidence One precedence path converts each provider response
-into {§provider-cost} evidence:
+§provider-monetary-evidence One precedence path converts each physical provider
+request into {§provider-cost} evidence before the request leaves the provider
+boundary:
 
 | Precedence | Evidence | Result |
 | --- | --- | --- |
-| 1 | A documented monetary field on that response | The adapter normalizes it as `ProviderResponse.charge`; its decimal USD equivalent wins. |
-| 2 | Exact response usage and the exact model's Models.dev rates | `calculateCharge` returns estimated USD, or explicit free when every applicable rate is zero. |
-| 3 | Neither | Unknown; no cost is reported. |
+| 1 | A documented monetary field on that response or error | The adapter validates and preserves its documented `charged` or `estimated` character; its exact amount wins. |
+| 2 | Known response usage and the exact model's Models.dev rates | The adapter returns an exact decimal USD `estimated` amount only when every differently-priced applicable category is known. |
+| 3 | Neither | `unknown` with a concrete reason. |
 
-Models.dev is the sole supported fallback rate table. Missing usage or rates
-never proves free. The numeric `calculateCost` method remains callable only as a
-frozen 1.x compatibility surface and is not a monetary-reporting authority.
-`providerCostUsd` exposes authoritative, estimated, and free evidence as decimal
-USD and returns `null` for unknown evidence.
+Models.dev is the sole supported fallback rate table. Missing usage, a missing
+applicable category, or missing rates never proves zero. An exact zero rate
+produces an ordinary estimated amount of USD `0`. Rate calculation is internal
+to the provider request; Core, digest, ping, and clients never call a parallel
+pricing method.
 
 ### Generation
 
-`generate` requires a non-empty, stable, opaque `workerId`. It accepts:
+§provider-cache-identity `generate` requires a non-empty, stable, opaque
+`workerId`. A durable worker uses one globally unique value for its lifetime;
+independent databases and processes cannot mint the same local sequence. A
+`bare` call instead uses a fresh per-call value, preventing unrelated prompts
+from acquiring affinity with either the parent worker or another BARE call.
+Providers MUST NOT interpret either value.
+
+`generate` accepts:
 
 - `messages`: system, user, and assistant text messages;
 - caller cancellation through `signal`;
 - optional `grammar` and `maxTokens`;
 - standard `sampling` intent;
+- the caller-owned `callKind` output contract when one applies;
 - opaque attribution tags plus client, strike, workspace, loop, and turn metadata.
 
+§provider-call-kind `callKind` is either `emission` (the response is a PLURNK
+turn emission) or `bare` (the response is unconstrained answer text). The
+consumer states this semantic fact explicitly; providers MUST NOT infer it from
+message count, grammar presence, worker identity, or another incidental request
+shape. The first-party adapter transports a supplied value as
+`Plurnk-Call-Kind`; the metadata gate drops it for every third-party backend.
+The signal is request metadata and never enters model-facing messages. Generic
+provider callers MAY omit it; Core supplies it for every model call.
+
 A successful return carries the model's raw content and reasoning, normalized
-usage, normalized finish reason, model identity, opaque evidence, optional
-metadata, and optional notices. The provider transports and observes model
+finish reason, model identity, its ordered {§provider-request-accounting},
+opaque evidence, optional metadata, and optional notices. A `ProviderError`
+carries the same accounting array. The provider transports and observes model
 output; it never retries, discards, or repairs an otherwise completed exchange
 because PLURNK grammar did not accept it.
 
-Usage obeys:
+§provider-request-observer When a consumer supplies the request observer, the
+provider opens one durable identity through it immediately before each physical
+I/O and settles that identity with the resulting
+`ProviderRequestAccounting`. This applies to every automatic retry and capacity
+failover request. The observer is a durability sink, not an alternate evidence
+representation; the same ordered records remain on the final response or error.
+
+Usage obeys {§provider-usage}:
 
 ```text
-total = prompt + completion + reasoning
-cached ⊆ prompt
+totalTokens = inputTokens + outputTokens
+cacheReadTokens, cacheWriteTokens ⊆ inputTokens
+reasoningTokens ⊆ outputTokens
 ```
 
-`completion` excludes reasoning. Ordinary vendor finish reasons normalize to
+Unknown fields remain absent. Ordinary vendor finish reasons normalize to
 `stop`, `length`, `tool_calls`, or `content_filter`; an unknown value becomes
 `null` and emits a warning. `resource_interrupted` is the distinct failed-attempt
 disposition defined by {§provider-interrupted-attempt}.
@@ -132,9 +158,9 @@ explicit alias-scoped response style:
 
 Tag projection never runs when readable structured reasoning is already
 present. Streamed and buffered transports converge on this response boundary.
-When the upstream reports only combined output usage, the existing
-sum-preserving text-proportion estimate reclassifies completion versus reasoning
-without changing prompt, cached input, total output, or billed output.
+When the upstream reports only combined output usage, that value remains
+`outputTokens` and its unavailable text/reasoning detail stays absent. The
+adapter never apportions tokens from character lengths.
 
 Grammar evidence retains the exact pre-projection sentence and its Unicode
 content offset. Response classification cannot rewrite what a transported GBNF
@@ -144,8 +170,10 @@ rail observed.
 
 §provider-sdk-boundary Cataloged providers instantiate their
 Models.dev-declared AI SDK package.
-Standard request shaping, streaming, retries, cancellation, timeouts, usage,
-and vendor error parsing belong to the SDK.
+Standard request shaping, streaming, usage, and vendor error parsing belong to
+the SDK. PLURNK supplies cancellation and deadline signals and owns the sole
+cross-attempt scheduler so every physical request remains observable and
+accountable.
 
 PLURNK maps its generic settings to AI SDK call settings:
 
@@ -153,19 +181,48 @@ PLURNK maps its generic settings to AI SDK call settings:
 - presence and frequency penalties;
 - stop sequences and seed;
 - output-token ceiling;
-- `off`, `adaptive`, or budget-derived reasoning intent.
+- `off`, provider-default `adaptive`, or explicit `on` reasoning intent, with
+  an optional operator budget.
 
 Provider-specific options are permitted only where they preserve a documented
 PLURNK product contract the generic SDK surface cannot express.
 
+§provider-readable-reasoning When the effective reasoning posture is not
+`off`, a native adapter MUST request readable reasoning summaries if its
+provider requires a separate response-visibility option. That option neither
+activates reasoning nor selects its depth. The exact wire projection belongs to
+the provider adapter; Models.dev's reasoning bit remains capability metadata.
+
+The portable SDK surface has no boolean-enabled reasoning value. An unqualified
+`on` therefore projects to its conventional `medium` enabled posture. This is a
+wire activation value, not a reasoning reserve or output-token ceiling.
+
+§provider-cache-affinity **Cache affinity is route-owned request projection.**
+When a provider documents a semantics-preserving conversation, session, or
+prompt-cache routing key, its catalog adapter projects `workerId` through that
+provider's documented header, body field, or native SDK option. The common
+transport neither guesses from protocol resemblance nor sends a generic cache
+field to an unknown provider. The operator may disable affinity globally or per
+alias; automatic provider caching without an affinity control remains untouched.
+
+§provider-cache-write-policy **Cache-write policy is separate from affinity.**
+`PLURNK_PROVIDERS_CACHE_WRITE_POLICY` is `off` or `stable-system`. The latter
+marks only the final leading system instruction as an explicit reusable cache
+boundary, and only on routes whose native SDK documents that control. It does
+not mark the changing user packet or enable an API-wide automatic cache mode.
+Unsupported routes receive no invented option. The default five-minute
+provider lifetime is used; a longer, differently priced lifetime is not an
+implicit transport choice.
+
 §deepseek-reasoning-request The direct DeepSeek catalog path maps the common
 reasoning intent to its OpenAI-compatible controls:
 
-| PLURNK mode | `thinking`            | `reasoning_effort`   |
-| ----------- | --------------------- | -------------------- |
-| `off`       | `{ type: disabled }`  | omitted              |
-| `adaptive`  | omitted               | omitted              |
-| `on`        | `{ type: enabled }`   | budget-derived tier  |
+| PLURNK posture | `thinking`            | `reasoning_effort`   |
+| --------------- | --------------------- | -------------------- |
+| `off`           | `{ type: disabled }`  | omitted              |
+| `adaptive`      | omitted               | omitted              |
+| `on`            | `{ type: enabled }`   | omitted              |
+| `on` + budget   | `{ type: enabled }`   | budget-derived tier  |
 
 The compatible transport is deliberately retained for:
 
@@ -195,9 +252,10 @@ The universal groups are:
 - reasoning activation and optional explicit budget;
 - explicit reasoning response-content style;
 - decode tuning;
-- request, stream-idle, retry, and probe budgets;
+- operation, physical-attempt, first-content, stream-idle, retry, and probe budgets;
 - local GBNF and llama-server capability pins;
 - context-window and generation-envelope overrides;
+- provider-documented cache affinity and explicit cache-write policy;
 - opt-in logprob and raw-body capture.
 
 Operator secrets and machine-specific values never belong in committed
@@ -219,11 +277,11 @@ Provider and model facts resolve independently:
 | Context window       | Catalog metadata or a local endpoint probe.            | `PLURNK_PROVIDERS_CONTEXT_WINDOW`.                   | Minimum when both exist; the sole value otherwise. A cataloged cloud miss fails construction; a compatible probe miss remains `null` with one warning. |
 | Completion envelope  | Catalog `maxOutput`; there is no live limit probe.     | `PLURNK_PROVIDERS_COMPLETION_RESERVE`.               | An absolute reserve wins. A percentage derives from the effective window and is capped by catalog `maxOutput` when present.                            |
 | Reasoning capability | Catalog `reasoning: true`, exposed by snapshot lookup. | Runtime activation, reserve, and adapter wire style. | The catalog bit is informational; provider construction neither activates nor blocks reasoning from it.                                                |
-| Estimated USD rates  | Models.dev input, output, and optional cache-read rates. | None. | Missing rates produce unknown evidence; explicit all-zero rates produce free evidence. No live price fetch exists. |
+| Estimated USD rates  | Models.dev input, output, and optional cache-read/cache-write rates. | None. | Missing differently-priced categories or rates produce unknown evidence; exact all-zero rates produce an estimated USD zero. No live price fetch exists. |
 
-Models.dev cache-read cost defaults to its input cost when omitted. Cache-write
-cost remains snapshot information; the current usage record has no cache-write
-quantity to price.
+Models.dev cache-read and cache-write cost default to input cost when omitted.
+When either differs from input, the corresponding usage detail must be known or
+the request estimate is unknown.
 
 `instantiateProvider` resolves in this order:
 
@@ -311,11 +369,12 @@ OpenAI-compatible generation endpoint through the SDK adapter.
 For a detected llama-server, PLURNK sends the complete reasoning contract on
 every request:
 
-| Mode | Template activation | `thinking_budget_tokens` |
+| Posture | Template activation | `thinking_budget_tokens` |
 |---|---:|---:|
 | `off` | false | `0` |
 | `adaptive` | true | resolved reasoning reserve |
-| `on` | true | explicit reasoning budget |
+| `on` | true | resolved reasoning reserve |
+| `on` + budget | true | explicit reasoning budget |
 
 The explicit budget may tighten but MUST NOT exceed the resolved reasoning
 reserve. Template calls normally use `reasoning_format: "auto"` for a separate
@@ -342,7 +401,7 @@ intent. It cannot override:
 - data-capture settings;
 - tool, modality, or multi-choice behavior;
 - the consumer-owned output envelope;
-- prompt-cache identity.
+- cache affinity identity or cache-write policy.
 
 Generic AI SDK calls accept only settings represented by the SDK's portable
 surface. Compatible endpoints may carry additional sampling keys after reserved
@@ -366,16 +425,30 @@ normal value. Retry exhaustion is preserved as `attempts` and
 `retryExhausted`, and the resulting Problem is not marked retryable after the
 provider has consumed its automatic retry budget.
 
-The AI SDK owns one attempt scheduler around the complete generation exchange.
-`PLURNK_PROVIDERS_RETRY_ATTEMPTS` is the maximum retry count, including a
-configured stream-chunk deadline that expires while consuming a response body.
-The total generation deadline and caller cancellation span that scheduler and
-every attempt; neither restarts during replay. Total and stream-chunk deadlines
-are separately configurable.
+§provider-connectivity The provider adapter owns one attempt scheduler around
+the complete generation exchange; SDK-internal retries are disabled.
+`PLURNK_PROVIDERS_RETRY_ATTEMPTS=N` permits at most `N + 1` physical requests.
+The layers are independent and a configured value of zero disables only that
+deadline:
+
+| Layer | Operator knob | Boundary | Expiry |
+| --- | --- | --- | --- |
+| Operation | `PLURNK_PROVIDERS_OPERATION_TIMEOUT` | Complete logical call, including every attempt and retry delay. | Final `deadline_exceeded` Problem at 504 with `timeoutPhase=operation`; never retried. |
+| Attempt | `PLURNK_PROVIDERS_FETCH_TIMEOUT` | One physical generation request, including response consumption. | Retryable `network_failure` with `timeoutPhase=attempt`. |
+| First content | `PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT` | Response-stream start through first semantic model content; metadata, empty deltas, and transport activity do not satisfy it. | Retryable `network_failure` with `timeoutPhase=first_content`. |
+| Stream idle | `PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT` | Silence between semantic content chunks after content begins. | Retryable `network_failure` with `timeoutPhase=stream_idle`. |
+
+Caller cancellation spans the operation and preserves the caller's reason.
+Inner deadline failures consume the ordinary retry budget; retry exhaustion
+adds `attempts` and `retryExhausted`, retains the inner `timeoutPhase` and
+`timeoutMs`, and is final. Every scheduler iteration opens and settles exactly
+one ordered {§provider-request-accounting} record, including response-less
+network failures and timed-out attempts.
 
 HTTP 408, 409, 429, and ordinary 5xx responses are retryable unless the endpoint
-explicitly says otherwise. Endpoint control responses 520–527 are final so a
-router can prevent multiplicative retries behind its own retry policy.
+explicitly says otherwise through `X-Should-Retry`. That header is authoritative;
+without an explicit directive, endpoint control responses 520–527 are final so
+a router can prevent multiplicative retries behind its own policy.
 
 ### §provider-interrupted-attempt Provider-declared interruption
 
@@ -386,10 +459,10 @@ completed exchange.
 | Concern                    | Contract                                                                                                                     |
 | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | Normalized finish reason   | Exact `insufficient_system_resource` becomes `resource_interrupted`; the raw value remains in `assistantRaw`.                |
-| `generate` outcome         | Throw `ProviderError(kind="resource_interrupted")` at local status 503 with the normalized attempt on `error.attempt`.       |
+| `generate` outcome         | Throw `ProviderError(kind="resource_interrupted")` at local status 503 with the normalized attempt on `error.attempt` and the same accounting on `error.accounting`. |
 | Partial response           | Preserve content, reasoning, usage, model, metadata, optional raw body, and other evidence without admitting it as success.  |
 | Automatic replay           | None; the Problem has `retryable: false`, and AI SDK retry scheduling has already completed at the successful transport.     |
-| Capacity-pool overflow     | None; a sibling success would erase the known billed failed attempt from the current `ProviderResponse` surface.             |
+| Capacity-pool overflow     | None under the existing routing policy; when other overflow-eligible failures do reach a sibling, the pool concatenates their request accounting. |
 | Consumer admission         | Persist the evidence as an unaccepted attempt; never parse it into executable work, even when its frame looks complete.      |
 
 ## §10 Grammar
@@ -398,8 +471,9 @@ GBNF is a local llama-server capability, not a generic provider expectation.
 The consumer chooses whether to supply a grammar. The provider never creates or
 rewrites one.
 
-GBNF defines the accepted raw sampled text; it runs before response reasoning
-is separated from regular content. The shipped PLURNK sentence is owned by
+GBNF defines the accepted sampled text; it runs before response reasoning is
+separated from regular content. A generated rail may declare a response root
+that composes a template-provided prefix for independent evidence grading. The shipped PLURNK sentence is owned by
 `plurnk-contracts` {§gbnf-turn-shape} and {§gbnf-reasoning-boundary}; this package does
 not restate or rewrite it.
 

package/dist/AiSdkProvider.d.ts

@@ -1,17 +1,29 @@
-import type { AuthoritativeChargeNormalizer, ChatMessage, PromptTokenMeasurement, Provider, ProviderResponse, ProviderUsage } from "./types.ts";
+import type { ChatMessage, PromptTokenMeasurement, Provider, ProviderCostNormalizer, ProviderGenerateArgs, ProviderResponse, ProviderUsage } from "./types.ts";
 import type { ProviderCost } from "@plurnk/plurnk-contracts";
+import type { JSONValue } from "ai";
 import type { Reasoning, ReasoningResponseStyle, ReserveSpec } from "./env.ts";
 import type { LanguageModel } from "ai";
 import type { PluginAttribution, PluginAttributionContext } from "@plurnk/plurnk-meta";
 export type ProviderFetch = typeof globalThis.fetch;
 export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" | "effort_explicit" | "thinking_effort" | "template" | "anthropic";
 export type GrammarStyle = "none" | "llamacpp";
+export type CacheAffinity = {
+    readonly target: "header" | "body";
+    readonly name: string;
+} | {
+    readonly target: "provider-option";
+    readonly provider: string;
+    readonly name: string;
+};
+export type AiSdkProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
 export type AiSdkProviderConfig = {
     model: string;
     url?: string;
     languageModel?: LanguageModel;
     attributions?: (context: PluginAttributionContext) => PluginAttribution;
     fetchTimeoutMs: number;
+    operationTimeoutMs: number;
+    firstContentTimeoutMs: number;
     streamIdleTimeoutMs?: number;
     headers?: Record<string, string>;
     fetch?: ProviderFetch;
@@ -19,14 +31,13 @@ export type AiSdkProviderConfig = {
     reasoningStyle?: ReasoningStyle;
     reasoningResponseStyle?: ReasoningResponseStyle;
     countPromptTokens?: (messages: readonly ChatMessage[], signal?: AbortSignal) => PromptTokenMeasurement | Promise<PromptTokenMeasurement>;
-    calculateCost?: (usage: ProviderUsage) => number;
-    calculateCharge?: (usage: ProviderUsage) => Exclude<ProviderCost, {
-        kind: "authoritative";
-    }>;
-    normalizeCharge?: AuthoritativeChargeNormalizer;
+    estimateCost?: (usage: ProviderUsage | undefined) => ProviderCost;
+    normalizeCost?: ProviderCostNormalizer;
     source?: string;
     grammarStyle?: GrammarStyle;
-    promptCacheKey?: boolean;
+    cacheAffinity?: CacheAffinity;
+    systemCacheProviderOptions?: AiSdkProviderOptions;
+    reasoningResponseProviderOptions?: AiSdkProviderOptions;
     serviceTier?: string;
     gbnfDebug?: boolean;
     streaming?: boolean;
@@ -69,24 +80,6 @@ export default class AiSdkProvider implements Provider {
     get requiresMaxTokens(): boolean | undefined;
     get constrainsOutput(): boolean;
     countPromptTokens(messages: readonly ChatMessage[], signal?: AbortSignal): Promise<PromptTokenMeasurement>;
-    calculateCost(usage: ProviderUsage): number;
-    calculateCharge(usage: ProviderUsage): Exclude<ProviderCost, {
-        kind: "authoritative";
-    }>;
-    generate({ messages, workerId, primaryWorkerId, signal, grammar, maxTokens, attributions, client, strikes, workspaceId, loop, turn, sampling }: {
-        messages: ChatMessage[];
-        workerId: string;
-        primaryWorkerId?: string;
-        signal?: AbortSignal;
-        grammar?: string;
-        maxTokens?: number;
-        attributions?: string[];
-        client?: string;
-        strikes?: number;
-        workspaceId?: string;
-        loop?: number;
-        turn?: number;
-        sampling?: Record<string, unknown>;
-    }): Promise<ProviderResponse>;
+    generate({ messages, workerId, primaryWorkerId, signal, grammar, maxTokens, attributions, client, strikes, workspaceId, loop, turn, sampling, observeRequest, callKind }: ProviderGenerateArgs): Promise<ProviderResponse>;
 }
 //# sourceMappingURL=AiSdkProvider.d.ts.map

package/dist/AiSdkProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AiSdkProvider.d.ts","sourceRoot":"","sources":["../src/AiSdkProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AiSdkProvider.d.ts","sourceRoot":"","sources":["../src/AiSdkProvider.ts"],"names":[],"mappings":"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"}