mcp-coordinator 0.1.0

package/dist/src/quota/quota-cache.js

@@ -0,0 +1,177 @@
+// Coordinator-side quota cache with hybrid refresh:
+//
+// - "lazy":       a consumer requesting /api/quota while the cache is stale
+//                 triggers a refresh on that call (single-flight-deduped so
+//                 simultaneous requesters share the same in-flight fetch).
+// - "background": when at least one agent is registered as active, a timer
+//                 pre-refreshes the cache every TTL seconds so consumers
+//                 always see fresh data without paying the Anthropic latency.
+//
+// When the credential reader throws NotImplementedError (non-macOS platforms
+// pre-impl) or the API is down, getCachedQuota() returns null and the HTTP
+// layer surfaces that as 503 — the consumer treats "unknown" as "continue",
+// per the project decision to fail-open on quota checks.
+import { createCredentialReader } from "./credential-reader.js";
+import { fetchQuotaFromAnthropic, QuotaUnavailableError } from "./quota.js";
+// 2 min — the quota endpoint moves in percentage points, not token counts, so
+// sub-minute freshness is overkill. Lower values caused Anthropic to 429 the
+// endpoint itself when several agents were online at once.
+export const DEFAULT_TTL_MS = 120_000;
+// Anthropic rate-limits the /api/oauth/usage endpoint itself. When we get 429,
+// we stop hammering and wait this long (or the server-provided Retry-After)
+// before attempting again. 5 min is a comfortable default for a usage endpoint
+// that only moves in %, not token counts — we don't need sub-minute freshness.
+const DEFAULT_429_COOLDOWN_MS = 5 * 60_000;
+const MIN_429_COOLDOWN_MS = 60_000;
+/**
+ * Returns true if the cached info is still within TTL. Pure function so
+ * callers can decide cache freshness without touching the cache instance.
+ */
+export function isFresh(info, ttlMs, now = Date.now()) {
+    if (!info)
+        return false;
+    return now - info.fetchedAt < ttlMs;
+}
+export class QuotaCache {
+    info = null;
+    lastError = null;
+    refreshInFlight = null;
+    activeAgents = 0;
+    backgroundTimer = null;
+    cooldownUntil = 0;
+    ttlMs;
+    reader;
+    logger;
+    fetcher;
+    onRefresh;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.reader = opts.reader ?? createCredentialReader();
+        this.logger = opts.logger;
+        this.fetcher = opts.fetcher ?? fetchQuotaFromAnthropic;
+        this.onRefresh = opts.onRefresh;
+    }
+    /**
+     * Returns the cached QuotaInfo if fresh, otherwise triggers a refresh and
+     * returns the new value. Returns null when fetching fails (fail-open path).
+     * Concurrent calls share a single in-flight fetch.
+     */
+    async get() {
+        if (isFresh(this.info, this.ttlMs))
+            return this.info;
+        return this.refresh();
+    }
+    /**
+     * Returns the cached value synchronously, even if stale or missing. Used
+     * by the HTTP handler to decide 200 vs 503 without awaiting a refresh.
+     */
+    snapshot() {
+        return {
+            info: this.info,
+            unavailable: this.info === null && this.lastError !== null,
+            lastError: this.lastError,
+            activeAgents: this.activeAgents,
+            ttlMs: this.ttlMs,
+            cooldownUntil: this.cooldownUntil > Date.now() ? this.cooldownUntil : null,
+        };
+    }
+    /**
+     * Force a refresh now. Returns the new value or null on failure. Subsequent
+     * concurrent callers share the same in-flight promise so we never issue
+     * parallel Anthropic calls for the same refresh window. During a 429
+     * cool-down we short-circuit to the cached value (possibly null) without
+     * hitting the API — keeps us from hammering an endpoint that's already
+     * pushing back.
+     */
+    async refresh() {
+        if (Date.now() < this.cooldownUntil) {
+            this.logger?.debug({ cooldown_ms_remaining: this.cooldownUntil - Date.now() }, "quota refresh skipped — 429 cool-down active");
+            return this.info;
+        }
+        if (this.refreshInFlight)
+            return this.refreshInFlight;
+        this.refreshInFlight = this.doRefresh()
+            .finally(() => { this.refreshInFlight = null; });
+        return this.refreshInFlight;
+    }
+    async doRefresh() {
+        try {
+            const info = await this.fetcher(this.reader);
+            this.info = info;
+            this.lastError = null;
+            this.cooldownUntil = 0;
+            this.logger?.debug({ five_hour: info.fiveHour.utilization, seven_day: info.sevenDay.utilization }, "quota refreshed");
+            this.onRefresh?.(info);
+            return info;
+        }
+        catch (err) {
+            const msg = err instanceof QuotaUnavailableError ? err.message : err.message;
+            this.lastError = msg;
+            // 429 = Anthropic itself is rate-limiting the usage endpoint. Back off
+            // to avoid making it worse — respect Retry-After when provided,
+            // otherwise apply a 5-minute cool-down. MIN_429_COOLDOWN_MS prevents
+            // Retry-After spoofing / zero values from letting us spam.
+            if (err instanceof QuotaUnavailableError && err.httpStatus === 429) {
+                const suggestedMs = err.retryAfterSeconds !== undefined
+                    ? err.retryAfterSeconds * 1000
+                    : DEFAULT_429_COOLDOWN_MS;
+                const cooldownMs = Math.max(suggestedMs, MIN_429_COOLDOWN_MS);
+                this.cooldownUntil = Date.now() + cooldownMs;
+                this.logger?.warn({ cooldown_ms: cooldownMs }, "quota 429 — backing off");
+            }
+            else if (this.info === null) {
+                // First-ever fetch failed for some other reason — warn once.
+                this.logger?.warn({ err: msg }, "quota fetch failed — consumers will see 503");
+            }
+            else {
+                this.logger?.debug({ err: msg }, "quota refresh failed — serving stale cache");
+            }
+            return null;
+        }
+    }
+    /**
+     * Call when an agent connects so the background tick keeps the cache warm
+     * during an active run. Multiple calls without a matching decrement are
+     * idempotent above 0 — the tick runs whenever activeAgents > 0.
+     */
+    onAgentActive() {
+        this.activeAgents++;
+        if (this.backgroundTimer === null)
+            this.startBackgroundTick();
+    }
+    /**
+     * Call when an agent disconnects so the background tick stops when the
+     * coordinator goes idle — no point re-fetching if nobody will read it.
+     */
+    onAgentInactive() {
+        if (this.activeAgents > 0)
+            this.activeAgents--;
+        if (this.activeAgents === 0)
+            this.stopBackgroundTick();
+    }
+    /**
+     * Stop the timer so process teardown doesn't leak. Safe to call multiple
+     * times. The next onAgentActive() will restart it.
+     */
+    stopBackgroundTick() {
+        if (this.backgroundTimer) {
+            clearInterval(this.backgroundTimer);
+            this.backgroundTimer = null;
+        }
+    }
+    startBackgroundTick() {
+        // Kick off one refresh immediately so the first consumer after a cold
+        // start doesn't eat the network latency.
+        void this.refresh();
+        this.backgroundTimer = setInterval(() => {
+            // Skip the tick if we have no agents — onAgentInactive will stop us,
+            // but belt-and-suspenders in case counting goes wrong.
+            if (this.activeAgents === 0)
+                return;
+            void this.refresh();
+        }, this.ttlMs);
+        // Don't keep the event loop alive just for the tick.
+        if (typeof this.backgroundTimer.unref === "function")
+            this.backgroundTimer.unref();
+    }
+}

package/dist/src/quota/quota.d.ts

@@ -0,0 +1,47 @@
+import type { CredentialReader } from "./credential-reader.js";
+export interface QuotaBucket {
+    /** 0.0 – 100.0 */
+    utilization: number;
+    /** ISO 8601 timestamp when this bucket resets */
+    resetsAt: string;
+    /** Positive = reset is in the future; negative = already reset */
+    minutesUntilReset: number;
+}
+export interface QuotaInfo {
+    fiveHour: QuotaBucket;
+    sevenDay: QuotaBucket;
+    /** The 7-day bucket limited to Sonnet usage. Anthropic omits it when absent. */
+    sevenDaySonnet: QuotaBucket | null;
+    /** Wall-clock time the coordinator fetched this, for cache freshness checks. */
+    fetchedAt: number;
+}
+export declare class QuotaUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    /** HTTP status from the upstream API when available — lets the cache
+     * differentiate "retry now" vs "back off" (e.g. 429 → cool-down). */
+    readonly httpStatus?: number | undefined;
+    /** Retry-After hint (seconds) from the upstream when provided. */
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, cause?: unknown | undefined, 
+    /** HTTP status from the upstream API when available — lets the cache
+     * differentiate "retry now" vs "back off" (e.g. 429 → cool-down). */
+    httpStatus?: number | undefined, 
+    /** Retry-After hint (seconds) from the upstream when provided. */
+    retryAfterSeconds?: number | undefined);
+}
+/**
+ * Fetch the current quota info from Anthropic. Throws QuotaUnavailableError
+ * if the credential is missing (non-macOS platforms stub this path), the API
+ * is unreachable, or the response shape is unexpected.
+ */
+export declare function fetchQuotaFromAnthropic(reader: CredentialReader): Promise<QuotaInfo>;
+/**
+ * Parse the JSON payload returned by /api/oauth/usage. Exported so tests can
+ * exercise shape handling without hitting the network.
+ */
+export declare function parseUsageResponse(payload: unknown): QuotaInfo;
+/**
+ * Positive = date is in the future. Returns 0 on an unparseable date so
+ * callers can still make a "quota already reset" decision without crashing.
+ */
+export declare function minutesUntil(iso8601: string): number;

package/dist/src/quota/quota.js

@@ -0,0 +1,117 @@
+// Anthropic OAuth quota endpoint — port from reserve/agents/src/quota.rs.
+//
+// Pipeline: credential reader → OAuth access token → HTTP GET /api/oauth/usage
+// → QuotaInfo with 3 buckets (5h / 7d / 7d-sonnet).
+//
+// This module is the wire protocol. The cache + refresh strategy live in
+// quota-cache.ts so this file stays side-effect-free and easy to test.
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const BETA_HEADER = "oauth-2025-04-20";
+export class QuotaUnavailableError extends Error {
+    cause;
+    httpStatus;
+    retryAfterSeconds;
+    constructor(message, cause, 
+    /** HTTP status from the upstream API when available — lets the cache
+     * differentiate "retry now" vs "back off" (e.g. 429 → cool-down). */
+    httpStatus, 
+    /** Retry-After hint (seconds) from the upstream when provided. */
+    retryAfterSeconds) {
+        super(message);
+        this.cause = cause;
+        this.httpStatus = httpStatus;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "QuotaUnavailableError";
+    }
+}
+/**
+ * Fetch the current quota info from Anthropic. Throws QuotaUnavailableError
+ * if the credential is missing (non-macOS platforms stub this path), the API
+ * is unreachable, or the response shape is unexpected.
+ */
+export async function fetchQuotaFromAnthropic(reader) {
+    let token;
+    try {
+        token = await reader.readClaudeOAuthToken();
+    }
+    catch (err) {
+        throw new QuotaUnavailableError(`cannot read OAuth token: ${err.message}`, err);
+    }
+    let resp;
+    try {
+        resp = await fetch(USAGE_URL, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "anthropic-beta": BETA_HEADER,
+            },
+        });
+    }
+    catch (err) {
+        throw new QuotaUnavailableError(`cannot reach Anthropic usage API: ${err.message}`, err);
+    }
+    if (!resp.ok) {
+        const retryAfterRaw = resp.headers.get("retry-after");
+        const retryAfter = retryAfterRaw ? Number(retryAfterRaw) : undefined;
+        throw new QuotaUnavailableError(`usage API returned HTTP ${resp.status}`, undefined, resp.status, Number.isFinite(retryAfter) ? retryAfter : undefined);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (err) {
+        throw new QuotaUnavailableError(`usage API returned non-JSON body: ${err.message}`, err);
+    }
+    return parseUsageResponse(body);
+}
+/**
+ * Parse the JSON payload returned by /api/oauth/usage. Exported so tests can
+ * exercise shape handling without hitting the network.
+ */
+export function parseUsageResponse(payload) {
+    if (!payload || typeof payload !== "object") {
+        throw new QuotaUnavailableError("usage API body is not an object");
+    }
+    const rec = payload;
+    const fiveHour = parseBucket(rec, "five_hour"); // required
+    const sevenDay = parseBucket(rec, "seven_day"); // required
+    // Anthropic sometimes omits the sonnet-specific bucket (e.g. workspaces
+    // without a seven_day_sonnet cap). Optional — null signals "not tracked".
+    let sevenDaySonnet = null;
+    try {
+        sevenDaySonnet = parseBucket(rec, "seven_day_sonnet");
+    }
+    catch {
+        sevenDaySonnet = null;
+    }
+    return { fiveHour, sevenDay, sevenDaySonnet, fetchedAt: Date.now() };
+}
+function parseBucket(payload, key) {
+    const raw = payload[key];
+    if (!raw || typeof raw !== "object") {
+        throw new QuotaUnavailableError(`usage API: field "${key}" missing or not an object`);
+    }
+    const bucket = raw;
+    const utilization = bucket.utilization;
+    if (typeof utilization !== "number") {
+        throw new QuotaUnavailableError(`usage API: "${key}.utilization" missing or non-numeric`);
+    }
+    const resetsAt = bucket.resets_at;
+    if (typeof resetsAt !== "string") {
+        throw new QuotaUnavailableError(`usage API: "${key}.resets_at" missing or non-string`);
+    }
+    return {
+        utilization,
+        resetsAt,
+        minutesUntilReset: minutesUntil(resetsAt),
+    };
+}
+/**
+ * Positive = date is in the future. Returns 0 on an unparseable date so
+ * callers can still make a "quota already reset" decision without crashing.
+ */
+export function minutesUntil(iso8601) {
+    const t = Date.parse(iso8601);
+    if (Number.isNaN(t))
+        return 0;
+    return Math.round((t - Date.now()) / 60_000);
+}

package/dist/src/serve-http.d.ts

@@ -0,0 +1,5 @@
+export interface ServerOptions {
+    port?: number;
+    dataDir?: string;
+}
+export declare function startServer(opts?: ServerOptions): Promise<void>;