@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/products/loader.js

@@ -0,0 +1,289 @@
+/**
+ * MCP Products — curated, agent-facing collections of tools.
+ *
+ * A Product is a named bundle that ships with branding metadata
+ * (icon, description, version) plus a list of allowed MCP tools.
+ * The agent calling /mcp can be told which Product it belongs to
+ * (via a future header / arg, slice 2+), and the server can filter
+ * tools/list and tools/call responses accordingly.
+ *
+ * Today's surface (slice 1):
+ *   - In-memory ProductsStore loaded from OMCP_PRODUCTS_FILE
+ *     (YAML or JSON). Missing/empty file → empty catalog.
+ *   - Strict validation: unknown action / unknown resource /
+ *     unexpected keys reject loudly.
+ *   - 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, stat } from "node:fs/promises";
+import yaml from "js-yaml";
+const EMPTY = { products: [] };
+const VALID_STATUS = new Set(["published", "staging"]);
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export class ProductsLoadError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "ProductsLoadError";
+    }
+}
+export async function readProductsFile(path) {
+    if (!path)
+        return EMPTY;
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return EMPTY;
+        console.warn(`[products] could not read ${path}: ${e.message} — starting with empty catalog`);
+        return EMPTY;
+    }
+    return parseProductsText(text, path);
+}
+export function parseProductsText(text, origin) {
+    let parsed;
+    try {
+        parsed = yaml.load(text);
+    }
+    catch (e) {
+        throw new ProductsLoadError(`${origin}: not valid YAML/JSON: ${e.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ProductsLoadError(`${origin}: root must be an object with a 'products' array`);
+    }
+    const root = parsed;
+    const rawProducts = root.products;
+    if (!Array.isArray(rawProducts)) {
+        throw new ProductsLoadError(`${origin}: 'products' must be an array`);
+    }
+    const out = [];
+    const seenIds = new Set();
+    for (let i = 0; i < rawProducts.length; i++) {
+        const e = rawProducts[i];
+        if (!e || typeof e !== "object" || Array.isArray(e)) {
+            throw new ProductsLoadError(`${origin}: products[${i}] must be an object`);
+        }
+        const r = e;
+        if (typeof r.id !== "string" || !ID_RE.test(r.id)) {
+            throw new ProductsLoadError(`${origin}: products[${i}].id must be a string matching ${ID_RE}`);
+        }
+        if (seenIds.has(r.id)) {
+            throw new ProductsLoadError(`${origin}: duplicate product id '${r.id}'`);
+        }
+        seenIds.add(r.id);
+        if (typeof r.name !== "string" || !r.name) {
+            throw new ProductsLoadError(`${origin}: products[${i}].name must be a non-empty string`);
+        }
+        const p = { id: r.id, name: r.name };
+        if (r.description !== undefined) {
+            if (typeof r.description !== "string")
+                throw new ProductsLoadError(`${origin}: products[${i}].description must be a string`);
+            p.description = r.description;
+        }
+        if (r.tools !== undefined) {
+            if (!Array.isArray(r.tools) || !r.tools.every((t) => typeof t === "string")) {
+                throw new ProductsLoadError(`${origin}: products[${i}].tools must be an array of strings`);
+            }
+            p.tools = r.tools;
+        }
+        if (r.version !== undefined) {
+            if (typeof r.version !== "string")
+                throw new ProductsLoadError(`${origin}: products[${i}].version must be a string`);
+            p.version = r.version;
+        }
+        if (r.status !== undefined) {
+            if (typeof r.status !== "string" || !VALID_STATUS.has(r.status)) {
+                throw new ProductsLoadError(`${origin}: products[${i}].status must be one of ${[...VALID_STATUS].join(", ")}`);
+            }
+            p.status = r.status;
+        }
+        if (r.tenant !== undefined) {
+            if (typeof r.tenant !== "string")
+                throw new ProductsLoadError(`${origin}: products[${i}].tenant must be a string`);
+            p.tenant = r.tenant;
+        }
+        if (r.branding !== undefined) {
+            if (!r.branding || typeof r.branding !== "object" || Array.isArray(r.branding)) {
+                throw new ProductsLoadError(`${origin}: products[${i}].branding must be an object`);
+            }
+            const b = r.branding;
+            p.branding = {};
+            if (b.iconUrl !== undefined) {
+                if (typeof b.iconUrl !== "string")
+                    throw new ProductsLoadError(`${origin}: products[${i}].branding.iconUrl must be a string`);
+                p.branding.iconUrl = b.iconUrl;
+            }
+            if (b.color !== undefined) {
+                if (typeof b.color !== "string")
+                    throw new ProductsLoadError(`${origin}: products[${i}].branding.color must be a string`);
+                p.branding.color = b.color;
+            }
+        }
+        // Reject unexpected top-level keys — operator typo guard
+        for (const k of Object.keys(r)) {
+            if (!["id", "name", "description", "tools", "version", "branding", "status", "tenant"].includes(k)) {
+                throw new ProductsLoadError(`${origin}: products[${i}] has unexpected key '${k}'`);
+            }
+        }
+        out.push(p);
+    }
+    return { products: out };
+}
+/** In-memory store with tenant- and status-aware queries. */
+export class ProductsStore {
+    file;
+    /** 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").
+     *  When `includeStaging` is false (default), staging products are
+     *  hidden from the result — admins should pass true. */
+    list(opts = {}) {
+        return this.file.products.filter((p) => {
+            if (opts.tenant) {
+                const pt = p.tenant || "default";
+                if (pt !== opts.tenant)
+                    return false;
+            }
+            if (!opts.includeStaging && p.status === "staging")
+                return false;
+            return true;
+        });
+    }
+    /** Lookup by id. Cross-tenant gets return undefined when `tenant` set. */
+    get(id, tenant) {
+        const p = this.file.products.find((x) => x.id === id);
+        if (!p)
+            return undefined;
+        if (tenant && (p.tenant || "default") !== tenant)
+            return undefined;
+        return p;
+    }
+    count(tenant) {
+        return this.list({ tenant, includeStaging: true }).length;
+    }
+    replace(file) {
+        this.file = file;
+    }
+    /** Upsert (replace if id exists, else append). Returns the new
+     *  ProductsFile so the caller can persist it. */
+    upsert(product) {
+        const i = this.file.products.findIndex((p) => p.id === product.id);
+        const next = this.file.products.slice();
+        if (i >= 0)
+            next[i] = product;
+        else
+            next.push(product);
+        this.file = { products: next };
+        return this.file;
+    }
+    /** Remove by id. Returns true when the product existed, false
+     *  otherwise. Caller persists the resulting file. */
+    delete(id) {
+        const i = this.file.products.findIndex((p) => p.id === id);
+        if (i < 0)
+            return { removed: false, file: this.file };
+        const next = this.file.products.slice();
+        next.splice(i, 1);
+        this.file = { products: next };
+        return { removed: true, file: this.file };
+    }
+    /** Snapshot of the current file (for tests / persistence). */
+    snapshot() {
+        return { products: this.file.products.slice() };
+    }
+}
+/** Validate a single product entry by routing it through the same
+ *  parser as the file format. Throws ProductsLoadError on any
+ *  shape problem. Used by PUT /api/products/:id so a typo / wrong
+ *  type / unknown key gets the same loud rejection a malformed
+ *  file would. */
+export function validateProduct(input, origin = "input") {
+    const wrapped = parseProductsText(yaml.dump({ products: [input] }), origin);
+    return wrapped.products[0];
+}
+/** Atomic write of the products file. Same tmp+rename pattern as
+ *  the audit-chain + token-budget snapshot, so a crash mid-write
+ *  leaves the previous file intact. */
+export async function writeProductsFile(path, file) {
+    const text = yaml.dump(file, { sortKeys: false, lineWidth: 100 });
+    const tmp = path + ".tmp";
+    await writeFile(tmp, text, "utf8");
+    await rename(tmp, path);
+}

package/dist/products/loader.test.d.ts

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

package/dist/products/loader.test.js

@@ -0,0 +1,257 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseProductsText, ProductsStore, ProductsLoadError, readProductsFile } 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");
+});
+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 {};