@thotischner/observability-mcp 1.7.0 → 1.8.1

package/dist/products/loader.test.js

@@ -0,0 +1,168 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseProductsText, ProductsStore, ProductsLoadError } from "./loader.js";
+test("parseProductsText — empty/minimal products array", () => {
+    const f = parseProductsText("products: []", "test");
+    assert.deepEqual(f.products, []);
+});
+test("parseProductsText — happy path with full shape", () => {
+    const yaml = `
+products:
+  - id: ops-bundle
+    name: Operations Bundle
+    description: Tools for incident response.
+    tools: [query_logs, query_metrics, get_service_health]
+    version: 1.2.0
+    status: published
+    branding:
+      iconUrl: https://example.test/icon.png
+      color: "#3178c6"
+  - id: dev-bundle
+    name: Developer Bundle
+    tools: [query_logs]
+    status: staging
+`;
+    const f = parseProductsText(yaml, "test");
+    assert.equal(f.products.length, 2);
+    assert.equal(f.products[0].id, "ops-bundle");
+    assert.deepEqual(f.products[0].tools, ["query_logs", "query_metrics", "get_service_health"]);
+    assert.equal(f.products[0].status, "published");
+    assert.equal(f.products[0].branding?.color, "#3178c6");
+    assert.equal(f.products[1].status, "staging");
+});
+test("parseProductsText — rejects malformed root / non-array products", () => {
+    assert.throws(() => parseProductsText("[]", "t"), /root must be an object/);
+    assert.throws(() => parseProductsText("products: notalist", "t"), /'products' must be an array/);
+});
+test("parseProductsText — rejects bad id / missing name / duplicate id", () => {
+    assert.throws(() => parseProductsText("products:\n  - id: '..bad'\n    name: x", "t"), /id must be a string matching/);
+    assert.throws(() => parseProductsText("products:\n  - id: ok\n    name: ''", "t"), /name must be a non-empty string/);
+    assert.throws(() => parseProductsText("products:\n  - id: dup\n    name: A\n  - id: dup\n    name: B", "t"), /duplicate product id 'dup'/);
+});
+test("parseProductsText — rejects unknown status / wrong types", () => {
+    assert.throws(() => parseProductsText("products:\n  - id: x\n    name: X\n    status: archived", "t"), /status must be one of/);
+    assert.throws(() => parseProductsText("products:\n  - id: x\n    name: X\n    tools: 'string-not-array'", "t"), /tools must be an array/);
+    assert.throws(() => parseProductsText("products:\n  - id: x\n    name: X\n    version: 42", "t"), /version must be a string/);
+});
+test("parseProductsText — rejects unexpected top-level keys (typo guard)", () => {
+    assert.throws(() => parseProductsText("products:\n  - id: x\n    name: X\n    toolss: []", "t"), /unexpected key 'toolss'/);
+});
+test("parseProductsText — rejects malformed branding shape", () => {
+    assert.throws(() => parseProductsText("products:\n  - id: x\n    name: X\n    branding: notobject", "t"), /branding must be an object/);
+    assert.throws(() => parseProductsText("products:\n  - id: x\n    name: X\n    branding:\n      iconUrl: 42", "t"), /branding.iconUrl must be a string/);
+});
+test("ProductsStore — list / get / count happy paths", () => {
+    const store = new ProductsStore({
+        products: [
+            { id: "a", name: "A", status: "published" },
+            { id: "b", name: "B", status: "staging" },
+            { id: "c", name: "C" }, // no explicit status → not "staging" → visible by default
+        ],
+    });
+    // Default: staging hidden
+    assert.equal(store.list().length, 2);
+    // Include staging
+    assert.equal(store.list({ includeStaging: true }).length, 3);
+    // get unfiltered
+    assert.equal(store.get("a")?.name, "A");
+    assert.equal(store.get("missing"), undefined);
+    // count includes everything
+    assert.equal(store.count(), 3);
+});
+test("ProductsStore — tenant filter scopes list / get / count", () => {
+    const store = new ProductsStore({
+        products: [
+            { id: "acme-ops", name: "Acme Ops", tenant: "acme" },
+            { id: "bigco-ops", name: "BigCo Ops", tenant: "bigco" },
+            { id: "shared", name: "Shared" }, // no tenant → "default"
+        ],
+    });
+    // Tenant-scoped
+    assert.equal(store.list({ tenant: "acme" }).length, 1);
+    assert.equal(store.get("acme-ops", "acme")?.name, "Acme Ops");
+    assert.equal(store.get("bigco-ops", "acme"), undefined, "cross-tenant get returns undefined");
+    assert.equal(store.count("default"), 1, "no-tenant entry counts under 'default'");
+});
+test("ProductsStore — staging hidden by default within a tenant filter", () => {
+    const store = new ProductsStore({
+        products: [
+            { id: "p1", name: "P1", tenant: "acme", status: "published" },
+            { id: "p2", name: "P2", tenant: "acme", status: "staging" },
+        ],
+    });
+    assert.equal(store.list({ tenant: "acme" }).length, 1, "staging is hidden");
+    assert.equal(store.list({ tenant: "acme", includeStaging: true }).length, 2);
+});
+test("ProductsStore.upsert — replaces existing, appends new", () => {
+    const store = new ProductsStore({
+        products: [
+            { id: "a", name: "Original" },
+            { id: "b", name: "Second" },
+        ],
+    });
+    // Replace existing
+    store.upsert({ id: "a", name: "Replaced" });
+    assert.equal(store.get("a")?.name, "Replaced");
+    assert.equal(store.count(), 2);
+    // Append new
+    store.upsert({ id: "c", name: "New" });
+    assert.equal(store.count(), 3);
+    assert.equal(store.get("c")?.name, "New");
+});
+test("ProductsStore.delete — returns removed flag + survivors", () => {
+    const store = new ProductsStore({
+        products: [{ id: "a", name: "A" }, { id: "b", name: "B" }],
+    });
+    const r1 = store.delete("a");
+    assert.equal(r1.removed, true);
+    assert.equal(store.count(), 1);
+    // Re-delete is a no-op
+    const r2 = store.delete("a");
+    assert.equal(r2.removed, false);
+    // Unknown id
+    const r3 = store.delete("nope");
+    assert.equal(r3.removed, false);
+});
+test("validateProduct — accepts a valid entry, rejects bad shape via same parser", async () => {
+    // Happy path
+    const p = await import("./loader.js").then((m) => m.validateProduct({ id: "x", name: "X" }));
+    assert.equal(p.name, "X");
+    // Bad shape uses the loader's strict rules
+    const { validateProduct } = await import("./loader.js");
+    assert.throws(() => validateProduct({ id: "x", name: "X", unknownKey: 1 }), /unexpected key 'unknownKey'/);
+    assert.throws(() => validateProduct({ id: "..bad", name: "X" }), /id must be a string matching/);
+});
+test("writeProductsFile + readProductsFile — atomic round-trip", async () => {
+    const { mkdtemp, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const { writeProductsFile, readProductsFile } = await import("./loader.js");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-products-"));
+    try {
+        const file = join(dir, "products.yaml");
+        await writeProductsFile(file, {
+            products: [
+                { id: "a", name: "A", status: "published" },
+                { id: "b", name: "B", tools: ["query_logs"], tenant: "acme" },
+            ],
+        });
+        const reloaded = await readProductsFile(file);
+        assert.equal(reloaded.products.length, 2);
+        assert.equal(reloaded.products[0].status, "published");
+        assert.equal(reloaded.products[1].tenant, "acme");
+        assert.deepEqual(reloaded.products[1].tools, ["query_logs"]);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("ProductsLoadError is the throw class", () => {
+    try {
+        parseProductsText("not-json", "t");
+    }
+    catch (e) {
+        assert.ok(e instanceof ProductsLoadError);
+        return;
+    }
+    assert.fail("expected throw");
+});

package/dist/quota/limiter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Per-identity sliding-window rate limiter for the MCP tool surface.
+ *
+ * The bearer-token credential resolved by `auth/credentials.ts`
+ * (`OMCP_API_KEYS`) names every distinct caller; this limiter caps how
+ * many MCP tool calls each named caller can make per minute. Anonymous
+ * MCP traffic (when no `OMCP_API_KEYS` is set) bypasses the per-identity
+ * cap — the existing express-rate-limit IP gate at the /mcp transport
+ * still applies.
+ *
+ * The window is sliding: each call records its timestamp under the
+ * identity's key, and `check()` first prunes entries older than the
+ * configured window before counting. Memory bound is O(callers × N)
+ * where N is the per-window cap — a few KB even for a busy deployment.
+ *
+ * Persistence is out of scope here. A future revision can plug a
+ * Redis-backed store via the same interface.
+ */
+/** Resolve `OMCP_TOOL_RATE_PER_MIN` (or any equivalent caller-supplied
+ * string) into the per-identity cap used by the limiter and reported
+ * by `/api/info` + `/api/usage`. Single source of truth, so the three
+ * call sites don't drift.
+ *
+ * Behaviour:
+ * - unset / empty / non-numeric → DEFAULT_LIMIT_PER_MIN (60)
+ * - `"0"` → DEFAULT_LIMIT_PER_MIN (limit=0 would deny every request,
+ *   which is almost never what an operator setting "0" wants — they
+ *   either mean "default" or "disable"; we treat it as "default" and
+ *   leave the explicit disable path on the roadmap)
+ * - negative → DEFAULT_LIMIT_PER_MIN (limit=-1 with the current
+ *   `count >= limit` check would also deny every request)
+ * - any positive integer ≥ 1 → that value
+ */
+export declare function resolveToolRatePerMin(raw: string | undefined): number;
+export interface LimiterConfig {
+    /** Cap per identity per window. Defaults to 60. */
+    limit?: number;
+    /** Window length in milliseconds. Defaults to 60_000. */
+    windowMs?: number;
+}
+export interface CheckResult {
+    /** True when the call is allowed (and the timestamp recorded). */
+    allowed: boolean;
+    /** Number of calls already made in the current window (after counting this one if allowed). */
+    count: number;
+    /** Configured per-window cap. */
+    limit: number;
+    /** Window length in ms. */
+    windowMs: number;
+    /** Seconds until the oldest in-window record falls off and a new
+     * slot opens. 0 when allowed. */
+    retryAfterSeconds: number;
+}
+export declare class IdentityRateLimiter {
+    private readonly limit;
+    private readonly windowMs;
+    private readonly buckets;
+    constructor(cfg?: LimiterConfig);
+    /** Record-and-test a call for the given identity. Returns the
+     * decision plus enough context to render a 429 with Retry-After. */
+    check(identity: string, now?: number): CheckResult;
+    /** Read-only snapshot — useful for /api/usage and tests. */
+    inspect(identity: string, now?: number): {
+        count: number;
+        limit: number;
+        windowMs: number;
+    };
+    /** All identities we've ever seen — for /api/usage aggregation. */
+    knownIdentities(): string[];
+    /** For testing — reset every identity's bucket. */
+    reset(): void;
+}

package/dist/quota/limiter.js

@@ -0,0 +1,105 @@
+/**
+ * Per-identity sliding-window rate limiter for the MCP tool surface.
+ *
+ * The bearer-token credential resolved by `auth/credentials.ts`
+ * (`OMCP_API_KEYS`) names every distinct caller; this limiter caps how
+ * many MCP tool calls each named caller can make per minute. Anonymous
+ * MCP traffic (when no `OMCP_API_KEYS` is set) bypasses the per-identity
+ * cap — the existing express-rate-limit IP gate at the /mcp transport
+ * still applies.
+ *
+ * The window is sliding: each call records its timestamp under the
+ * identity's key, and `check()` first prunes entries older than the
+ * configured window before counting. Memory bound is O(callers × N)
+ * where N is the per-window cap — a few KB even for a busy deployment.
+ *
+ * Persistence is out of scope here. A future revision can plug a
+ * Redis-backed store via the same interface.
+ */
+const DEFAULT_LIMIT_PER_MIN = 60;
+const DEFAULT_WINDOW_MS = 60_000;
+/** Resolve `OMCP_TOOL_RATE_PER_MIN` (or any equivalent caller-supplied
+ * string) into the per-identity cap used by the limiter and reported
+ * by `/api/info` + `/api/usage`. Single source of truth, so the three
+ * call sites don't drift.
+ *
+ * Behaviour:
+ * - unset / empty / non-numeric → DEFAULT_LIMIT_PER_MIN (60)
+ * - `"0"` → DEFAULT_LIMIT_PER_MIN (limit=0 would deny every request,
+ *   which is almost never what an operator setting "0" wants — they
+ *   either mean "default" or "disable"; we treat it as "default" and
+ *   leave the explicit disable path on the roadmap)
+ * - negative → DEFAULT_LIMIT_PER_MIN (limit=-1 with the current
+ *   `count >= limit` check would also deny every request)
+ * - any positive integer ≥ 1 → that value
+ */
+export function resolveToolRatePerMin(raw) {
+    if (raw === undefined || raw === "")
+        return DEFAULT_LIMIT_PER_MIN;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+        return DEFAULT_LIMIT_PER_MIN;
+    return Math.floor(n);
+}
+export class IdentityRateLimiter {
+    limit;
+    windowMs;
+    // identity → ring of millisecond timestamps, newest at the end.
+    buckets = new Map();
+    constructor(cfg = {}) {
+        this.limit = cfg.limit ?? DEFAULT_LIMIT_PER_MIN;
+        this.windowMs = cfg.windowMs ?? DEFAULT_WINDOW_MS;
+    }
+    /** Record-and-test a call for the given identity. Returns the
+     * decision plus enough context to render a 429 with Retry-After. */
+    check(identity, now = Date.now()) {
+        const cutoff = now - this.windowMs;
+        const bucket = this.buckets.get(identity) ?? [];
+        // Drop expired entries from the front of the bucket.
+        let i = 0;
+        while (i < bucket.length && bucket[i] <= cutoff)
+            i++;
+        const fresh = i === 0 ? bucket : bucket.slice(i);
+        if (fresh.length >= this.limit) {
+            // Compute when the oldest in-window record drops off.
+            const retryAfterMs = fresh[0] + this.windowMs - now;
+            // Don't store the call we just denied — that would push the
+            // window forward and starve the next legitimate request.
+            this.buckets.set(identity, fresh);
+            return {
+                allowed: false,
+                count: fresh.length,
+                limit: this.limit,
+                windowMs: this.windowMs,
+                retryAfterSeconds: Math.max(1, Math.ceil(retryAfterMs / 1000)),
+            };
+        }
+        fresh.push(now);
+        this.buckets.set(identity, fresh);
+        return {
+            allowed: true,
+            count: fresh.length,
+            limit: this.limit,
+            windowMs: this.windowMs,
+            retryAfterSeconds: 0,
+        };
+    }
+    /** Read-only snapshot — useful for /api/usage and tests. */
+    inspect(identity, now = Date.now()) {
+        const cutoff = now - this.windowMs;
+        const bucket = this.buckets.get(identity) ?? [];
+        let count = 0;
+        for (const t of bucket)
+            if (t > cutoff)
+                count++;
+        return { count, limit: this.limit, windowMs: this.windowMs };
+    }
+    /** All identities we've ever seen — for /api/usage aggregation. */
+    knownIdentities() {
+        return Array.from(this.buckets.keys());
+    }
+    /** For testing — reset every identity's bucket. */
+    reset() {
+        this.buckets.clear();
+    }
+}

package/dist/quota/limiter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/quota/limiter.test.js

@@ -0,0 +1,119 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { IdentityRateLimiter, resolveToolRatePerMin } from "./limiter.js";
+test("resolveToolRatePerMin — unset / empty / non-numeric returns default 60", () => {
+    assert.equal(resolveToolRatePerMin(undefined), 60);
+    assert.equal(resolveToolRatePerMin(""), 60);
+    assert.equal(resolveToolRatePerMin("not-a-number"), 60);
+    assert.equal(resolveToolRatePerMin("NaN"), 60);
+});
+test("resolveToolRatePerMin — zero / negative falls back to default (limit=0 would deny every call)", () => {
+    // Footgun pin: "0" looks like "disable" but the limiter treats it as
+    // "instantly over-cap". Treat as default so operators don't lock
+    // themselves out by mistake.
+    assert.equal(resolveToolRatePerMin("0"), 60);
+    assert.equal(resolveToolRatePerMin("-1"), 60);
+    assert.equal(resolveToolRatePerMin("-1000"), 60);
+});
+test("resolveToolRatePerMin — positive integer passes through; decimals floored", () => {
+    assert.equal(resolveToolRatePerMin("1"), 1);
+    assert.equal(resolveToolRatePerMin("120"), 120);
+    assert.equal(resolveToolRatePerMin("240"), 240);
+    assert.equal(resolveToolRatePerMin("60.7"), 60);
+});
+test("allows up to the configured limit, then denies", () => {
+    const lim = new IdentityRateLimiter({ limit: 3, windowMs: 60_000 });
+    const t = 1_700_000_000_000;
+    assert.equal(lim.check("alice", t + 0).allowed, true);
+    assert.equal(lim.check("alice", t + 100).allowed, true);
+    assert.equal(lim.check("alice", t + 200).allowed, true);
+    const denied = lim.check("alice", t + 300);
+    assert.equal(denied.allowed, false);
+    assert.equal(denied.count, 3);
+    assert.equal(denied.limit, 3);
+    assert.ok(denied.retryAfterSeconds >= 1);
+});
+test("sliding window: expired entries free up slots", () => {
+    const lim = new IdentityRateLimiter({ limit: 2, windowMs: 10_000 });
+    const t = 1_700_000_000_000;
+    lim.check("alice", t + 0);
+    lim.check("alice", t + 5_000);
+    // At t+9s alice is still at the cap.
+    assert.equal(lim.check("alice", t + 9_000).allowed, false);
+    // At t+11s the first entry has aged out → one slot opens.
+    const after = lim.check("alice", t + 11_000);
+    assert.equal(after.allowed, true);
+    assert.equal(after.count, 2);
+});
+test("identities are isolated from each other", () => {
+    const lim = new IdentityRateLimiter({ limit: 1, windowMs: 60_000 });
+    const t = 1_700_000_000_000;
+    assert.equal(lim.check("alice", t).allowed, true);
+    assert.equal(lim.check("alice", t).allowed, false);
+    // bob has his own fresh bucket.
+    assert.equal(lim.check("bob", t).allowed, true);
+});
+test("retryAfterSeconds points at the oldest in-window record's expiry", () => {
+    const lim = new IdentityRateLimiter({ limit: 1, windowMs: 30_000 });
+    const t = 1_700_000_000_000;
+    lim.check("alice", t);
+    const denied = lim.check("alice", t + 5_000);
+    assert.equal(denied.allowed, false);
+    // 30s window started at t, so expiry is t+30s → 25s from t+5s.
+    assert.equal(denied.retryAfterSeconds, 25);
+});
+test("denied calls do NOT push the window forward", () => {
+    const lim = new IdentityRateLimiter({ limit: 1, windowMs: 10_000 });
+    const t = 1_700_000_000_000;
+    lim.check("alice", t);
+    // Multiple denies — none of them should reset the oldest-timestamp.
+    for (let i = 1; i < 10; i++)
+        lim.check("alice", t + i * 100);
+    // Still expecting expiry at t+10s, not pushed forward by the denies.
+    const justAfterExpiry = lim.check("alice", t + 10_001);
+    assert.equal(justAfterExpiry.allowed, true);
+});
+test("inspect: returns counts without consuming a slot", () => {
+    const lim = new IdentityRateLimiter({ limit: 5, windowMs: 60_000 });
+    const t = 1_700_000_000_000;
+    lim.check("alice", t);
+    lim.check("alice", t);
+    const ins = lim.inspect("alice", t);
+    assert.equal(ins.count, 2);
+    assert.equal(ins.limit, 5);
+    // Subsequent check still has room for 3 more.
+    assert.equal(lim.check("alice", t).allowed, true);
+});
+test("knownIdentities — returns every identity that has been checked", () => {
+    const lim = new IdentityRateLimiter({ limit: 5, windowMs: 60_000 });
+    const t = 1_700_000_000_000;
+    lim.check("alice", t);
+    lim.check("bob", t);
+    lim.check("alice", t);
+    const ids = lim.knownIdentities().sort();
+    assert.deepEqual(ids, ["alice", "bob"]);
+});
+test("inspect on an unknown identity returns count=0", () => {
+    const lim = new IdentityRateLimiter({ limit: 5, windowMs: 60_000 });
+    const ins = lim.inspect("never-seen");
+    assert.equal(ins.count, 0);
+    assert.equal(ins.limit, 5);
+});
+test("reset clears all buckets", () => {
+    const lim = new IdentityRateLimiter({ limit: 1, windowMs: 60_000 });
+    const t = 1_700_000_000_000;
+    lim.check("alice", t);
+    lim.check("bob", t);
+    lim.reset();
+    assert.equal(lim.check("alice", t).allowed, true);
+    assert.equal(lim.check("bob", t).allowed, true);
+});
+test("default limit applies when constructed with no args", () => {
+    const lim = new IdentityRateLimiter();
+    // Exhaust the default 60/min cap.
+    const t = 1_700_000_000_000;
+    for (let i = 0; i < 60; i++) {
+        assert.equal(lim.check("alice", t + i).allowed, true);
+    }
+    assert.equal(lim.check("alice", t + 60).allowed, false);
+});

package/dist/quota/token-budget.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Per-identity token-budget tracker.
+ *
+ * The MCP transport gets per-call sliding-window cap from
+ * `IdentityRateLimiter`. Operators with paid-tier LLM agents want a
+ * second axis: a daily token quota that limits the number of tokens
+ * a credential can pull through the tool layer in a 24-hour rolling
+ * window. This module is the data-plane half of that knob.
+ *
+ * Token estimation:
+ *   The MCP tool response (and the agent's request args) cross the
+ *   boundary as JSON text. We don't tokenize with a real tokenizer
+ *   here — pulling in tiktoken / gpt-tokenizer would add a non-trivial
+ *   wasm/dep that the airgapped-friendly posture wants to avoid. The
+ *   estimate uses a deliberate over-approximation:
+ *       tokens ≈ ceil(chars / 4) * 1.05
+ *   which tends to over-count by ~5% vs. cl100k_base on prose payloads
+ *   and ~15% on dense code/JSON. Under-counting is the worse error
+ *   mode for budget control, so the rounding direction is intentional.
+ *
+ * Window:
+ *   24h rolling, bucketed at 1-hour resolution to keep memory bounded.
+ *   Each bucket records (hour-aligned timestamp, tokens). On every
+ *   `check()` we drop buckets older than 24h and sum the rest.
+ *
+ * Persistence is OUT OF SCOPE for this slice (planned for E6/3). The
+ * in-memory tracker is constructed fresh at boot; restart-survival
+ * requires the persistence layer.
+ */
+/** Estimate tokens from a string. Intentionally over-counts. */
+export declare function estimateTokens(text: string): number;
+/** Estimate tokens for an arbitrary JSON-serialisable value. */
+export declare function estimateTokensFor(v: unknown): number;
+export interface TokenBudgetConfig {
+    /** Daily cap in tokens per identity. 0 / undefined / negative
+     *  disables the cap (the limiter never denies). */
+    dailyLimit?: number;
+    /** Override Date.now for tests. */
+    now?: () => number;
+    /** Optional path to a JSON snapshot file. When set, the tracker
+     *  loads buckets on bootstrap() and atomically rewrites the
+     *  snapshot on a debounced timer after each charge — so a server
+     *  restart picks up the rolling 24h window where it left off.
+     *  Unset → in-memory only (fine for demo / single-instance). */
+    filePath?: string;
+    /** Debounce window in ms for snapshot writes; default 1000. Tests
+     *  pass 0 to flush synchronously between assertions. */
+    flushDebounceMs?: number;
+}
+export interface CheckResult {
+    allowed: boolean;
+    /** Tokens used in the trailing 24h window AFTER this call was
+     *  counted (when allowed) — or as of now (when denied). */
+    used: number;
+    /** Configured daily cap. 0 means uncapped. */
+    limit: number;
+    /** Seconds until ENOUGH buckets drop off to fit the denied request.
+     *  Walks the bucket list oldest-first and stops at the first
+     *  timestamp where dropping every bucket older would free
+     *  >= (used + tokens - limit) tokens. Rounded up. 0 when allowed
+     *  (or when uncapped). */
+    retryAfterSeconds: number;
+    /** How many tokens will be available again at retryAfterSeconds.
+     *  Useful for HTTP 429 bodies + Retry-After hints. 0 when allowed. */
+    freedAtRetry: number;
+}
+/** Per-identity 24h-rolling token budget with 1h buckets. */
+export declare class TokenBudget {
+    private readonly limit;
+    private readonly now;
+    private readonly buckets;
+    private readonly filePath;
+    private readonly debounceMs;
+    private flushTimer;
+    private writeQueue;
+    private bootstrapped;
+    constructor(cfg?: TokenBudgetConfig);
+    /** Load a prior snapshot from disk (when filePath is set).
+     *  Safe to call multiple times — bootstraps once and caches. */
+    bootstrap(): Promise<void>;
+    /** Record-and-test: does adding `tokens` keep `identity` under the
+     *  daily cap? When `allowed`, the tokens are persisted into the
+     *  bucket; when denied, they are NOT recorded (so a single huge
+     *  request can't push the bucket arbitrarily over the cap and
+     *  starve the rest of the window). */
+    check(identity: string, tokens: number, now?: number): CheckResult;
+    /** Read-only snapshot for /api/usage. */
+    inspect(identity: string, now?: number): {
+        used: number;
+        limit: number;
+        windowMs: number;
+    };
+    /** All identities the tracker has ever seen — for /api/usage aggregation. */
+    knownIdentities(): string[];
+    /** For tests — clear everything. */
+    reset(): void;
+    /** Internal: append `tokens` to the current hour's bucket for
+     *  `identity`. Creates a new bucket when the hour boundary rolls. */
+    private record;
+    /** Debounce a snapshot write. No-op when filePath isn't configured. */
+    private scheduleFlush;
+    /** Write the current bucket state to disk atomically (tmp + rename).
+     *  Public so a graceful shutdown can `await tokenBudget.flushNow()`. */
+    flushNow(): Promise<void>;
+    /** Internal: drop buckets older than 24h and return the remainder. */
+    private pruneOld;
+    private usedInWindow;
+    /** Walk the bucket list oldest-first until enough tokens would have
+     *  dropped off to fit a request needing `needed` extra headroom.
+     *  Returns the wait in ms + the cumulative freed tokens at that
+     *  point. When `needed` exceeds the entire window's content (the
+     *  caller wants more than the cap), returns the time until the
+     *  newest bucket drops + everything freed. */
+    private nextEnoughHeadroom;
+}
+/** Parse OMCP_TOOL_DAILY_TOKENS into a daily limit. Mirrors the
+ *  resolveToolRatePerMin pattern: unset / empty / non-numeric /
+ *  zero / negative → uncapped (0). Positive integers pass through. */
+export declare function resolveDailyTokenLimit(raw: string | undefined): number;