@plurnk/plurnk-providers 1.21.1 → 1.22.0

package/.env.defaults

@@ -11,11 +11,15 @@
 # PLURNK_MODEL_local=openai/model-name-from-endpoint
 # PLURNK_BASEURL_local=http://127.0.0.1:8080/v1
 # PLURNK_MODEL=cloud
-# PLURNK_MODEL=google/gemini-3-flash
+# PLURNK_MODEL=deepseek/deepseek-v4-flash
 
 # --- Capacity ---
-# Total output envelope INCLUDING reasoning: positive tokens or context percentage in (0,100).
-# Known model limits cap it. Must leave input capacity; the context budget is derived, not set here.
+# Simultaneous inference attempts per resolved endpoint in this process; -1 = unrestricted.
+# Positive limits queue excess calls. Aliases sharing an endpoint must agree on its limit.
+PLURNK_PROVIDERS_MAX_CONCURRENCY=-1
+# PLURNK_PROVIDERS_MAX_CONCURRENCY_local=1
+# Reserved output INCLUDING reasoning: positive tokens or context percentage in (0,100).
+# Known model limits cap it; input capacity is derived. Exact-counting calls may grant unused context.
 PLURNK_PROVIDERS_OUTPUT_BUDGET=35%
 # Optional reasoning subset of output, using the same units; must be smaller than total output.
 # Unset/empty = provider-adaptive budget, not reasoning off.
@@ -26,16 +30,29 @@ PLURNK_PROVIDERS_OUTPUT_BUDGET=35%
 
 # --- Reasoning ---
 # off | adaptive | low | medium | high | xhigh | max. Seed for durable Worker reasoning.
-# adaptive uses native dynamic reasoning where supported, otherwise the supported high posture.
-PLURNK_PROVIDERS_REASONING=adaptive
+# adaptive prefers native dynamic reasoning, then the supported fallback below.
+PLURNK_PROVIDERS_EFFORT=adaptive
+# Fixed effort when native adaptation is unavailable; empty/unsupported = enabled provider default.
+PLURNK_PROVIDERS_EFFORT_FALLBACK=high
 # Response interpretation: verbatim = trust structured reasoning fields; think-tags = extract one
 # leading <think> envelope. Select only for an endpoint that emits it; independent of activation.
 PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE=verbatim
-# Reasoning wire for one route, over PLURNK_PROVIDERS_PROVIDER_<NAME>_REASONING_STYLE; usually
-# alias-scoped. thinking_config = Gemini through an OpenAI-compatible endpoint (readable thoughts,
-# levels low/medium/high, no off). Empty = the provider's declaration.
-# PLURNK_PROVIDERS_REASONING_STYLE=
-# PLURNK_PROVIDERS_REASONING_STYLE_<alias>=thinking_config
+# Compatible wire declarations below supplement Models.dev; native SDKs own their protocols.
+# Route knobs use the same suffix, e.g. PLURNK_PROVIDERS_REASONING_BUDGET_PATH_<alias>.
+# PLURNK_PROVIDERS_OUTPUT_PATH_<alias>=/max_completion_tokens
+# PLURNK_PROVIDERS_REASONING_EFFORT_PATH_<alias>=/reasoning_effort
+# PLURNK_PROVIDERS_REASONING_CONTROLS_<alias>=exclusive
+# PLURNK_PROVIDERS_REASONING_ON_BODY_<alias>='{"enable_thinking":true}'
+# PLURNK_PROVIDERS_REASONING_OFF_BODY_<alias>='{"enable_thinking":false}'
+# PLURNK_PROVIDERS_REASONING_EFFORTS_<alias>=low,medium,high
+# PLURNK_PROVIDERS_REASONING_TRANSPORT_EFFORTS_<alias>=none,low,medium,high
+# PLURNK_PROVIDERS_OPTIONS_NAMESPACE_<alias>=openrouter
+# PLURNK_PROVIDERS_REASONING_ADAPTIVE_BODY_<alias>='{}'
+# PLURNK_PROVIDERS_REASONING_TOGGLE_BODY_<alias>='{"reasoning":{"enabled":true}}'
+# PLURNK_PROVIDERS_ADAPTIVE_OPTIONS_<alias>='[{"models":["*"],"options":{"<sdk-namespace>":{…}}}]'
+# PLURNK_PROVIDERS_SYSTEM_CACHE_OPTIONS_<alias>=
+# PLURNK_PROVIDERS_APP_URL_<alias>=https://example.test/app
+# PLURNK_PROVIDERS_APP_NAME_<alias>=Example
 
 # --- Sampling ---
 # Temperature; empty = omit, retaining the provider's sampling default.
@@ -64,7 +81,15 @@ PLURNK_PROVIDERS_DRY_MULTIPLIER=0
 # --- Cache and billing ---
 # Stable Worker affinity on supported routes: 1 = on; 0 = off. Unknown routes get no guessed field.
 PLURNK_PROVIDERS_CACHE_AFFINITY=1
-# Explicit cache writes: stable-system = reusable system boundary on supported Claude routes;
+# FIELD declares placement, independent of the enable switch; null clears it for an alias.
+# target is header or body with name, or provider-option with provider and name.
+# PLURNK_PROVIDERS_CACHE_AFFINITY_FIELD_<alias>='{"target":"header","name":"x-session-id"}'
+PLURNK_PROVIDERS_PROVIDER_OPENAI_CACHE_AFFINITY_FIELD='{"target":"provider-option","provider":"openai","name":"promptCacheKey"}'
+PLURNK_PROVIDERS_PROVIDER_DEEPINFRA_CACHE_AFFINITY_FIELD='{"target":"provider-option","provider":"deepinfra","name":"prompt_cache_key"}'
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_CACHE_AFFINITY_FIELD='{"target":"header","name":"x-session-id"}'
+PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_CACHE_AFFINITY_FIELD='{"target":"header","name":"x-session-affinity"}'
+PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_CACHE_AFFINITY_FIELD='{"target":"header","name":"x-session-affinity"}'
+# Explicit cache writes: stable-system = reusable system boundary where SYSTEM_CACHE_OPTIONS declares it;
 # off = no explicit writes. This is distinct from affinity and can affect billing.
 PLURNK_PROVIDERS_CACHE_WRITE_POLICY=stable-system
 # Provider service tier; unset = provider default. Usually set per alias: routing can change cost.
@@ -75,14 +100,21 @@ PLURNK_PROVIDERS_CACHE_WRITE_POLICY=stable-system
 # PLURNK_PROVIDERS_COST=input=0.22,output=0.66,reasoning=0.66,cacheRead=0.007
 
 # --- Connectivity (milliseconds; each deadline accepts 0 = off) ---
-# Logical generation deadline, including physical attempts and retry delays.
+# Logical generation deadline, including admission queues, physical attempts and retry delays.
 PLURNK_PROVIDERS_OPERATION_TIMEOUT=2700000
 # Deadline per physical generation attempt; a streamed attempt is bounded only until content flows.
 PLURNK_PROVIDERS_FETCH_TIMEOUT=600000
-# Wait from stream start to first semantic content; metadata/empty deltas do not count.
+# Wait from dispatch (after admission, before response headers) to first semantic content;
+# metadata/empty deltas do not count.
 PLURNK_PROVIDERS_FIRST_CONTENT_TIMEOUT=180000
 # Maximum silence between semantic content chunks after content begins.
 PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT=120000
+# A line of 16+ characters streamed this many times stops the response as a repetition; 0 = off.
+PLURNK_PROVIDERS_REPEATED_LINE_LIMIT=32
+# A response billed for this many more output tokens than it streamed characters (text and reasoning)
+# never delivered its output; it fails as output_dropped and is re-issued (a tool-call finish always
+# does). Reasoning billed but not streamed is exempt. 0 = off.
+PLURNK_PROVIDERS_DROPPED_OUTPUT_TOKENS=32
 # Retries for 429, Retry-After, or X-Should-Retry:true; 0 = none. Other failures return immediately
 # to Core's separate recovery window. Retry-After takes precedence over backoff.
 PLURNK_PROVIDERS_RETRY_ATTEMPTS=3
@@ -112,14 +144,60 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
 # PLURNK_PROVIDERS_PROVIDER_ACME_NPM=@ai-sdk/openai-compatible
 # PLURNK_PROVIDERS_PROVIDER_ACME_BASE_URL=https://api.acme.example/v1
 # PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV=ACME_API_KEY
-# Reasoning wire adaptations that are not expressed by catalog metadata:
-# Fireworks requires an explicit off effort; Cloudflare graded models require an effort.
-PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_STYLE=effort_explicit
-PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_STYLE=effort_required
+# Compatible request fields use RFC 6901 pointers; output defaults to the SDK's max_tokens.
+# Effort vocabulary and budget bounds come from Models.dev; EFFORTS adds declared values.
+# ON_BODY applies whenever reasoning is active. OFF_BODY disables it. ADAPTIVE_BODY replaces
+# the graded fallback; {} leaves the enabled endpoint at its native default.
+# TOGGLE_BODY enables a catalog toggle when no adaptive body or supported fallback applies.
+# Bodies contain only reasoning controls, not model/messages, sampling, or token ceilings.
+# With both paths declared, CONTROLS must say exclusive or combined. Fixed effort plus a numeric
+# budget on an exclusive route fails before inference; adaptive + budget selects the numeric dial.
+# PLURNK_PROVIDERS_PROVIDER_ACME_OUTPUT_PATH=/max_completion_tokens
+# PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_EFFORT_PATH=/reasoning/effort
+# PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_BUDGET_PATH=/reasoning/max_tokens
+# PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_CONTROLS=exclusive
+# PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_EFFORTS=low,medium,high
+# PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_ON_BODY='{"reasoning":{"enabled":true}}'
+# PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_OFF_BODY='{"reasoning":{"enabled":false}}'
+# PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_ADAPTIVE_BODY='{}'
+PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_EFFORT_PATH=/reasoning_effort
+PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_OFF_BODY='{"reasoning_effort":"none"}'
+PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_TOGGLE_BODY='{"reasoning_effort":true}'
+PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_EFFORT_PATH=/reasoning_effort
 # Additional supported Cloudflare effort values, comma-separated; empty = Models.dev only.
 PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_EFFORTS=
 # Direct DeepSeek thinking activation and effort.
-PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_STYLE=thinking_effort
+PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_EFFORT_PATH=/reasoning_effort
+PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_ON_BODY='{"thinking":{"type":"enabled"}}'
+PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_OFF_BODY='{"thinking":{"type":"disabled"}}'
+# OpenRouter's native SDK accepts these same fields in per-call provider options.
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_OPTIONS_NAMESPACE=openrouter
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_EFFORT_PATH=/reasoning/effort
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_BUDGET_PATH=/reasoning/max_tokens
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_CONTROLS=exclusive
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_TRANSPORT_EFFORTS=none,minimal,low,medium,high,xhigh,max
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_ON_BODY='{"reasoning":{"enabled":true}}'
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_OFF_BODY='{"reasoning":{"effort":"none"}}'
+# DeepInfra's and Together's native SDKs extend openai-compatible, which overwrites a raw `reasoning_effort`
+# option; the effort rides the SDK's own `reasoningEffort`, so every catalog effort, max included, reaches the wire.
+PLURNK_PROVIDERS_PROVIDER_DEEPINFRA_OPTIONS_NAMESPACE=deepinfra
+PLURNK_PROVIDERS_PROVIDER_DEEPINFRA_REASONING_EFFORT_PATH=/reasoningEffort
+PLURNK_PROVIDERS_PROVIDER_DEEPINFRA_REASONING_OFF_BODY='{"reasoningEffort":"none"}'
+PLURNK_PROVIDERS_PROVIDER_TOGETHERAI_OPTIONS_NAMESPACE=togetherai
+PLURNK_PROVIDERS_PROVIDER_TOGETHERAI_REASONING_EFFORT_PATH=/reasoningEffort
+PLURNK_PROVIDERS_PROVIDER_TOGETHERAI_REASONING_OFF_BODY='{"reasoningEffort":"none"}'
+# Model-family provider options: a JSON array of {"models":["<glob>",…],"options":{…}} rules matched
+# against the route's model id, first match wins ({§provider-model-options}). ADAPTIVE_OPTIONS replaces the
+# adaptive policy's projection; SYSTEM_CACHE_OPTIONS marks the stable system prompt for cache writes.
+# None ship: the shipped defaults serve open models only; declare a closed family's options yourself.
+# Alibaba DashScope (OpenAI-compatible): max_tokens is answer-only, max_completion_tokens is inclusive;
+# effort and thinking budget are alternatives; enable_thinking switches reasoning.
+PLURNK_PROVIDERS_PROVIDER_ALIBABA_OUTPUT_PATH=/max_completion_tokens
+PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_EFFORT_PATH=/reasoning_effort
+PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_BUDGET_PATH=/thinking_budget
+PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_CONTROLS=exclusive
+PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_ON_BODY='{"enable_thinking":true}'
+PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_OFF_BODY='{"enable_thinking":false}'
 # Uncataloged compatible providers: SDK, endpoint, and credential-variable name.
 PLURNK_PROVIDERS_PROVIDER_BAICHUAN_NPM=@ai-sdk/openai-compatible
 PLURNK_PROVIDERS_PROVIDER_BAICHUAN_BASE_URL=https://api.baichuan-ai.com/v1
@@ -132,8 +210,8 @@ PLURNK_PROVIDERS_PROVIDER_QIANFAN_API_KEY_ENV=QIANFAN_API_KEY
 # OpenAI-compatible fallback endpoint; PLURNK_BASEURL_<alias> overrides it for one declared alias.
 OPENAI_BASE_URL=https://api.openai.com/v1
 
-# --- OpenRouter application attribution ---
-# Public application URL; empty suppresses attribution, including the title.
-OPENROUTER_HTTP_REFERER=https://github.com/plurnk/plurnk-service
-# Application display name, sent only with a nonempty URL.
-OPENROUTER_APP_TITLE=Plurnk
+# --- Application attribution (routes on the OpenRouter SDK) ---
+# Public application URL the SDK sends as HTTP-Referer; empty suppresses attribution, including the name.
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_APP_URL=https://github.com/plurnk/plurnk-service
+# Application display name the SDK sends as X-OpenRouter-Title, only with a nonempty URL.
+PLURNK_PROVIDERS_PROVIDER_OPENROUTER_APP_NAME=Plurnk

package/README.md

@@ -47,16 +47,16 @@ discovery and environment-file defaults.
 Select a catalog route directly:
 
 ```dotenv
-PLURNK_MODEL=google/gemini-3-flash
-GEMINI_API_KEY=...
+PLURNK_MODEL=deepseek/deepseek-v4-flash
+DEEPSEEK_API_KEY=...
 ```
 
 Declare an alias when the route needs a reusable name or scoped tuning:
 
 ```dotenv
-PLURNK_MODEL_fast=openai/gpt-5-mini
+PLURNK_MODEL_fast=deepinfra/zai-org/GLM-5.3-Flash
 PLURNK_MODEL=fast
-OPENAI_API_KEY=...
+DEEPINFRA_API_KEY=...
 ```
 
 Cataloged providers need no endpoint declaration. To add an
@@ -108,8 +108,9 @@ flowchart TD
 ```
 
 - **Effort** and **budget** are independent. `adaptive` requests native dynamic
-  reasoning where supported, otherwise the supported high posture. Fixed effort
-  names must be supported by the route; an unsupported request is not silently downgraded.
+  reasoning where supported, otherwise `PLURNK_PROVIDERS_EFFORT_FALLBACK`
+  (default `high`). An unavailable fallback retains the reasoning-enabled provider default.
+  Fixed effort names must be supported by the route; unsupported requests are not silently downgraded.
 - **Output** accepts positive tokens or a percentage of context; known model
   limits cap it. An explicit reasoning budget must be smaller than total output.
   Leaving the reasoning budget unset does not disable reasoning.
@@ -166,6 +167,8 @@ PLURNK_MODEL=local
 # Optional explicit generation allowances, in tokens:
 # PLURNK_PROVIDERS_OUTPUT_BUDGET_local=8192
 # PLURNK_PROVIDERS_REASONING_BUDGET_local=4096
+# Optional: serialize inference on a single-slot endpoint without serializing workers:
+# PLURNK_PROVIDERS_MAX_CONCURRENCY_local=1
 ```
 
 Endpoint probing supplies served-model capacity and llama-server capabilities.
@@ -184,6 +187,7 @@ opt-in for endpoints that emit a leading `<think>` envelope, not a reasoning swi
 
 | Concern | Boundary |
 | --- | --- |
+| Inference concurrency | Optional per-endpoint, process-local admission; queued calls remain cancellable. The default is unrestricted ({§provider-inference-admission}). |
 | Attempt, first-content, idle deadlines | Provider transport; a timeout surfaces a failure, not a fabricated response. |
 | Provider-directed waits | Bounded retries honor `Retry-After`; other recoverable failures return to Core. |
 | Loop recovery | Core reissues within its recovery window, then parks for a prompt or wake. |

package/SPEC.md

@@ -261,8 +261,8 @@ PLURNK maps its generic settings to AI SDK call settings:
 - 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.
@@ -277,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
@@ -315,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 |
@@ -345,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:
 
@@ -383,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
@@ -458,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. |
@@ -554,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
 
@@ -599,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
@@ -622,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
 
@@ -642,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
@@ -716,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
@@ -748,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`.
@@ -766,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.      |
 
@@ -852,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
@@ -867,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
@@ -880,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
@@ -908,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