@plurnk/plurnk-providers 1.5.0 → 1.6.1

package/.env.defaults

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

package/README.md

@@ -21,6 +21,21 @@ reasoning activation, and estimated prices resolve independently
 ({§model-fact-resolution}). PLURNK does not fetch live per-token prices, and the
 local estimate is not an authoritative relay-settled charge.
 
+## Runtime-neutral accounting
+
+Browser and edge Workers import the accounting contract through its dedicated
+runtime-neutral subpath ({§provider-runtime-neutral-accounting}):
+
+```js
+import {
+  aggregateProviderAccounting,
+  estimateProviderCost,
+} from "@plurnk/plurnk-providers/accounting";
+```
+
+The package root composes the complete Node provider runtime, including plugin
+discovery and environment-file defaults.
+
 ## Configure a model
 
 Declare an alias, then select it: