@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/quota/charge.test.js

@@ -0,0 +1,83 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { applyBudgetDecision } from "./charge.js";
+function decision(over) {
+    return {
+        allowed: false,
+        used: 0,
+        limit: 1000,
+        retryAfterSeconds: 3600,
+        freedAtRetry: 100,
+        ...over,
+    };
+}
+const sampleResult = () => ({ content: [{ text: "original tool output" }] });
+test("applyBudgetDecision — passes the result through when allowed", () => {
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ allowed: true }), 50, "query_logs");
+    assert.equal(out, r, "exact passthrough when allowed");
+});
+test("applyBudgetDecision — passes through when uncapped (limit === 0)", () => {
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ allowed: false, limit: 0 }), 50_000, "query_logs");
+    assert.equal(out.content[0].text, "original tool output");
+});
+test("applyBudgetDecision — cumulative exceed emits OMCP_TOKEN_BUDGET_EXCEEDED", () => {
+    // Tokens fit a single request (<= limit) but cumulative pushes over.
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ used: 950, limit: 1000, retryAfterSeconds: 7200, freedAtRetry: 200 }), 100, "query_logs");
+    const body = JSON.parse(out.content[0].text);
+    assert.equal(body.error, "OMCP_TOKEN_BUDGET_EXCEEDED");
+    assert.equal(body.tool, "query_logs");
+    assert.equal(body.used, 950);
+    assert.equal(body.limit, 1000);
+    assert.equal(body.requested, 100);
+    assert.equal(body.retryAfterSeconds, 7200);
+    assert.equal(body.freedAtRetry, 200);
+    assert.match(body.message, /Daily token budget exceeded/);
+    assert.match(body.message, /Try again in ~2h/);
+});
+test("applyBudgetDecision — single request > limit emits the DISTINCT OMCP_TOKEN_REQUEST_EXCEEDS_BUDGET", () => {
+    // The whole point of the distinct code: an agent that sees this
+    // must NOT retry — waiting can never fit a request larger than the
+    // entire daily cap. retryAfterSeconds is forced to 0 so naive
+    // backoff loops terminate.
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ used: 0, limit: 1000, retryAfterSeconds: 3600, freedAtRetry: 0 }), 5000, // request > limit
+    "query_metrics");
+    const body = JSON.parse(out.content[0].text);
+    assert.equal(body.error, "OMCP_TOKEN_REQUEST_EXCEEDS_BUDGET");
+    assert.equal(body.tool, "query_metrics");
+    assert.equal(body.requested, 5000);
+    assert.equal(body.limit, 1000);
+    assert.equal(body.retryAfterSeconds, 0, "retry-loop killer: 0 instead of inherited 3600");
+    assert.match(body.message, /larger than the entire daily budget/);
+    assert.match(body.message, /Retrying won't help/);
+});
+test("applyBudgetDecision — boundary: request == limit is NOT the request-exceeds-cap code", () => {
+    // A request exactly equal to the cap can theoretically succeed on
+    // an empty bucket — it's the cumulative-exceeded path, not the
+    // unconditional-deny path.
+    const r = sampleResult();
+    const out = applyBudgetDecision(r, decision({ used: 100, limit: 1000 }), 1000, "query_logs");
+    const body = JSON.parse(out.content[0].text);
+    assert.equal(body.error, "OMCP_TOKEN_BUDGET_EXCEEDED");
+});
+test("applyBudgetDecision — preserves additional content entries past the first", () => {
+    const r = {
+        content: [
+            { text: "first", extraField: 42 },
+            { text: "second" },
+            { text: "third" },
+        ],
+    };
+    const out = applyBudgetDecision(r, decision({}), 10, "t");
+    assert.equal(out.content.length, 3);
+    // First entry's text replaced; its other fields (extraField) preserved.
+    const body = JSON.parse(out.content[0].text);
+    assert.equal(body.error, "OMCP_TOKEN_BUDGET_EXCEEDED");
+    assert.equal(out.content[0].extraField, 42);
+    // Trailing entries pass through verbatim.
+    assert.equal(out.content[1].text, "second");
+    assert.equal(out.content[2].text, "third");
+});

package/dist/quota/limiter.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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"; this function maps it to the
+ *   default so they aren't accidentally locked out, and the explicit
+ *   disable path is one of the UNLIMITED_TOKENS instead)
+ * - `"off"` / `"none"` / `"unlimited"` / `"disabled"` / `"false"`
+ *   (case-insensitive) → Number.POSITIVE_INFINITY, which the
+ *   `count >= limit` comparison in check() always allows. JSON
+ *   serialisation renders Infinity as `null`; consumers can treat
+ *   a null limit as "uncapped".
+ * - 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 {
+    /** Default cap per identity per window. Defaults to 60. */
+    limit?: number;
+    /** Window length in milliseconds. Defaults to 60_000. */
+    windowMs?: number;
+    /** Optional per-identity override. Returns the cap for the named
+     *  identity, or undefined to fall back to the default `limit`.
+     *  Useful for the OMCP_KEY_RATE_PER_MIN credential-level override
+     *  (`agent=600;ci=240`) — admin gives a noisy automation a higher
+     *  quota without affecting every other caller. Returning Infinity
+     *  disables the cap for that identity (matches the global
+     *  unlimited-token contract). */
+    limitFor?: (identity: string) => number | undefined;
+}
+/** Parse OMCP_KEY_RATE_PER_MIN — `name=count;name2=count2`. Same
+ *  shape as parseKeyTenants / parseKeyProducts so operators have one
+ *  syntactic model across all per-credential overrides. Unknown
+ *  counts (non-numeric / ≤ 0) silently skip. Magic disable tokens
+ *  (off/none/unlimited/disabled/false) map to Infinity, same as the
+ *  global OMCP_TOOL_RATE_PER_MIN. */
+export declare function parseKeyRateLimits(raw: string | undefined): Map<string, 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 defaultLimit;
+    private readonly windowMs;
+    private readonly limitFor?;
+    private readonly buckets;
+    constructor(cfg?: LimiterConfig);
+    /** Resolved cap for one identity: the per-identity override wins
+     *  when defined; otherwise the process-wide default applies. */
+    private resolveLimit;
+    /** 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,161 @@
+/**
+ * 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;
+/** Magic strings that explicitly disable the per-identity cap.
+ *  Matched case-insensitively. Operators picked any of these to
+ *  mean "no rate limit at all" — useful when the caps are enforced
+ *  upstream (envoy / API-gateway) and OMCP shouldn't double-count. */
+const UNLIMITED_TOKENS = new Set(["off", "none", "unlimited", "disabled", "false"]);
+/** 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"; this function maps it to the
+ *   default so they aren't accidentally locked out, and the explicit
+ *   disable path is one of the UNLIMITED_TOKENS instead)
+ * - `"off"` / `"none"` / `"unlimited"` / `"disabled"` / `"false"`
+ *   (case-insensitive) → Number.POSITIVE_INFINITY, which the
+ *   `count >= limit` comparison in check() always allows. JSON
+ *   serialisation renders Infinity as `null`; consumers can treat
+ *   a null limit as "uncapped".
+ * - 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;
+    if (UNLIMITED_TOKENS.has(raw.trim().toLowerCase()))
+        return Number.POSITIVE_INFINITY;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+        return DEFAULT_LIMIT_PER_MIN;
+    return Math.floor(n);
+}
+/** Parse OMCP_KEY_RATE_PER_MIN — `name=count;name2=count2`. Same
+ *  shape as parseKeyTenants / parseKeyProducts so operators have one
+ *  syntactic model across all per-credential overrides. Unknown
+ *  counts (non-numeric / ≤ 0) silently skip. Magic disable tokens
+ *  (off/none/unlimited/disabled/false) map to Infinity, same as the
+ *  global OMCP_TOOL_RATE_PER_MIN. */
+export function parseKeyRateLimits(raw) {
+    const m = new Map();
+    if (!raw)
+        return m;
+    for (const entry of raw.split(";").map((s) => s.trim()).filter(Boolean)) {
+        const eq = entry.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const name = entry.slice(0, eq).trim();
+        const valueRaw = entry.slice(eq + 1).trim();
+        if (!name || !valueRaw)
+            continue;
+        if (UNLIMITED_TOKENS.has(valueRaw.toLowerCase())) {
+            m.set(name, Number.POSITIVE_INFINITY);
+            continue;
+        }
+        const n = Number(valueRaw);
+        if (!Number.isFinite(n) || n < 1)
+            continue;
+        m.set(name, Math.floor(n));
+    }
+    return m;
+}
+export class IdentityRateLimiter {
+    defaultLimit;
+    windowMs;
+    limitFor;
+    // identity → ring of millisecond timestamps, newest at the end.
+    buckets = new Map();
+    constructor(cfg = {}) {
+        this.defaultLimit = cfg.limit ?? DEFAULT_LIMIT_PER_MIN;
+        this.windowMs = cfg.windowMs ?? DEFAULT_WINDOW_MS;
+        this.limitFor = cfg.limitFor;
+    }
+    /** Resolved cap for one identity: the per-identity override wins
+     *  when defined; otherwise the process-wide default applies. */
+    resolveLimit(identity) {
+        if (this.limitFor) {
+            const v = this.limitFor(identity);
+            if (typeof v === "number" && (Number.isFinite(v) ? v >= 1 : v === Number.POSITIVE_INFINITY)) {
+                return v;
+            }
+        }
+        return this.defaultLimit;
+    }
+    /** 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);
+        const limit = this.resolveLimit(identity);
+        if (fresh.length >= 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,
+                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,
+            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.resolveLimit(identity), 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,205 @@
+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);
+});
+test("resolveToolRatePerMin — explicit-disable tokens map to Infinity (any case, with whitespace)", () => {
+    for (const tok of ["off", "OFF", "Off", "none", "NONE", "unlimited", "UNLIMITED", "disabled", "false", "  off  "]) {
+        assert.equal(resolveToolRatePerMin(tok), Number.POSITIVE_INFINITY, `'${tok}' should disable the limiter`);
+    }
+});
+test("IdentityRateLimiter — limit=Infinity always allows (the explicit-disable contract)", () => {
+    const lim = new IdentityRateLimiter({ limit: Number.POSITIVE_INFINITY });
+    const t = 1_700_000_000_000;
+    // Burst far past the default cap; every call must allow.
+    for (let i = 0; i < 1000; i++) {
+        const r = lim.check("alice", t + i);
+        assert.equal(r.allowed, true);
+        assert.equal(r.retryAfterSeconds, 0);
+        // Limit reflects the configured Infinity — JSON serialisation
+        // would render this as null; callers can branch on Number.isFinite.
+        assert.equal(r.limit, Number.POSITIVE_INFINITY);
+    }
+});
+test("resolveToolRatePerMin — disable tokens are NOT a number trap (\"infinity\" alone is not a token)", () => {
+    // We deliberately do NOT accept the literal string "infinity"
+    // because Number("Infinity") === Infinity — operators expect
+    // OMCP_TOOL_RATE_PER_MIN=Infinity to error out, not silently
+    // mean "unlimited". The explicit tokens are off/none/unlimited/
+    // disabled/false. (Number.isFinite is what the resolver checks.)
+    assert.equal(resolveToolRatePerMin("Infinity"), 60, "literal 'Infinity' must NOT secretly enable unlimited mode");
+});
+import { parseKeyRateLimits } from "./limiter.js";
+test("parseKeyRateLimits — parses name=count pairs, skips malformed entries", () => {
+    const m = parseKeyRateLimits("agent=600;ci=240;bad;empty=;negative=-1;zero=0;notnum=abc");
+    assert.equal(m.get("agent"), 600);
+    assert.equal(m.get("ci"), 240);
+    assert.equal(m.get("bad"), undefined);
+    assert.equal(m.get("empty"), undefined);
+    assert.equal(m.get("negative"), undefined);
+    assert.equal(m.get("zero"), undefined);
+    assert.equal(m.get("notnum"), undefined);
+});
+test("parseKeyRateLimits — disable tokens map to Infinity (same vocabulary as the global override)", () => {
+    const m = parseKeyRateLimits("agent=off;ci=unlimited;loud=DISABLED");
+    assert.equal(m.get("agent"), Number.POSITIVE_INFINITY);
+    assert.equal(m.get("ci"), Number.POSITIVE_INFINITY);
+    assert.equal(m.get("loud"), Number.POSITIVE_INFINITY);
+});
+test("IdentityRateLimiter — limitFor override wins over the default cap", () => {
+    // Default is 60; override gives agent=2.
+    const lim = new IdentityRateLimiter({
+        limit: 60,
+        limitFor: (id) => (id === "default agent" ? 2 : undefined),
+    });
+    const t = 1_700_000_000_000;
+    // Two calls allowed for agent, third denies.
+    assert.equal(lim.check("default agent", t).allowed, true);
+    assert.equal(lim.check("default agent", t + 1).allowed, true);
+    const denied = lim.check("default agent", t + 2);
+    assert.equal(denied.allowed, false);
+    assert.equal(denied.limit, 2, "reported limit must be the per-identity override, not the default");
+    // Default identity still gets the global 60.
+    for (let i = 0; i < 60; i++) {
+        assert.equal(lim.check("default other", t + i).allowed, true);
+    }
+    assert.equal(lim.check("default other", t + 60).allowed, false);
+});
+test("IdentityRateLimiter — limitFor returning undefined falls back to default; Infinity disables for that identity", () => {
+    const lim = new IdentityRateLimiter({
+        limit: 5,
+        limitFor: (id) => (id === "default vip" ? Number.POSITIVE_INFINITY : undefined),
+    });
+    const t = 1_700_000_000_000;
+    // VIP can burst far past 5.
+    for (let i = 0; i < 1000; i++) {
+        assert.equal(lim.check("default vip", t + i).allowed, true);
+    }
+    // Default user still capped at 5.
+    for (let i = 0; i < 5; i++) {
+        assert.equal(lim.check("default user", t + i).allowed, true);
+    }
+    assert.equal(lim.check("default user", t + 5).allowed, false);
+});
+test("IdentityRateLimiter — inspect() reports the per-identity limit too (not just the default)", () => {
+    const lim = new IdentityRateLimiter({
+        limit: 60,
+        limitFor: (id) => (id === "default agent" ? 600 : undefined),
+    });
+    assert.equal(lim.inspect("default agent").limit, 600);
+    assert.equal(lim.inspect("default other").limit, 60);
+});

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;