feat(scheduler-gate): throttle background AI on battery / busy CPU

[senamakel]

Summary

• New openhuman::scheduler_gate module that gates background LLM-bound work based on power state (battery via starship-battery), CPU pressure (sysinfo two-shot), and deployment mode (env + /.dockerenv + Kubernetes detection).
• Hooked into the memory-tree worker pool (memory/tree/jobs/worker.rs) right before the existing llm_slots semaphore — only is_llm_bound() jobs (ExtractChunk, Seal, DigestDaily, TopicRoute) are throttled. AppendBuffer / FlushStale (pure DB IO) keep running freely.
• Composio periodic tick relaxed from 60s → 300s. Per-provider sync_interval_secs still bounds the minimum delay between actual syncs; this just stops the scheduler from waking the host every minute to find nothing due.
• New [scheduler_gate] config section with mode (auto / always_on / off), battery_floor (0.80), cpu_busy_threshold_pct (70.0), throttled_backoff_ms, paused_poll_ms.
• Background sampler refreshes signals every 30s on a tokio task; cooperative wait_for_capacity() returns immediately for Aggressive/Normal, sleeps for Throttled, polls for Paused.

Why: background memory-tree digests + embeddings ran flat-out and made the laptop visibly lag, especially on battery. The gate sits exactly at the LLM boundary — composio's ingest path (ingest_email → regex score → jobs::enqueue_tx) does not touch the LLM inline, only the worker pool does, so throttling the worker is sufficient.

Test plan

• cargo check --lib clean
• cargo test --lib scheduler_gate — 8/8 policy tests pass (off/always_on/server-mode/plugged-in/below-floor/above-floor/busy-cpu/no-battery)
• cargo test --lib composio::periodic — 6/6 pass (incl. relaxed tick_seconds_is_sane_default)
• cargo fmt
• Manual reproducer documented: OPENHUMAN_ON_AC_POWER=false OPENHUMAN_BATTERY_CHARGE=0.5 forces Throttled; watch [scheduler_gate] debug logs for the policy transition
• Manual override documented: OPENHUMAN_DEPLOYMENT=server forces Aggressive regardless of host signals

Summary by CodeRabbit

• New Features

  • Added adaptive throttling of background AI work based on system conditions (battery level, CPU usage, and deployment mode).
  • Introduced configurable scheduler modes: Auto (adaptive), Always-On, and Off.

• Configuration

  • New scheduler configuration parameters for battery thresholds, CPU utilization limits, and throttle/pause intervals.

• Performance

  • Extended periodic task interval from 60 seconds to 5 minutes.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a scheduler gate that samples host signals (battery, CPU, deployment), decides an operational policy (Aggressive/Normal/Throttled/Paused), exposes an async capacity gate, integrates it into startup and job workers, and introduces config types and a battery probe dependency.

Changes

Cohort / File(s)	Summary
Scheduler Gate Implementation src/openhuman/scheduler_gate/mod.rs, src/openhuman/scheduler_gate/gate.rs, src/openhuman/scheduler_gate/policy.rs, src/openhuman/scheduler_gate/signals.rs	New module implementing global state, signal sampling (battery, CPU, server mode), policy decision logic (Aggressive/Normal/Throttled/Paused), background sampling loop, config update, and async wait_for_capacity() gate.
Public API Export src/openhuman/mod.rs	Exports the new scheduler_gate submodule for crate-wide access.
Configuration src/openhuman/config/schema/scheduler_gate.rs, src/openhuman/config/schema/mod.rs, src/openhuman/config/mod.rs, src/openhuman/config/schema/types.rs	Adds SchedulerGateMode and SchedulerGateConfig, integrates scheduler_gate into top-level Config with serde defaults and updates public re-exports.
Integration Points src/core/jsonrpc.rs, src/openhuman/memory/tree/jobs/worker.rs	Initializes global scheduler gate during startup before worker spawn; job worker awaits wait_for_capacity() before claiming LLM-bound jobs to avoid holding DB locks while gated.
Dependencies & Tuning Cargo.toml, src/openhuman/composio/periodic.rs	Adds starship-battery = "0.10" for battery probing; increases periodic scheduler tick from 60s to 300s and updates test bounds accordingly.

Sequence Diagram(s)

sequenceDiagram
    participant Startup as Startup
    participant Gate as SchedulerGate
    participant Sampler as SignalSampler
    participant Policy as PolicyEngine
    participant BgLoop as BgLoop(30s)
    participant JobWorker as JobWorker

    Startup->>Gate: init_global(&config)
    Gate->>Gate: init OnceLock / seed Signals
    Gate->>Sampler: Signals::sample()
    Sampler-->>Gate: Signals
    Gate->>Policy: decide(signals, config)
    Policy-->>Gate: Policy
    Gate->>Gate: store State
    Gate->>BgLoop: spawn periodic sampler

    loop every 30s
        BgLoop->>Sampler: sample()
        Sampler-->>BgLoop: Signals
        BgLoop->>Policy: decide(signals, config)
        Policy-->>BgLoop: Policy
        BgLoop->>Gate: update State
    end

    JobWorker->>Gate: wait_for_capacity().await
    alt Policy == Aggressive or Normal
        Gate-->>JobWorker: return immediately
    else Policy == Throttled
        Gate->>JobWorker: sleep(throttled_backoff_ms)
        JobWorker-->>JobWorker: proceed
    else Policy == Paused
        loop until policy changes
            Gate->>JobWorker: sleep(paused_poll_ms)
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• openhuman#873: Modifies startup initialization in src/core/jsonrpc.rs affecting background scheduler/worker startup sequencing; overlaps with this PR's insertion of init_global before worker spawn.

Poem

🐰 A curious rabbit taps the gate,
I listen to battery, fans, and state.
If your laptop sighs, I'll softly pause—
Else I hop, compute, and mind my cause. 🥕✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(scheduler-gate): throttle background AI on battery / busy CPU' directly and clearly summarizes the main change: adding a scheduler gate to throttle background AI work based on power state and CPU usage.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Review rate limit: 2/5 reviews remaining, refill in 24 minutes and 41 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/openhuman/memory/tree/jobs/worker.rs (1)

76-89: ⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Don't block after claiming the job.

claim_next() has already locked the row, so wait_for_capacity() can hold that lock indefinitely in Paused mode. Once DEFAULT_LOCK_DURATION_MS elapses, recover_stale_locks() can requeue the same job and another worker may process it again, duplicating side effects.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/openhuman/memory/tree/jobs/worker.rs` around lines 76 - 89, You are
currently awaiting scheduler_gate::wait_for_capacity() and llm_slots.acquire()
after claim_next(), which holds the DB lock and can cause the job row to be
re-claimed by recover_stale_locks() when DEFAULT_LOCK_DURATION_MS expires;
change the flow so you never block while holding the claim: either move capacity
checks before calling claim_next() or, if you must claim first, use non-blocking
checks (e.g., a scheduler_gate::try_check / llm_slots.try_acquire) and if they
would block, immediately release the claim (call whatever function releases the
claim or requeue the job) and return Ok(false) instead of awaiting; ensure
references to claim_next, wait_for_capacity, llm_slots.acquire,
DEFAULT_LOCK_DURATION_MS and recover_stale_locks are updated accordingly.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/openhuman/scheduler_gate/policy.rs`:
- Around line 43-50: Clamp the configuration thresholds before using them in
policy decisions: ensure cfg.battery_floor is clamped into a valid range (e.g.,
0..=100) and cfg.cpu_busy_threshold_pct is clamped into 0..=100 (or the
appropriate domain for those types) and then use the clamped values in the
battery_ok and cpu_ok checks; update the logic around the battery_ok computation
(which references cfg.battery_floor) and the cpu_ok computation (which uses
cfg.cpu_busy_threshold_pct) to refer to the clamped values to prevent
out-of-range config values from disabling or forcing throttling.

In `@src/openhuman/scheduler_gate/signals.rs`:
- Around line 43-49: The current env_on_ac parsing coerces any unrecognized
OPENHUMAN_ON_AC_POWER value to false; change the parsing for env_on_ac to only
accept explicit true tokens ("1","true","yes") as Some(true) and explicit false
tokens ("0","false","no") as Some(false), returning None for any other/invalid
input so invalid env values are ignored instead of treated as false (update the
env_on_ac expression that reads OPENHUMAN_ON_AC_POWER accordingly); keep
env_charge parsing as-is (it may remain .and_then(|v|
v.parse::<f32>().ok()).map(|v| v.clamp(0.0,1.0))).

---

Outside diff comments:
In `@src/openhuman/memory/tree/jobs/worker.rs`:
- Around line 76-89: You are currently awaiting
scheduler_gate::wait_for_capacity() and llm_slots.acquire() after claim_next(),
which holds the DB lock and can cause the job row to be re-claimed by
recover_stale_locks() when DEFAULT_LOCK_DURATION_MS expires; change the flow so
you never block while holding the claim: either move capacity checks before
calling claim_next() or, if you must claim first, use non-blocking checks (e.g.,
a scheduler_gate::try_check / llm_slots.try_acquire) and if they would block,
immediately release the claim (call whatever function releases the claim or
requeue the job) and return Ok(false) instead of awaiting; ensure references to
claim_next, wait_for_capacity, llm_slots.acquire, DEFAULT_LOCK_DURATION_MS and
recover_stale_locks are updated accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b2c4ebd0-1877-4b03-b08b-0a31a39049a2

📥 Commits

Reviewing files that changed from the base of the PR and between 44988bd and 22e0409.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (13)

• Cargo.toml
• src/core/jsonrpc.rs
• src/openhuman/composio/periodic.rs
• src/openhuman/config/mod.rs
• src/openhuman/config/schema/mod.rs
• src/openhuman/config/schema/scheduler_gate.rs
• src/openhuman/config/schema/types.rs
• src/openhuman/memory/tree/jobs/worker.rs
• src/openhuman/mod.rs
• src/openhuman/scheduler_gate/gate.rs
• src/openhuman/scheduler_gate/mod.rs
• src/openhuman/scheduler_gate/policy.rs
• src/openhuman/scheduler_gate/signals.rs

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/openhuman/scheduler_gate/signals.rs`:
- Around line 15-20: The fields and related variables in signals.rs use
snake_case but must follow camelCase for this module; rename struct fields
on_ac_power, battery_charge, cpu_usage_pct, server_mode to onAcPower,
batteryCharge, cpuUsagePct, serverMode (and the local variables/env flags
env_on_ac, env_charge, no_battery to envOnAc, envCharge, noBattery), then update
every usage, pattern match, constructor, method, impl, test, and
serialization/deserialization attribute that references those symbols (e.g., the
Signal struct, env_* locals, and any functions that read/write them) so names
are consistent; if external JSON/serde keys must remain snake_case, add
appropriate serde(rename = "...") attributes to the renamed fields.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b376add9-9ffb-4d4b-8aa9-b25435634402

📥 Commits

Reviewing files that changed from the base of the PR and between 22e0409 and be13be2.

📒 Files selected for processing (3)

• src/openhuman/memory/tree/jobs/worker.rs
• src/openhuman/scheduler_gate/policy.rs
• src/openhuman/scheduler_gate/signals.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• src/openhuman/scheduler_gate/policy.rs

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Align identifiers with the repo’s camelCase naming rule for this path.

This module introduces several snake_case variable/field names (on_ac_power, battery_charge, cpu_usage_pct, server_mode, env_on_ac, env_charge, no_battery) that conflict with the naming convention for src/openhuman/**/*.rs.

As per coding guidelines src/openhuman/**/*.rs: Use camelCase for variable names.

Also applies to: 26-33, 46-56, 130-151

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/openhuman/scheduler_gate/signals.rs` around lines 15 - 20, The fields and
related variables in signals.rs use snake_case but must follow camelCase for
this module; rename struct fields on_ac_power, battery_charge, cpu_usage_pct,
server_mode to onAcPower, batteryCharge, cpuUsagePct, serverMode (and the local
variables/env flags env_on_ac, env_charge, no_battery to envOnAc, envCharge,
noBattery), then update every usage, pattern match, constructor, method, impl,
test, and serialization/deserialization attribute that references those symbols
(e.g., the Signal struct, env_* locals, and any functions that read/write them)
so names are consistent; if external JSON/serde keys must remain snake_case, add
appropriate serde(rename = "...") attributes to the renamed fields.