npm - oira666_pi-limits-wait - Versions diffs - 0.5.6 → 0.5.7 - Mend

oira666_pi-limits-wait 0.5.6 → 0.5.7

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 (8) hide show

package/README.md CHANGED Viewed

@@ -1,172 +1,257 @@
-# Pi Limits Wait
-[![npm](https://img.shields.io/npm/v/oira666_pi-limits-wait?style=flat-square&logo=npm&logoColor=white&label=npm&color=7c3aed)](https://www.npmjs.com/package/oira666_pi-limits-wait) [![node](https://img.shields.io/badge/node-%3E%3D22.19-7c3aed?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org)
-Pi extension that keeps requests alive when a provider rate-limits you or returns `server_is_overloaded`.
-## Install
-```bash
-pi install npm:oira666_pi-limits-wait
-```
-Restart Pi or run `/reload` after installing.
-## What it does
-- Targets Pi 0.80.10+ (developed and tested against Pi 0.83.0) and works with model providers that use `ModelRuntime.streamSimple`.
-- Intercepts the current runtime without registering synthetic providers; every retry and fallback re-enters Pi's normal provider/auth/base URL/configured-header composition, including OAuth refresh checks.
-- Reload-safe ownership ensures `/reload` transfers interception cleanly and aborts waits still owned by the previous extension instance. The interception has one process-global active extension owner, matching the interactive Pi CLI's single active session runtime lifecycle; SDK processes running multiple concurrent Pi sessions are not supported.
-- On rate-limit errors (`429`, `rate_limit`, `too many requests`, quota/reset messages), waits and retries in a loop.
-- Uses provider retry timing when exposed through response callbacks or provider errors (`retry-after`, `retry-after-ms`, `retry in ...`, reset messages).
-- If no retry timing is available for a rate limit, waits 30 minutes before retrying.
-- On `server_is_overloaded`, waits 5 minutes, then retries. If the provider is still overloaded after Pi's normal retries, it waits another 5 minutes and repeats.
-- On transient network/transport failures — including undici idle-timeout aborts (`UND_ERR_HEADERS_TIMEOUT` / `UND_ERR_BODY_TIMEOUT`), `fetch failed`, `terminated`, `ECONNRESET`, `ETIMEDOUT`, etc. — treats the error as retryable with a short backoff (default 15s, or the provider's `retry-after`) instead of giving up. This prevents a stalled streaming request from turning into a silent hang.
-- Leaves context-overflow recovery entirely to Pi. The extension uses Pi's own `isContextOverflow()` detector and immediately surfaces matching failures without waiting, retrying, or selecting another fallback. If the overflow came from a fallback already attempted for the request, the extension makes that attempted model current when Pi is still on the request's original model and accepts the switch; it never overrides a newer user model selection. Pi intentionally ignores overflow errors from non-current models. Successful over-window responses and zero-output length stops also pass through unchanged, allowing Pi to compact and perform its built-in recovery.
-- For any other (unclassified) provider error — including an API `Internal server error` and HTTP `400`/`403` failures — waits and retries the same model. There is deliberately no permanent-HTTP-status allowlist. This retry-all behavior is enabled by default and uses a configurable retry limit and interval; it does not alter model-limit wait intervals.
-- Reports retry/fallback waits in chat notifications without adding persistent TUI status lines.
-- In non-interactive hosts (`rpc` and `json` modes) the extension never reports a planned retry as an error. While it is waiting to retry, it publishes `info`-level liveliness notifications (plus a `setStatus` entry) describing what it is doing, how long it will wait, and why. An `error`-level notification is emitted only when the extension stops retrying and surfaces the terminal failure. See [Non-interactive (RPC) reporting](#non-interactive-rpc-reporting).
-- Press Enter during a retry wait to skip the wait and retry immediately.
-- Optionally falls back to configured models when the current/default model is rate-limited. Every fallback to a different model—even on the same provider—deliberately discards request-owned credentials, headers, environment overrides, and provider-specific options so the target runtime resolves its own configuration.
-- Preserves Pi's `before_provider_request` / `after_provider_response` callback flow and sanitises only the exact Anthropic OAuth system-block shape generated by current Pi; Pi remains responsible for OAuth identity insertion.
-### Unsupported interception limitation
-Pi 0.83 has no public stream middleware that can intercept a failed provider stream, wait, and re-enter `ModelRuntime` for another attempt. For that reason, limits-wait still installs a reload-safe trampoline on `ModelRuntime.prototype.streamSimple`. This is an unsupported internal interception point and could require changes when Pi changes `ModelRuntime`; it also assumes the interactive CLI's one active session runtime per process. SDK processes with multiple concurrent Pi sessions are not supported.
-`after_provider_response` is preserved for observers, but it is not an equivalent retry hook: it cannot replace stream-error interception, own retry/fallback control flow, or recreate a complete target-model request. In particular, Pi 0.83 still does not expose a public factory for rebuilding the SDK's target-model-aware `transformHeaders` callback. Reusing the source request's closure on a fallback would apply source-model attribution and could leak extension-added headers, so limits-wait intentionally omits it for every different-model fallback. The target `ModelRuntime` still resolves target auth, base URL, configured provider/model headers, environment, and provider implementation canonically, but `before_provider_headers` cannot be re-fired for that fallback through the current public API.
-## Non-interactive (RPC) reporting
-In RPC/JSON mode Pi turns `ctx.ui.setWorkingMessage()` into a no-op, so the interactive countdown is invisible to clients. To keep those clients informed without misreporting recoverable situations as failures, the extension separates progress from failure:
-| Situation | RPC output |
-| --- | --- |
-| Rate limit, overload, auth refresh, network error, unknown error, frozen model — a retry/fallback is still planned | `extension_ui_request` `notify` with `notifyType: "info"`, repeated every `PI_LIMITS_WAIT_LIVELINESS_INTERVAL` seconds while waiting, plus a `setStatus` entry under key `oira666.pi-limits-wait` |
-| Wait finished, retry started, or request completed | The `setStatus` entry is cleared |
-| Retries exhausted / retrying disabled — the request ends with a provider error | one `extension_ui_request` `notify` with `notifyType: "error"` describing the model and the final error, alongside the normal terminal `error` event |
-| Aborted by the client | no error notification (abort is not a failure); the status entry is cleared |
-Liveliness messages include the retry reason, the model, the remaining wait, and the originating error message, e.g.:
-```
-⏳ pi-limits-wait: rate limited on anthropic/claude-sonnet-4-5; still alive, waiting 12m 04s before the next retry. Why: HTTP 429 retry-after-ms 724000
-```
-Interactive (TUI) behavior is unchanged: retry notices remain `warning`-level chat notifications with the live countdown, and no duplicate error notification is added because the terminal error event is already rendered in the transcript.
-## Wait event contract
-Every positive extension-managed wait emits public telemetry on Pi's shared event bus. Import the channel constant and payload union from the package entry point:
-```ts
-import {
-  LIMITS_WAIT_EVENT_CHANNEL,
-  type LimitsWaitEventPayload,
-} from "oira666_pi-limits-wait";
-pi.events.on(LIMITS_WAIT_EVENT_CHANNEL, (data) => {
-  const event = data as LimitsWaitEventPayload;
-  // event.version === 1; event.phase is "start" or "end"
-});
-```
-The versioned, namespaced channel is `oira666.pi-limits-wait.wait.v1`. No event is emitted for a zero/negative-duration wait.
-Both phases contain:
-- `version: 1`, `phase`, and a correlating `waitId`;
-- optional `periodId` for the associated extension retry period;
-- `reason` (`rate-limit`, `overloaded`, `authentication`, `model-frozen`, `network`, or `retry`);
-- `plannedDurationMs`, `plannedDeadline`, and `startedAt` (`plannedDeadline`/`startedAt` are Unix milliseconds);
-- optional `model: { provider, id }` and a normalized `error` string.
-The `end` phase additionally contains `endedAt`, `actualElapsedMs`, and `outcome: "waited" | "skipped" | "aborted"`. Start and end are emitted for normal completion, Enter-to-skip, Escape, signal abort, and pre-aborted positive waits. Telemetry is observational: event-bus failures are isolated and cannot cancel or alter a wait.
-## Session retry summaries
-A retry period begins only when a failure will lead to another extension-created attempt or fallback. For each contiguous extension-managed retry period/stream, limits-wait queues one standard Pi custom entry and appends it after the associated assistant turn (normally on `turn_end`, with `agent_end` and `session_shutdown` as duplicate-safe fallbacks):
-```json
-{
-  "type": "custom",
-  "customType": "limits-wait",
-  "data": {
-    "totalWaitingTime": 12.345,
-    "reasons": ["HTTP 429 retry-after-ms 10000", "fetch failed"],
-    "retries_total": 2
-  }
-}
-```
-`totalWaitingTime` is actual elapsed extension wait time in seconds, not the planned duration. `reasons` contains whitespace-normalized error messages, deduplicated while preserving first-seen order. `retries_total` counts attempts/fallbacks created by this extension: the initial provider request and retries performed internally by a provider SDK do not count; an immediate fallback or zero-wait retry does count. A wait aborted before another attempt does not create a retry count by itself.
-Pi custom entries created with `pi.appendEntry()` do not participate in LLM context. The summary is transcript metadata only.
-## Optional fallback models
-By default, if you do not configure fallback models, the extension behaves exactly as before: it waits for the current model's limit to reset and retries.
-To enable automatic model fallback, add `fallback-models` to a `limits-wait.json` file.
-The extension reads these files in order; later files override earlier ones:
-| Location | Scope | Trust behavior |
-|----------|-------|----------------|
-| `~/.config/.pi/limits-wait.json` | Global defaults | Always loaded |
-| `<Pi agent dir>/limits-wait.json` (for example `~/.pi/agent/limits-wait.json`, or `PI_CODING_AGENT_DIR/limits-wait.json`) | Pi agent directory | Always loaded |
-| `.limits-wait.json` | Project root override | Loaded only when `ctx.isProjectTrusted()` is `true` |
-| `.pi/limits-wait.json` | Pi project override | Loaded only when `ctx.isProjectTrusted()` is `true` |
-For an untrusted project, both project-local paths are ignored completely (including malformed-file warnings); global and agent settings still apply. The trust decision is Pi's effective session trust, including temporary/CLI trust decisions. The same rule is applied every time settings are reread before an LLM call.
-Example:
-```json
-{
-  "fallback-models": [
-    {
-      "provider": "anthropic",
-      "modelname": "claude-sonnet-4-5",
-      "reasoning effort": "medium"
-    },
-    {
-      "provider": "openai",
-      "modelname": "gpt-5.1-codex"
-    }
-  ]
-}
-```
-Each `fallback-models` entry supports:
-- `provider` — required. The Pi provider name, for example `anthropic`, `openai`, `google`, etc.
-- `modelname` — required. The model id/name as Pi knows it.
-- `reasoning effort` — optional. One of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. If omitted, Pi's current/default reasoning level is used.
-Fallback behavior:
-1. Pi starts with the normal default or user-selected model.
-2. If that model is rate-limited, the extension tries models in this order:
-   - the original default/user-selected model;
-   - then every model from `fallback-models`, top to bottom.
-3. The first model that responds without a rate-limit becomes the active Pi model for the rest of the session/task.
-4. If that model later becomes rate-limited too, the extension starts again from the same ordered list.
-5. Rate-limit reset times are remembered only in memory, so known-limited models are skipped until their countdown expires. This memory is cleared when Pi restarts.
-The extension rereads these files before every LLM call, so changes made during a long-running task take effect on the next LLM call without restarting Pi or using `/reload`. Tool calls do not trigger a settings read. When the settings are loaded, the extension shows the full usable fallback model list. When models become rate-limited, it reports the wait in chat notifications.
-## Environment variables
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PI_LIMITS_WAIT_DISABLE_ALL_WAITING` | `false` | Master kill switch for this extension's error handling, retries, fallbacks, freezing, waiting, notifications, telemetry, and retry summaries. Set to `true` (also accepts `1`, `yes`, `on`) to leave only Anthropic OAuth system-prompt cleaning enabled; requests continue through Pi's normal runtime, including its normal Anthropic headers. This takes precedence over every setting below. |
-| `PI_LIMITS_WAIT_DEFAULT_WAITING` | `true` | Whether unclassified/unknown provider errors enter the wait-and-retry cycle. Set to `false` (also accepts `0`, `no`, `off`) to surface the error immediately. Rate-limit, overload, authentication, and network retry behavior is unchanged. |
-| `PI_LIMITS_WAIT_MAX_RETRY` | `999999` | Maximum extension-created retries for an unclassified/unknown provider error. The initial failed request and provider-internal retries do not count. HTTP 400/403 remain eligible. Must be a non-negative integer. |
-| `PI_LIMITS_WAIT_LIVELINESS_INTERVAL` | `15` | Seconds between liveliness notifications published while waiting in non-interactive (`rpc`/`json`) modes. Must be a non-negative integer; values below 1 second are clamped to 1 second. Ignored in TUI mode. |
-| `PI_LIMITS_WAIT_RETRY_INTERVAL` | `5` | Seconds to wait between unclassified/unknown provider-error retries. Must be a non-negative integer (values above 2147483 are capped to Node's maximum reliable timer delay). This does not affect model-limit wait intervals. |
-| `PI_LIMITS_WAIT_FREEZING_ENABLED` | `true` | When a model keeps failing with a non-retryable error, it is normally "frozen" for 10 minutes and skipped in favour of other configured models. Set this to `false` (also accepts `0`, `no`, `off`) to disable freezing entirely: the extension will instead try each configured candidate once (after the bounded retries) and then surface the error, never blocking on a long "model-frozen" wait. Useful for non-interactive / subagent runs where no one can press Enter to skip. |
-## License
-MIT
+# Pi Limits Wait
+[![npm](https://img.shields.io/npm/v/oira666_pi-limits-wait?style=flat-square&logo=npm&logoColor=white&label=npm&color=7c3aed)](https://www.npmjs.com/package/oira666_pi-limits-wait) [![node](https://img.shields.io/badge/node-%3E%3D22.19-7c3aed?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org)
+Pi extension that keeps requests alive when a provider rate-limits you or returns `server_is_overloaded`.
+## Install
+```bash
+pi install npm:oira666_pi-limits-wait
+```
+Restart Pi or run `/reload` after installing.
+## What it does
+- Targets Pi 0.80.10+ (developed and tested against Pi 0.83.0) and works with model providers that use `ModelRuntime.streamSimple`.
+- Intercepts the current runtime without registering synthetic providers; every retry and fallback re-enters Pi's normal provider/auth/base URL/configured-header composition, including OAuth refresh checks.
+- Reload-safe ownership ensures `/reload` transfers interception cleanly and aborts waits still owned by the previous extension instance. The interception has one process-global active extension owner, matching the interactive Pi CLI's single active session runtime lifecycle; SDK processes running multiple concurrent Pi sessions are not supported.
+- On rate-limit errors (`429`, `rate_limit`, `too many requests`, quota/reset messages), waits and retries in a loop.
+- Uses provider retry timing when exposed through response callbacks or provider errors (`retry-after`, `retry-after-ms`, `retry in ...`, reset messages).
+- If no retry timing is available for a rate limit, waits 30 minutes before retrying.
+- On `server_is_overloaded`, waits 5 minutes, then retries. If the provider is still overloaded after Pi's normal retries, it waits another 5 minutes and repeats.
+- On transient network/transport failures — including undici idle-timeout aborts (`UND_ERR_HEADERS_TIMEOUT` / `UND_ERR_BODY_TIMEOUT`), `fetch failed`, `terminated`, `ECONNRESET`, `ETIMEDOUT`, etc. — treats the error as retryable with a short backoff (default 15s, or the provider's `retry-after`) instead of giving up. This prevents a stalled streaming request from turning into a silent hang.
+- Leaves context-overflow recovery entirely to Pi. The extension uses Pi's own `isContextOverflow()` detector and immediately surfaces matching failures without waiting, retrying, or selecting another fallback. If the overflow came from a fallback already attempted for the request, the extension makes that attempted model current when Pi is still on the request's original model and accepts the switch; it never overrides a newer user model selection. Pi intentionally ignores overflow errors from non-current models. Successful over-window responses and zero-output length stops also pass through unchanged, allowing Pi to compact and perform its built-in recovery.
+- For any other (unclassified) provider error — including an API `Internal server error` and HTTP `400`/`403` failures — waits and retries the same model. There is deliberately no permanent-HTTP-status allowlist. This retry-all behavior is enabled by default and uses a configurable retry limit and interval; it does not alter model-limit wait intervals.
+- Reports retry/fallback waits in chat notifications without adding persistent TUI status lines.
+- In non-interactive hosts (`rpc` and `json` modes) the extension never reports a planned retry as an error. While it is waiting to retry, it publishes `info`-level liveliness notifications (plus a `setStatus` entry) describing what it is doing, how long it will wait, and why. An `error`-level notification is emitted only when the extension stops retrying and surfaces the terminal failure. See [Non-interactive (RPC) reporting](#non-interactive-rpc-reporting).
+- Press Enter during a retry wait to skip the wait and retry immediately.
+- Optionally falls back to configured models when the current/default model is rate-limited. Every fallback to a different model—even on the same provider—deliberately discards request-owned credentials, headers, environment overrides, and provider-specific options so the target runtime resolves its own configuration.
+- Preserves Pi's `before_provider_request` / `after_provider_response` callback flow and sanitises only the exact Anthropic OAuth system-block shape generated by current Pi; Pi remains responsible for OAuth identity insertion.
+### Unsupported interception limitation
+Pi 0.83 has no public stream middleware that can intercept a failed provider stream, wait, and re-enter `ModelRuntime` for another attempt. For that reason, limits-wait still installs a reload-safe trampoline on `ModelRuntime.prototype.streamSimple`. This is an unsupported internal interception point and could require changes when Pi changes `ModelRuntime`; it also assumes the interactive CLI's one active session runtime per process. SDK processes with multiple concurrent Pi sessions are not supported.
+`after_provider_response` is preserved for observers, but it is not an equivalent retry hook: it cannot replace stream-error interception, own retry/fallback control flow, or recreate a complete target-model request. In particular, Pi 0.83 still does not expose a public factory for rebuilding the SDK's target-model-aware `transformHeaders` callback. Reusing the source request's closure on a fallback would apply source-model attribution and could leak extension-added headers, so limits-wait intentionally omits it for every different-model fallback. The target `ModelRuntime` still resolves target auth, base URL, configured provider/model headers, environment, and provider implementation canonically, but `before_provider_headers` cannot be re-fired for that fallback through the current public API.
+## Non-interactive (RPC) reporting
+In RPC/JSON mode Pi turns `ctx.ui.setWorkingMessage()` into a no-op, so the interactive countdown is invisible to clients. To keep those clients informed without misreporting recoverable situations as failures, the extension separates progress from failure:
+| Situation | RPC output |
+| --- | --- |
+| Rate limit, overload, auth refresh, network error, unknown error, frozen model — a retry/fallback is still planned | `extension_ui_request` `notify` with `notifyType: "info"`, repeated every `PI_LIMITS_WAIT_LIVELINESS_INTERVAL` seconds while waiting, plus a `setStatus` entry under key `oira666.pi-limits-wait` |
+| Wait finished, retry started, or request completed | The `setStatus` entry is cleared |
+| Retries exhausted / retrying disabled — the request ends with a provider error | one `extension_ui_request` `notify` with `notifyType: "error"` describing the model and the final error, alongside the normal terminal `error` event |
+| Aborted by the client | no error notification (abort is not a failure); the status entry is cleared |
+Liveliness messages include the retry reason, the model, the remaining wait, and the originating error message, e.g.:
+```
+⏳ pi-limits-wait: rate limited on anthropic/claude-sonnet-4-5; still alive, waiting 12m 04s before the next retry. Why: HTTP 429 retry-after-ms 724000
+```
+Interactive (TUI) behavior is unchanged: retry notices remain `warning`-level chat notifications with the live countdown, and no duplicate error notification is added because the terminal error event is already rendered in the transcript.
+### Structured status channel
+Since 0.5.7 the extension publishes a **second, machine-readable** `setStatus` entry beside the prose one, under its own key:
+```
+{"type":"extension_ui_request","id":"<uuid>","method":"setStatus",
+ "statusKey":"oira666.pi-limits-wait.json","statusText":"<minified JSON>"}
+```
+The prose key `oira666.pi-limits-wait` is **unchanged** in text, key, cadence and clearing semantics, so a host that only knows 0.5.6 is unaffected. The JSON key is published on exactly the same schedule as the prose notice (immediately when a wait starts, then every `PI_LIMITS_WAIT_LIVELINESS_INTERVAL` seconds while waiting) and only in non-interactive (`rpc`/`json`) hosts. A blank/absent `statusText` under this key is the end-of-window marker.
+`statusText` is one minified JSON line:
+```json
+{"v":1,"ext":"0.5.7","event":"wait","waitId":"wait-mfk3z1-7","periodId":"period-3","reason":"rate-limit","message":"⏳ pi-limits-wait: rate limited on anthropic/claude-sonnet-4-5; still alive, waiting 12m 04s before the next retry. Why: HTTP 429 retry-after-ms 724000","error":"HTTP 429 retry-after-ms 724000","model":{"provider":"anthropic","id":"claude-sonnet-4-5"},"plannedDurationMs":1800000,"plannedDeadline":1786000000000,"startedAt":1785998200000,"remainingMs":724000,"attempt":null,"maxAttempts":null,"livelinessIntervalMs":15000,"controlFile":"/tmp/ram-pi-.../limits-wait.control"}
+```
+End of a wait (published once, immediately before both keys are cleared):
+```json
+{"v":1,"ext":"0.5.7","event":"wait_end","waitId":"wait-mfk3z1-7","reason":"rate-limit","message":"…","error":"…","plannedDurationMs":1800000,"plannedDeadline":1786000000000,"startedAt":1785998200000,"remainingMs":0,"attempt":null,"maxAttempts":null,"livelinessIntervalMs":15000,"controlFile":"…","outcome":"skipped","actualElapsedMs":41233}
+```
+Terminal give-up (the extension has stopped retrying and surfaces the final error):
+```json
+{"v":1,"ext":"0.5.7","event":"give_up","waitId":null,"reason":null,"message":"anthropic/claude-sonnet-4-5 failed and pi-limits-wait is not retrying: …","error":"…","plannedDurationMs":null,"plannedDeadline":null,"startedAt":null,"remainingMs":null,"attempt":null,"maxAttempts":null,"livelinessIntervalMs":15000,"controlFile":"…"}
+```
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `v` | `1` | Payload schema version. Bumped only on a breaking change. |
+| `ext` | string | Extension version that produced the frame, e.g. `"0.5.7"`. |
+| `event` | `"wait"` \| `"wait_end"` \| `"give_up"` | Liveliness tick, end of a wait, or terminal give-up. |
+| `waitId` | string \| null | Correlates every frame of one wait. `null` only for `give_up`. |
+| `periodId` | string (optional) | Retry-period id, when the wait belongs to one. |
+| `reason` | `"rate-limit"` \| `"overloaded"` \| `"authentication"` \| `"model-frozen"` \| `"network"` \| `"retry"` \| null | `null` only for `give_up`. |
+| `message` | string | The same human text published on the prose channel (≤500 chars, single line). |
+| `error` | string \| null | Normalised originating provider error (≤500 chars). |
+| `model` | `{provider,id}` (optional) | Model the wait applies to, when known. |
+| `plannedDurationMs` | number \| null | Planned wait length. |
+| `plannedDeadline` | number \| null | Epoch ms when the retry is planned. |
+| `startedAt` | number \| null | Epoch ms when the wait began. |
+| `remainingMs` | number \| null | `max(0, plannedDeadline - now)` at publish time; `0` on `wait_end`. |
+| `attempt` | number \| null | 1-based extension-created attempt. Only the unknown-error path counts attempts; classified waits send `null`. |
+| `maxAttempts` | number \| null | `PI_LIMITS_WAIT_MAX_RETRY + 1`, or `null` when not applicable. |
+| `livelinessIntervalMs` | number | Publishing interval, so a consumer can compute staleness itself. |
+| `controlFile` | string \| null | The path this process polls for skip tokens, or `null` when disabled. |
+| `outcome` | `"waited"` \| `"skipped"` \| `"aborted"` (optional) | `wait_end` only. |
+| `actualElapsedMs` | number (optional) | `wait_end` only. |
+Set `PI_LIMITS_WAIT_STATUS_JSON=false` to suppress this channel entirely and restore exact 0.5.6 wire behavior. `PI_LIMITS_WAIT_DISABLE_ALL_WAITING=true` also suppresses it (nothing is published and no control file is polled).
+The payload type is exported for TypeScript hosts:
+```ts
+import {
+  LIVELINESS_JSON_STATUS_KEY,
+  type LimitsWaitStatusPayload,
+} from "oira666_pi-limits-wait";
+```
+### Skipping a wait from the host
+In `rpc`/`json` mode there is no terminal, so the interactive "press Enter to retry now" affordance is unavailable. Instead, set `PI_LIMITS_WAIT_CONTROL_FILE` to an absolute path (one per pi process; the extension echoes it back as `controlFile` in every structured frame). While — and only while — a wait is in progress, the extension polls that path once per second from the countdown ticker it already runs. Signals are deliberately **not** used: `SIGUSR2` with no handler installed terminates the process, and a signal cannot carry a `waitId`.
+Write a token to make the extension stop waiting and retry immediately:
+```json
+{"action":"skip","waitId":"wait-mfk3z1-7","issuedAt":1785998240123,"by":"ramcore"}
+```
+- `action` must be `"skip"`; anything else is ignored.
+- `waitId` must equal the current wait's `waitId` (from the structured frame), or the wildcard `"*"` for "skip whichever wait is current".
+- `issuedAt` is epoch ms and must be `>= startedAt` of the current wait.
+- Writers should write a temp file and rename it into place (atomic move) so a partial read is impossible.
+The extension consumes a token by atomically renaming the canonical control path to a unique `.consumed-<waitId>-<random>` path in the same directory, then reading and validating that claimed file. It removes only the unique claimed path. A writer may therefore rename a newer token onto the canonical path immediately after the claim without cleanup deleting that replacement. An accepted claim settles the wait with `outcome: "skipped"` — the exact same path the Enter key uses, so the retry proceeds normally and a `wait_end` frame with `"outcome":"skipped"` is published. Polls are serialized; a slow filesystem operation cannot overlap the next one-second tick.
+Two content guards ensure a claimed leftover token can never skip a **later** legitimate wait: (a) `waitId` equality — a token written for wait *N* cannot match wait *N+1*'s freshly generated id; (b) `issuedAt >= startedAt` — a `"*"` token issued before this wait began is rejected. Claimed malformed, stale, and non-matching files are discarded, while any newer token at the canonical path is left untouched. The extension deliberately does not unlink the canonical path at wait start, because that would race with a token written microseconds earlier.
+A missing or unclaimable control path is silently ignored. If `PI_LIMITS_WAIT_CONTROL_FILE` is unset (or all waiting is disabled), no filesystem access happens at all.
+## Wait event contract
+Every positive extension-managed wait emits public telemetry on Pi's shared event bus. Import the channel constant and payload union from the package entry point:
+```ts
+import {
+  LIMITS_WAIT_EVENT_CHANNEL,
+  type LimitsWaitEventPayload,
+} from "oira666_pi-limits-wait";
+pi.events.on(LIMITS_WAIT_EVENT_CHANNEL, (data) => {
+  const event = data as LimitsWaitEventPayload;
+  // event.version === 1; event.phase is "start" or "end"
+});
+```
+The versioned, namespaced channel is `oira666.pi-limits-wait.wait.v1`. No event is emitted for a zero/negative-duration wait.
+Both phases contain:
+- `version: 1`, `phase`, and a correlating `waitId`;
+- optional `periodId` for the associated extension retry period;
+- `reason` (`rate-limit`, `overloaded`, `authentication`, `model-frozen`, `network`, or `retry`);
+- `plannedDurationMs`, `plannedDeadline`, and `startedAt` (`plannedDeadline`/`startedAt` are Unix milliseconds);
+- optional `model: { provider, id }` and a normalized `error` string.
+The `end` phase additionally contains `endedAt`, `actualElapsedMs`, and `outcome: "waited" | "skipped" | "aborted"`. Start and end are emitted for normal completion, Enter-to-skip, Escape, signal abort, and pre-aborted positive waits. Telemetry is observational: event-bus failures are isolated and cannot cancel or alter a wait.
+## Session retry summaries
+A retry period begins only when a failure will lead to another extension-created attempt or fallback. For each contiguous extension-managed retry period/stream, limits-wait queues one standard Pi custom entry and appends it after the associated assistant turn (normally on `turn_end`, with `agent_end` and `session_shutdown` as duplicate-safe fallbacks):
+```json
+{
+  "type": "custom",
+  "customType": "limits-wait",
+  "data": {
+    "totalWaitingTime": 12.345,
+    "reasons": ["HTTP 429 retry-after-ms 10000", "fetch failed"],
+    "retries_total": 2
+  }
+}
+```
+`totalWaitingTime` is actual elapsed extension wait time in seconds, not the planned duration. `reasons` contains whitespace-normalized error messages, deduplicated while preserving first-seen order. `retries_total` counts attempts/fallbacks created by this extension: the initial provider request and retries performed internally by a provider SDK do not count; an immediate fallback or zero-wait retry does count. A wait aborted before another attempt does not create a retry count by itself.
+Pi custom entries created with `pi.appendEntry()` do not participate in LLM context. The summary is transcript metadata only.
+## Optional fallback models
+By default, if you do not configure fallback models, the extension behaves exactly as before: it waits for the current model's limit to reset and retries.
+To enable automatic model fallback, add `fallback-models` to a `limits-wait.json` file.
+The extension reads these files in order; later files override earlier ones:
+| Location | Scope | Trust behavior |
+|----------|-------|----------------|
+| `~/.config/.pi/limits-wait.json` | Global defaults | Always loaded |
+| `<Pi agent dir>/limits-wait.json` (for example `~/.pi/agent/limits-wait.json`, or `PI_CODING_AGENT_DIR/limits-wait.json`) | Pi agent directory | Always loaded |
+| `.limits-wait.json` | Project root override | Loaded only when `ctx.isProjectTrusted()` is `true` |
+| `.pi/limits-wait.json` | Pi project override | Loaded only when `ctx.isProjectTrusted()` is `true` |
+For an untrusted project, both project-local paths are ignored completely (including malformed-file warnings); global and agent settings still apply. The trust decision is Pi's effective session trust, including temporary/CLI trust decisions. The same rule is applied every time settings are reread before an LLM call.
+Example:
+```json
+{
+  "fallback-models": [
+    {
+      "provider": "anthropic",
+      "modelname": "claude-sonnet-4-5",
+      "reasoning effort": "medium"
+    },
+    {
+      "provider": "openai",
+      "modelname": "gpt-5.1-codex"
+    }
+  ]
+}
+```
+Each `fallback-models` entry supports:
+- `provider` — required. The Pi provider name, for example `anthropic`, `openai`, `google`, etc.
+- `modelname` — required. The model id/name as Pi knows it.
+- `reasoning effort` — optional. One of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. If omitted, Pi's current/default reasoning level is used.
+Fallback behavior:
+1. Pi starts with the normal default or user-selected model.
+2. If that model is rate-limited, the extension tries models in this order:
+   - the original default/user-selected model;
+   - then every model from `fallback-models`, top to bottom.
+3. The first model that responds without a rate-limit becomes the active Pi model for the rest of the session/task.
+4. If that model later becomes rate-limited too, the extension starts again from the same ordered list.
+5. Rate-limit reset times are remembered only in memory, so known-limited models are skipped until their countdown expires. This memory is cleared when Pi restarts.
+The extension rereads these files before every LLM call, so changes made during a long-running task take effect on the next LLM call without restarting Pi or using `/reload`. Tool calls do not trigger a settings read. When the settings are loaded, the extension shows the full usable fallback model list. When models become rate-limited, it reports the wait in chat notifications.
+## Environment variables
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PI_LIMITS_WAIT_DISABLE_ALL_WAITING` | `false` | Master kill switch for this extension's error handling, retries, fallbacks, freezing, waiting, notifications, telemetry, and retry summaries. Set to `true` (also accepts `1`, `yes`, `on`) to leave only Anthropic OAuth system-prompt cleaning enabled; requests continue through Pi's normal runtime, including its normal Anthropic headers. This takes precedence over every setting below. |
+| `PI_LIMITS_WAIT_DEFAULT_WAITING` | `true` | Whether unclassified/unknown provider errors enter the wait-and-retry cycle. Set to `false` (also accepts `0`, `no`, `off`) to surface the error immediately. Rate-limit, overload, authentication, and network retry behavior is unchanged. |
+| `PI_LIMITS_WAIT_MAX_RETRY` | `999999` | Maximum extension-created retries for an unclassified/unknown provider error. The initial failed request and provider-internal retries do not count. HTTP 400/403 remain eligible. Must be a non-negative integer. |
+| `PI_LIMITS_WAIT_LIVELINESS_INTERVAL` | `15` | Seconds between liveliness notifications published while waiting in non-interactive (`rpc`/`json`) modes. Must be a non-negative integer; values below 1 second are clamped to 1 second. Ignored in TUI mode. Also drives the structured status channel and is reported inside it as `livelinessIntervalMs`. |
+| `PI_LIMITS_WAIT_STATUS_JSON` | `true` | Whether the machine-readable status channel (`statusKey` `oira666.pi-limits-wait.json`) is published in non-interactive modes. Set to `false` (also accepts `0`, `no`, `off`) to restore exact 0.5.6 wire behavior. The prose channel is never affected. |
+| `PI_LIMITS_WAIT_CONTROL_FILE` | *(unset)* | Absolute path of the out-of-band control file polled once per second **while waiting**, used by the host to skip the current wait and retry immediately. Unset disables the feature and all filesystem access. See [Skipping a wait from the host](#skipping-a-wait-from-the-host). |
+| `PI_LIMITS_WAIT_RETRY_INTERVAL` | `5` | Seconds to wait between unclassified/unknown provider-error retries. Must be a non-negative integer (values above 2147483 are capped to Node's maximum reliable timer delay). This does not affect model-limit wait intervals. |
+| `PI_LIMITS_WAIT_FREEZING_ENABLED` | `true` | When a model keeps failing with a non-retryable error, it is normally "frozen" for 10 minutes and skipped in favour of other configured models. Set this to `false` (also accepts `0`, `no`, `off`) to disable freezing entirely: the extension will instead try each configured candidate once (after the bounded retries) and then surface the error, never blocking on a long "model-frozen" wait. Useful for non-interactive / subagent runs where no one can press Enter to skip. |
+## License
+MIT

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-limits-wait",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Extension for PI that allows to automatically wait for limits to reset and retry the request",
   "type": "module",
   "exports": {

package/src/constants.ts CHANGED Viewed

@@ -35,6 +35,12 @@ export const DEFAULT_UNKNOWN_ERROR_RETRY_INTERVAL_MS = 5 * 1_000; // 5 seconds
 export const LIVELINESS_STATUS_KEY = "oira666.pi-limits-wait";
 export const DEFAULT_LIVELINESS_INTERVAL_MS = 15 * 1_000; // 15 seconds
+/** Machine-readable sibling of LIVELINESS_STATUS_KEY. Compact JSON, never prose. */
+export const LIVELINESS_JSON_STATUS_KEY = "oira666.pi-limits-wait.json";
+/** Payload schema version for LIVELINESS_JSON_STATUS_KEY. Bump only on a breaking change. */
+export const LIVELINESS_JSON_VERSION = 1;
+export const EXTENSION_VERSION = "0.5.7";
 export const SETTINGS_FILE_NAME = "limits-wait.json";
 export const FALLBACK_MODELS_KEY = "fallback-models";
 export const DISABLE_ALL_WAITING_ENV_VAR = "PI_LIMITS_WAIT_DISABLE_ALL_WAITING";
@@ -43,3 +49,7 @@ export const DEFAULT_WAITING_ENV_VAR = "PI_LIMITS_WAIT_DEFAULT_WAITING";
 export const MAX_RETRY_ENV_VAR = "PI_LIMITS_WAIT_MAX_RETRY";
 export const RETRY_INTERVAL_ENV_VAR = "PI_LIMITS_WAIT_RETRY_INTERVAL";
 export const LIVELINESS_INTERVAL_ENV_VAR = "PI_LIMITS_WAIT_LIVELINESS_INTERVAL";
+/** Set to false/0/no/off to suppress the structured status channel. */
+export const STATUS_JSON_ENV_VAR = "PI_LIMITS_WAIT_STATUS_JSON";
+/** Absolute path of the out-of-band control file polled while waiting. Unset => no control. */
+export const CONTROL_FILE_ENV_VAR = "PI_LIMITS_WAIT_CONTROL_FILE";

package/src/index.ts CHANGED Viewed

@@ -31,6 +31,26 @@ export {
 export {
   LIMITS_WAIT_EVENT_CHANNEL,
 } from "./telemetry.js";
+export {
+  CONTROL_FILE_ENV_VAR,
+  EXTENSION_VERSION,
+  LIVELINESS_JSON_STATUS_KEY,
+  LIVELINESS_JSON_VERSION,
+  LIVELINESS_STATUS_KEY,
+  STATUS_JSON_ENV_VAR,
+} from "./constants.js";
+export {
+  clearStatusJson,
+  controlFilePath,
+  publishStatusJson,
+  statusJsonEnabled,
+  statusPayload,
+} from "./status-json.js";
+export type {
+  LimitsWaitStatusContext,
+  LimitsWaitStatusEvent,
+  LimitsWaitStatusPayload,
+} from "./status-json.js";
 export type {
   LimitsWaitEndEventPayload,
   LimitsWaitEventPayload,