@plurnk/plurnk-providers 6.1.0 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/.env.defaults +7 -7
  2. package/README.md +31 -213
  3. package/SPEC.md +15 -10
  4. package/dist/InferenceAdmission.d.ts +10 -1
  5. package/dist/InferenceAdmission.d.ts.map +1 -1
  6. package/dist/InferenceAdmission.js +79 -15
  7. package/dist/InferenceAdmission.js.map +1 -1
  8. package/dist/LeadingReasoning.js.map +1 -1
  9. package/dist/Mock.d.ts +5 -1
  10. package/dist/Mock.d.ts.map +1 -1
  11. package/dist/Mock.js +7 -1
  12. package/dist/Mock.js.map +1 -1
  13. package/dist/ModelProvider.d.ts +8 -3
  14. package/dist/ModelProvider.d.ts.map +1 -1
  15. package/dist/ModelProvider.js +14 -8
  16. package/dist/ModelProvider.js.map +1 -1
  17. package/dist/ModelRequestBody.js.map +1 -1
  18. package/dist/Pool.d.ts +2 -0
  19. package/dist/Pool.d.ts.map +1 -1
  20. package/dist/Pool.js +8 -0
  21. package/dist/Pool.js.map +1 -1
  22. package/dist/ProviderRegistry.d.ts.map +1 -1
  23. package/dist/ProviderRegistry.js +5 -10
  24. package/dist/ProviderRegistry.js.map +1 -1
  25. package/dist/RequestCapture.js.map +1 -1
  26. package/dist/accounting.js.map +1 -1
  27. package/dist/accountingPublic.js.map +1 -1
  28. package/dist/capacity.js.map +1 -1
  29. package/dist/catalogProvider.d.ts +3 -3
  30. package/dist/catalogProvider.d.ts.map +1 -1
  31. package/dist/catalogProvider.js +5 -4
  32. package/dist/catalogProvider.js.map +1 -1
  33. package/dist/compatibleProvider.d.ts.map +1 -1
  34. package/dist/compatibleProvider.js +6 -3
  35. package/dist/compatibleProvider.js.map +1 -1
  36. package/dist/cost.js.map +1 -1
  37. package/dist/defaults.js.map +1 -1
  38. package/dist/discover.d.ts +0 -2
  39. package/dist/discover.d.ts.map +1 -1
  40. package/dist/discover.js +2 -8
  41. package/dist/discover.js.map +1 -1
  42. package/dist/env.d.ts +4 -2
  43. package/dist/env.d.ts.map +1 -1
  44. package/dist/env.js +26 -4
  45. package/dist/env.js.map +1 -1
  46. package/dist/errors.js.map +1 -1
  47. package/dist/index.d.ts +4 -2
  48. package/dist/index.d.ts.map +1 -1
  49. package/dist/index.js +2 -1
  50. package/dist/index.js.map +1 -1
  51. package/dist/modelAdapters.d.ts +2 -2
  52. package/dist/modelAdapters.d.ts.map +1 -1
  53. package/dist/modelAdapters.js +68 -4
  54. package/dist/modelAdapters.js.map +1 -1
  55. package/dist/notices.js.map +1 -1
  56. package/dist/ollama.js.map +1 -1
  57. package/dist/openai.js.map +1 -1
  58. package/dist/pi-transport.d.ts +6 -3
  59. package/dist/pi-transport.d.ts.map +1 -1
  60. package/dist/pi-transport.js +436 -38
  61. package/dist/pi-transport.js.map +1 -1
  62. package/dist/promptTokens.js.map +1 -1
  63. package/dist/provider-env.js.map +1 -1
  64. package/dist/providerError.js.map +1 -1
  65. package/dist/reasoning-effort.js.map +1 -1
  66. package/dist/retry-deadline.js.map +1 -1
  67. package/dist/stream-forensics.d.ts.map +1 -1
  68. package/dist/stream-forensics.js +70 -0
  69. package/dist/stream-forensics.js.map +1 -1
  70. package/dist/types.d.ts +10 -0
  71. package/dist/types.d.ts.map +1 -1
  72. package/dist/types.js.map +1 -1
  73. package/dist/usage.js.map +1 -1
  74. package/dist/warnings.js.map +1 -1
  75. package/docs/models.md +7 -17
  76. package/package.json +5 -5
package/.env.defaults CHANGED
@@ -16,8 +16,9 @@
16
16
  # PLURNK_BASEURL_<alias>=<url>
17
17
 
18
18
  # --- Capacity ---
19
- # Simultaneous inference attempts per resolved endpoint in this process; -1 = unrestricted.
20
- # Positive limits queue excess calls. Aliases sharing an endpoint must agree on its limit.
19
+ # Simultaneous inference attempts per resolved endpoint in this process; -1 = unrestricted, or
20
+ # bounded automatically by probed physical slot capacity (e.g. llama-server GET /props total_slots).
21
+ # Positive limits queue excess calls and are capped by probed physical slots.
21
22
  PLURNK_PROVIDERS_MAX_CONCURRENCY=-1
22
23
  # PLURNK_PROVIDERS_MAX_CONCURRENCY_local=1
23
24
  # Reserved output INCLUDING reasoning: positive tokens or context percentage in (0,100).
@@ -77,9 +78,10 @@ PLURNK_PROVIDERS_DRY_MULTIPLIER=0
77
78
  # --- Cache and billing ---
78
79
  # Stable Session affinity on supported routes: 1 = on; 0 = off. Unknown routes get no guessed field.
79
80
  PLURNK_PROVIDERS_CACHE_AFFINITY=1
80
- # Explicit cache writes: stable-system = reusable system boundary on routes whose adapter supports it;
81
- # off = no explicit writes. This is distinct from affinity and can affect billing.
82
- PLURNK_PROVIDERS_CACHE_WRITE_POLICY=stable-system
81
+ # Explicit cache writes on explicit-breakpoint routes (Anthropic, MiniMax Anthropic, OpenRouter Anthropic, Bedrock Claude, OpenAI GPT-5.6+):
82
+ # conversation = system + rolling conversation/log prefix before volatile turn status;
83
+ # stable-system = reusable system boundary only; off = no explicit writes (suppresses paid implicit writes on OpenAI GPT-5.6+). Distinct from affinity and affects billing.
84
+ PLURNK_PROVIDERS_CACHE_WRITE_POLICY=conversation
83
85
  # Provider service tier; unset = provider default. Usually set per alias: routing can change cost.
84
86
  # Native routes send it only where the SDK documents one ({§provider-request-authority}); others warn.
85
87
  # PLURNK_PROVIDERS_SERVICE_TIER=
@@ -129,8 +131,6 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
129
131
  # PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_EFFORTS=low,medium,high
130
132
  # The form of every provider declaration; NAME is the route's provider segment.
131
133
  # PLURNK_PROVIDERS_PROVIDER_<NAME>_<SETTING>=<value>
132
- # Additional supported Cloudflare effort values, comma-separated; empty = Models.dev only.
133
- PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_EFFORTS=
134
134
  # Uncataloged compatible providers: adapter, endpoint, and credential-variable name.
135
135
  PLURNK_PROVIDERS_PROVIDER_BAICHUAN_ADAPTER=openai-compatible
136
136
  PLURNK_PROVIDERS_PROVIDER_BAICHUAN_BASE_URL=https://api.baichuan-ai.com/v1
package/README.md CHANGED
@@ -1,254 +1,72 @@
1
1
  # @plurnk/plurnk-providers
2
2
 
3
- PLURNK's stable model-provider contract and its transport adapters over
4
- `@earendil-works/pi-ai` and OpenAI-compatible HTTP endpoints.
3
+ Model-provider contract and transport adapters over `@earendil-works/pi-ai` and OpenAI-compatible HTTP endpoints. Native tool calling is disabled across protocols; PLURNK operations travel as text ({§provider-interface}).
5
4
 
6
- Ordinary provider behavior is intentionally not reimplemented here:
5
+ - **Contract:** [`SPEC.md`](SPEC.md)
6
+ - **Model-facing reference:** [`docs/models.md`](docs/models.md)
7
+ - **Operator panel:** [`.env.defaults`](.env.defaults) (`PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT` bounds upstream error detail)
7
8
 
8
- - A release-time Models.dev snapshot supplies provider adapter, endpoint, and
9
- credential names, plus context-window, output-limit, reasoning-capability,
10
- and pricing metadata.
11
- - Protocol adapters own vendor request and response protocols.
12
- - PLURNK owns aliases, generation envelopes, normalized usage and errors,
13
- evidence capture, first-party metadata, and local endpoint capabilities.
14
-
15
- Native tool calling is explicitly disabled through each protocol's standard
16
- controls; PLURNK operations travel as text ({§provider-interface}).
17
-
18
- See [SPEC.md](SPEC.md) for the contract, [the model reference](docs/models.md)
19
- for what a model is told about routes and generation, and
20
- [.env.defaults](.env.defaults) for every knob.
21
- The package-owned `PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT` bounds upstream
22
- diagnostic text in public provider Problems.
23
-
24
- Model facts do not share one fallback chain. Context windows, output envelopes,
25
- reasoning activation, and estimated prices resolve independently
26
- ({§model-fact-resolution}). PLURNK does not fetch live per-token prices, and the
27
- local estimate is not an authoritative relay-settled charge.
28
- Router accounting includes separately billed BYOK inference, not merely the
29
- router fee; incomplete billing evidence remains unknown ({§provider-monetary-evidence}).
30
-
31
- ## Runtime-neutral contracts
32
-
33
- Browser and edge Sessions import accounting and normalized failures through
34
- their dedicated runtime-neutral subpaths
35
- ({§provider-interface}):
9
+ ## Subpaths
36
10
 
37
11
  ```js
38
- import {
39
- aggregateProviderAccounting,
40
- estimateProviderCost,
41
- } from "@plurnk/plurnk-providers/accounting";
12
+ import { aggregateProviderAccounting, estimateProviderCost } from "@plurnk/plurnk-providers/accounting";
42
13
  import { ProviderError } from "@plurnk/plurnk-providers/errors";
43
14
  ```
44
15
 
45
- The package root composes the complete Node provider runtime, including extension
46
- discovery and environment-file defaults.
16
+ Root entry composes the Node runtime, extension discovery, and `.env.defaults`; `/accounting` and `/errors` are runtime-neutral ({§provider-interface}).
47
17
 
48
18
  ## Configure a model
49
19
 
50
- Select a catalog route directly:
51
-
52
- ```dotenv
53
- PLURNK_MODEL=deepseek/deepseek-v4-flash
54
- DEEPSEEK_API_KEY=...
55
- ```
56
-
57
- Declare an alias when the route needs a reusable name or scoped tuning:
20
+ Run `plurnk onboard` for interactive setup, or keep route selectors in `~/.config/plurnk/.env` and credentials in the shell / `~/.config/environment.d/*.conf`:
58
21
 
59
22
  ```dotenv
23
+ # ~/.config/plurnk/.env
60
24
  PLURNK_MODEL_fast=deepinfra/zai-org/GLM-5.3-Flash
61
- PLURNK_MODEL=fast
62
- DEEPINFRA_API_KEY=...
25
+ PLURNK_MODEL=deepseek/deepseek-v4-flash
63
26
  ```
64
27
 
65
- Cataloged providers need no endpoint declaration. To add an
66
- OpenAI-compatible provider that Models.dev does not describe:
67
-
68
- ```dotenv
69
- PLURNK_PROVIDERS_PROVIDER_ACME_ADAPTER=openai-compatible
70
- PLURNK_PROVIDERS_PROVIDER_ACME_BASE_URL=https://api.acme.example/v1
71
- PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV=ACME_API_KEY
72
- PLURNK_MODEL_acme=acme/model-id
28
+ ```sh
29
+ # Login shell or user service environment (never in .env)
30
+ export DEEPSEEK_API_KEY="..."
31
+ export DEEPINFRA_API_KEY="..."
73
32
  ```
74
33
 
75
- Provider declarations are configuration, not secrets. Secret values remain in
76
- the operator environment.
77
-
78
- The forms, in one table:
79
-
80
34
  | Form | Meaning |
81
35
  | --- | --- |
82
- | `PLURNK_MODEL=provider/model` | Select a route without an alias. |
83
- | `PLURNK_MODEL_<alias>=provider/model` | Declare a named route and tuning scope. |
84
- | `PLURNK_BASEURL_<alias>=https://endpoint/v1` | Override that declared alias's endpoint. |
85
- | `PLURNK_PROVIDERS_<KNOB>_<alias>=value` | Nonempty per-alias override of the bare knob; alias case is ignored. |
86
- | `PLURNK_PROVIDERS_PROVIDER_<NAME>_*` | Provider-wide declaration, not per-alias tuning. |
87
-
88
- Models.dev supplies cataloged providers' endpoints, credential-variable names,
89
- model limits, reasoning capabilities, and rates. The operator supplies
90
- credentials to the service environment; a client's environment does not
91
- configure a remote daemon. Session model and reasoning selections persist:
92
- changing a startup default is not a command to retarget existing Sessions.
93
- Clients expose explicit model, reasoning, and child-model controls; their
94
- available effort choices come from the selected route.
95
-
96
- Sampling uses endpoint defaults unless configured. `TEMPERATURE`, `TOP_P`,
97
- `TOP_K`, `PRESENCE_PENALTY`, `FREQUENCY_PENALTY`, and `SEED` use the same
98
- `PLURNK_PROVIDERS_<KNOB>_<alias>` form. Supported values depend on the endpoint;
99
- Models.dev does not supply a recommended sampling profile. See the
100
- [sampling contract](SPEC.md) ({§provider-configuration}) and
101
- [environment panel](.env.defaults) for ranges and omission rules.
102
-
103
- ## Capacity and reasoning
104
-
105
- ```mermaid
106
- flowchart TD
107
- Limits[Model context and input/output limits] --> Input[Available input capacity]
108
- Output[Total output envelope, including reasoning] --> Input
109
- Input --> Context[Core's calibrated context allowance]
110
- Output --> Reasoning[Optional smaller reasoning budget]
111
- ```
112
-
113
- - **Effort** and **budget** are independent. `adaptive` requests native dynamic
114
- reasoning where supported, otherwise `PLURNK_PROVIDERS_EFFORT_FALLBACK`
115
- (default `high`). An unavailable fallback retains the reasoning-enabled provider default.
116
- Fixed effort names must be supported by the route; unsupported requests are not silently downgraded.
117
- - **Output** accepts positive tokens or a percentage of context; known model
118
- limits cap it. An explicit reasoning budget must be smaller than total output.
119
- Leaving the reasoning budget unset does not disable reasoning.
120
- - **Output floor** (`PLURNK_PROVIDERS_OUTPUT_FLOOR`, shipped `25%`) is the least
121
- response room any request keeps, never above the output budget. The window less
122
- the floor is the input wall: a packet past the budget is still sent with its
123
- grant flexed down to the remainder; only a packet past the wall cannot be sent
124
- ({§provider-capacity-admission}).
125
- - **Context** is derived from the live endpoint or catalog. An operator cap can
126
- shrink known capacity or declare unknown capacity, never enlarge known limits.
127
- Prompt projection and initialization reasoning READ limits are separate Core policy.
128
-
129
- ## Provider extensions
130
-
131
- Most integrations should use an MCP server, executor, scheme, or a provider
132
- declaration. A provider extension is only needed for a protocol binding unavailable
133
- through the catalog and installed SDK packages.
134
-
135
- It may use any npm scope. Its package manifest declares the PLURNK name:
136
-
137
- ```json
138
- {
139
- "plurnk": {
140
- "kind": "provider",
141
- "name": "acme"
142
- },
143
- "peerDependencies": {
144
- "@plurnk/plurnk-providers": "^6.0.0"
145
- }
146
- }
147
- ```
148
-
149
- The default export is a `ProviderExtension` with
150
- `model(modelId)`. PLURNK adapts that model transport into its own
151
- contract, so extensions do not reproduce retries, usage normalization, envelopes,
152
- notices, or RFC 9457 failure normalization.
36
+ | `PLURNK_MODEL=provider/model` | Select a catalog route directly. |
37
+ | `PLURNK_MODEL_<alias>=provider/model` | Declare a named alias and tuning scope (`alias` is case-insensitive). |
38
+ | `PLURNK_BASEURL_<alias>=https://endpoint/v1` | Override that alias's endpoint URL. |
39
+ | `PLURNK_PROVIDERS_<KNOB>_<alias>=value` | Per-alias override (`OUTPUT_BUDGET`, `REASONING_BUDGET`, `TEMPERATURE`, `TOP_P`, `TOP_K`, `PRESENCE_PENALTY`, `FREQUENCY_PENALTY`, `SEED`, `MAX_CONCURRENCY`, etc., {§provider-configuration}). |
40
+ | `PLURNK_PROVIDERS_PROVIDER_<NAME>_*` | Declare an uncataloged OpenAI-compatible provider (`ADAPTER`, `BASE_URL`, `API_KEY_ENV`). |
153
41
 
154
- The manifest may declare always-on `plurnk.attribution`. The default export may
155
- also implement synchronous `attributions(context)` and decide per provider
156
- attempt whether to return no, one, or many additional opaque tags
157
- ({§extension-discovery}).
42
+ Catalog metadata ships from Models.dev and can be refreshed into `$XDG_CACHE_HOME/plurnk/models.json` via `plurnk-service update`, `plurnk update`, or `/update` ({§model-catalog-cache}). Context window, output limits, reasoning activation, and cost resolve independently ({§model-fact-resolution}, {§provider-monetary-evidence}).
158
43
 
159
- Discovery is scope-agnostic and rejects duplicate names.
160
- Third-party discovery uses the shared pre-import trust contract ({§extension-discovery}).
161
-
162
- ## Local endpoints
163
-
164
- `openai` and `ollama` retain small in-package adapters because local operation
165
- requires runtime facts no static catalog owns: served model, context window,
166
- llama-server capabilities, slots, EOS token, and exact tokenization.
44
+ ### Local endpoints (`openai` / `ollama`)
167
45
 
168
46
  ```dotenv
169
47
  PLURNK_MODEL_local=openai/model-name-from-endpoint
170
48
  PLURNK_BASEURL_local=http://127.0.0.1:8080/v1
171
49
  PLURNK_MODEL=local
172
- # Optional explicit generation allowances, in tokens:
173
- # PLURNK_PROVIDERS_OUTPUT_BUDGET_local=8192
174
- # PLURNK_PROVIDERS_REASONING_BUDGET_local=4096
175
- # Optional: serialize inference on a single-slot endpoint without serializing sessions:
176
50
  # PLURNK_PROVIDERS_MAX_CONCURRENCY_local=1
177
51
  ```
178
52
 
179
- Endpoint probing supplies served-model capacity and llama-server capabilities.
180
- Pin `PLURNK_PROVIDERS_LLAMA_SERVER_local=1` only for a known llama-server that
181
- cannot be fingerprinted reliably.
53
+ In-package `openai` and `ollama` adapters probe live context windows, `llama-server` slots/capabilities (`PLURNK_PROVIDERS_LLAMA_SERVER_<alias>=1` pins when unprobed), EOS tokens, and exact tokenization; `think-tags` is an explicit opt-in for leading `<think>` envelopes.
182
54
 
183
- Sampling stays at endpoint defaults unless configured. Repetition penalties can
184
- fight exact source copying and operation syntax repetition. Measure local tuning; it is
185
- not a portable cloud policy. `think-tags` response interpretation is a separate
186
- opt-in for endpoints that emit a leading `<think>` envelope, not a reasoning switch.
55
+ ## Capacity, reasoning, and runtime boundaries
187
56
 
188
- ## Connectivity, caching, and cost
189
-
190
- | Concern | Boundary |
57
+ | Boundary | Rule |
191
58
  | --- | --- |
192
- | Inference concurrency | Optional per-endpoint, process-local admission; queued calls remain cancellable. The default is unrestricted ({§provider-inference-admission}). |
193
- | Generation deadline | One whole-call allowance across queueing, requests and retries; caller cancellation still applies. No first-content or inter-chunk cutoff. |
194
- | Discovery/tokenizer HTTP | Separate non-generation fetch bound; does not limit inference. |
195
- | Provider-directed waits | Bounded retries honor `Retry-After`; other recoverable failures return to Core. |
196
- | Loop recovery | Core reissues within its recovery window, then parks for a review-capable owner or concludes on the failure. |
197
- | Cache affinity | Stable Session identity through documented provider controls; not a cache-hit guarantee. |
198
- | Explicit cache writes | Separate policy on supported routes; can affect billing. |
199
- | Service tier | Explicit route choice that may change price and availability. |
200
- | Cost | Provider monetary evidence wins; known usage and catalog rates yield an estimate, not a settled charge. |
201
-
202
- For uncataloged compatible endpoints, declare the adapter, URL, and credential-variable
203
- name together; the examples are in the defaults reference. A provider extension is
204
- needed only when the protocol cannot be expressed by the installed adapters.
205
-
206
- ## Configured-provider packet conformance matrix
207
-
208
- Every configured model alias is exercised through a real PLURNK loop — the
209
- production packet, a model-selected operation, its materialized result, and
210
- completion — never a transport-only completion. Provider-exposed reasoning must
211
- survive in the durable assistant packet and digest; a provider with no private
212
- reasoning is valid when the observable operation cycle succeeds.
213
-
214
- One specimen at a time, deterministically:
215
-
216
- ```sh
217
- cd plurnk-core
218
- npm run test:live -- --specimen "<exact specimen name>"
219
- ```
220
-
221
- The selector inserts `--test-name-pattern` before the expanded live file list in
222
- the exact standard `test:live` invocation; trailing npm arguments alone cannot
223
- narrow the suite. This procedure is `plurnk-core`'s own; the ledger below is
224
- maintained with the evidence for every alias it names.
225
-
226
- ### Classifications
227
-
228
- | Class | Meaning |
229
- |---|---|
230
- | pass | Full packet cycle completed; durable packet and digest verified |
231
- | auth/credential | The route is blocked before the model by authorization or credential handling |
232
- | transport | The route fails at a transport/capability boundary, not the model |
233
- | op:stable-fail | An operation-level failure repeated on replay; assertion unweakened |
234
- | op:stochastic | An operation-level failure did not repeat on a later roll |
235
- | unreachable | The endpoint cannot be reached from this machine |
236
-
237
- Authorization and credential failures are reported as their own class, never as
238
- model failures. Repeated stochastic and stable operation failures are reported
239
- separately in the ledger's specimens.
240
-
241
- A route's classification is established by running the live drill against it and
242
- reading the digest, never by reputation. Record the outcome where the work is
243
- tracked; this README owns the procedure and the vocabulary, not a snapshot of any
244
- one installation's configured aliases.
59
+ | Effort & reasoning budget | `adaptive` requests dynamic reasoning or falls back to `PLURNK_PROVIDERS_EFFORT_FALLBACK` (`high`); explicit fixed efforts must be route-supported. Unset reasoning budget leaves reasoning enabled. |
60
+ | Output & floor (`PLURNK_PROVIDERS_OUTPUT_FLOOR`) | Shipped `25%` floor sets the input wall (`contextWindow - floor`); packets past the output budget flex output down to the remainder ({§provider-capacity-admission}). |
61
+ | Concurrency & deadlines | Per-endpoint FIFO `MAX_CONCURRENCY` gate ({§provider-inference-admission}), automatically bounded by probed `llama-server` `total_slots` and resized live across `.env` reloads; one whole-call generation deadline across queueing and `Retry-After` retries. |
62
+ | Provider extensions | First-party `@plurnk/*` packages with `plurnk: { "kind": "provider", "name": "..." }` default-export `ProviderExtension` (`model(modelId)`, optional `attributions(context)`, {§extension-discovery}). |
245
63
 
246
- ## Development
64
+ ## Live conformance & development
247
65
 
248
66
  ```sh
249
67
  npm run test:lint -w @plurnk/plurnk-providers
250
68
  npm run test:unit -w @plurnk/plurnk-providers
69
+ npm --prefix plurnk-core run test:live -- --specimen "<exact specimen name>"
251
70
  ```
252
71
 
253
- `npm run probe:providers` is an explicit paid diagnostic; it calls each
254
- keyed provider once and prints the retained sanitized evidence directory.
72
+ Live classifications: `pass`, `auth/credential`, `transport`, `op:stable-fail`, `op:stochastic`, `unreachable`. `npm run probe:providers` runs an explicit paid diagnostic across keyed providers.
package/SPEC.md CHANGED
@@ -16,7 +16,7 @@ Every `Provider` instance exposes:
16
16
 
17
17
  | Member | Contract |
18
18
  |---|---|
19
- | Physical & policy getters | `model`, `servedModel`, `contextWindow`, `maxInputTokens`, `maxOutputTokens`, `outputBudget`, `outputFloor`, `reasoningBudget`, `inputCapacity`, `inputWall`, `supportedEfforts`, `inputModalities` (`ReadonlySet<"image" \| "audio" \| "video" \| "pdf">`), and `requiresOutputBudget` |
19
+ | Physical & policy getters | `model`, `servedModel`, `contextWindow`, `maxInputTokens`, `maxOutputTokens`, `outputBudget`, `outputFloor`, `reasoningBudget`, `inputCapacity`, `inputWall`, `supportedEfforts`, `inputModalities` (`ReadonlySet<"image" \| "audio" \| "video" \| "pdf">`), `temperature`, `seed`, and `requiresOutputBudget` |
20
20
  | `countPromptTokens(messages, signal?)` | Measures or estimates prompt token weight (`PromptTokenMeasurement`) |
21
21
  | `assessRequestCapacity(messages, maxOutputTokens?, signal?)` | Evaluates `inputCapacity`, `inputWall`, admission `decision` (`"admit" \| "defer" \| "reject"`), and flexed `responseMax` |
22
22
  | `generate(args)` | Requires non-empty `sessionId` (used for KV-cache and slot affinity), optional `callKind` (`"emission"` or `"bare"`), `maxOutputTokens`, `sampling`, `observeRequest`, and `observeReasoning`. Native tool calls are unconditionally disabled on every protocol |
@@ -59,7 +59,10 @@ Every physical attempt settles a `ProviderRequestAccounting` record (`{ provider
59
59
  `ModelProvider.ts` delegates streaming, protocol framing, vendor request assembly, model compatibility flags (`getBuiltinModels`), header normalization (`headersToRecord`), interruptible backoff (`sleep`), token estimation (`estimateMessageTokens`), and context-overflow pattern matching (`getOverflowPatterns`) to `@earendil-works/pi-ai` across all supported APIs (`anthropic-messages`, `openai-completions`, `openai-responses`, `google-generative-ai`, `bedrock-converse-stream`):
60
60
 
61
61
  - Prompt cache affinity (`PLURNK_PROVIDERS_CACHE_AFFINITY=1`) projects each provider's documented session key (`sessionId` -> `prompt_cache_key` / `x-session-id` / `x-session-affinity`).
62
- - Stable-system cache write policy (`PLURNK_PROVIDERS_CACHE_WRITE_POLICY=stable-system`) attaches ephemeral cache retention (`cache_control: { type: "ephemeral" }`) on providers that support prompt cache breakpoints (Anthropic and Anthropic routes on OpenRouter).
62
+ - Explicit prompt-cache write policy (`PLURNK_PROVIDERS_CACHE_WRITE_POLICY`, default `conversation`: `conversation | stable-system | off`) governs explicit cache breakpoints (`cache_control: { type: "ephemeral" }` on Anthropic, MiniMax Anthropic, and OpenRouter Anthropic routes; `cachePoint: { type: "default" }` on Bedrock Claude prompt-caching routes; `prompt_cache_options: { mode: "explicit" }` with `prompt_cache_breakpoint: { mode: "explicit" }` on OpenAI GPT-5.6+ routes, including OpenRouter `openai/*`), suppressed on stateless `callKind: "bare"` calls:
63
+ - `off` (and `callKind: "bare"`): zero explicit cache breakpoints; on OpenAI GPT-5.6+ routes `prompt_cache_options: { mode: "explicit" }` is still sent with zero breakpoints so implicit paid cache writes are disabled.
64
+ - `stable-system`: one breakpoint on the final leading `system` instruction.
65
+ - `conversation`: splits caller-delimited `userCachePrefixes` on historical `user` messages into separate content blocks so prior turns' cached durable log blocks retain their exact block boundaries. Ephemeral-breakpoint routes (`cache_control` / `cachePoint`) place breakpoints on the final leading `system` instruction, the penultimate conversation message, and the durable prefix of the final `user` message before any volatile per-turn status tail (or the full final `user` message when no volatile tail is delimited), staying within three breakpoints per request; OpenAI GPT-5.6+ explicit routes keep monotonic `prompt_cache_breakpoint` markers on the final leading `system` instruction and each `user` message's durable prefix across turns so prior segment boundaries remain stable while writing only new uncached prefixes.
63
66
  - Output token allowance (`responseMax ?? outputBudget`) is enforced both in flight during streaming (aborting a runaway stream once mid-stream reported output tokens or conservative token lower-bound `floor(estimateMessageTokens(partial) / 2)` exceeds the granted allowance) and on final reported `usage.outputTokens`.
64
67
 
65
68
  ## §provider-effort Reasoning effort and readable trace
@@ -81,20 +84,20 @@ Every physical attempt settles a `ProviderRequestAccounting` record (`{ provider
81
84
  | `PLURNK_PROVIDERS_EFFORT` / `EFFORT_FALLBACK` | `adaptive` / `high` | Portable reasoning effort selector and graded-route fallback |
82
85
  | `PLURNK_PROVIDERS_FETCH_TIMEOUT` / `OPERATION_TIMEOUT` | `30000` / `600000` ms | Per-attempt fetch/idle timeout and total operation wall-clock timeout |
83
86
  | `PLURNK_PROVIDERS_RETRY_ATTEMPTS` | `3` | Maximum automatic retry attempts for retryable transport failures |
84
- | `PLURNK_PROVIDERS_MAX_CONCURRENCY` | `-1` (unbounded or positive integer) | Per-endpoint FIFO concurrency gate ({§provider-inference-admission}) |
87
+ | `PLURNK_PROVIDERS_MAX_CONCURRENCY` | `-1` (unbounded when unprobed, or positive integer) | Per-endpoint FIFO concurrency gate, automatically bounded by probed physical endpoint slots ({§provider-inference-admission}) |
85
88
  | `PLURNK_PROVIDERS_COST_<CATEGORY>` | empty (non-negative USD per 1M tokens for `INPUT`, `OUTPUT`, `REASONING`, `CACHE_READ`, `CACHE_WRITE`) | Per-category operator rate overrides merged over catalog rates ({§provider-monetary-evidence}) |
86
89
  | `PLURNK_PROVIDERS_RAWBODY` | `0` (`0 \| 1`) | Retains redacted raw request/response forensic bodies in `forensicEvidence` |
87
90
 
88
91
  - Every knob in `PROVIDERS_KNOBS` is documented in `plurnk-providers/.env.defaults` and supports case-insensitive per-alias suffix scoping (`<KNOB>_<ALIAS>`) via `scopeEnvToAlias(env, alias)`.
89
92
  - Sampling knobs (`TEMPERATURE`, `TOP_P`, `TOP_K`, `PRESENCE_PENALTY`, `FREQUENCY_PENALTY`, `SEED`, `REPEAT_PENALTY`, `REPEAT_LAST_N`, `DRY_MULTIPLIER`, `DRY_BASE`, `DRY_ALLOWED_LENGTH`) validate at construction; caller `sampling` overrides configured defaults on a per-call basis, and `DRY_MULTIPLIER=0` suppresses all DRY fields.
90
- - `instantiateProvider` resolves cataloged providers and `ollama` in-framework before scanning `node_modules` for third-party provider extensions (gated by `PLURNK_EXTENSIONS_TRUSTED_ONLY`). `providerReadiness(provider, env)` and `routeReadiness(route, env)` report missing credentials or endpoint configuration without exposing secret values.
93
+ - `instantiateProvider` resolves cataloged providers and `ollama` in-framework before scanning `node_modules` for first-party `@plurnk/*` provider extensions ({§extension-discovery}). `providerReadiness(provider, env)` and `routeReadiness(route, env)` report missing credentials or endpoint configuration without exposing secret values.
91
94
 
92
95
  ## §model-fact-resolution Route facts and local probes
93
96
 
94
97
  | Route family | Fact authority |
95
98
  |---|---|
96
99
  | Cataloged cloud provider (`catalogProvider.ts`) | `resolveModel(provider, model)` from `@plurnk/plurnk-models`, capped by optional `PLURNK_PROVIDERS_CONTEXT_WINDOW`. Uncataloged models on a catalog provider require an explicit `PLURNK_PROVIDERS_CONTEXT_WINDOW`. Catalog credential names (`info.env`) or `PLURNK_PROVIDERS_PROVIDER_<ID>_API_KEY_ENV` (one exact variable name, never a comma list) supply authentication. |
97
- | Local / compatible endpoint (`compatibleProvider.ts`) | Probes `GET <baseUrl>/models` for `n_ctx` / `max_model_len` / `context_length`. When llama-server is detected (`meta.n_ctx` or `PLURNK_PROVIDERS_LLAMA_SERVER=1`), probes `/props` for `total_slots` and `eos_token` and measures prompts via `/v1/chat/completions/input_tokens`. |
100
+ | Local / compatible endpoint (`compatibleProvider.ts`) | Probes `GET <baseUrl>/models` for `n_ctx` / `max_model_len` / `context_length`. When llama-server is detected (`meta.n_ctx` or `PLURNK_PROVIDERS_LLAMA_SERVER=1`), probes `/props` for `total_slots` (bounding endpoint inference concurrency via {§provider-inference-admission}) and `eos_token` and measures prompts via `/v1/chat/completions/input_tokens`. |
98
101
  | Built-in Ollama rail (`ollama.ts`) | Probes `POST <origin>/api/show` for `*.context_length`, capped by optional `PLURNK_PROVIDERS_CONTEXT_WINDOW`, and dispatches chat completions to `<origin>/v1/chat/completions`. |
99
102
  | Operator probe scripts (`scripts/`) | `providers-ping.mjs` probes one cheapest declared route per keyed provider and writes redacted JSON evidence; `token-envelope-probe.mjs` probes explicit aliases across configured or physical output limits. |
100
103
 
@@ -123,14 +126,16 @@ All transport and response failures normalize into `ProviderError` carrying an R
123
126
  | `model_refused` | Upstream safety/content refusal finish reason | 422 | `false` | `attempt` |
124
127
 
125
128
  - Outbound HTTP requests honor `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, and `NO_PROXY`.
126
- - When an upstream stream terminates with an error or length finish reason (`MALFORMED_RESPONSE`, `MALFORMED_FUNCTION_CALL`, `MAX_TOKENS`) after delivering a complete, balanced fenced emission with no unclosed fence, no native tool calls, and no trailing unfenced text, `finishReason` normalizes to `"stop"` while preserving `rawFinishReason` in forensic evidence.
127
- - Transient HTTP failures, upstream malformed-decoder aborts (`MALFORMED_RESPONSE`, `MALFORMED_FUNCTION_CALL`, `UNEXPECTED_TOOL_CALL`) without a complete fenced emission, and reasoning-only `MAX_TOKENS` cutoffs with empty visible content retry up to `PLURNK_PROVIDERS_RETRY_ATTEMPTS` inside the provider (stepping down Google thinking posture on retry when reasoning starved visible output); if a stream fails after emitting partial visible output and a retry succeeds, a `provider_retry` notice is attached.
129
+ - When an upstream stream terminates with an error or length finish reason (`MALFORMED_RESPONSE`, `MALFORMED_FUNCTION_CALL`, `MAX_TOKENS`) after delivering complete Code Mode content with no incomplete tool call (`hasCompleteCodeModeContent`), `finishReason` normalizes to `"stop"` while preserving `rawFinishReason` in forensic evidence.
130
+ - Transient HTTP failures, upstream malformed-decoder aborts (`MALFORMED_RESPONSE`, `MALFORMED_FUNCTION_CALL`, `UNEXPECTED_TOOL_CALL`) without complete Code Mode content, and reasoning-only `MAX_TOKENS` cutoffs with empty visible content retry up to `PLURNK_PROVIDERS_RETRY_ATTEMPTS` inside the provider (stepping down Google thinking posture on retry when reasoning starved visible output); if a stream fails after emitting partial visible output and a retry succeeds, a `provider_retry` notice is attached.
128
131
  - Problem `detail` and structured `cause.causeMessage` strings are bounded to `PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT` characters without leaking raw payloads or headers.
129
132
 
130
133
  ## §provider-inference-admission Inference admission
131
134
 
132
- `InferenceAdmission.forEndpoint(endpoint, maxConcurrency)` coordinates in-flight generations across all `Provider` instances targeting the same canonical endpoint URL (`PLURNK_PROVIDERS_MAX_CONCURRENCY`, default `-1` unbounded, or a positive safe integer):
135
+ `InferenceAdmission.forEndpoint(endpoint, maxConcurrency, options?)` coordinates in-flight generations across all `Provider` instances targeting the same canonical endpoint URL (`PLURNK_PROVIDERS_MAX_CONCURRENCY`, default `-1` unbounded, or a positive safe integer):
133
136
 
137
+ - `effectiveMaxConcurrency(configuredLimit, physicalSlots)` reconciles operator policy with probed physical endpoint slot capacity (`GET /props` `total_slots` on llama-server routes, `null` when unprobed): `-1` adopts `physicalSlots` when probed (remaining `-1` when `null`), and a positive `configuredLimit` resolves to `min(configuredLimit, physicalSlots)` when probed.
134
138
  - Waiters acquire slots in strict FIFO order before opening a physical request (`observeRequest` does not fire while queued) and hold the slot until the response stream or error settles.
135
- - Aborted waiters are removed from the queue immediately without consuming capacity; retry backoff releases the slot before sleeping and re-acquires it for the next attempt.
136
- - Conflicting positive/unbounded `PLURNK_PROVIDERS_MAX_CONCURRENCY` declarations for the same canonical endpoint throw at construction.
139
+ - Aborted waiters are removed from the queue immediately in $O(1)$ without consuming capacity or retaining signal listeners; retry backoff releases the slot before sleeping and re-acquires it for the next attempt.
140
+ - Within one configuration generation, conflicting effective allowances across aliases targeting the same canonical endpoint throw at construction; aliases that resolve to the same effective allowance (such as `-1` alongside explicit `1` on a 1-slot llama-server) share the gate.
141
+ - Advancing the configuration generation (`InferenceAdmission.advanceGeneration`) on operator `.env` reload or observing a changed physical `total_slots` under unchanged operator policy resizes the existing endpoint semaphore in place: growing immediately wakes queued FIFO waiters up to the new allowance, and shrinking lets surplus in-flight leases finish naturally before admitting queued work.
@@ -1,7 +1,16 @@
1
+ export interface InferenceAdmissionOptions {
2
+ readonly configuredLimit?: number;
3
+ readonly generation?: number;
4
+ }
1
5
  export default class InferenceAdmission {
2
6
  #private;
3
- static forEndpoint(endpoint: string, limit: number): InferenceAdmission;
7
+ static get currentGeneration(): number;
8
+ static advanceGeneration(generation?: number): number;
9
+ static forEndpoint(endpoint: string, limit: number, options?: InferenceAdmissionOptions): InferenceAdmission;
4
10
  private constructor();
11
+ get limit(): number;
12
+ get activeCount(): number;
13
+ get waitingCount(): number;
5
14
  acquire(signal?: AbortSignal): Promise<() => void>;
6
15
  }
7
16
  //# sourceMappingURL=InferenceAdmission.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"InferenceAdmission.d.ts","sourceRoot":"","sources":["../src/InferenceAdmission.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,OAAO,OAAO,kBAAkB;;IAMnC,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAetE;IAED,OAAO,eAEN;IAED,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CA4BjD;CACJ"}
1
+ {"version":3,"file":"InferenceAdmission.d.ts","sourceRoot":"","sources":["../src/InferenceAdmission.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAChC;AASD,MAAM,CAAC,OAAO,OAAO,kBAAkB;;IAUnC,MAAM,KAAK,iBAAiB,IAAI,MAAM,CAErC;IAID,MAAM,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAYpD;IAED,MAAM,CAAC,WAAW,CACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,yBAAyB,GACpC,kBAAkB,CAiCpB;IAED,OAAO,eAIN;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAeD,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CA0BjD;CACJ"}
@@ -1,37 +1,104 @@
1
- // {§provider-inference-admission} One process-local allowance per resolved endpoint.
1
+ const assertValidLimit = (limit) => {
2
+ if (!Number.isSafeInteger(limit) || limit !== -1 && limit < 1) {
3
+ throw new TypeError("PLURNK_PROVIDERS_MAX_CONCURRENCY must be -1 or a positive safe integer");
4
+ }
5
+ };
6
+ // {§provider-inference-admission} One process-local FIFO allowance per canonical endpoint.
2
7
  export default class InferenceAdmission {
3
8
  static #endpoints = new Map();
9
+ static #currentGeneration = 0;
4
10
  #limit;
11
+ #configuredLimit;
12
+ #generation;
5
13
  #waiting = new Set();
6
14
  #active = 0;
7
- static forEndpoint(endpoint, limit) {
8
- if (!Number.isSafeInteger(limit) || limit !== -1 && limit < 1) {
9
- throw new TypeError("PLURNK_PROVIDERS_MAX_CONCURRENCY must be -1 or a positive safe integer");
15
+ static get currentGeneration() {
16
+ return this.#currentGeneration;
17
+ }
18
+ // Advance the configuration generation monotonically on operator environment reload so live
19
+ // endpoints resize in place while conflicting aliases within the same generation still fail fast.
20
+ static advanceGeneration(generation) {
21
+ if (generation === undefined) {
22
+ this.#currentGeneration += 1;
23
+ return this.#currentGeneration;
24
+ }
25
+ if (!Number.isSafeInteger(generation) || generation < 0) {
26
+ throw new TypeError("InferenceAdmission generation must be a non-negative safe integer");
27
+ }
28
+ if (generation > this.#currentGeneration) {
29
+ this.#currentGeneration = generation;
30
+ }
31
+ return this.#currentGeneration;
32
+ }
33
+ static forEndpoint(endpoint, limit, options) {
34
+ assertValidLimit(limit);
35
+ const configuredLimit = options?.configuredLimit ?? limit;
36
+ assertValidLimit(configuredLimit);
37
+ const generation = options?.generation ?? this.#currentGeneration;
38
+ if (!Number.isSafeInteger(generation) || generation < 0) {
39
+ throw new TypeError("InferenceAdmission generation must be a non-negative safe integer");
10
40
  }
11
41
  const key = new URL(endpoint).href.replace(/\/+$/, "");
12
42
  const existing = this.#endpoints.get(key);
13
43
  if (existing !== undefined) {
14
- if (existing.#limit !== limit) {
15
- throw new TypeError(`Provider aliases resolving to ${key} have conflicting PLURNK_PROVIDERS_MAX_CONCURRENCY values ${existing.#limit} and ${limit}; one endpoint has one allowance`);
44
+ if (generation > existing.#generation) {
45
+ existing.#generation = generation;
46
+ existing.#configuredLimit = configuredLimit;
47
+ existing.#resize(limit);
48
+ return existing;
49
+ }
50
+ if (existing.#limit === limit) {
51
+ if (configuredLimit !== -1)
52
+ existing.#configuredLimit = configuredLimit;
53
+ return existing;
54
+ }
55
+ // Same operator policy on a restarted endpoint whose probed physical slot count changed.
56
+ if (existing.#configuredLimit === configuredLimit) {
57
+ existing.#resize(limit);
58
+ return existing;
16
59
  }
17
- return existing;
60
+ throw new TypeError(`Provider aliases resolving to ${key} have conflicting PLURNK_PROVIDERS_MAX_CONCURRENCY values ${existing.#limit} and ${limit}; one endpoint has one allowance`);
18
61
  }
19
- const admission = new InferenceAdmission(limit);
62
+ const admission = new InferenceAdmission(limit, configuredLimit, generation);
20
63
  this.#endpoints.set(key, admission);
21
64
  return admission;
22
65
  }
23
- constructor(limit) {
66
+ constructor(limit, configuredLimit, generation) {
24
67
  this.#limit = limit;
68
+ this.#configuredLimit = configuredLimit;
69
+ this.#generation = generation;
70
+ }
71
+ get limit() {
72
+ return this.#limit;
73
+ }
74
+ get activeCount() {
75
+ return this.#active;
76
+ }
77
+ get waitingCount() {
78
+ return this.#waiting.size;
79
+ }
80
+ #resize(limit) {
81
+ this.#limit = limit;
82
+ this.#drainQueue();
83
+ }
84
+ #drainQueue() {
85
+ while (this.#waiting.size > 0 && (this.#limit === -1 || this.#active < this.#limit)) {
86
+ const next = this.#waiting.values().next().value;
87
+ this.#waiting.delete(next);
88
+ next();
89
+ }
25
90
  }
26
91
  acquire(signal) {
27
92
  signal?.throwIfAborted();
28
93
  return new Promise((resolve, reject) => {
94
+ let queued = false;
29
95
  const abort = () => {
30
96
  this.#waiting.delete(enter);
31
97
  reject(signal.reason);
32
98
  };
33
99
  const enter = () => {
34
- signal?.removeEventListener("abort", abort);
100
+ if (queued)
101
+ signal?.removeEventListener("abort", abort);
35
102
  this.#active += 1;
36
103
  let released = false;
37
104
  resolve(() => {
@@ -39,16 +106,13 @@ export default class InferenceAdmission {
39
106
  throw new Error("Inference admission lease was released twice");
40
107
  released = true;
41
108
  this.#active -= 1;
42
- const next = this.#waiting.values().next().value;
43
- if (next !== undefined) {
44
- this.#waiting.delete(next);
45
- next();
46
- }
109
+ this.#drainQueue();
47
110
  });
48
111
  };
49
112
  if (this.#limit === -1 || this.#active < this.#limit)
50
113
  enter();
51
114
  else {
115
+ queued = true;
52
116
  this.#waiting.add(enter);
53
117
  signal?.addEventListener("abort", abort, { once: true });
54
118
  }
@@ -1 +1 @@
1
- {"version":3,"file":"InferenceAdmission.js","sourceRoot":"","sources":["../src/InferenceAdmission.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"InferenceAdmission.js","sourceRoot":"","sources":["../src/InferenceAdmission.ts"],"names":[],"mappings":"AAKA,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAQ,EAAE;IAC7C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,SAAS,CAAC,wEAAwE,CAAC,CAAC;IAClG,CAAC;AACL,CAAC,CAAC;AAEF,2FAA2F;AAC3F,MAAM,CAAC,OAAO,OAAO,kBAAkB;IACnC,MAAM,CAAU,UAAU,GAAG,IAAI,GAAG,EAA8B,CAAC;IACnE,MAAM,CAAC,kBAAkB,GAAG,CAAC,CAAC;IAE9B,MAAM,CAAS;IACf,gBAAgB,CAAS;IACzB,WAAW,CAAS;IACX,QAAQ,GAAG,IAAI,GAAG,EAAc,CAAC;IAC1C,OAAO,GAAG,CAAC,CAAC;IAEZ,MAAM,KAAK,iBAAiB;QACxB,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACnC,CAAC;IAED,4FAA4F;IAC5F,kGAAkG;IAClG,MAAM,CAAC,iBAAiB,CAAC,UAAmB;QACxC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,kBAAkB,IAAI,CAAC,CAAC;YAC7B,OAAO,IAAI,CAAC,kBAAkB,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,UAAU,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACvC,IAAI,CAAC,kBAAkB,GAAG,UAAU,CAAC;QACzC,CAAC;QACD,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,WAAW,CACd,QAAgB,EAChB,KAAa,EACb,OAAmC;QAEnC,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACxB,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,KAAK,CAAC;QAC1D,gBAAgB,CAAC,eAAe,CAAC,CAAC;QAClC,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,kBAAkB,CAAC;QAClE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;QAC7F,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,UAAU,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;gBACpC,QAAQ,CAAC,WAAW,GAAG,UAAU,CAAC;gBAClC,QAAQ,CAAC,gBAAgB,GAAG,eAAe,CAAC;gBAC5C,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACxB,OAAO,QAAQ,CAAC;YACpB,CAAC;YACD,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;gBAC5B,IAAI,eAAe,KAAK,CAAC,CAAC;oBAAE,QAAQ,CAAC,gBAAgB,GAAG,eAAe,CAAC;gBACxE,OAAO,QAAQ,CAAC;YACpB,CAAC;YACD,yFAAyF;YACzF,IAAI,QAAQ,CAAC,gBAAgB,KAAK,eAAe,EAAE,CAAC;gBAChD,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACxB,OAAO,QAAQ,CAAC;YACpB,CAAC;YACD,MAAM,IAAI,SAAS,CACf,iCAAiC,GAAG,6DAA6D,QAAQ,CAAC,MAAM,QAAQ,KAAK,kCAAkC,CAClK,CAAC;QACN,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,kBAAkB,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,CAAC,CAAC;QAC7E,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACpC,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,YAAoB,KAAa,EAAE,eAAuB,EAAE,UAAkB;QAC1E,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,gBAAgB,GAAG,eAAe,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;IAClC,CAAC;IAED,IAAI,KAAK;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,IAAI,WAAW;QACX,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,IAAI,YAAY;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED,OAAO,CAAC,KAAa;QACjB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;IAED,WAAW;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAClF,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC;YAClD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,EAAE,CAAC;QACX,CAAC;IACL,CAAC;IAED,OAAO,CAAC,MAAoB;QACxB,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,IAAI,MAAM,GAAG,KAAK,CAAC;YACnB,MAAM,KAAK,GAAG,GAAS,EAAE;gBACrB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC5B,MAAM,CAAC,MAAO,CAAC,MAAM,CAAC,CAAC;YAC3B,CAAC,CAAC;YACF,MAAM,KAAK,GAAG,GAAS,EAAE;gBACrB,IAAI,MAAM;oBAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBACxD,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;gBAClB,IAAI,QAAQ,GAAG,KAAK,CAAC;gBACrB,OAAO,CAAC,GAAG,EAAE;oBACT,IAAI,QAAQ;wBAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;oBAC9E,QAAQ,GAAG,IAAI,CAAC;oBAChB,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;oBAClB,IAAI,CAAC,WAAW,EAAE,CAAC;gBACvB,CAAC,CAAC,CAAC;YACP,CAAC,CAAC;YACF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM;gBAAE,KAAK,EAAE,CAAC;iBACzD,CAAC;gBACF,MAAM,GAAG,IAAI,CAAC;gBACd,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACzB,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;CACJ","sourcesContent":["export interface InferenceAdmissionOptions {\n readonly configuredLimit?: number;\n readonly generation?: number;\n}\n\nconst assertValidLimit = (limit: number): void => {\n if (!Number.isSafeInteger(limit) || limit !== -1 && limit < 1) {\n throw new TypeError(\"PLURNK_PROVIDERS_MAX_CONCURRENCY must be -1 or a positive safe integer\");\n }\n};\n\n// {§provider-inference-admission} One process-local FIFO allowance per canonical endpoint.\nexport default class InferenceAdmission {\n static readonly #endpoints = new Map<string, InferenceAdmission>();\n static #currentGeneration = 0;\n\n #limit: number;\n #configuredLimit: number;\n #generation: number;\n readonly #waiting = new Set<() => void>();\n #active = 0;\n\n static get currentGeneration(): number {\n return this.#currentGeneration;\n }\n\n // Advance the configuration generation monotonically on operator environment reload so live\n // endpoints resize in place while conflicting aliases within the same generation still fail fast.\n static advanceGeneration(generation?: number): number {\n if (generation === undefined) {\n this.#currentGeneration += 1;\n return this.#currentGeneration;\n }\n if (!Number.isSafeInteger(generation) || generation < 0) {\n throw new TypeError(\"InferenceAdmission generation must be a non-negative safe integer\");\n }\n if (generation > this.#currentGeneration) {\n this.#currentGeneration = generation;\n }\n return this.#currentGeneration;\n }\n\n static forEndpoint(\n endpoint: string,\n limit: number,\n options?: InferenceAdmissionOptions,\n ): InferenceAdmission {\n assertValidLimit(limit);\n const configuredLimit = options?.configuredLimit ?? limit;\n assertValidLimit(configuredLimit);\n const generation = options?.generation ?? this.#currentGeneration;\n if (!Number.isSafeInteger(generation) || generation < 0) {\n throw new TypeError(\"InferenceAdmission generation must be a non-negative safe integer\");\n }\n const key = new URL(endpoint).href.replace(/\\/+$/, \"\");\n const existing = this.#endpoints.get(key);\n if (existing !== undefined) {\n if (generation > existing.#generation) {\n existing.#generation = generation;\n existing.#configuredLimit = configuredLimit;\n existing.#resize(limit);\n return existing;\n }\n if (existing.#limit === limit) {\n if (configuredLimit !== -1) existing.#configuredLimit = configuredLimit;\n return existing;\n }\n // Same operator policy on a restarted endpoint whose probed physical slot count changed.\n if (existing.#configuredLimit === configuredLimit) {\n existing.#resize(limit);\n return existing;\n }\n throw new TypeError(\n `Provider aliases resolving to ${key} have conflicting PLURNK_PROVIDERS_MAX_CONCURRENCY values ${existing.#limit} and ${limit}; one endpoint has one allowance`,\n );\n }\n const admission = new InferenceAdmission(limit, configuredLimit, generation);\n this.#endpoints.set(key, admission);\n return admission;\n }\n\n private constructor(limit: number, configuredLimit: number, generation: number) {\n this.#limit = limit;\n this.#configuredLimit = configuredLimit;\n this.#generation = generation;\n }\n\n get limit(): number {\n return this.#limit;\n }\n\n get activeCount(): number {\n return this.#active;\n }\n\n get waitingCount(): number {\n return this.#waiting.size;\n }\n\n #resize(limit: number): void {\n this.#limit = limit;\n this.#drainQueue();\n }\n\n #drainQueue(): void {\n while (this.#waiting.size > 0 && (this.#limit === -1 || this.#active < this.#limit)) {\n const next = this.#waiting.values().next().value!;\n this.#waiting.delete(next);\n next();\n }\n }\n\n acquire(signal?: AbortSignal): Promise<() => void> {\n signal?.throwIfAborted();\n return new Promise((resolve, reject) => {\n let queued = false;\n const abort = (): void => {\n this.#waiting.delete(enter);\n reject(signal!.reason);\n };\n const enter = (): void => {\n if (queued) signal?.removeEventListener(\"abort\", abort);\n this.#active += 1;\n let released = false;\n resolve(() => {\n if (released) throw new Error(\"Inference admission lease was released twice\");\n released = true;\n this.#active -= 1;\n this.#drainQueue();\n });\n };\n if (this.#limit === -1 || this.#active < this.#limit) enter();\n else {\n queued = true;\n this.#waiting.add(enter);\n signal?.addEventListener(\"abort\", abort, { once: true });\n }\n });\n }\n}\n"]}
@@ -1 +1 @@
1
- {"version":3,"file":"LeadingReasoning.js","sourceRoot":"","sources":["../src/LeadingReasoning.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"LeadingReasoning.js","sourceRoot":"","sources":["../src/LeadingReasoning.ts"],"names":[],"mappings":"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","sourcesContent":["export type ReasoningEnvelope = readonly [opening: string, closing: string];\n\n// {§provider-interface} One leading envelope, shared by incremental\n// observation and settled response projection. Only an undecided delimiter is held.\nexport default class LeadingReasoning {\n static readonly THINK: readonly ReasoningEnvelope[] = [[\"<think>\", \"</think>\"]];\n\n readonly #envelopes: readonly ReasoningEnvelope[];\n #pending = \"\";\n #closing: string | null = null;\n #closed = false;\n #projected = false;\n #reasoning = \"\";\n #content = \"\";\n\n constructor(envelopes: readonly ReasoningEnvelope[]) {\n this.#envelopes = envelopes;\n }\n\n push(text: string): string {\n if (this.#closed) {\n this.#content += text;\n return \"\";\n }\n this.#pending += text;\n if (this.#closing === null) {\n const envelope = this.#envelopes.find(([opening]) => this.#pending.startsWith(opening));\n if (envelope === undefined) {\n if (!this.#envelopes.some(([opening]) => opening.startsWith(this.#pending))) {\n this.#content = this.#pending;\n this.#pending = \"\";\n this.#closed = true;\n }\n return \"\";\n }\n const [opening, closing] = envelope;\n this.#pending = this.#pending.slice(opening.length);\n this.#closing = closing;\n this.#projected = true;\n }\n const end = this.#pending.indexOf(this.#closing);\n if (end !== -1) {\n const delta = this.#emit(this.#pending.slice(0, end));\n this.#content = this.#pending.slice(end + this.#closing.length);\n this.#pending = \"\";\n this.#closed = true;\n return delta;\n }\n let held = Math.min(this.#pending.length, this.#closing.length - 1);\n while (held > 0 && !this.#pending.endsWith(this.#closing.slice(0, held))) held--;\n const split = this.#pending.length - held;\n const delta = this.#emit(this.#pending.slice(0, split));\n this.#pending = this.#pending.slice(split);\n return delta;\n }\n\n finish(): string {\n const delta = this.#projected ? this.#emit(this.#pending) : \"\";\n if (!this.#projected) this.#content += this.#pending;\n this.#pending = \"\";\n this.#closed = true;\n return delta;\n }\n\n #emit(delta: string): string {\n this.#reasoning += delta;\n return delta;\n }\n\n static project(content: string, reasoning: string, envelopes: readonly ReasoningEnvelope[]): {\n content: string; reasoning: string; projected: boolean;\n } {\n if (reasoning.length > 0) {\n for (const [opening, closing] of envelopes) {\n const closeIdx = content.indexOf(closing);\n if (closeIdx !== -1 && !content.slice(0, closeIdx).includes(opening)) {\n return {\n content: content.slice(closeIdx + closing.length).replace(/^\\r?\\n+/u, \"\"),\n reasoning: reasoning + content.slice(0, closeIdx),\n projected: true,\n };\n }\n }\n return { content, reasoning, projected: false };\n }\n const parser = new LeadingReasoning(envelopes);\n parser.push(content);\n parser.finish();\n return { content: parser.#content, reasoning: parser.#reasoning, projected: parser.#projected };\n }\n}\n"]}