c64bridge 0.5.0

package/dist/rag/init.js

@@ -0,0 +1,139 @@
+/*
+C64 Bridge - Local RAG bootstrap
+GPL-2.0-only
+*/
+import fs from "node:fs/promises";
+import path from "node:path";
+import { LocalMiniHashEmbedding } from "./embeddings.js";
+import { buildAllIndexes, loadIndexes } from "./indexer.js";
+import { LocalRagRetriever } from "./retriever.js";
+import { LoggingRagRetriever } from "./loggingRetriever.js";
+const EXTERNAL_DIR = path.resolve("external");
+const BASIC_DATA_DIR = path.resolve("data/basic/examples");
+const ASM_DATA_DIR = path.resolve("data/assembly/examples");
+const DOC_DIR = path.resolve("doc");
+const CONTEXT_DIR = path.resolve("doc/context");
+const BOOTSTRAP_PATH = path.join(CONTEXT_DIR, "bootstrap.md");
+const AGENTS_PATH = path.resolve("AGENTS.md");
+const PROMPTS_DIR = path.resolve(".github/prompts");
+const CHAT_PATH = path.join(CONTEXT_DIR, "chat.md");
+function resolveEmbeddingsDir() {
+    return path.resolve(process.env.RAG_EMBEDDINGS_DIR ?? "data");
+}
+function embeddingIndexPaths() {
+    const dir = resolveEmbeddingsDir();
+    return {
+        dir,
+        basic: path.join(dir, "embeddings_basic.json"),
+        asm: path.join(dir, "embeddings_asm.json"),
+        mixed: path.join(dir, "embeddings_mixed.json"),
+        hardware: path.join(dir, "embeddings_hardware.json"),
+        other: path.join(dir, "embeddings_other.json"),
+    };
+}
+export async function initRag() {
+    const model = new LocalMiniHashEmbedding(384);
+    // Build on start only when explicitly requested
+    const buildOnStart = String(process.env.RAG_BUILD_ON_START ?? "").trim().toLowerCase();
+    if (buildOnStart === "1" || buildOnStart === "true" || buildOnStart === "yes") {
+        const needBuild = await needsRebuild();
+        if (needBuild) {
+            await buildAllIndexes({ model });
+        }
+    }
+    const embeddingsDir = resolveEmbeddingsDir();
+    const { basic, asm, mixed, hardware, other } = await loadIndexes({ embeddingsDir });
+    const baseRetriever = new LocalRagRetriever(model, { basic, asm, mixed, hardware, other });
+    const loggingRetriever = new LoggingRagRetriever(baseRetriever);
+    // Background watcher: reindex if source files change (checks mtimes periodically)
+    // Default disabled to avoid churn/conflicts unless explicitly enabled
+    const intervalMs = Number(process.env.RAG_REINDEX_INTERVAL_MS ?? 0);
+    if (intervalMs > 0) {
+        setInterval(async () => {
+            try {
+                if (await needsRebuild()) {
+                    await buildAllIndexes({ model });
+                    const updated = await loadIndexes({ embeddingsDir: resolveEmbeddingsDir() });
+                    baseRetriever.updateIndexes(updated);
+                }
+            }
+            catch (err) {
+                // swallow in background to avoid crashing server
+                // eslint-disable-next-line no-console
+                console.warn("RAG reindex error", err);
+            }
+        }, intervalMs).unref();
+    }
+    return loggingRetriever;
+}
+async function fileMtime(file) {
+    try {
+        const stat = await fs.stat(file);
+        return stat.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+async function dirMtimeRecursive(root) {
+    let newest = 0;
+    async function walk(dir) {
+        let entries = [];
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else if (entry.isFile()) {
+                const stat = await fs.stat(full);
+                if (stat.mtimeMs > newest)
+                    newest = stat.mtimeMs;
+            }
+        }
+    }
+    await walk(root);
+    return newest;
+}
+async function needsRebuild() {
+    const paths = embeddingIndexPaths();
+    const indexFiles = [paths.basic, paths.asm, paths.mixed, paths.hardware, paths.other];
+    const indexTimes = await Promise.all(indexFiles.map((file) => fileMtime(file)));
+    if (indexTimes.some((time) => time === null)) {
+        return true;
+    }
+    const oldestIndex = Math.min(...indexTimes);
+    const [basicDataM, asmDataM, externalM, docsM, bootstrapM, agentsM, promptsM, chatM] = await Promise.all([
+        dirMtimeRecursive(BASIC_DATA_DIR),
+        dirMtimeRecursive(ASM_DATA_DIR),
+        dirMtimeRecursive(EXTERNAL_DIR),
+        dirMtimeRecursive(DOC_DIR).catch(() => 0),
+        fileMtime(BOOTSTRAP_PATH).then((v) => v ?? 0),
+        fileMtime(AGENTS_PATH).then((v) => v ?? 0),
+        promptFilesMtime().then((v) => v ?? 0),
+        fileMtime(CHAT_PATH).then((v) => v ?? 0),
+    ]);
+    const newestSource = Math.max(basicDataM, asmDataM, externalM, docsM, bootstrapM, agentsM, promptsM, chatM);
+    return newestSource > oldestIndex;
+}
+async function promptFilesMtime() {
+    let newest = 0;
+    try {
+        const entries = await fs.readdir(PROMPTS_DIR, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".prompt.md"))
+                continue;
+            const stat = await fs.stat(path.join(PROMPTS_DIR, entry.name)).catch(() => null);
+            if (stat && stat.mtimeMs > newest)
+                newest = stat.mtimeMs;
+        }
+    }
+    catch {
+        return 0;
+    }
+    return newest;
+}

package/dist/rag/knowledgeIndex.js

@@ -0,0 +1,361 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+const KNOWLEDGE_BUNDLES = [
+    {
+        id: "orientation",
+        title: "Workflow & Orientation",
+        summary: "Mandatory workflow and safety guidance before issuing any C64 commands.",
+        prompts: ["basic-program", "assembly-program", "memory-debug"],
+        tools: ["upload_and_run_basic", "upload_and_run_asm", "read_screen", "read_memory"],
+        resources: [
+            {
+                uri: "c64://context/bootstrap",
+                name: "Workflow Rules & Best Practices",
+                description: "CRITICAL: Mandatory workflow rules for all C64 programming",
+                relativePath: "data/context/bootstrap.md",
+                priority: "critical",
+                summary: "Step-by-step rules for safe automation, verification, and rollback on the C64.",
+                prompts: ["basic-program", "assembly-program", "memory-debug"],
+                tools: ["upload_and_run_basic", "upload_and_run_asm", "read_screen", "read_memory"],
+                tags: ["workflow", "safety"],
+            },
+        ],
+    },
+    {
+        id: "languages",
+        title: "Programming Languages",
+        summary: "Language references required before generating BASIC or 6502 assembly programs.",
+        prompts: ["basic-program", "assembly-program"],
+        tools: ["upload_and_run_basic", "upload_and_run_asm", "read_screen", "read_memory"],
+        resources: [
+            {
+                uri: "c64://specs/basic",
+                name: "Commodore BASIC v2 Specification",
+                description: "Complete BASIC v2 reference. READ THIS BEFORE generating any BASIC code!",
+                relativePath: "data/basic/basic-spec.md",
+                priority: "critical",
+                summary: "Token definitions, syntax rules, and device I/O guidance for BASIC v2.",
+                prompts: ["basic-program"],
+                tools: ["upload_and_run_basic", "read_screen"],
+                relatedResources: ["c64://context/bootstrap"],
+                tags: ["basic", "language"],
+            },
+            {
+                uri: "c64://specs/assembly",
+                name: "6502/6510 Assembly Reference",
+                description: "Full instruction set and addressing modes. READ THIS BEFORE generating assembly!",
+                relativePath: "data/assembly/assembly-spec.md",
+                priority: "critical",
+                summary: "Official opcode matrix, addressing modes, and zero-page strategy for the 6510 CPU.",
+                prompts: ["assembly-program"],
+                tools: ["upload_and_run_asm", "read_memory"],
+                relatedResources: ["c64://context/bootstrap"],
+                tags: ["assembly", "language"],
+            },
+        ],
+    },
+    {
+        id: "audio",
+        title: "SID & Audio",
+        summary: "All references needed to compose, play, and verify SID music.",
+        prompts: ["sid-music"],
+        tools: ["music_generate", "sid_note_on", "sid_note_off", "sid_volume", "sidplay_file", "analyze_audio"],
+        resources: [
+            {
+                uri: "c64://specs/sid",
+                name: "SID Chip Programming Guide",
+                description: "Sound Interface Device registers and music programming",
+                relativePath: "data/audio/sid-spec.md",
+                priority: "critical",
+                summary: "Register map, waveform behaviour, and ADSR envelopes for expressive SID playback.",
+                prompts: ["sid-music"],
+                tools: ["sid_note_on", "sid_note_off", "sid_volume", "music_generate", "analyze_audio"],
+                relatedResources: ["c64://specs/sidwave", "c64://docs/sid/file-structure"],
+                tags: ["sid", "audio"],
+            },
+            {
+                uri: "c64://specs/sidwave",
+                name: "SIDWAVE Music Format Specification",
+                description: "YAML/JSON music composition format for SID chip",
+                relativePath: "data/audio/sidwave.md",
+                priority: "reference",
+                summary: "Defines the SIDWAVE interchange format used by the SID composer workflow.",
+                prompts: ["sid-music"],
+                tools: ["music_generate", "sidplay_file"],
+                relatedResources: ["c64://specs/sid", "c64://docs/sid/file-structure"],
+                tags: ["sid", "format"],
+            },
+            {
+                uri: "c64://docs/sid/file-structure",
+                name: "SID File Structure Reference",
+                description: "Breakdown of the SID file format layout and metadata",
+                relativePath: "data/audio/sid-file-structure.md",
+                priority: "reference",
+                summary: "Explains PSID/RSID headers, metadata blocks, and compatibility notes for imported music.",
+                prompts: ["sid-music"],
+                tools: ["sidplay_file", "music_generate"],
+                relatedResources: ["c64://specs/sid", "c64://specs/sidwave"],
+                tags: ["sid", "format"],
+            },
+        ],
+    },
+    {
+        id: "graphics",
+        title: "Graphics & VIC-II",
+        summary: "Key material for PETSCII art, sprites, and raster control on the VIC-II.",
+        prompts: ["graphics-demo"],
+        tools: ["render_petscii_screen", "generate_sprite_prg", "write_memory"],
+        resources: [
+            {
+                uri: "c64://specs/vic",
+                name: "VIC-II Graphics Specification",
+                description: "Video chip, sprites, raster programming, and timing",
+                relativePath: "data/video/vic-spec.md",
+                priority: "critical",
+                summary: "Covers raster timing, sprite control, colour RAM, and bitmap modes on the VIC-II.",
+                prompts: ["graphics-demo"],
+                tools: ["render_petscii_screen", "generate_sprite_prg", "write_memory"],
+                relatedResources: ["c64://specs/assembly"],
+                tags: ["vic", "graphics"],
+            },
+        ],
+    },
+    {
+        id: "printer",
+        title: "Printers & Hardcopy",
+        summary: "Guides for Commodore MPS and Epson FX printing workflows, including prompts.",
+        prompts: ["printer-job"],
+        tools: [
+            "printer_guide",
+            "printer_commodore_text",
+            "printer_commodore_bitmap",
+            "printer_epson_text",
+            "printer_epson_bitmap",
+            "printer_prompts",
+        ],
+        resources: [
+            {
+                uri: "c64://specs/printer",
+                name: "Printer Programming Guide",
+                description: "Commodore MPS and Epson FX printer control",
+                relativePath: "data/printer/printer-spec.md",
+                priority: "critical",
+                summary: "Covers device setup, control codes, and Ultimate 64 integration for printers.",
+                prompts: ["printer-job"],
+                tools: ["printer_guide", "printer_commodore_text", "printer_epson_text"],
+                relatedResources: [
+                    "c64://docs/printer/guide",
+                    "c64://docs/printer/commodore-text",
+                    "c64://docs/printer/epson-text",
+                ],
+                tags: ["printer", "spec"],
+            },
+            {
+                uri: "c64://docs/printer/guide",
+                name: "Printer Workflow Guide",
+                description: "Unified quick reference for Commodore and Epson printers",
+                relativePath: "data/printer/printer-spec.md",
+                priority: "reference",
+                summary: "Quick-look workflow covering setup, troubleshooting, and sample jobs for both printer families.",
+                prompts: ["printer-job"],
+                tools: ["printer_guide"],
+                relatedResources: [
+                    "c64://specs/printer",
+                    "c64://docs/printer/commodore-text",
+                    "c64://docs/printer/epson-text",
+                ],
+                tags: ["printer", "workflow"],
+            },
+            {
+                uri: "c64://docs/printer/commodore-text",
+                name: "Commodore Printer Text Guide",
+                description: "Device 4 character printing reference for Commodore MPS printers",
+                relativePath: "data/printer/printer-commodore.md",
+                priority: "reference",
+                summary: "Character sets, control codes, and formatting for Commodore MPS text output.",
+                prompts: ["printer-job"],
+                tools: ["printer_commodore_text"],
+                relatedResources: [
+                    "c64://specs/printer",
+                    "c64://docs/printer/commodore-bitmap",
+                ],
+                tags: ["printer", "commodore"],
+            },
+            {
+                uri: "c64://docs/printer/commodore-bitmap",
+                name: "Commodore Printer Bitmap Guide",
+                description: "Bitmap and custom character printing workflow for Commodore printers",
+                relativePath: "data/printer/printer-commodore-bitmap.md",
+                priority: "reference",
+                summary: "Details bitmap modes, graphics commands, and data layout for MPS bitmap printing.",
+                prompts: ["printer-job"],
+                tools: ["printer_commodore_bitmap"],
+                relatedResources: [
+                    "c64://docs/printer/commodore-text",
+                    "c64://specs/printer",
+                ],
+                tags: ["printer", "commodore", "graphics"],
+            },
+            {
+                uri: "c64://docs/printer/epson-text",
+                name: "Epson Printer Text Guide",
+                description: "Text control sequences for Epson FX-compatible printers",
+                relativePath: "data/printer/printer-epson.md",
+                priority: "reference",
+                summary: "Lists ESC/P control codes and formatting advice for Epson FX text output.",
+                prompts: ["printer-job"],
+                tools: ["printer_epson_text"],
+                relatedResources: [
+                    "c64://docs/printer/epson-bitmap",
+                    "c64://specs/printer",
+                ],
+                tags: ["printer", "epson"],
+            },
+            {
+                uri: "c64://docs/printer/epson-bitmap",
+                name: "Epson Printer Bitmap Guide",
+                description: "Bitmap printing and graphics control for Epson FX printers",
+                relativePath: "data/printer/printer-epson-bitmap.md",
+                priority: "reference",
+                summary: "Explains bit-image modes, density options, and data packing for Epson bitmap jobs.",
+                prompts: ["printer-job"],
+                tools: ["printer_epson_bitmap"],
+                relatedResources: [
+                    "c64://docs/printer/epson-text",
+                    "c64://specs/printer",
+                ],
+                tags: ["printer", "epson", "graphics"],
+            },
+            {
+                uri: "c64://docs/printer/prompts",
+                name: "Printer Prompt Templates",
+                description: "Template prompts and workflow guidance for printer jobs",
+                relativePath: "data/printer/printer-prompts.md",
+                priority: "supplemental",
+                summary: "Reusable prompt templates that drive complex printer jobs through the MCP server.",
+                prompts: ["printer-job"],
+                tools: ["printer_prompts"],
+                relatedResources: [
+                    "c64://docs/printer/guide",
+                    "c64://docs/printer/commodore-text",
+                    "c64://docs/printer/epson-text",
+                ],
+                tags: ["printer", "prompts"],
+            },
+        ],
+    },
+];
+const BASE_RESOURCES = KNOWLEDGE_BUNDLES.flatMap((bundle, bundleIndex) => bundle.resources.map((resource, resourceIndex) => ({
+    uri: resource.uri,
+    name: resource.name,
+    description: resource.description,
+    mimeType: "text/markdown",
+    relativePath: resource.relativePath,
+    metadata: {
+        domain: bundle.id,
+        priority: resource.priority,
+        summary: resource.summary,
+        prompts: resource.prompts,
+        tools: resource.tools,
+        tags: resource.tags ?? [],
+        bundle: {
+            id: bundle.id,
+            title: bundle.title,
+            summary: bundle.summary,
+            order: bundleIndex,
+        },
+        order: resourceIndex,
+        relatedResources: resource.relatedResources ?? [],
+    },
+})));
+const INDEX_RESOURCE = {
+    uri: "c64://docs/index",
+    name: "C64 Knowledge Map",
+    description: "Start here for a guided tour of all Commodore 64 knowledge resources",
+    mimeType: "text/markdown",
+    metadata: {
+        domain: "overview",
+        priority: "critical",
+        summary: "Explains how to approach each knowledge bundle and when to consult it.",
+        prompts: ["basic-program", "assembly-program", "sid-music", "graphics-demo", "printer-job", "memory-debug"],
+        tools: [
+            "upload_and_run_basic",
+            "upload_and_run_asm",
+            "music_generate",
+            "render_petscii_screen",
+            "printer_guide",
+            "read_memory",
+        ],
+        tags: ["overview"],
+        bundle: {
+            id: "overview",
+            title: "Knowledge Overview",
+            summary: "Read this first to understand how the MCP server organizes Commodore 64 expertise.",
+            order: -1,
+        },
+        order: 0,
+        relatedResources: BASE_RESOURCES.map((resource) => resource.uri),
+    },
+    buildContent: (resources) => renderKnowledgeIndex(resources),
+};
+const ALL_RESOURCES = [...BASE_RESOURCES, INDEX_RESOURCE];
+function renderKnowledgeIndex(resources) {
+    const sections = KNOWLEDGE_BUNDLES.map((bundle) => {
+        const bundleResources = resources.filter((resource) => resource.metadata.bundle.id === bundle.id);
+        const entries = bundleResources
+            .map((resource) => {
+            const star = resource.metadata.priority === "critical" ? "★ " : "";
+            const prompts = resource.metadata.prompts.length
+                ? ` Prompts: ${resource.metadata.prompts
+                    .map((prompt) => `\`${prompt}\``)
+                    .join(", ")}.`
+                : "";
+            const tools = resource.metadata.tools.length
+                ? ` Tools: ${resource.metadata.tools
+                    .map((tool) => `\`${tool}\``)
+                    .join(", ")}.`
+                : "";
+            const tags = resource.metadata.tags.length
+                ? ` Tags: ${resource.metadata.tags.join(", ")}.`
+                : "";
+            return `- ${star}**${resource.name}** (\`${resource.uri}\`) — ${resource.metadata.summary}.${prompts}${tools}${tags}`;
+        })
+            .join("\n");
+        return `## ${bundle.title}\n\n${bundle.summary}\n\n${entries}`;
+    });
+    return [
+        "# C64 Knowledge Map",
+        "Start with critical (★) entries before invoking tools or generating code.",
+        ...sections,
+    ].join("\n\n");
+}
+export function listKnowledgeResources() {
+    return ALL_RESOURCES;
+}
+export function getKnowledgeResource(uri) {
+    return ALL_RESOURCES.find((resource) => resource.uri === uri);
+}
+export function readKnowledgeResource(uri, projectRoot) {
+    const resource = getKnowledgeResource(uri);
+    if (!resource) {
+        return undefined;
+    }
+    if (resource.buildContent) {
+        const baseResources = ALL_RESOURCES.filter((item) => item.uri !== resource.uri);
+        return {
+            uri: resource.uri,
+            mimeType: resource.mimeType,
+            text: resource.buildContent(baseResources),
+        };
+    }
+    if (!resource.relativePath) {
+        return undefined;
+    }
+    const fullPath = join(projectRoot, resource.relativePath);
+    const text = readFileSync(fullPath, "utf-8");
+    return {
+        uri: resource.uri,
+        mimeType: resource.mimeType,
+        text,
+    };
+}

package/dist/rag/loggingRetriever.js

@@ -0,0 +1,46 @@
+import { formatErrorMessage, formatPayloadForDebug, loggerFor, payloadByteLength } from "../logger.js";
+export class LoggingRagRetriever {
+    constructor(inner, logger = loggerFor("rag")) {
+        this.inner = inner;
+        this.log = logger;
+    }
+    async retrieve(query, topK, filterLanguage) {
+        const startedAt = Date.now();
+        if (this.log.isDebugEnabled()) {
+            this.log.debug("rag request", {
+                query,
+                topK,
+                language: filterLanguage,
+            });
+        }
+        try {
+            const results = await this.inner.retrieve(query, topK, filterLanguage);
+            const latency = Date.now() - startedAt;
+            const bytes = payloadByteLength(results);
+            const keywords = summarizeQuery(query);
+            const language = filterLanguage ?? "any";
+            this.log.info(`retrieve language=${language} keywords="${keywords}" hits=${results.length} bytes=${bytes} latencyMs=${latency}`);
+            if (this.log.isDebugEnabled()) {
+                this.log.debug("rag response", {
+                    results: formatPayloadForDebug(results),
+                });
+            }
+            return results;
+        }
+        catch (error) {
+            const latency = Date.now() - startedAt;
+            const keywords = summarizeQuery(query);
+            const language = filterLanguage ?? "any";
+            this.log.error(`retrieve language=${language} keywords="${keywords}" bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
+            throw error;
+        }
+    }
+}
+function summarizeQuery(query) {
+    const cleaned = query.trim().replace(/\s+/g, " ");
+    if (!cleaned)
+        return "";
+    const words = cleaned.split(" ").slice(0, 6);
+    const summary = words.join(" ");
+    return summary.length > 64 ? `${summary.slice(0, 61)}...` : summary;
+}

package/dist/rag/rateLimiter.js

@@ -0,0 +1,127 @@
+/*
+C64 Bridge - Simple per-domain rate limiter
+GPL-2.0-only
+*/
+export class RealTimeSource {
+    nowMs() {
+        return Date.now();
+    }
+    async sleepMs(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Sliding-window rate limiter enforcing at most `maxPerSecond` events per key.
+ */
+export class SlidingWindowRateLimiter {
+    constructor(maxPerSecond, timeSource = new RealTimeSource()) {
+        this.keyToTimestamps = new Map();
+        this.maxPerSecond = maxPerSecond;
+        this.timeSource = timeSource;
+    }
+    pruneOld(key, now) {
+        const windowStart = now - 1000;
+        const arr = this.keyToTimestamps.get(key);
+        if (!arr)
+            return;
+        let startIdx = 0;
+        while (startIdx < arr.length && arr[startIdx] < windowStart)
+            startIdx++;
+        if (startIdx > 0)
+            arr.splice(0, startIdx);
+    }
+    /**
+     * Wait until a token is available for the given key, then consume it.
+     */
+    async consume(key) {
+        if (this.maxPerSecond === Infinity)
+            return; // disabled
+        if (this.maxPerSecond <= 0)
+            throw new Error("maxPerSecond must be > 0 or Infinity");
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const now = this.timeSource.nowMs();
+            const arr = this.keyToTimestamps.get(key) ?? [];
+            this.pruneOld(key, now);
+            const inWindow = arr.length;
+            if (inWindow < this.maxPerSecond) {
+                arr.push(now);
+                this.keyToTimestamps.set(key, arr);
+                return;
+            }
+            const oldest = arr[0];
+            const waitMs = Math.max(0, 1000 - (now - oldest));
+            await this.timeSource.sleepMs(Math.min(waitMs, 50));
+        }
+    }
+}
+export class AdaptiveRateLimiter {
+    constructor(defaultRps, timeSource = new RealTimeSource(), opts = {}) {
+        this.keyToTimestamps = new Map();
+        this.keyToRps = new Map(); // [currentRps]
+        this.keyToLastAdjust = new Map();
+        if (!(defaultRps > 0))
+            throw new Error("defaultRps must be > 0");
+        this.defaultRps = defaultRps;
+        this.timeSource = timeSource;
+        this.minRps = opts.minRps ?? 1;
+        this.increaseIntervalMs = opts.increaseIntervalMs ?? 15000;
+        this.increaseStep = opts.increaseStep ?? 1;
+    }
+    pruneOld(key, now) {
+        const arr = this.keyToTimestamps.get(key);
+        if (!arr || arr.length === 0)
+            return;
+        const cutoff = now - 1000;
+        let i = 0;
+        while (i < arr.length && arr[i] < cutoff)
+            i++;
+        if (i > 0)
+            arr.splice(0, i);
+    }
+    currentRps(key) {
+        const cur = this.keyToRps.get(key)?.[0];
+        if (cur && cur > 0)
+            return cur;
+        this.keyToRps.set(key, [this.defaultRps]);
+        return this.defaultRps;
+    }
+    /** Notify the limiter that throttling occurred, reducing RPS for the key. */
+    notifyThrottle(key, factor = 0.5) {
+        const now = this.timeSource.nowMs();
+        const cur = this.currentRps(key);
+        const next = Math.max(this.minRps, Math.floor(cur * factor));
+        this.keyToRps.set(key, [next]);
+        this.keyToLastAdjust.set(key, now);
+    }
+    maybeRecover(key, now) {
+        const cur = this.currentRps(key);
+        if (cur >= this.defaultRps)
+            return;
+        const last = this.keyToLastAdjust.get(key) ?? 0;
+        if (now - last >= this.increaseIntervalMs) {
+            const next = Math.min(this.defaultRps, cur + this.increaseStep);
+            this.keyToRps.set(key, [next]);
+            this.keyToLastAdjust.set(key, now);
+        }
+    }
+    /** Wait until a token is available for the given key, then consume it. */
+    async consume(key) {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const now = this.timeSource.nowMs();
+            const arr = this.keyToTimestamps.get(key) ?? [];
+            this.pruneOld(key, now);
+            this.maybeRecover(key, now);
+            const maxPerSecond = this.currentRps(key);
+            if (arr.length < maxPerSecond) {
+                arr.push(now);
+                this.keyToTimestamps.set(key, arr);
+                return;
+            }
+            const oldest = arr[0];
+            const waitMs = Math.max(0, 1000 - (now - oldest));
+            await this.timeSource.sleepMs(Math.min(waitMs, 10));
+        }
+    }
+}