From 9bc25b34fd98f70e65a86d64ba4d9789cdc51660 Mon Sep 17 00:00:00 2001 From: Ben Meadors Date: Mon, 11 May 2026 07:42:04 -0500 Subject: [PATCH] Add guidance to use Throttle for time-based rate limiting in agent instructions --- .github/copilot-instructions.md | 1 + AGENTS.md | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8980aca1a..8573b5f45 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -197,6 +197,7 @@ firmware/ - Use `assert()` for invariants that should never fail - C++17 features are available (`std::optional`, structured bindings, `if constexpr`, etc.) - **Keep code comments minimal — one or two lines, max.** Comment only when the _why_ isn't obvious from the code; never restate what the next line does. No multi-paragraph block comments explaining straightforward changes. The diff and commit message carry the rationale; the code carries the behavior. +- **Use `Throttle` for time-based rate limiting, not raw `millis()` math.** `src/mesh/Throttle.h` provides `Throttle::isWithinTimespanMs(lastMs, intervalMs)` (returns true while inside the cooldown) and `Throttle::execute(&lastMs, intervalMs, func)` (function-pointer form that updates the timestamp on fire). Use these for any "did N ms pass since X" check — raw `millis() > lastMs + N` is rollover-unsafe (breaks after ~49.7 days) and inconsistent with the rest of the codebase. The helpers compute `now - lastMs` with unsigned subtraction, which wraps correctly. ### Naming Conventions diff --git a/AGENTS.md b/AGENTS.md index 113f12591..82912f252 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,6 +67,7 @@ Key rotation to never trigger casually: only the **full** factory reset (`factor - **Run `trunk fmt` before proposing a commit.** The `trunk_check` CI gate will reject unformatted code. - **`confirm=True` on destructive MCP tools is a real gate, not a formality.** Don't bypass it via auto-approve settings. - **Keep code comments minimal — one or two lines, max.** Comment only when the _why_ isn't obvious from the code; never restate what the next line does. No multi-paragraph block comments explaining straightforward changes. The diff and commit message carry the rationale; the code carries the behavior. +- **Use `Throttle` for time-based rate limiting, not raw `millis()` math.** `src/mesh/Throttle.h` provides `Throttle::isWithinTimespanMs(lastMs, intervalMs)` (returns true while inside the cooldown) and `Throttle::execute(&lastMs, intervalMs, func)` (function-pointer form that updates the timestamp on fire). Use these for any "did N ms pass since X" check — raw `millis() > lastMs + N` is rollover-unsafe (breaks after ~49.7 days) and inconsistent with the rest of the codebase. The helpers compute `now - lastMs` with unsigned subtraction, which wraps correctly. ## Typical agent workflows