@thotischner/observability-mcp 1.8.1 → 3.0.0

package/dist/postmortem/synthesizer.test.d.ts

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

package/dist/postmortem/synthesizer.test.js

@@ -0,0 +1,141 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { synthesizePostmortem, } from "./synthesizer.js";
+function input(overrides = {}) {
+    return {
+        service: "payment",
+        window: "1h",
+        tenant: "default",
+        fromIso: "2026-06-06T00:00:00.000Z",
+        toIso: "2026-06-06T01:00:00.000Z",
+        anomalies: [],
+        blastRadius: { nodes: [], edges: [] },
+        traces: [],
+        ...overrides,
+    };
+}
+function anomaly(ts, score, method = "mad", severity = "warn", signal) {
+    return { ts, service: "payment", score, method, severity, signal };
+}
+test("synthesizePostmortem: empty input returns synopsis + 'no anomalies' follow-up", () => {
+    const r = synthesizePostmortem(input());
+    assert.match(r.synopsis, /No anomalies recorded/);
+    assert.equal(r.sections.timeline.length, 0);
+    assert.equal(r.sections.followUps.length, 1);
+    assert.match(r.sections.followUps[0], /OMCP_ANOMALY_HISTORY_REMOTE_WRITE/);
+});
+test("synthesizePostmortem: timeline is sorted by ts ascending", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [
+            anomaly("2026-06-06T00:30:00Z", 0.5),
+            anomaly("2026-06-06T00:10:00Z", 0.4),
+            anomaly("2026-06-06T00:50:00Z", 0.9),
+        ],
+    }));
+    assert.deepEqual(r.sections.timeline.map((t) => t.ts), ["2026-06-06T00:10:00Z", "2026-06-06T00:30:00Z", "2026-06-06T00:50:00Z"]);
+});
+test("synthesizePostmortem: contributing signals aggregated by signal label + ranked by mean score desc", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [
+            anomaly("2026-06-06T00:10Z", 0.5, "mad", "warn", "request_latency"),
+            anomaly("2026-06-06T00:20Z", 0.4, "mad", "warn", "request_latency"),
+            anomaly("2026-06-06T00:30Z", 0.95, "seasonality", "critical", "error_rate"),
+        ],
+    }));
+    const sigs = r.sections.contributingSignals;
+    assert.equal(sigs.length, 2);
+    // error_rate (0.95 mean) ranks above request_latency (0.45 mean)
+    assert.equal(sigs[0].signal, "error_rate");
+    assert.equal(sigs[0].count, 1);
+    assert.equal(sigs[0].meanScore, 0.95);
+    assert.equal(sigs[1].signal, "request_latency");
+    assert.equal(sigs[1].count, 2);
+    assert.equal(sigs[1].meanScore, 0.45);
+});
+test("synthesizePostmortem: missing signal label falls back to method", () => {
+    const r = synthesizePostmortem(input({ anomalies: [anomaly("2026-06-06T00:10Z", 0.6, "correlator")] }));
+    assert.equal(r.sections.contributingSignals[0].signal, "correlator");
+});
+test("synthesizePostmortem: critical peak triggers a follow-up mentioning the threshold", () => {
+    const r = synthesizePostmortem(input({ anomalies: [anomaly("2026-06-06T00:30Z", 0.95)] }));
+    assert.ok(r.sections.followUps.some((f) => /Peak anomaly score 0\.95/.test(f)));
+});
+test("synthesizePostmortem: errors-in-traces triggers errorsOnly drill-in suggestion", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.6)],
+        traces: [
+            { traceId: "aaa", rootName: "GET /pay", rootService: "payment", durationMs: 800, hasError: true },
+        ],
+    }));
+    assert.ok(r.sections.followUps.some((f) => /errorsOnly=true/.test(f)));
+});
+test("synthesizePostmortem: large blast radius triggers stale-topology hint", () => {
+    const nodes = Array.from({ length: 7 }, (_, i) => ({ id: `n${i}`, kind: "pod", name: `n${i}`, root: i === 0 }));
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.6)],
+        blastRadius: { nodes, edges: [{ from: "n0", to: "n1", relation: "CALLS" }] },
+    }));
+    assert.ok(r.sections.followUps.some((f) => /7 nodes/.test(f) && /stale topology/i.test(f)));
+});
+test("synthesizePostmortem: clean window returns a 'stable, consider closing' follow-up", () => {
+    // The "all signals stable" branch fires only when:
+    //   anomalies present (not zero)
+    //   peak < 0.9
+    //   no error traces
+    //   blast radius <= 5
+    //   no log highlights
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.3)],
+        blastRadius: { nodes: [{ id: "n0", kind: "pod", name: "n0", root: true }], edges: [] },
+    }));
+    assert.ok(r.sections.followUps.some((f) => /stable for this window/.test(f)));
+});
+test("synthesizePostmortem: markdown contains every section header in order", () => {
+    const r = synthesizePostmortem(input({
+        anomalies: [anomaly("2026-06-06T00:10Z", 0.7)],
+        blastRadius: {
+            nodes: [{ id: "p", kind: "deployment", name: "payment", root: true }],
+            edges: [{ from: "p", to: "rds", relation: "READS_FROM" }],
+        },
+        traces: [{ traceId: "t", rootName: "GET /pay", rootService: "payment", durationMs: 200, hasError: false }],
+        logHighlights: ["payment-service: 12 5xx in window"],
+    }));
+    for (const heading of [
+        "# Post-mortem — payment",
+        "## Synopsis",
+        "## Anomaly timeline",
+        "## Blast radius at peak",
+        "## Contributing signals (ranked)",
+        "## Related traces",
+        "## Log highlights",
+        "## Suggested follow-ups",
+    ]) {
+        assert.ok(r.markdown.includes(heading), `markdown missing section: ${heading}`);
+    }
+    // The order check — anomaly timeline should appear before blast radius
+    assert.ok(r.markdown.indexOf("## Anomaly timeline") < r.markdown.indexOf("## Blast radius at peak"));
+});
+test("synthesizePostmortem: timeline > 20 rows is truncated with an ellipsis row", () => {
+    const anomalies = Array.from({ length: 25 }, (_, i) => anomaly(`2026-06-06T00:${String(i).padStart(2, "0")}:00Z`, 0.5 + i * 0.01));
+    const r = synthesizePostmortem(input({ anomalies }));
+    // The structured section has all 25
+    assert.equal(r.sections.timeline.length, 25);
+    // The markdown table is capped at 20 data rows + an ellipsis row
+    // — count rows specifically inside the Anomaly timeline section
+    // (other sections also use | ` ... | tables and would inflate a
+    // global grep).
+    const md = r.markdown;
+    const timelineStart = md.indexOf("## Anomaly timeline");
+    const blastStart = md.indexOf("## Blast radius at peak");
+    const timelineSection = md.slice(timelineStart, blastStart);
+    const tableRows = timelineSection.split("\n").filter((l) => l.startsWith("| `")).length;
+    assert.equal(tableRows, 20);
+    assert.match(timelineSection, /_5 more rows_/);
+});
+test("synthesizePostmortem: report carries the input window + iso bounds back into the structured shape", () => {
+    const r = synthesizePostmortem(input({ window: "6h" }));
+    assert.equal(r.service, "payment");
+    assert.equal(r.window, "6h");
+    assert.equal(r.fromIso, "2026-06-06T00:00:00.000Z");
+    assert.equal(r.toIso, "2026-06-06T01:00:00.000Z");
+});

package/dist/products/loader.d.ts

@@ -12,8 +12,13 @@
  *     (YAML or JSON). Missing/empty file → empty catalog.
  *   - Strict validation: unknown action / unknown resource /
  *     unexpected keys reject loudly.
- *   - Hot-reload on next /api/products call (slice 2 wires the
- *     reload trigger; for now the file is read once at boot).
+ *   - Mtime-poll hot-reload: callers (e.g. each /api/products
+ *     handler) `await store.maybeReload()` before reading. If the
+ *     file mtime advanced since the last load, the store re-parses
+ *     and atomically swaps the in-memory file; parse errors keep
+ *     the previous good state and log loudly. One `stat()` call per
+ *     reload-aware request — too cheap to matter vs. the network
+ *     round-trip, no FSWatcher platform fragility (WSL / NFS).
  */
 export interface Product {
     /** Stable identifier — used in URLs, audit entries, /api/products/{id}. */
@@ -47,7 +52,30 @@ export declare function parseProductsText(text: string, origin: string): Product
 /** In-memory store with tenant- and status-aware queries. */
 export declare class ProductsStore {
     private file;
-    constructor(file?: ProductsFile);
+    /** Optional source file path. When set, `maybeReload()` polls its
+     *  mtime and re-parses on change. Mutations via upsert/delete update
+     *  `lastMtimeMs` after the caller persists, so the store does not
+     *  reload its own writes. */
+    private path?;
+    private lastMtimeMs;
+    constructor(file?: ProductsFile, opts?: {
+        path?: string;
+        initialMtimeMs?: number;
+    });
+    /** Re-read the source file if its mtime has advanced since the last
+     *  load. No-op when no path was supplied at construction. Parse or
+     *  IO errors are logged and the previous good state is kept — the
+     *  invariant is "the store always reflects a valid catalogue", so a
+     *  broken edit on disk never takes the running server down. */
+    maybeReload(): Promise<{
+        reloaded: boolean;
+    }>;
+    /** Re-stat the source file and pin the mtime cursor to its current
+     *  value. Call this after a successful write so the store does not
+     *  treat its own change as an external reload trigger. Best-effort:
+     *  if the stat fails, the next maybeReload() will simply reload the
+     *  file once and find it identical. */
+    pinMtimeAfterWrite(): Promise<void>;
     /** Return the product list. When `tenant` is set, filters to that
      *  tenant (entries without a tenant field treated as "default").
      *  When `includeStaging` is false (default), staging products are

package/dist/products/loader.js

@@ -12,10 +12,15 @@
  *     (YAML or JSON). Missing/empty file → empty catalog.
  *   - Strict validation: unknown action / unknown resource /
  *     unexpected keys reject loudly.
- *   - Hot-reload on next /api/products call (slice 2 wires the
- *     reload trigger; for now the file is read once at boot).
+ *   - Mtime-poll hot-reload: callers (e.g. each /api/products
+ *     handler) `await store.maybeReload()` before reading. If the
+ *     file mtime advanced since the last load, the store re-parses
+ *     and atomically swaps the in-memory file; parse errors keep
+ *     the previous good state and log loudly. One `stat()` call per
+ *     reload-aware request — too cheap to matter vs. the network
+ *     round-trip, no FSWatcher platform fragility (WSL / NFS).
  */
-import { readFile, writeFile, rename } from "node:fs/promises";
+import { readFile, writeFile, rename, stat } from "node:fs/promises";
 import yaml from "js-yaml";
 const EMPTY = { products: [] };
 const VALID_STATUS = new Set(["published", "staging"]);
@@ -134,8 +139,76 @@ export function parseProductsText(text, origin) {
 /** In-memory store with tenant- and status-aware queries. */
 export class ProductsStore {
     file;
-    constructor(file = EMPTY) {
+    /** Optional source file path. When set, `maybeReload()` polls its
+     *  mtime and re-parses on change. Mutations via upsert/delete update
+     *  `lastMtimeMs` after the caller persists, so the store does not
+     *  reload its own writes. */
+    path;
+    lastMtimeMs = 0;
+    constructor(file = EMPTY, opts = {}) {
         this.file = file;
+        this.path = opts.path;
+        this.lastMtimeMs = opts.initialMtimeMs ?? 0;
+    }
+    /** Re-read the source file if its mtime has advanced since the last
+     *  load. No-op when no path was supplied at construction. Parse or
+     *  IO errors are logged and the previous good state is kept — the
+     *  invariant is "the store always reflects a valid catalogue", so a
+     *  broken edit on disk never takes the running server down. */
+    async maybeReload() {
+        if (!this.path)
+            return { reloaded: false };
+        let mtimeMs;
+        try {
+            const s = await stat(this.path);
+            mtimeMs = s.mtimeMs;
+        }
+        catch (e) {
+            const code = e.code;
+            // File gone (ENOENT) — keep last good state. Re-creating the
+            // file will land in this branch's else on the next call when
+            // stat succeeds again with a fresh mtime.
+            if (code !== "ENOENT") {
+                console.warn(`[products] hot-reload stat(${this.path}) failed: ${e.message} — keeping previous catalogue`);
+            }
+            return { reloaded: false };
+        }
+        if (mtimeMs <= this.lastMtimeMs)
+            return { reloaded: false };
+        let next;
+        try {
+            next = await readProductsFile(this.path);
+        }
+        catch (e) {
+            // readProductsFile downgrades IO errors to EMPTY but lets
+            // parse errors (ProductsLoadError) propagate — so a broken
+            // YAML edit lands here, and we explicitly do NOT swap state.
+            console.warn(`[products] hot-reload of ${this.path} failed: ${e.message} — keeping previous catalogue`);
+            // Bump the mtime cursor anyway so we don't re-log the same
+            // failure on every subsequent request until the operator fixes
+            // the file (next save advances mtime past this value).
+            this.lastMtimeMs = mtimeMs;
+            return { reloaded: false };
+        }
+        this.file = next;
+        this.lastMtimeMs = mtimeMs;
+        return { reloaded: true };
+    }
+    /** Re-stat the source file and pin the mtime cursor to its current
+     *  value. Call this after a successful write so the store does not
+     *  treat its own change as an external reload trigger. Best-effort:
+     *  if the stat fails, the next maybeReload() will simply reload the
+     *  file once and find it identical. */
+    async pinMtimeAfterWrite() {
+        if (!this.path)
+            return;
+        try {
+            const s = await stat(this.path);
+            this.lastMtimeMs = s.mtimeMs;
+        }
+        catch {
+            // Silent — see method JSDoc.
+        }
     }
     /** Return the product list. When `tenant` is set, filters to that
      *  tenant (entries without a tenant field treated as "default").

package/dist/products/loader.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { parseProductsText, ProductsStore, ProductsLoadError } from "./loader.js";
+import { parseProductsText, ProductsStore, ProductsLoadError, readProductsFile } from "./loader.js";
 test("parseProductsText — empty/minimal products array", () => {
     const f = parseProductsText("products: []", "test");
     assert.deepEqual(f.products, []);
@@ -166,3 +166,92 @@ test("ProductsLoadError is the throw class", () => {
     }
     assert.fail("expected throw");
 });
+test("ProductsStore.maybeReload — picks up out-of-band edits on next call", async () => {
+    const { mkdtemp, rm, writeFile, utimes } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-products-reload-"));
+    try {
+        const file = join(dir, "products.yaml");
+        await writeFile(file, "products:\n  - id: a\n    name: A\n", "utf8");
+        const initial = await readProductsFile(file);
+        const store = new ProductsStore(initial, { path: file });
+        await store.pinMtimeAfterWrite();
+        assert.equal(store.list().length, 1);
+        assert.equal(store.list()[0].id, "a");
+        // Simulate an out-of-band edit. Bump mtime explicitly because
+        // some filesystems (WSL → 9P) round mtime to the second, so a
+        // back-to-back write can land in the same second and look
+        // unchanged to stat().
+        await writeFile(file, "products:\n  - id: a\n    name: A\n  - id: b\n    name: B\n", "utf8");
+        const future = new Date(Date.now() + 5_000);
+        await utimes(file, future, future);
+        const { reloaded } = await store.maybeReload();
+        assert.equal(reloaded, true);
+        assert.equal(store.list().length, 2);
+        // A second call with no further edit is a no-op.
+        const r2 = await store.maybeReload();
+        assert.equal(r2.reloaded, false);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("ProductsStore.maybeReload — broken YAML on disk keeps previous good state", async () => {
+    const { mkdtemp, rm, writeFile, utimes } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-products-broken-"));
+    try {
+        const file = join(dir, "products.yaml");
+        await writeFile(file, "products:\n  - id: a\n    name: A\n", "utf8");
+        const store = new ProductsStore(await readProductsFile(file), { path: file });
+        await store.pinMtimeAfterWrite();
+        // Corrupt the file with an unknown top-level key — fails the
+        // strict typo guard inside parseProductsText.
+        await writeFile(file, "products:\n  - id: a\n    name: A\n    junk: true\n", "utf8");
+        const future = new Date(Date.now() + 5_000);
+        await utimes(file, future, future);
+        const { reloaded } = await store.maybeReload();
+        // We did NOT swap state — caller sees the previous good catalogue.
+        assert.equal(reloaded, false);
+        assert.equal(store.list().length, 1);
+        assert.equal(store.list()[0].name, "A");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("ProductsStore.maybeReload — no path = no-op", async () => {
+    const store = new ProductsStore({ products: [{ id: "a", name: "A" }] });
+    const r = await store.maybeReload();
+    assert.equal(r.reloaded, false);
+    assert.equal(store.list().length, 1);
+});
+test("ProductsStore.pinMtimeAfterWrite — own writes do not trigger a redundant reload", async () => {
+    const { mkdtemp, rm, writeFile, utimes } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const { writeProductsFile } = await import("./loader.js");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-products-pin-"));
+    try {
+        const file = join(dir, "products.yaml");
+        await writeFile(file, "products:\n  - id: a\n    name: A\n", "utf8");
+        const store = new ProductsStore(await readProductsFile(file), { path: file });
+        await store.pinMtimeAfterWrite();
+        // Simulate the server-side mutate-then-persist path.
+        store.upsert({ id: "b", name: "B" });
+        // Move mtime forward so writeProductsFile genuinely advances it
+        // past our cursor (1-second-resolution FS guard).
+        const future = new Date(Date.now() + 5_000);
+        await writeProductsFile(file, store.snapshot());
+        await utimes(file, future, future);
+        await store.pinMtimeAfterWrite();
+        const { reloaded } = await store.maybeReload();
+        assert.equal(reloaded, false, "own write must not re-trigger maybeReload");
+        assert.equal(store.list().length, 2);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});

package/dist/quota/charge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure helper that turns a TokenBudget decision into either the
+ * original tool result (when allowed / uncapped) or a structured
+ * error payload distinguishing the two budget-denial cases:
+ *
+ *   - OMCP_TOKEN_BUDGET_EXCEEDED         — cumulative trailing-24h
+ *     usage would push the principal past its cap. Waiting helps;
+ *     `retryAfterSeconds` says how long until enough buckets drop
+ *     off to fit the request.
+ *
+ *   - OMCP_TOKEN_REQUEST_EXCEEDS_BUDGET  — this single response is
+ *     larger than the entire daily cap. Waiting does NOT help — the
+ *     agent must narrow the query or the operator must raise the
+ *     cap. `retryAfterSeconds` is 0 here so retry-with-backoff loops
+ *     terminate instead of churning.
+ *
+ * Extracted from the createMcpServer closure in index.ts purely for
+ * unit-testability. Behaviour is identical to the previous inline
+ * version.
+ */
+import type { CheckResult } from "./token-budget.js";
+export interface ToolResult {
+    content: Array<{
+        text: string;
+        [k: string]: unknown;
+    }>;
+}
+export declare function applyBudgetDecision<T extends ToolResult>(result: T, decision: CheckResult, tokens: number, toolName: string): T;

package/dist/quota/charge.js

@@ -0,0 +1,30 @@
+export function applyBudgetDecision(result, decision, tokens, toolName) {
+    if (decision.allowed || decision.limit === 0)
+        return result;
+    // A request larger than the entire daily cap can never succeed by
+    // waiting — distinct error code so the agent doesn't spin.
+    const requestExceedsCap = tokens > decision.limit;
+    const errBody = {
+        error: requestExceedsCap ? "OMCP_TOKEN_REQUEST_EXCEEDS_BUDGET" : "OMCP_TOKEN_BUDGET_EXCEEDED",
+        tool: toolName,
+        used: decision.used,
+        limit: decision.limit,
+        requested: tokens,
+        retryAfterSeconds: requestExceedsCap ? 0 : decision.retryAfterSeconds,
+        freedAtRetry: decision.freedAtRetry,
+        message: requestExceedsCap
+            ? `This single response (~${tokens} tokens) is larger than the entire daily budget (${decision.limit}). Retrying won't help — narrow the query (smaller window / lower limit / more selective filter) or raise OMCP_TOOL_DAILY_TOKENS.`
+            : `Daily token budget exceeded (${decision.used}/${decision.limit} tokens used in the trailing 24h; this call would have added ~${tokens}). Try again in ~${Math.ceil(decision.retryAfterSeconds / 3600)}h or raise OMCP_TOOL_DAILY_TOKENS.`,
+    };
+    // Preserve any additional content entries (e.g. a future tool
+    // returning [text, image]) — only the text payload of the first
+    // entry is replaced with the error JSON; everything after passes
+    // through unchanged.
+    return {
+        ...result,
+        content: [
+            { ...result.content[0], text: JSON.stringify(errBody) },
+            ...result.content.slice(1),
+        ],
+    };
+}

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

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

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

@@ -25,19 +25,40 @@
  * - 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)
+ *   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 {
-    /** Cap per identity per window. Defaults to 60. */
+    /** 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;
@@ -52,10 +73,14 @@ export interface CheckResult {
     retryAfterSeconds: number;
 }
 export declare class IdentityRateLimiter {
-    private readonly limit;
+    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;