@plurnk/plurnk-providers 1.21.0 → 1.22.0

package/SPEC.md

@@ -125,6 +125,23 @@ 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.
 
+Router accounting uses the complete cost to the caller, not just the router's
+fee. OpenRouter's response `usage` is authoritative; its SDK metadata projection
+omits the BYOK discriminator. Apply the same rule to successful and failed
+requests, independently of raw-body capture:
+
+| OpenRouter evidence | Monetary result |
+| --- | --- |
+| `is_byok: false` and `cost` | `charged`: `cost`; upstream inference is already included. |
+| `is_byok: true`, `cost`, and `cost_details.upstream_inference_cost` | `charged`: exact decimal sum of router fee and upstream charge. |
+| A monetary field without a BYOK discriminator, or BYOK missing either component | `unknown`; neither zero nor catalog pricing completes the reported charge. |
+| No reported charge and no BYOK indication | Ordinary Models.dev fallback above. |
+
+Explicit zero components are valid. Malformed monetary values are contract
+violations, never coerced. Raw routing and billing evidence remain available
+under {§provider-evidence}; Core and clients consume the existing single cost.
+See [OpenRouter usage accounting](https://openrouter.ai/docs/cookbook/administration/usage-accounting).
+
 ### Generation
 
 §provider-cache-identity `generate` requires a non-empty, stable, opaque
@@ -231,14 +248,21 @@ the SDK. PLURNK supplies cancellation and deadline signals and owns the sole
 cross-attempt scheduler so every physical request remains observable and
 accountable.
 
+| Usage input | Normalization |
+| --- | --- |
+| Native protocol | Preserve the SDK's inclusive totals and category counts; raw protocol counters are evidence, not interchangeable totals. |
+| OpenAI-compatible wire | Retain extended counters and exact total identities the SDK may omit. |
+| Compatible SDK input partition | Retain its uncached count when total input and an explicitly reported cache-read count agree with the wire; never promote SDK defaults over absent or contradictory wire counts. |
+| Input total plus two partition counts | Derive the remaining count exactly; otherwise preserve absence. |
+
 PLURNK maps its generic settings to AI SDK call settings:
 
 - `temperature`, `top_p`, `top_k`;
 - presence and frequency penalties;
 - stop sequences and seed;
 - output-token ceiling;
-- `off`, `adaptive`, or fixed `low`, `medium`, or `high` reasoning policy, with
-  an independent optional operator budget.
+- the supported efforts and optional numeric control under
+  {§provider-effort}.
 
 Provider-specific options are permitted only where they preserve a documented
 PLURNK product contract the generic SDK surface cannot express.
@@ -253,28 +277,31 @@ catalog figure. Without catalog rates the override must declare `input` and
 response cost still outranks any estimate. Unknown keys, repeats, and negative
 or non-numeric rates refuse at construction.
 
-§provider-reasoning-policy The portable vocabulary comes from
-{§reasoning-policy-wire}. `adaptive` requests the provider's
-documented dynamic mechanism where one exists. Otherwise, a cataloged graded
-route receives its strongest positive Models.dev effort that the installed
-transport can represent; a route that declares a toggle control receives an
-explicit enable on transports that document one (OpenRouter `reasoning.enabled`,
-Fireworks Boolean `reasoning_effort`) — an unconfigured reasoning-capable route
-must not run reasoning-off, and `off` stays the explicit opt-out; otherwise the
-provider default holds. A fixed policy retains its exact name and is rejected before
-provider I/O when either the route or transport cannot represent it. Every
-provider exposes that exact intersection. A numeric reasoning budget constrains
+§provider-effort The portable vocabulary comes from
+{§effort-wire}. `adaptive` uses the first applicable projection:
+
+| Condition | Projection |
+| --- | --- |
+| Explicit adaptive declaration: `REASONING_ADAPTIVE_BODY`, or a native model family's `ADAPTIVE_OPTIONS` ({§provider-model-options}) | Preserve that mechanism; an explicit `{}` retains the enabled endpoint's default. |
+| The configured `PLURNK_PROVIDERS_EFFORT_FALLBACK` is supported by both model and transport | Send that exact effort. The shipped fallback is `high`, not the strongest available level. |
+| No supported fallback, including an empty fallback setting | Retain reasoning activation and the provider's default effort; never invent a level or escalate to another one. |
+
+Activation is distinct from effort: declared enable fields accompany active
+reasoning, and a toggle-only route uses its documented enable mechanism.
+Non-reasoning models receive no reasoning controls; `off` is the explicit opt-out.
+A fixed policy retains its exact name and is rejected before provider I/O when
+either the route or transport cannot represent it. Every provider exposes that
+exact intersection. A numeric reasoning budget constrains
 the generation envelope independently and never selects or changes policy. On
-the OpenRouter transport a resolved budget under `adaptive` reaches the wire as
-the `reasoning.max_tokens` form — the only dial a budget_tokens-only route
-understands; a fixed policy keeps the `effort` form, and `off` suppresses the
-budget.
-
-`catalogReasoningPolicies` projects that same admission calculation from catalog
-facts and provider-wide environment declarations without constructing a model,
-requiring credentials, or performing provider I/O.
+routes whose controls are exclusive, fixed effort plus a numeric budget is
+rejected before I/O. Under `adaptive`, an explicit budget selects the numeric
+control; `off` suppresses it.
+
+`catalogEfforts` projects that same admission calculation from catalog
+facts and provider-wide environment declarations over the installed defaults,
+without constructing a model, requiring credentials, or performing provider I/O.
 Admission respects the installed projection: native SDK fixed efforts exclude
-`max`; the OpenRouter model-settings projection also excludes `xhigh`.
+`max`; declared transport vocabularies constrain per-call option projections.
 
 Models.dev's route-specific `reasoning_options` is the capability authority for
 what the daemon offers on its own; the daemon never adds vendor behaviour absent
@@ -291,7 +318,7 @@ explicit compatible adapter owns the wire projection:
 | --- | --- | --- |
 | `reasoning: false` | No reasoning request | `off` |
 | `reasoning_options: []` | Provider default | None |
-| `effort.values` | Native dynamic mechanism, otherwise strongest transportable positive value | Transportable fixed members of {§reasoning-policy-wire}; `off` only when `none` is transportable |
+| `effort.values` | Native dynamic mechanism, otherwise the supported configured fallback or provider default | Transportable fixed members of {§effort-wire}; `off` only when `none` is transportable |
 | `toggle` | Native or explicitly declared activation, otherwise provider default | `off` only when that transport owns the toggle wire |
 | `budget_tokens` | Does not select policy | None; an adapter may use its bounds when projecting the independent budget |
 | No catalog entry | Explicit adapter declaration | Only the declaration's exact subset |
@@ -321,34 +348,36 @@ 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.
+The environment's `CACHE_AFFINITY_FIELD` declares that placement as
+`{"target":"header"|"body","name":"…"}` or
+`{"target":"provider-option","provider":"…","name":"…"}`. It follows
+the provider/route/alias precedence of {§provider-wire-declaration}; `null`
+clears the declaration. Placement is independent of the enable switch, cannot
+replace transport-owned fields, and does not imply support from a provider's name.
+
+§provider-model-options **A model family's native options are a provider declaration.** Models.dev
+does not say which models on a native SDK take adaptive reasoning or explicit cache writes, and the SDKs
+do not export their tables, so a provider declares them as data: `ADAPTIVE_OPTIONS` and
+`SYSTEM_CACHE_OPTIONS` are JSON arrays of `{"models":["<glob>",…],"options":{…}}` rules. The first rule
+with a glob matching the route's model id (`path.matchesGlob`) supplies its per-call provider options;
+without a match none apply. They follow the provider/route/alias precedence of
+{§provider-wire-declaration}, an empty value declares none, and a malformed value fails construction.
+None ships: Plurnk's shipped defaults serve open models only, and an operator who routes a closed model
+family declares its options in their own configuration.
 
 §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
+boundary, and only on routes whose provider declares the control in
+`SYSTEM_CACHE_OPTIONS` ({§provider-model-options}). 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 posture | `thinking`            | `reasoning_effort`   |
-| --------------- | --------------------- | -------------------- |
-| `off`           | `{ type: disabled }`  | omitted              |
-| `adaptive`      | `{ type: enabled }`   | omitted              |
-| `high`          | `{ type: enabled }`   | `high`                |
-
-The direct API does not distinguish portable `low` or `medium` intent and
-therefore advertises only `off`, `adaptive`, and `high`.
-
-§provider-reasoning-style A reasoning style names the wire a compatible route's
-reasoning controls take. `PLURNK_PROVIDERS_PROVIDER_<PREFIX>_REASONING_STYLE`
-declares it for every route of a provider; `PLURNK_PROVIDERS_REASONING_STYLE`,
-alias-scopable like every bare knob, declares it for one route and wins. One
-provider can serve models whose controls differ, so a route states its own style. The daemon never infers a
-style from a model name.
+§deepseek-reasoning-request Direct DeepSeek uses the panel's request-field
+declarations under {§provider-wire-declaration}. Models.dev supplies each
+model's effort vocabulary; it is not a second fixed list in this adapter.
 
 The compatible transport is deliberately retained for:
 
@@ -359,6 +388,49 @@ The compatible transport is deliberately retained for:
 It carries PLURNK-only fields and raw wire evidence without reimplementing the
 SDK's ordinary transport.
 
+### §provider-wire-declaration Request-field declarations
+
+Models.dev owns model capabilities, effort vocabulary, and numeric budget bounds.
+For endpoints whose field names it does not describe, the provider's
+environment panel supplies a bounded projection, independent of provider identity:
+
+| Declaration suffix | Meaning |
+| --- | --- |
+| `OPTIONS_NAMESPACE` | Native SDK's per-call `providerOptions` namespace. Without one, declared fields target the compatible request body. |
+| `OUTPUT_PATH` | RFC 6901 object-member pointer for the **inclusive** output ceiling; absent uses the compatible SDK's `max_tokens` field. |
+| `REASONING_EFFORT_PATH` / `REASONING_BUDGET_PATH` | Pointers for exact effort or numeric reasoning subset. No pointer means no such control. |
+| `REASONING_EFFORTS` | Additional declared effort values, unioned with Models.dev. |
+| `REASONING_TRANSPORT_EFFORTS` | Optional transport vocabulary, intersected with catalog/declaration efforts. It adds no model capability. |
+| `REASONING_CONTROLS` | Required when both pointers exist: `exclusive` refuses fixed effort plus budget; `combined` sends both. |
+| `REASONING_ON_BODY` | Static reasoning activation fields, merged with the selected control. |
+| `REASONING_OFF_BODY` | Explicit disable fields; otherwise a declared `none` effort can disable. |
+| `REASONING_ADAPTIVE_BODY` | Explicit adaptive fields, ahead of graded fallback; `{}` retains the enabled endpoint's default. |
+| `REASONING_TOGGLE_BODY` | Reasoning enable fields when Models.dev declares a toggle and neither an explicit adaptive body nor a supported fallback effort applies. |
+
+The existing provider declaration prefix is
+`PLURNK_PROVIDERS_PROVIDER_<NAME>_`; `PLURNK_PROVIDERS_<suffix>` overrides
+it for the route and accepts the ordinary alias suffix. These are data, not
+executable transformations. Static bodies cannot replace transport, sampling,
+or managed numeric controls; pointers cannot overlap. Configuration fails at
+construction before inference when a requested policy or numeric control is
+unrepresentable. A tighter per-call envelope reprojects the same declaration.
+Discovery and generation share the resolved policy set. A cataloged
+non-reasoning model receives no reasoning fields.
+Native SDKs retain their own output field; `OUTPUT_PATH` is incompatible with an
+options namespace. Request-local options are projected after the effective
+envelope is known, never frozen into SDK model construction. Streaming and
+non-streaming calls use the same projection.
+Retired `REASONING_STYLE` selectors fail at the selected provider/alias boundary;
+they neither select a preset nor silently coexist with these declarations.
+
+A native SDK's portable reasoning setting has no `max`, so a native route without
+a namespace cannot send an effort the catalog documents beyond it; construction
+refuses it and names the declaration that would. Native SDKs built on
+openai-compatible (DeepInfra, Together) write `reasoning_effort` from their own
+`reasoningEffort` option after spreading the others, overwriting a raw
+`reasoning_effort`; their shipped declarations therefore point at
+`/reasoningEffort`, with `{"reasoningEffort":"none"}` as the off body.
+
 ## §4 Operator configuration
 
 §provider-configuration Every operational value is an environment knob
@@ -434,8 +506,8 @@ Provider and model facts resolve independently:
 | Context window | Catalog metadata or local endpoint probe. | `PLURNK_PROVIDERS_CONTEXT_WINDOW`. | Minimum when both exist; sole value otherwise. Cataloged cloud miss fails construction; compatible probe miss remains `null` with one warning. |
 | Maximum input | Catalog `limit.input`; no generic live probe. | None. | Catalog value or `null`; never reconstructed from context and output. |
 | Maximum output | Catalog `limit.output`; no generic live probe. | None. | Minimum of catalog value and effective context, or `null`. |
-| Total output budget | None. | `PLURNK_PROVIDERS_OUTPUT_BUDGET`. | Percentage of effective context or absolute count, capped by known context/output limits; a call may only tighten it. |
-| Reasoning policy | Catalog `reasoning_options` intersected with the installed adapter; explicit adapter declaration for uncataloged routes. | `PLURNK_PROVIDERS_REASONING`, initially; durable worker selection thereafter. | One supported member of `off`, `adaptive`, `low`, `medium`, or `high`; `adaptive` is the default. |
+| Total output budget | None. | `PLURNK_PROVIDERS_OUTPUT_BUDGET`. | Curation reservation: percentage of effective context or absolute count, capped by known context/output limits; a call may only tighten it. The response grant may expand under {§provider-flexed-allowance}. |
+| Effort | Catalog `reasoning_options` intersected with the installed adapter; explicit adapter declaration for uncataloged routes. | `PLURNK_PROVIDERS_EFFORT`, initially; durable worker selection thereafter. | A supported member of {§effort-wire}, projected under {§provider-effort}. The shipped selection is `adaptive`. |
 | Reasoning budget | None. | Optional `PLURNK_PROVIDERS_REASONING_BUDGET`. | Percentage of effective context or absolute count; valid only as a strict subset of total output and effective unless reasoning is `off`. |
 | Cost override | None. | Optional `PLURNK_PROVIDERS_COST`. | {§operator-cost-override} — comma-separated `key=value` per-1M-token USD rates over `input, output, reasoning, cacheRead, cacheWrite`; merges over the Models.dev catalog block (the catalog is the starting point), alias-scoped like every knob. Without catalog rates the override must declare `input` and `output`. The cost estimate's `source` names the override; a provider-reported response cost still outranks any estimate. |
 | Reasoning capability | Catalog `reasoning` and route-specific `reasoning_options`. | Adapter wire style only where the catalog cannot name the native field. | Catalog controls determine admissible policy; the adapter determines its wire projection. |
@@ -477,9 +549,9 @@ forcing a vendor-owned resource prefix into PLURNK aliases. Ambiguous suffixes
 fail to resolve.
 
 The catalog package identifies the protocol family, not a mandatory client
-implementation. OpenRouter and DeepInfra carry exact charges their AI SDK
-projection omits, so each supplies a cost normalizer that reads the documented
-response rather than the projection.
+implementation. OpenRouter charges and DeepInfra estimates use cost normalizers
+over documented response fields, retaining their distinct monetary character
+under {§provider-monetary-evidence}.
 
 §provider-fact-authority Provider declarations configure facts, not
 credentials, and Models.dev is authoritative for cataloged providers: package
@@ -530,8 +602,7 @@ PLURNK `Provider`, read PLURNK tuning knobs, or reproduce transport policy.
 Discovery is scope-agnostic and memoized per process. Duplicate names fail hard.
 The common plugin trust gate applies before import ({§plugin-trust-boundary}). A plugin absent from
 Models.dev requires an explicit context-window pin because PLURNK will not guess
-model physics. `Discovery.packageAttributions` carries the canonical package map;
-the published name-keyed `Discovery.attributions` remains its 1.x projection.
+model physics. `Discovery.packageAttributions` carries the canonical package map.
 
 ## §7 Local capabilities
 
@@ -575,6 +646,16 @@ reasoning enclosure only after preserving grammar evidence. Process-wide
 llama-server flags are fallback server configuration, not part of the PLURNK
 contract and need not be synchronized with an alias.
 
+§repetition-stop **A response that repeats itself is stopped.** A degenerate model can stream one line
+without end; content keeps arriving, so no silence deadline fires, and the call runs to its output
+allowance. The transport counts the complete lines of each streamed channel, text and reasoning, and
+when one line of 16 or more characters has appeared `PLURNK_PROVIDERS_REPEATED_LINE_LIMIT` times it stops
+reading: the stream is cancelled, the physical request settles with whatever usage the chunks carried,
+and the call fails as `repetition` (422, not retryable) carrying the partial attempt and the sentence
+"The response repeated one line N times and was stopped: `<line>`". The consumer reads it as an invalid
+emission, never as a provider failure to recover. Measured: a granite-4.2-8b run repeated one line 358
+times across 45,875 tokens and 9 min 42 s; a limit of 32 stops it 14.6% of the way in (#876).
+
 §llama-reasoning-request The allowance is cumulative across the complete response. Opening a second or
 later reasoning block does not replenish it. Template parsing, the reasoning
 sampler, normalized usage, and the returned reasoning channel MUST agree on that
@@ -598,14 +679,14 @@ Generic AI SDK calls accept only settings represented by the SDK's portable
 surface. Compatible endpoints may carry additional sampling keys after reserved
 keys are removed.
 
-§openrouter-app-attribution **The cataloged OpenRouter route identifies the
-calling application through OpenRouter's current app-attribution headers.**
-`HTTP-Referer` is the absolute HTTP(S) application URL and
-`X-OpenRouter-Title` is its optional display title. The shipped floor identifies
-the public Plurnk repository and may be replaced by operator configuration; an
-explicitly empty `OPENROUTER_HTTP_REFERER` suppresses both headers. Attribution
-applies only to the cataloged `openrouter` route and never leaks to another
-provider merely because it uses the same SDK package.
+§openrouter-app-attribution **A route on the OpenRouter SDK identifies the calling
+application only as its provider declares.** `APP_URL`, an absolute HTTP(S) URL, and
+the optional `APP_NAME` are provider declarations (`PLURNK_PROVIDERS_PROVIDER_<NAME>_`,
+overridable per route or alias); the SDK sends them as `HTTP-Referer` and
+`X-OpenRouter-Title`. The shipped floor declares them for `openrouter` only, so
+another provider on the same SDK package sends none; an empty `APP_URL` suppresses
+both. The retired `OPENROUTER_HTTP_REFERER`, `OPENROUTER_APP_TITLE` and
+`OPENROUTER_X_TITLE` fail construction.
 
 ## §9 Failures, retries, and cancellation
 
@@ -618,8 +699,15 @@ into an empty model turn or reduced to a message plus a generic status.
 Upstream diagnostic text is bounded by
 `PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT`; the committed `.env.defaults` owns its
 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.
+`retryExhausted`; it does not change the Problem's `retryable`.
+
+§provider-retryable-truth **`retryable` states what happens next.** A Problem's
+`retryable` is exactly membership of its kind in the exported
+`RETRYABLE_PROVIDER_KINDS` — `rate_limit`, `network_failure`, `deadline_exceeded`,
+`resource_interrupted`, `output_dropped` — and Core's provider recovery re-issues
+exactly those kinds by reading the same set. It never copies the transport's own
+retry policy: a 502 or 524 that the transport will not replay is still re-issued by
+the consumer, so it reports `retryable: true`. Every other kind reports `false`.
 
 §provider-failure-cause **The wrapper's cause is evidence, bounded.** The SDK
 reports every processing failure of a 2xx body with one message ("Failed to
@@ -660,20 +748,29 @@ and the notice names the true per-call grant (`capacity.responseMax` on the
 response) — the tolerance's honest edge, never worse than the fixed allowance
 it forgives.
 
-§provider-sampling-passthrough **The service imposes no sampling opinion.** With
-no configured value, a request carries no `temperature` and no repetition
-control — the provider's or model's own defaults govern, as a normal agentic
-service behaves. `PLURNK_PROVIDERS_TEMPERATURE` and
-`PLURNK_PROVIDERS_REPEAT_PENALTY` parse empty as null and exist as per-alias
-measurement instruments; caller `sampling` always outranks a configured value,
-and router-owned-tuning providers suppress configured floors entirely. The
-justified exception the penalty knob exists for: grammar-constrained decoding
-can loop under the mask — greedy continuation of an exactly-repeatable sequence
-the grammar keeps legal (measured on the July local rail work, #9/#30; and
-unconstrained on firefast, where 4/86 bench turns ran straight to the token cap
-on pure repetition, run52) — and a per-alias `repeat_penalty` (llama.cpp
-backends) or `frequency_penalty` (cloud backends, #426) is the measured remedy
-for a model that exhibits it, never a service-wide floor.
+§provider-sampling-passthrough **Unconfigured sampling retains endpoint defaults.**
+The provider panel owns tuning; Models.dev capabilities are not recommended
+sampling values. Every knob accepts the ordinary alias override
+({§provider-configuration}). Both cataloged and local providers apply the same
+validation and precedence: configured values, then caller `sampling`, then
+transport-owned fields ({§provider-request-authority}).
+
+| `PLURNK_PROVIDERS_` suffix | Compatible wire / native SDK | Accepted configuration |
+| --- | --- | --- |
+| `TEMPERATURE` | `temperature` / `temperature` | Finite non-negative number; empty/unset omits. |
+| `TOP_P` | `top_p` / `topP` | Finite number in `[0,1]`; empty/unset omits. |
+| `TOP_K` | `top_k` / `topK` | Non-negative safe integer; empty/unset omits. Zero semantics are endpoint-owned. |
+| `PRESENCE_PENALTY` | `presence_penalty` / `presencePenalty` | Finite number in `[-2,2]`; empty/unset omits. |
+| `FREQUENCY_PENALTY` | `frequency_penalty` / `frequencyPenalty` | Required finite number in `[-2,2]`; the panel's zero selects no configured override. Negative values survive unchanged. |
+| `SEED` | `seed` / `seed` | Safe integer; empty/unset omits. No guarantee of reproducibility. |
+
+Configured zero is preserved except for the frequency knob's explicit
+no-override sentinel; a caller-supplied zero always overrides a configured value.
+Invalid configuration fails by knob name before inference. The SDK/endpoint
+owns narrower model restrictions and unsupported-setting diagnostics; Plurnk
+does not clamp values or invent model-specific sampling profiles.
+`REPEAT_PENALTY` and DRY remain explicit llama-server extensions, omitted when
+unconfigured. Their grammar protection remains at {§provider-grammar-transport}.
 
 §provider-connectivity The provider adapter owns one attempt scheduler around
 the complete generation exchange; SDK-internal retries are disabled.
@@ -683,20 +780,29 @@ 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. Enforced as a race, not only the advisory signal, so a wedged transport that never observes the abort cannot hang the loop past the deadline (#505); a well-behaved transport unwinds within a short grace and settles its own attempt evidence first. |
-| Attempt | `PLURNK_PROVIDERS_FETCH_TIMEOUT` | One physical generation request. A non-streamed request is bounded through response consumption; a streamed one only until its first semantic content, after which stream-idle catches a stall and the operation deadline bounds the whole, so a stream still producing (long reasoning) is never cut off. | Surfaced `network_failure` with `timeoutPhase=attempt`; never transport-retried (#479) — the consumer's recovery owns re-issue. |
-| 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. | Surfaced `network_failure` with `timeoutPhase=first_content`; never transport-retried (#479). |
+| Operation | `PLURNK_PROVIDERS_OPERATION_TIMEOUT` | Complete logical call, including admission queueing, every attempt and retry delay. | Final `deadline_exceeded` Problem at 504 with `timeoutPhase=operation`; not retried inside this operation. Consumer recovery is separate. Enforced as a race, not only the advisory signal, so a wedged transport that never observes the abort cannot hang the loop past the deadline (#505); a well-behaved transport unwinds within a short grace and settles its own attempt evidence first. |
+| Attempt | `PLURNK_PROVIDERS_FETCH_TIMEOUT` | One physical generation request. A non-streamed request is bounded through response consumption; a streamed one only until its first semantic content. After content begins, stream-idle bounds silence and the operation deadline still bounds the whole call. | Surfaced `network_failure` with `timeoutPhase=attempt`; never transport-retried (#479) — the consumer's recovery owns re-issue. |
+| First content | `PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT` | Dispatch through first semantic model content ({§provider-first-content-at-dispatch}); metadata, empty deltas, and transport activity do not satisfy it. | Surfaced `network_failure` with `timeoutPhase=first_content`; never transport-retried (#479). |
 | Stream idle | `PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT` | Silence between semantic content chunks after content begins. | Surfaced `network_failure` with `timeoutPhase=stream_idle`; never transport-retried (#479). |
+| Repeated line | `PLURNK_PROVIDERS_REPEATED_LINE_LIMIT` | A streamed line of 16 or more characters repeated this many times; `0` disables. | Stopped as `repetition` ({§repetition-stop}); never transport-retried. |
+
+§provider-first-content-at-dispatch The first-content deadline is armed when the
+admitted attempt is dispatched, before response headers, so an endpoint that accepts
+the request and never answers fails at `timeoutPhase=first_content` instead of holding
+the attempt for the whole attempt deadline. It still begins only after admission
+({§provider-inference-admission}).
+
+Settled calls remove their deadline timers and cancellation subscriptions.
 
 Caller cancellation spans the operation and preserves the caller's reason.
 A 2xx exchange whose body cannot be processed (a provider invalid-response)
 classifies as the non-retryable 502 on the first failure unless an explicit
-`x-should-retry` directive says otherwise (#479 supersedes #446's budgeted
-promotion). Inner deadline failures surface on the first failure; when a
+`x-should-retry` directive says otherwise (#479). Inner deadline failures surface on the first failure; when a
 directive-driven retry sequence exhausts, `attempts` and `retryExhausted`
-are added and the classification is final. Every scheduler iteration opens and settles exactly
-one ordered {§provider-request-accounting} record, including response-less
-network failures and timed-out attempts.
+are added and the classification is final. Every admitted physical attempt opens
+and settles exactly one ordered {§provider-request-accounting} record, including
+response-less network failures and timed-out attempts. A cancelled or expired
+admission wait opens no physical request.
 
 Each streamed physical request assembles its own response. Failed partial answer
 bytes never enter a later request's completed `ProviderResponse`; recovery is a
@@ -715,6 +821,21 @@ ordinary 5xx surface on the first failure as consumer-recoverable kinds; one
 retry authority — the consumer's own provider-recovery machinery — owns
 re-issue, backoff, and park above the transport.
 
+§provider-output-dropped **A completed exchange whose own evidence proves its
+text never arrived is `output_dropped`**, a 502 carrying the complete response as
+`error.attempt` and `stage: "provider-response"`; it is never admitted as an empty or
+truncated turn, and the consumer re-issues it ({§provider-retryable-truth}):
+
+| Evidence | Detail | Facts |
+| --- | --- | --- |
+| `finish_reason` `tool_calls` (Plurnk never declares tools) | `The provider ended the response with tool calls although no tools were declared (N native tool call(s)); the response text was not delivered as text.` | `toolCallCount` |
+| Billed output tokens exceed the code points streamed across every channel — text and reasoning, before projection — by at least `PLURNK_PROVIDERS_DROPPED_OUTPUT_TOKENS` (`0` disables; an output token decodes to at least one character) | `The provider billed T output tokens but streamed C characters of text and reasoning; at least T−C tokens of output never arrived.` | `billedOutputTokens`, `streamedCharacters`, `droppedOutputTokens` |
+
+The token rule needs a billed output count, and it does not apply when the response bills
+reasoning tokens but streamed no reasoning in any channel: that is hidden or summarized
+reasoning, which the characters cannot account for. Text-only comparisons are not made —
+a route may bill reasoning inside its text count.
+
 §provider-request-rejection An HTTP 4xx rejection not classified as authorization,
 quota, capacity, grammar, rate limit, or transient transport failure is
 `request_rejected`: preserve the upstream status and detail, with `retryable: false`.
@@ -733,7 +854,7 @@ completed exchange.
 | 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` 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.     |
+| Automatic replay           | None inside the provider; AI SDK retry scheduling has already completed. The Problem has `retryable: true`: the consumer re-issues it ({§provider-retryable-truth}). |
 | 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.      |
 
@@ -777,19 +898,26 @@ by index with their arguments as streamed, the finish reasons seen, and the verb
 of every string field the record does not already hold. Nothing is opt-in and nothing is
 reinterpreted: a blank emission reads as thirteen chunks that carried nothing, or as a
 tool-call section the model emitted into a channel the protocol does not read, instead of
-being guessed at from token counts. Covered by `aiSdkTransport.test.ts`.
+being guessed at from token counts. Frames outside the recognized OpenAI-compatible
+envelope remain verbatim in `wire.unmappedChunks`; the recorder never discards an
+unrecognized/native payload or invents another provider parser. This required
+evidence is independent of the optional complete `rawBody` dataset capture.
+Covered by `aiSdkTransport.test.ts` and core's `Digest.wire-evidence.test.ts`.
 
 §provider-usage-refusal **The provider's bookkeeping is not the exchange.** Usage
-normalization is exact and refuses counters that contradict each other (a
-reasoning detail larger than its output aggregate, a total that disagrees with
-its parts). A refusal is not a request failure: the response is delivered, its
-accounting row carries no `usage` and a cost of kind `unknown` with the reason
-(never an invented, clamped, or zero counter), and the transport record keeps
-`usageRefusal` — the normalizer's reason beside the counters exactly as the
-wire reported them — so the digest can read what the provider said. The same
-holds for the usage inside failure evidence. Before this rule a contradictory
-counter turned a complete response into a retryable `network_failure` and lost
-the response (#580). Covered by `aiSdkTransport.test.ts` and
+normalization is exact; a refusal never fails or retries the response. The same
+rules apply to usage inside failure evidence:
+
+| Contradiction | Normalized evidence |
+| --- | --- |
+| Invalid aggregate or total inconsistent with its parts | No `usage`. |
+| Invalid optional counter | Omit that counter; retain independently valid quantities. |
+| Cache or reasoning breakdown inconsistent with its aggregate | Omit that breakdown; retain valid aggregates and the other breakdown. |
+
+Every refusal retains `usageRefusal`: the reason and the original wire counters.
+No value is clamped, zeroed, or estimated. Cost uses authoritative charges when
+available; catalog estimation requires all quantities its rates need, otherwise
+cost is `unknown`. Covered by `usage.test.ts`, `aiSdkTransport.test.ts`, and
 `AiSdkProvider.test.ts`.
 
 §provider-open-reasoning **Plurnk reads the model's own reasoning.** The service is
@@ -812,8 +940,9 @@ budget is a strict subset of that total, never an additive reserve. The
 configured total is a percentage of effective context or an absolute count;
 percentages resolve to the nearest whole token with a one-token minimum. It is
 capped by known context and model-output limits; `generate.maxOutputTokens` may
-only tighten it for one call. The effective reasoning subset tightens with that
-total and remains strictly smaller.
+only tighten this reservation for one call. The effective reasoning subset tightens
+with that total and remains strictly smaller. Exact prompt measurements may expand
+the response grant beyond the reservation under {§provider-flexed-allowance}.
 
 The adapter owns native projection. A backend whose generic SDK maximum already
 includes reasoning receives the total directly. When a native SDK instead adds
@@ -827,7 +956,7 @@ and provider minimum; an envelope too small to represent the minimum fails
 before provider I/O.
 
 §provider-output-budget-conformance When a completed response reports
-normalized output-token usage greater than its effective total output budget,
+normalized output-token usage greater than its response grant ({§provider-flexed-allowance}),
 the exchange is an `invalid_response` at 502 rather than an admitted result or
 a prompt-capacity 413. Its complete failed-attempt evidence and settled charged
 request remain available. The violation is final and is never automatically
@@ -840,7 +969,29 @@ limit advertises `requiresOutputBudget` and fails construction when no total can
 be resolved. The retired additive reserve knobs fail hard rather than creating
 a second envelope contract.
 
-## §13 Capacity pool
+## §13 Inference capacity
+
+### Admission
+
+§provider-inference-admission `PLURNK_PROVIDERS_MAX_CONCURRENCY` controls physical
+generation attempts per resolved endpoint within one process: `-1` is unrestricted;
+a positive safe integer admits that many concurrent attempts. It follows ordinary
+alias scoping. Zero, other negative values and non-integers are invalid.
+
+| Boundary | Contract |
+| --- | --- |
+| Identity | Provider instances and aliases sharing the resolved API base URL share one allowance. SDK/plugin-owned endpoints without a resolved URL share their provider identity. Conflicting limits for one identity fail construction, naming the identity and both values; they never create independent queues. The daemon reads its environment once at boot, so an identity's limit cannot change within a process: reconstructing a provider from that environment reuses its allowance, and in-flight leases keep counting. |
+| Admission | FIFO among live waiters. The lease begins before the physical request observer and ends after the complete response or transport failure settles, including streamed bodies. |
+| Cancellation | A queued abort removes that waiter and preserves the caller's reason. It opens no physical request or accounting row. In-flight cancellation signals the transport; capacity is released when that attempt unwinds. A transport still running despite abort does not authorize exceeding the limit. |
+| Retries | Backoff holds no lease. Each retry rejoins admission as a new physical attempt. |
+| Deadlines | The existing operation deadline includes queueing. Attempt, first-content and stream-idle deadlines begin only after admission; queued work is not a stalled stream. |
+| Scope | Workers, tools, messages, waits, token measurement and endpoint discovery are not serialized by inference admission. Independent endpoints progress independently. No cross-process or machine-wide capacity guarantee is implied. |
+
+Admission neither changes worker lifecycle nor selects another model or endpoint.
+Core consumes the same asynchronous Provider contract. A waiting worker holds no
+inference lease; BARE and ordinary generation use the same physical boundary.
+
+### Pool
 
 §provider-capacity-pool `Pool` fronts interchangeable `Provider` instances. It
 keeps workers sticky for
@@ -868,6 +1019,8 @@ Coverage MUST prove:
 - native SDK request mapping and normalized responses;
 - compatible extension preservation;
 - timeout, retry, cancellation, interrupted-attempt, and final-error behavior;
+- shared endpoint inference admission, FIFO queueing, queued/in-flight cancellation,
+  full-stream lease lifetime, retry release, and independent endpoint progress;
 - local capability probes and pins;
 - exact, bounded, estimated, and unavailable complete-request measurements;
 - independent input/context/output limits, asymmetric admission, and normalized

package/dist/AiSdkProvider.d.ts

@@ -1,14 +1,15 @@
-import type { ChatMessage, PromptTokenMeasurement, Provider, ProviderCostNormalizer, ProviderGenerateArgs, ProviderRequestCapacity, ProviderResponse, ProviderUsage, ReasoningPolicy } from "./types.ts";
+import type { ChatMessage, PromptTokenMeasurement, Provider, ProviderCostNormalizer, ProviderGenerateArgs, ProviderRequestCapacity, ProviderResponse, ProviderUsage, Effort } from "./types.ts";
 import type { ProviderCost } from "@plurnk/plurnk-contracts";
 import type { JSONValue } from "ai";
-import { type Reasoning, type ReasoningResponseStyle } from "./env.ts";
+import type { EffortSetting, ReasoningResponseStyle } from "./env.ts";
 import type { InputModality } from "./types.ts";
 import type { LanguageModel } from "ai";
 import type { PluginAttribution, PluginAttributionContext } from "@plurnk/plurnk-meta";
+import type RequestFields from "./RequestFields.ts";
+import type InferenceAdmission from "./InferenceAdmission.ts";
 export type ProviderFetch = typeof globalThis.fetch;
-export type ReasoningStyle = "none" | "think" | "include_reasoning" | "effort" | "effort_explicit" | "effort_required" | "thinking_effort" | "template" | "anthropic";
-export type NativeReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
-export type CompatibleReasoningEffort = NativeReasoningEffort | "max";
+export type ReasoningStyle = "none" | "think" | "template";
+export type NativeEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
 export type GrammarStyle = "none" | "llamacpp";
 export type CacheAffinity = {
     readonly target: "header" | "body";
@@ -20,6 +21,7 @@ export type CacheAffinity = {
 };
 export type AiSdkProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
 export type AiSdkProviderConfig = {
+    inferenceAdmission?: InferenceAdmission;
     model: string;
     url?: string;
     languageModel?: LanguageModel;
@@ -28,6 +30,8 @@ export type AiSdkProviderConfig = {
     operationTimeoutMs: number;
     firstContentTimeoutMs: number;
     streamIdleTimeoutMs?: number;
+    repeatedLineLimit?: number;
+    droppedOutputTokens?: number;
     headers?: Record<string, string>;
     fetch?: ProviderFetch;
     contextWindow?: number | null;
@@ -36,14 +40,12 @@ export type AiSdkProviderConfig = {
     maxOutputTokens?: number | null;
     outputBudget?: number | null;
     reasoningBudget?: number | null;
-    supportedReasoningPolicies?: readonly ReasoningPolicy[];
-    adaptiveReasoning?: NativeReasoningEffort | "provider-default";
-    reasoningToggle?: boolean;
-    compatibleAdaptiveReasoning?: CompatibleReasoningEffort | "provider-default";
-    compatibleOffReasoning?: "none";
-    adaptiveReasoningProviderOptions?: AiSdkProviderOptions;
+    supportedEfforts?: readonly Effort[];
+    adaptiveEffort?: NativeEffort | "provider-default";
+    adaptiveEffortProviderOptions?: AiSdkProviderOptions;
     additiveReasoningProvider?: "anthropic" | "bedrock";
     reasoningStyle?: ReasoningStyle;
+    requestFields?: RequestFields;
     reasoningResponseStyle?: ReasoningResponseStyle;
     countPromptTokens?: (messages: readonly ChatMessage[], signal?: AbortSignal) => PromptTokenMeasurement | Promise<PromptTokenMeasurement>;
     estimateCost?: (usage: ProviderUsage | undefined) => ProviderCost;
@@ -63,8 +65,12 @@ export type AiSdkProviderConfig = {
     promptTokensUrl?: string;
     servedModel?: string;
     requiresOutputBudget?: boolean;
-    reasoning: Reasoning;
+    effort: EffortSetting;
     temperature: number | null;
+    topP?: number;
+    topK?: number;
+    presencePenalty?: number;
+    seed?: number;
     repeatPenalty: number | null;
     frequencyPenalty?: number;
     dryMultiplier?: number;
@@ -87,7 +93,7 @@ export default class AiSdkProvider implements Provider {
     get maxOutputTokens(): number | null;
     get outputBudget(): number | null;
     get reasoningBudget(): number | null;
-    get supportedReasoningPolicies(): readonly ReasoningPolicy[];
+    get supportedEfforts(): readonly Effort[];
     get inputCapacity(): number | null;
     get model(): string;
     get servedModel(): string | undefined;