ambient: adaptive scheduler never receives rate-limit data, so `calculate_interval` always falls back to `max_interval_minutes`

[unclesamwk]

docs/AMBIENT_MODE.md documents an adaptive wake interval driven by provider rate-limit headers. The algorithm exists in scheduler.rs and is unit-tested, but nothing ever supplies it with data: both call sites pass None, and RateLimitInfo has no producer anywhere in the workspace. The documented behavior is therefore unreachable.

Checked against master at be248c6 (v0.85.0), which is current as of writing.

Expected

docs/AMBIENT_MODE.md#L344-L356:

Rate Limit Discovery

Rate limits are learned from provider response headers:

x-ratelimit-limit-tokens: 100000
x-ratelimit-remaining-tokens: 85000
x-ratelimit-reset-requests: 2026-02-08T15:00:00Z

The interval is then derived from the remaining window and budget.

Actual

ambient/scheduler.rs#L187 implements exactly that algorithm and returns early when it gets nothing:

let info = match rate_limit_info {
    Some(i) => i,
    None => return self.apply_backoff(max),
};

Both callers pass None, and they are the only callers in the workspace:

• ambient/runner.rs#L681
• ambient/runner.rs#L814

$ rg -n 'calculate_interval' --type rust | rg -v 'scheduler.rs'
crates/jcode-app-core/src/ambient/runner.rs:681:  .calculate_interval(None)
crates/jcode-app-core/src/ambient/runner.rs:814:  let interval = scheduler.calculate_interval(None);

RateLimitInfo is declared and consumed by the scheduler, but never constructed with real values anywhere.

No provider runtime reads x-ratelimit-*. The two rate-limit modules that do exist serve other purposes:

• crates/jcode-app-core/src/update_rate_limit.rs — GitHub API limits for update checks.
• crates/jcode-provider-core/src/retry_after.rs — per-request Retry-After handling, carried through anyhow::Error, not surfaced to ambient scheduling.

Consequence

With rate_limit_info = None, calculate_interval returns apply_backoff(max), and apply_backoff clamps to max_interval_minutes. So:

• Ambient wakes on a fixed cadence of max_interval_minutes (default 120) regardless of quota state, rather than adapting to the window.
• min_interval_minutes never takes effect.
• The exponential backoff in on_rate_limit_hit is inert, because the interval is already clamped at max.
• user_budget_reserve never takes effect, so there is no reservation of headroom for the interactive user.

Separately, runner.rs#L800-L802 calls on_rate_limit_hit() in the generic cycle-error branch, so any failure is treated as a rate-limit hit.

Question before sending a patch

The existing usage plumbing does not fit RateLimitInfo as-is: ProviderUsage/UsageLimit carry usage_percent: f32 and resets_at: String behind a 120s cache, not token counts. Capturing x-ratelimit-* per provider runtime touches a dozen crates, so I would rather ask first than guess:

1. Should the capture live in each provider runtime, or behind one shared response hook?
2. Is reusing the existing ProviderUsage snapshot acceptable instead, which would mean widening RateLimitInfo (or the algorithm) to accept a percentage plus reset time?

Happy to send a PR once the direction is clear.

Related

• docs: AMBIENT_MODE.md status stuck at "Design" while the feature is fully implemented #965 closed the stale "Design" status on AMBIENT_MODE.md and cites scheduler.rs as evidence the feature shipped; this is the one documented piece of that file that is not reached at runtime.
• Feature request: make long unattended runs possible (continuation currently lives in the client) #686 (long unattended runs) is adjacent — a quota-aware wake interval is part of surviving a rate-limit window unattended.

Environment

v0.85.0, be248c6, macOS 26.6.2 (arm64).

[1jehuang]

Thanks, confirmed in current code: both ambient runner calls still use calculate_interval(None), so the scheduler uses its maximum-interval fallback. The generic cycle-error branch also calls on_rate_limit_hit(). A safe fix needs a decision on the quota data contract rather than guessing token counts from percentages. Recommendation: choose a shared, timestamped quota snapshot with explicit unknown/stale handling, then wire it into the scheduler and add a runner-level test. Leaving this open for that design decision.

---

Jcode agent (automated triage), on behalf of @1jehuang

[unclesamwk]

Thanks — that direction works for me. Concrete proposal for the contract, so there is something specific to accept or reject.

Snapshot

pub struct QuotaSnapshot {
    pub provider: String,
    /// When this was measured, not when it was read.
    pub observed_at: DateTime<Utc>,
    pub headroom: Headroom,
    pub resets_at: Option<DateTime<Utc>>,
    pub hard_limit_reached: bool,
}

pub enum Headroom {
    /// No usable reading. Not the same as "no headroom".
    Unknown,
    /// Remaining share of the window, 0.0..=1.0 — what `ProviderUsage` can give today.
    Fraction(f32),
    /// What `x-ratelimit-*` headers would give, if they are captured later.
    Tokens { remaining: u64, limit: Option<u64> },
}

Two variants rather than one so the percentage path available today and a future header path can coexist without a second contract change. Unknown is a variant instead of an Option so "we did not measure" cannot be silently read as "empty".

Staleness

observed_at plus a bound, rather than a freshness flag, so the decision stays with the consumer. Suggested bound: 2 × PROVIDER_USAGE_CACHE_TTL (currently 120s, crates/jcode-base/src/usage.rs:46). Past that, the scheduler treats the snapshot as Unknown.

The scheduler reads the existing PROVIDER_USAGE_CACHE and never triggers a fetch: no network on the scheduling path, and an empty cache is Unknown rather than a stall.

Scheduler behaviour

Input	Interval
Unknown, or older than the staleness bound	apply_backoff(max) — today's behaviour, unchanged
hard_limit_reached with resets_at	wake at the reset, clamped to [min, max]
Fraction(f)	max - (max - min) × f × (1 - user_budget_reserve), clamped
Tokens { .. }	the existing token algorithm, unchanged

max_interval_minutes stays a hard cap in every branch, so a distant reset means re-checking at least every max, never sleeping past it. That keeps the current invariant and makes min_interval_minutes and user_budget_reserve load-bearing for the first time.

The Fraction row is a heuristic, not a budget calculation — with a percentage there is no token count to divide by avg_tokens_per_ambient_cycle. It is monotone in the right direction and stays inside the existing bounds.

Worth stating plainly: with the defaults (min 5, max 120, user_budget_reserve 0.8) even a full window only pulls the interval to ~97 minutes, because ambient is limited to 20% of headroom by design. That is deliberate but modest, and user_budget_reserve is the knob. If you would rather ambient react more sharply when the window is empty than when it is full, an alternative is to keep max whenever headroom is below some threshold and interpolate only above it. Happy to take either.

Tests

At runner level, since that is where the regression was:

1. Stale or unknown snapshot yields exactly the current fallback interval — proves the change is inert where data is missing.
2. Fresh snapshot with high headroom moves the interval toward min.
3. hard_limit_reached with a reset inside the window wakes no later than the reset; with a reset beyond max, wakes at max.

Out of scope here

The generic error branch calling on_rate_limit_hit() (crates/jcode-app-core/src/ambient/runner.rs:800-802) is a separate one-line classification fix. Happy to send it as its own PR so this one stays reviewable.

I can implement the above if it looks right. Given the autonomous: no label I would rather have an explicit go-ahead on the contract first than open a PR against an undecided design.