@vymalo/opencode-ratelimit 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vymalo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @vymalo/opencode-ratelimit
+
+OpenCode plugin that makes OpenAI-compatible providers **rate-limit aware**. It reads the IETF draft-03 rate-limit response headers emitted by [Envoy Gateway](https://gateway.envoyproxy.io/docs/tasks/traffic/global-rate-limit/)'s global rate limiting (`x-ratelimit-limit` / `-remaining` / `-reset`), proactively pauses new requests when the quota is exhausted, and backs off + retries on HTTP `429` — so your OpenCode client cooperates with the gateway instead of hammering it.
+
+Auth-agnostic by design: it runs as an OpenCode `config` hook and only wraps the provider's `fetch`. It never reads or sets `Authorization`, so it composes with `@vymalo/opencode-oauth2`, static API keys, or no auth at all.
+
+## Why use this
+
+OpenCode has no built-in client-side rate-limit handling. If your inference sits behind a gateway that advertises a quota on every response, a burst of requests (streaming + title generation + parallel tool calls) blows through the limit and earns a wall of `429`s. This plugin observes the advertised quota and the reset window and waits the right amount of time — automatically, per provider.
+
+## How it works
+
+OpenCode's plugin API has **no post-response hook**, so the only way to observe response status and headers is to inject a custom `fetch` onto the provider's `options.fetch` during the `config` hook (OpenCode forwards it to the AI SDK provider). This plugin wraps that fetch:
+
+1. **Pre-request gate** — if the last response said `remaining: 0`, hold new requests until `x-ratelimit-reset` elapses.
+2. **Send** the request through the underlying fetch (or any fetch a prior plugin already installed).
+3. **Read** the rate-limit headers from the response and update per-provider state.
+4. **On `429`** — wait the reset window (`x-ratelimit-reset`, or `Retry-After` as a fallback) and retry, up to `maxRetries`.
+
+The `Response` is returned untouched (no `.clone()`), so the streaming body reaches OpenCode intact.
+
+> **Where the headers live.** Envoy attaches its rate-limit `BackendTrafficPolicy` to a specific route — in practice `/v1/chat/completions`, **not** `/v1/models`. So the plugin sees the quota on the inference calls that matter, and a `curl` of `/v1/models` may show no `x-ratelimit-*` at all. The `limit` header is also commonly *multi-policy*, e.g. `x-ratelimit-limit: 200, 200;w=60, 200000;w=60, 50000000;w=2592000` — the parser takes the first token as `limit`, while `remaining`/`reset` already track whichever bucket is closest to its cap (which is all the throttle logic needs).
+
+## Installation
+
+```sh
+npm install @vymalo/opencode-ratelimit
+```
+
+## Usage
+
+A provider opts in via `options.meta.rateLimit`. All fields are optional:
+
+```json
+{
+  "plugin": ["@vymalo/opencode-ratelimit"],
+  "provider": {
+    "my-provider": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "baseURL": "https://api.example.com/v1",
+        "meta": {
+          "rateLimit": {
+            "enabled": true,
+            "maxWaitMs": 0,
+            "maxRetries": 5,
+            "headerPrefix": "x-ratelimit"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Set `false` to opt a provider out while keeping the block. Omitting the whole `rateLimit` block also opts out. |
+| `maxWaitMs` | `0` | Upper bound on any single wait, in ms. **`0` = unlimited** (wait the full reset window). |
+| `maxRetries` | `5` | How many times a `429` is retried before the response is handed back as-is. |
+| `headerPrefix` | `x-ratelimit` | Lowercased prefix of the draft-03 triple. Remap for gateways that use e.g. `ratelimit-*`. |
+
+If you also use `@vymalo/opencode-oauth2`, list it **before** this plugin in `plugin` (config hooks run in registration order). It is only a soft recommendation — this plugin's fetch wrapping is auth-independent.
+
+## Caveats
+
+### Long waits can be cut short by OpenCode's own timeouts
+
+OpenCode wraps the injected `fetch` with its own `headerTimeout` / `chunkTimeout` logic, and our pre-request gate and `429` backoff wait **inside** that fetch. With the default `maxWaitMs: 0`, a 55-second reset window means a 55-second wait — which OpenCode may abort if it exceeds the header timeout. When that happens the wait is cancelled cleanly (a `ratelimit_wait_aborted` event is logged and the abort is propagated as a normal cancellation).
+
+If you expect long waits, raise the provider's `headerTimeout` (and `chunkTimeout`) above your largest reset window:
+
+```json
+"options": { "headerTimeout": 90000, "chunkTimeout": 90000 }
+```
+
+### State is in-memory only
+
+Unlike `@vymalo/opencode-oauth2` and `-models-info`, this plugin keeps **no cache on disk** — rate-limit windows are measured in seconds, so per-process state is all that matters and surviving a restart would be pointless (and stale).
+
+### Concurrency
+
+During a known cooldown window all in-flight callers share a **single** timer (a 10-way burst produces one wait, not ten) and resume together; each still honors its own request `signal`. Outside a cooldown, requests flow concurrently and each response's headers correct the shared state — a burst that races past `remaining: 0` is mopped up by the `429` backoff path.
+
+## Logged events
+
+Structured events flow through OpenCode's log stream (service `opencode-ratelimit-plugin`) with a JSON-console fallback:
+
+| Event | Level | When |
+| --- | --- | --- |
+| `ratelimit_plugin_initialized` | info | once per config load (`providerCount`) |
+| `ratelimit_provider_enabled` | info | a provider opted in |
+| `ratelimit_provider_skipped` | debug | a provider did not opt in |
+| `ratelimit_quota` | debug | every response (`remaining`, `limit`, `resetSeconds`) |
+| `ratelimit_throttle_wait` | info | pre-request gate engaged |
+| `ratelimit_429_backoff` | warn | a `429` was retried |
+| `ratelimit_wait_aborted` | warn | a wait was cancelled by the request signal |
+| `ratelimit_giveup` | error | `maxRetries` exhausted, `429` returned as-is |
+| `ratelimit_header_parse_failed` | debug | a response's headers could not be parsed |
+
+## Library API
+
+The `./lib` subpath exports the testable internals for embedders: `parseRateLimit`, `parseRateLimitOptions`, `makeRateLimitFetch`, `installRateLimiter`, `createProviderState`, and the `createOpencodeRatelimitPlugin` factory.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+import type { RateLimitOptions } from "./types.js";
+export declare const DEFAULT_MAX_WAIT_MS = 0;
+export declare const DEFAULT_MAX_RETRIES = 5;
+export declare const DEFAULT_HEADER_PREFIX = "x-ratelimit";
+/**
+ * Parse a provider's `options.meta.rateLimit` block into resolved
+ * {@link RateLimitOptions}. Returns `null` when the provider has NOT opted in
+ * (no `meta.rateLimit`) or has explicitly disabled it (`enabled: false`) — in
+ * both cases the provider's fetch is left untouched.
+ *
+ * Mirrors `@vymalo/opencode-models-info`'s `parseMetaOptions` opt-in idiom.
+ */
+export declare function parseRateLimitOptions(providerOptions: Record<string, unknown> | undefined): RateLimitOptions | null;

package/dist/config.js

@@ -0,0 +1,62 @@
+export const DEFAULT_MAX_WAIT_MS = 0; // 0 = unlimited (wait the full reset window)
+export const DEFAULT_MAX_RETRIES = 5;
+export const DEFAULT_HEADER_PREFIX = "x-ratelimit";
+const META_KEY = "meta";
+const RATE_LIMIT_KEY = "rateLimit";
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function asBoolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function asPositiveInt(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+        return Math.floor(value);
+    }
+    return fallback;
+}
+/** Like {@link asPositiveInt} but accepts `0` — used for `maxWaitMs` where 0 means unlimited. */
+function asNonNegativeInt(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return Math.floor(value);
+    }
+    return fallback;
+}
+/**
+ * Parse a provider's `options.meta.rateLimit` block into resolved
+ * {@link RateLimitOptions}. Returns `null` when the provider has NOT opted in
+ * (no `meta.rateLimit`) or has explicitly disabled it (`enabled: false`) — in
+ * both cases the provider's fetch is left untouched.
+ *
+ * Mirrors `@vymalo/opencode-models-info`'s `parseMetaOptions` opt-in idiom.
+ */
+export function parseRateLimitOptions(providerOptions) {
+    if (!providerOptions) {
+        return null;
+    }
+    const meta = asRecord(providerOptions[META_KEY]);
+    if (!meta) {
+        return null;
+    }
+    const rateLimit = asRecord(meta[RATE_LIMIT_KEY]);
+    if (!rateLimit) {
+        return null;
+    }
+    const enabled = asBoolean(rateLimit.enabled, true);
+    if (!enabled) {
+        return null;
+    }
+    return {
+        enabled: true,
+        maxWaitMs: asNonNegativeInt(rateLimit.maxWaitMs, DEFAULT_MAX_WAIT_MS),
+        maxRetries: asPositiveInt(rateLimit.maxRetries, DEFAULT_MAX_RETRIES),
+        headerPrefix: (asString(rateLimit.headerPrefix) ?? DEFAULT_HEADER_PREFIX).toLowerCase()
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,CAAC,6CAA6C;AACnF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAEnD,MAAM,QAAQ,GAAG,MAAM,CAAC;AACxB,MAAM,cAAc,GAAG,WAAW,CAAC;AAEnC,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAgC,CAAC;AAC1C,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACzF,CAAC;AAED,SAAS,SAAS,CAAC,KAAc,EAAE,QAAiB;IAClD,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;AACvD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc,EAAE,QAAgB;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACrE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,iGAAiG;AACjG,SAAS,gBAAgB,CAAC,KAAc,EAAE,QAAgB;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,eAAoD;IAEpD,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IACjD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACnD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,gBAAgB,CAAC,SAAS,CAAC,SAAS,EAAE,mBAAmB,CAAC;QACrE,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,UAAU,EAAE,mBAAmB,CAAC;QACpE,YAAY,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,qBAAqB,CAAC,CAAC,WAAW,EAAE;KACxF,CAAC;AACJ,CAAC"}

package/dist/headers.d.ts

@@ -0,0 +1,18 @@
+import type { RateLimitSnapshot } from "./types.js";
+/**
+ * Parse the IETF draft-03 rate-limit triple (as emitted by Envoy Gateway's
+ * global rate limit) plus an optional `Retry-After` fallback into a
+ * {@link RateLimitSnapshot}.
+ *
+ * Envoy emits these on BOTH 200 and 429 responses, e.g.:
+ *   x-ratelimit-limit:     3, 3;w=60
+ *   x-ratelimit-remaining: 2
+ *   x-ratelimit-reset:     48          (seconds until the bucket resets)
+ *
+ * `Retry-After` is NOT emitted by Envoy Gateway today, so it is only consulted
+ * as a fallback when present (all-digits → seconds; otherwise an HTTP-date).
+ *
+ * Header names are case-insensitive (the Fetch `Headers` object lowercases
+ * them); `prefix` should already be lowercased by the caller.
+ */
+export declare function parseRateLimit(headers: Headers, prefix: string, nowMs: number): RateLimitSnapshot;

package/dist/headers.js

@@ -0,0 +1,82 @@
+/**
+ * Parse the IETF draft-03 rate-limit triple (as emitted by Envoy Gateway's
+ * global rate limit) plus an optional `Retry-After` fallback into a
+ * {@link RateLimitSnapshot}.
+ *
+ * Envoy emits these on BOTH 200 and 429 responses, e.g.:
+ *   x-ratelimit-limit:     3, 3;w=60
+ *   x-ratelimit-remaining: 2
+ *   x-ratelimit-reset:     48          (seconds until the bucket resets)
+ *
+ * `Retry-After` is NOT emitted by Envoy Gateway today, so it is only consulted
+ * as a fallback when present (all-digits → seconds; otherwise an HTTP-date).
+ *
+ * Header names are case-insensitive (the Fetch `Headers` object lowercases
+ * them); `prefix` should already be lowercased by the caller.
+ */
+export function parseRateLimit(headers, prefix, nowMs) {
+    const snapshot = {};
+    const limit = parseLimit(headers.get(`${prefix}-limit`));
+    if (limit !== undefined) {
+        snapshot.limit = limit;
+    }
+    const remaining = parseInteger(headers.get(`${prefix}-remaining`));
+    if (remaining !== undefined) {
+        snapshot.remaining = remaining;
+    }
+    const resetSeconds = parseInteger(headers.get(`${prefix}-reset`));
+    if (resetSeconds !== undefined) {
+        snapshot.resetSeconds = resetSeconds;
+        snapshot.resetAtMs = nowMs + resetSeconds * 1000;
+    }
+    const retryAfterMs = parseRetryAfter(headers.get("retry-after"), nowMs);
+    if (retryAfterMs !== undefined) {
+        snapshot.retryAfterMs = retryAfterMs;
+    }
+    return snapshot;
+}
+/**
+ * `x-ratelimit-limit` carries the effective limit followed by optional
+ * window descriptors, e.g. `"3, 3;w=60"`. We take the first comma-separated
+ * token and strip any `;w=...` quota-policy suffix → `3`. A plain `"3"` works too.
+ */
+function parseLimit(raw) {
+    if (raw === null) {
+        return undefined;
+    }
+    const firstToken = raw.split(",", 1)[0]?.split(";", 1)[0];
+    return parseInteger(firstToken);
+}
+function parseInteger(raw) {
+    if (raw === null || raw === undefined) {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0 || !/^-?\d+$/.test(trimmed)) {
+        return undefined;
+    }
+    const value = Number.parseInt(trimmed, 10);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * `Retry-After` is either a non-negative integer (delay-seconds) or an
+ * HTTP-date. Returns the wait in ms, never negative.
+ */
+function parseRetryAfter(raw, nowMs) {
+    if (raw === null) {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    if (/^\d+$/.test(trimmed)) {
+        return Number.parseInt(trimmed, 10) * 1000;
+    }
+    const dateMs = Date.parse(trimmed);
+    if (Number.isNaN(dateMs)) {
+        return undefined;
+    }
+    return Math.max(0, dateMs - nowMs);
+}
+//# sourceMappingURL=headers.js.map

package/dist/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./opencode.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// OpenCode plugin entry. The host iterates every named export of this module
+// and rejects any export that isn't a Plugin function (or { server: Plugin }).
+// Library API is exposed via the "./lib" subpath in package.json.
+export { default } from "./opencode.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,+EAA+E;AAC/E,kEAAkE;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/lib.d.ts

@@ -0,0 +1,6 @@
+export { createOpencodeRatelimitPlugin, OpencodeRatelimitPlugin, type OpenCodePluginFactoryOptions } from "./opencode.js";
+export { DEFAULT_HEADER_PREFIX, DEFAULT_MAX_RETRIES, DEFAULT_MAX_WAIT_MS, parseRateLimitOptions } from "./config.js";
+export { parseRateLimit } from "./headers.js";
+export { createJsonConsoleLogger, DEFAULT_LOG_LEVEL, fromOpenCodeLogLevel, type LogFields, type Logger, type LogLevel } from "./logging.js";
+export { createProviderState, DEFAULT_BACKOFF_MS, type InstallConfigInput, installRateLimiter, makeRateLimitFetch, type ProviderConfigLike, type ProviderRateState, type RateLimitDeps } from "./plugin.js";
+export type { RateLimitOptions, RateLimitSnapshot } from "./types.js";

package/dist/lib.js

@@ -0,0 +1,6 @@
+export { createOpencodeRatelimitPlugin, OpencodeRatelimitPlugin } from "./opencode.js";
+export { DEFAULT_HEADER_PREFIX, DEFAULT_MAX_RETRIES, DEFAULT_MAX_WAIT_MS, parseRateLimitOptions } from "./config.js";
+export { parseRateLimit } from "./headers.js";
+export { createJsonConsoleLogger, DEFAULT_LOG_LEVEL, fromOpenCodeLogLevel } from "./logging.js";
+export { createProviderState, DEFAULT_BACKOFF_MS, installRateLimiter, makeRateLimitFetch } from "./plugin.js";
+//# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EAExB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EAIrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAElB,kBAAkB,EAClB,kBAAkB,EAInB,MAAM,aAAa,CAAC"}

package/dist/logging.d.ts

@@ -0,0 +1,15 @@
+import type { LogLevel } from "./types.js";
+export type { LogLevel } from "./types.js";
+export declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+export declare const DEFAULT_LOG_LEVEL: LogLevel;
+export interface LogFields {
+    [key: string]: unknown;
+}
+export interface Logger {
+    debug(event: string, fields?: LogFields): void;
+    info(event: string, fields?: LogFields): void;
+    warn(event: string, fields?: LogFields): void;
+    error(event: string, fields?: LogFields): void;
+}
+export declare function createJsonConsoleLogger(minLevel?: LogLevel): Logger;
+export declare function fromOpenCodeLogLevel(value: unknown): LogLevel | undefined;

package/dist/logging.js

@@ -0,0 +1,69 @@
+export const LOG_LEVEL_PRIORITY = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40
+};
+export const DEFAULT_LOG_LEVEL = "info";
+function redactFields(fields) {
+    if (!fields) {
+        return undefined;
+    }
+    const redacted = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (/token|secret|password|authorization/i.test(key)) {
+            redacted[key] = "[redacted]";
+            continue;
+        }
+        redacted[key] = value;
+    }
+    return redacted;
+}
+export function createJsonConsoleLogger(minLevel = DEFAULT_LOG_LEVEL) {
+    const minPriority = LOG_LEVEL_PRIORITY[minLevel];
+    const write = (level, event, fields) => {
+        if (LOG_LEVEL_PRIORITY[level] < minPriority) {
+            return;
+        }
+        const payload = {
+            ts: new Date().toISOString(),
+            level,
+            event,
+            ...(redactFields(fields) ?? {})
+        };
+        const line = JSON.stringify(payload);
+        if (level === "error") {
+            console.error(line);
+            return;
+        }
+        if (level === "warn") {
+            console.warn(line);
+            return;
+        }
+        console.log(line);
+    };
+    return {
+        debug: (event, fields) => write("debug", event, fields),
+        info: (event, fields) => write("info", event, fields),
+        warn: (event, fields) => write("warn", event, fields),
+        error: (event, fields) => write("error", event, fields)
+    };
+}
+export function fromOpenCodeLogLevel(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    switch (value.toUpperCase()) {
+        case "DEBUG":
+            return "debug";
+        case "INFO":
+            return "info";
+        case "WARN":
+            return "warn";
+        case "ERROR":
+            return "error";
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=logging.js.map

package/dist/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,kBAAkB,GAA6B;IAC1D,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAa,MAAM,CAAC;AAalD,SAAS,YAAY,CAAC,MAAkB;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,sCAAsC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,QAAQ,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;YAC7B,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,WAAqB,iBAAiB;IAC5E,MAAM,WAAW,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAEjD,MAAM,KAAK,GAAG,CAAC,KAAe,EAAE,KAAa,EAAE,MAAkB,EAAQ,EAAE;QACzE,IAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG,WAAW,EAAE,CAAC;YAC5C,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG;YACd,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,KAAK;YACL,KAAK;YACL,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;SAChC,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACpB,OAAO;QACT,CAAC;QACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,OAAO;QACT,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;QACvD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;QACrD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;QACrD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,QAAQ,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QAC5B,KAAK,OAAO;YACV,OAAO,OAAO,CAAC;QACjB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,OAAO,CAAC;QACjB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/opencode.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { type Logger } from "./logging.js";
+export interface OpenCodePluginFactoryOptions {
+    logger?: Logger;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export declare function createOpencodeRatelimitPlugin(factoryOptions?: OpenCodePluginFactoryOptions): Plugin;
+export declare const OpencodeRatelimitPlugin: Plugin;
+export default OpencodeRatelimitPlugin;

package/dist/opencode.js

@@ -0,0 +1,55 @@
+import { createJsonConsoleLogger, DEFAULT_LOG_LEVEL, fromOpenCodeLogLevel, LOG_LEVEL_PRIORITY } from "./logging.js";
+import { installRateLimiter } from "./plugin.js";
+const PLUGIN_SERVICE_NAME = "opencode-ratelimit-plugin";
+/**
+ * Pipe plugin logs through OpenCode's `client.app.log` so they show up in the
+ * host's structured log stream, with the JSON console as a reliable fallback.
+ * Mirrors the pattern used by `@vymalo/opencode-oauth2` and `-models-info`.
+ */
+function createOpenCodeLogger(client, getMinLevel) {
+    const fallback = createJsonConsoleLogger("debug");
+    const write = (level, event, fields) => {
+        if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[getMinLevel()]) {
+            return;
+        }
+        fallback[level](event, fields);
+        void client.app
+            .log({
+            body: {
+                service: PLUGIN_SERVICE_NAME,
+                level,
+                message: event,
+                extra: fields
+            }
+        })
+            .catch(() => {
+            /* best-effort */
+        });
+    };
+    return {
+        debug: (event, fields) => write("debug", event, fields),
+        info: (event, fields) => write("info", event, fields),
+        warn: (event, fields) => write("warn", event, fields),
+        error: (event, fields) => write("error", event, fields)
+    };
+}
+export function createOpencodeRatelimitPlugin(factoryOptions = {}) {
+    return async ({ client }) => {
+        let currentLogLevel = DEFAULT_LOG_LEVEL;
+        const logger = factoryOptions.logger ?? createOpenCodeLogger(client, () => currentLogLevel);
+        return {
+            config: async (config) => {
+                currentLogLevel = fromOpenCodeLogLevel(config.logLevel) ?? DEFAULT_LOG_LEVEL;
+                installRateLimiter(config, {
+                    logger,
+                    fetchImpl: factoryOptions.fetchImpl,
+                    now: factoryOptions.now,
+                    sleep: factoryOptions.sleep
+                });
+            }
+        };
+    };
+}
+export const OpencodeRatelimitPlugin = createOpencodeRatelimitPlugin();
+export default OpencodeRatelimitPlugin;
+//# sourceMappingURL=opencode.js.map

package/dist/opencode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode.js","sourceRoot":"","sources":["../src/opencode.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EAEpB,kBAAkB,EAGnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAA2B,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE1E,MAAM,mBAAmB,GAAG,2BAA2B,CAAC;AAWxD;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,MAA6B,EAAE,WAA2B;IACtF,MAAM,QAAQ,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAElD,MAAM,KAAK,GAAG,CAAC,KAAe,EAAE,KAAa,EAAE,MAAkB,EAAE,EAAE;QACnE,IAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG,kBAAkB,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAClE,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC/B,KAAK,MAAM,CAAC,GAAG;aACZ,GAAG,CAAC;YACH,IAAI,EAAE;gBACJ,OAAO,EAAE,mBAAmB;gBAC5B,KAAK;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,MAAM;aACd;SACF,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACV,iBAAiB;QACnB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;QACvD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;QACrD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;QACrD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,iBAA+C,EAAE;IAEjD,OAAO,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;QAC1B,IAAI,eAAe,GAAa,iBAAiB,CAAC;QAClD,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,IAAI,oBAAoB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;QAE5F,OAAO;YACL,MAAM,EAAE,KAAK,EAAE,MAAsB,EAAE,EAAE;gBACvC,eAAe,GAAG,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,iBAAiB,CAAC;gBAC7E,kBAAkB,CAAC,MAA4B,EAAE;oBAC/C,MAAM;oBACN,SAAS,EAAE,cAAc,CAAC,SAAS;oBACnC,GAAG,EAAE,cAAc,CAAC,GAAG;oBACvB,KAAK,EAAE,cAAc,CAAC,KAAK;iBAC5B,CAAC,CAAC;YACL,CAAC;SACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,EAAE,CAAC;AAEvE,eAAe,uBAAuB,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,64 @@
+import type { Logger } from "./logging.js";
+import type { RateLimitOptions } from "./types.js";
+/** Fallback backoff when a 429 carries no `x-ratelimit-reset` and no `Retry-After`. */
+export declare const DEFAULT_BACKOFF_MS = 1000;
+/**
+ * Mutable, in-memory rate-limit state for a single provider. Created fresh per
+ * {@link installRateLimiter} call and captured by the provider's fetch wrapper
+ * closure, so it lives for the process lifetime. Never persisted — a reset
+ * window is measured in seconds, so survival across process boots is pointless.
+ */
+export interface ProviderRateState {
+    /**
+     * Epoch ms until which new requests should be held back. 0 = no cooldown.
+     * This is the ONLY field that drives the gate — it is set from a response's
+     * `x-ratelimit-reset` (when `remaining` hits 0) or from a 429 backoff. We
+     * deliberately do not retain the raw `remaining`/`limit`: out-of-order
+     * responses would race on it and nothing reads it (the `ratelimit_quota` log
+     * uses the per-response snapshot directly).
+     */
+    cooldownUntilMs: number;
+    /** A single in-flight wait shared by every caller during a cooldown window. */
+    cooldownPromise?: Promise<void>;
+    /**
+     * Epoch ms at which {@link cooldownPromise} is scheduled to resolve. Lets a
+     * caller that needs a shorter wait detect a too-long shared timer and fall
+     * back to its own sleep, so it never waits past its required time / `maxWaitMs`.
+     */
+    cooldownPromiseUntilMs?: number;
+}
+export declare function createProviderState(): ProviderRateState;
+export interface RateLimitDeps {
+    logger: Logger;
+    /** Defaults to `Date.now`. */
+    now?: () => number;
+    /** Defaults to a real `setTimeout`-based, abort-aware sleep. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Underlying fetch when a provider has no pre-existing `options.fetch`. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export interface ProviderConfigLike {
+    options?: Record<string, unknown>;
+}
+export interface InstallConfigInput {
+    provider?: Record<string, ProviderConfigLike | undefined>;
+}
+/**
+ * Walk every provider in the assembled OpenCode config; for each one that has
+ * opted in via `options.meta.rateLimit`, wrap its `options.fetch` with a
+ * rate-limit-aware fetch. Synchronous — all real work happens lazily inside the
+ * wrapper at request time.
+ */
+export declare function installRateLimiter(input: InstallConfigInput, deps: RateLimitDeps): void;
+/**
+ * Build the fetch wrapper for one provider. The wrapper:
+ *  1. Pre-request gate: if a cooldown window is armed, waits until it clears.
+ *  2. Sends the request via the underlying fetch.
+ *  3. Reads the rate-limit headers; if the window is exhausted, arms the gate
+ *     (`cooldownUntilMs`) for the next callers.
+ *  4. On a 429, waits the reset window and retries (up to `maxRetries`).
+ *
+ * The Response is returned untouched (no `.clone()`) — we only read `status`
+ * and `headers`, so the body stream is delivered to OpenCode intact.
+ */
+export declare function makeRateLimitFetch(providerId: string, opts: RateLimitOptions, state: ProviderRateState, deps: RateLimitDeps, delegate?: typeof fetch): typeof fetch;

package/dist/plugin.js

@@ -0,0 +1,246 @@
+import { parseRateLimitOptions } from "./config.js";
+import { parseRateLimit } from "./headers.js";
+/** Fallback backoff when a 429 carries no `x-ratelimit-reset` and no `Retry-After`. */
+export const DEFAULT_BACKOFF_MS = 1000;
+export function createProviderState() {
+    return { cooldownUntilMs: 0 };
+}
+/**
+ * Walk every provider in the assembled OpenCode config; for each one that has
+ * opted in via `options.meta.rateLimit`, wrap its `options.fetch` with a
+ * rate-limit-aware fetch. Synchronous — all real work happens lazily inside the
+ * wrapper at request time.
+ */
+export function installRateLimiter(input, deps) {
+    const providers = input.provider;
+    if (!providers) {
+        deps.logger.info("ratelimit_plugin_initialized", { providerCount: 0 });
+        return;
+    }
+    let enabledCount = 0;
+    for (const [providerId, providerConfig] of Object.entries(providers)) {
+        if (!providerConfig) {
+            continue;
+        }
+        const opts = parseRateLimitOptions(providerConfig.options);
+        if (!opts) {
+            deps.logger.debug("ratelimit_provider_skipped", { providerId, reason: "not_opted_in" });
+            continue;
+        }
+        const options = (providerConfig.options ??= {});
+        // Compose with any fetch a prior plugin already installed (capture it now,
+        // not at call time, so we delegate to the original — not to ourselves).
+        const delegate = typeof options.fetch === "function" ? options.fetch : undefined;
+        const state = createProviderState();
+        options.fetch = makeRateLimitFetch(providerId, opts, state, deps, delegate);
+        enabledCount += 1;
+        deps.logger.info("ratelimit_provider_enabled", {
+            providerId,
+            maxWaitMs: opts.maxWaitMs,
+            maxRetries: opts.maxRetries,
+            headerPrefix: opts.headerPrefix
+        });
+    }
+    deps.logger.info("ratelimit_plugin_initialized", { providerCount: enabledCount });
+}
+/**
+ * Build the fetch wrapper for one provider. The wrapper:
+ *  1. Pre-request gate: if a cooldown window is armed, waits until it clears.
+ *  2. Sends the request via the underlying fetch.
+ *  3. Reads the rate-limit headers; if the window is exhausted, arms the gate
+ *     (`cooldownUntilMs`) for the next callers.
+ *  4. On a 429, waits the reset window and retries (up to `maxRetries`).
+ *
+ * The Response is returned untouched (no `.clone()`) — we only read `status`
+ * and `headers`, so the body stream is delivered to OpenCode intact.
+ */
+export function makeRateLimitFetch(providerId, opts, state, deps, delegate) {
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? defaultSleep;
+    const underlying = delegate ?? deps.fetchImpl ?? globalThis.fetch;
+    const { logger } = deps;
+    const wrapped = async (input, init) => {
+        const signal = init?.signal ?? undefined;
+        // 1. Pre-request gate.
+        if (state.cooldownUntilMs > now()) {
+            const waitMs = clampWait(state.cooldownUntilMs - now(), opts.maxWaitMs);
+            if (waitMs > 0) {
+                logger.info("ratelimit_throttle_wait", { providerId, waitMs, reason: "remaining_zero" });
+                await waitGate(state, sleep, now, opts.maxWaitMs, signal, logger, providerId, "pre_request");
+            }
+        }
+        // 2-4. Attempt loop.
+        let attempt = 0;
+        for (;;) {
+            const response = await underlying(input, init);
+            const snapshot = readSnapshot(response, opts, now(), logger, providerId);
+            logger.debug("ratelimit_quota", {
+                providerId,
+                remaining: snapshot.remaining,
+                limit: snapshot.limit,
+                resetSeconds: snapshot.resetSeconds
+            });
+            if (response.status !== 429) {
+                // Arm the gate for the NEXT callers when the window is exhausted.
+                if (snapshot.remaining !== undefined &&
+                    snapshot.remaining <= 0 &&
+                    snapshot.resetAtMs !== undefined) {
+                    state.cooldownUntilMs = snapshot.resetAtMs;
+                }
+                return response;
+            }
+            if (attempt >= opts.maxRetries) {
+                logger.error("ratelimit_giveup", { providerId, attempts: attempt });
+                return response;
+            }
+            const waitMs = clampWait(computeBackoff(snapshot, now()), opts.maxWaitMs);
+            state.cooldownUntilMs = now() + waitMs;
+            logger.warn("ratelimit_429_backoff", {
+                providerId,
+                attempt: attempt + 1,
+                waitMs,
+                resetSeconds: snapshot.resetSeconds
+            });
+            await waitGate(state, sleep, now, opts.maxWaitMs, signal, logger, providerId, "backoff");
+            attempt += 1;
+        }
+    };
+    return wrapped;
+}
+function readSnapshot(response, opts, nowMs, logger, providerId) {
+    try {
+        return parseRateLimit(response.headers, opts.headerPrefix, nowMs);
+    }
+    catch (error) {
+        logger.debug("ratelimit_header_parse_failed", {
+            providerId,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return {};
+    }
+}
+function computeBackoff(snapshot, nowMs) {
+    if (snapshot.resetAtMs !== undefined) {
+        return Math.max(0, snapshot.resetAtMs - nowMs);
+    }
+    if (snapshot.retryAfterMs !== undefined) {
+        return snapshot.retryAfterMs;
+    }
+    return DEFAULT_BACKOFF_MS;
+}
+/** `maxWaitMs` of 0 means unlimited (wait the full reset window). */
+function clampWait(ms, maxWaitMs) {
+    const nonNegative = Math.max(0, ms);
+    return maxWaitMs > 0 ? Math.min(nonNegative, maxWaitMs) : nonNegative;
+}
+/**
+ * Wait until `state.cooldownUntilMs` has elapsed. Two concurrency properties:
+ *
+ *  - **One shared timer.** The first caller to hit the gate creates the timer on
+ *    `state.cooldownPromise`; concurrent callers await that same timer rather
+ *    than each starting their own, so a burst during cooldown produces ONE wait,
+ *    not N. The shared timer is not tied to any single caller's `signal` — each
+ *    caller races it against its own signal (see `raceWithAbort`), so one
+ *    request's cancellation never aborts the others.
+ *  - **Honors the longest window.** After the shared timer resolves we re-check
+ *    `cooldownUntilMs`. If another caller extended the window (e.g. a 429 landed
+ *    with a further-out reset) while we were waiting — or the shared timer was
+ *    created for a shorter wait than we now require — we wait again for the
+ *    remainder instead of returning early and hammering the gateway.
+ *
+ * `maxWaitMs` (when > 0) bounds the TOTAL wait of a single call: once a caller
+ * has waited that long it proceeds even if the window hasn't fully elapsed. A
+ * caller that needs LESS than the in-flight shared timer (the window shrank, or
+ * the timer was created by a caller with a later deadline) falls back to its own
+ * private sleep so it is never held past its own required time — the shared
+ * timer is reserved for the common case where everyone is waiting the same span.
+ */
+async function waitGate(state, sleep, now, maxWaitMs, signal, logger, providerId, phase) {
+    const deadlineMs = maxWaitMs > 0 ? now() + maxWaitMs : Number.POSITIVE_INFINITY;
+    for (;;) {
+        const target = Math.min(state.cooldownUntilMs, deadlineMs);
+        const remainingMs = target - now();
+        if (remainingMs <= 0) {
+            return;
+        }
+        // Reuse the shared timer only if it won't make us wait longer than we need.
+        let pending = state.cooldownPromise;
+        if (pending &&
+            state.cooldownPromiseUntilMs !== undefined &&
+            state.cooldownPromiseUntilMs - now() > remainingMs) {
+            pending = undefined;
+        }
+        if (!pending) {
+            const created = sleep(remainingMs).finally(() => {
+                if (state.cooldownPromise === created) {
+                    state.cooldownPromise = undefined;
+                    state.cooldownPromiseUntilMs = undefined;
+                }
+            });
+            // Publish as the shared timer only when there isn't already a (shorter)
+            // one in flight — never clobber it with our longer/private wait.
+            if (!state.cooldownPromise) {
+                state.cooldownPromise = created;
+                state.cooldownPromiseUntilMs = now() + remainingMs;
+            }
+            pending = created;
+        }
+        try {
+            await raceWithAbort(pending, signal);
+        }
+        catch (error) {
+            if (isAbortError(error)) {
+                logger.warn("ratelimit_wait_aborted", { providerId, phase });
+            }
+            throw error;
+        }
+        // Loop: re-check in case the window was extended while we waited.
+    }
+}
+function raceWithAbort(promise, signal) {
+    if (!signal) {
+        return promise;
+    }
+    if (signal.aborted) {
+        return Promise.reject(toAbortError(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(toAbortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+function defaultSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(toAbortError(signal));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(toAbortError(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function toAbortError(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error) {
+        return reason;
+    }
+    return new DOMException("The operation was aborted", "AbortError");
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Resolved, defaults-applied rate-limit configuration for a single provider,
+ * derived from `provider.options.meta.rateLimit`. See {@link parseRateLimitOptions}.
+ */
+export interface RateLimitOptions {
+    /** Whether rate-limit handling is active for this provider. */
+    enabled: boolean;
+    /**
+     * Upper bound on any single wait (pre-request throttle or 429 backoff), in
+     * milliseconds. `0` means unlimited — wait the full reset window.
+     */
+    maxWaitMs: number;
+    /** How many times a 429 is retried before the response is handed back as-is. */
+    maxRetries: number;
+    /**
+     * Lowercased header-name prefix for the IETF draft-03 triple, e.g.
+     * `x-ratelimit` → `x-ratelimit-limit` / `-remaining` / `-reset`.
+     */
+    headerPrefix: string;
+}
+/**
+ * What a single response told us about the current rate-limit window. Every
+ * field is optional: a gateway may emit a partial set, and missing/garbage
+ * headers leave the field `undefined` (treated as "unknown → let requests flow").
+ */
+export interface RateLimitSnapshot {
+    /** Effective limit — the first integer token of `x-ratelimit-limit`. */
+    limit?: number;
+    /** Requests left in the current window (`x-ratelimit-remaining`). */
+    remaining?: number;
+    /** Seconds until the window resets (`x-ratelimit-reset`). */
+    resetSeconds?: number;
+    /** Absolute reset time in epoch ms, derived from `resetSeconds` + observation time. */
+    resetAtMs?: number;
+    /** Fallback wait derived from a `Retry-After` header, in ms (seconds or HTTP-date). */
+    retryAfterMs?: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@vymalo/opencode-ratelimit",
+  "version": "0.5.0",
+  "description": "OpenCode plugin that makes OpenAI-compatible providers rate-limit aware: it reads Envoy Gateway / IETF draft-03 rate-limit response headers (x-ratelimit-limit/remaining/reset), proactively throttles requests when the quota is exhausted, and backs off and retries on HTTP 429.",
+  "license": "MIT",
+  "author": "vymalo contributors",
+  "homepage": "https://github.com/vymalo/opencode-oauth2#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vymalo/opencode-oauth2.git",
+    "directory": "packages/opencode-ratelimit"
+  },
+  "bugs": {
+    "url": "https://github.com/vymalo/opencode-oauth2/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "rate-limit",
+    "throttle",
+    "429",
+    "envoy",
+    "ai-sdk"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./lib": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.15.10"
+  },
+  "devDependencies": {
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "biome lint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "format": "biome format --write .",
+    "format:check": "biome format ."
+  }
+}