Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(scheduling): add adaptive sleep-hint seam to the kernel

shadowinlifedfdd5b0cfbef
diff --git a/agent/src/scheduling/kernel.py b/agent/src/scheduling/kernel.py
index e46bcda5e..661c1901b 100644
--- a/agent/src/scheduling/kernel.py
+++ b/agent/src/scheduling/kernel.py
@@ -14,7 +14,10 @@ Responsibilities (the complete list):
with a ``task.cancel()`` fallback so shutdown never waits a full tick;
* :meth:`SchedulerKernel._run` / :meth:`SchedulerKernel._sleep_or_wake` —
the tick loop with per-tick exception isolation and an ``asyncio.Event``
- wakeup that shortens the inter-tick sleep;
+ wakeup that shortens the inter-tick sleep; the sleep is the fixed
+ ``tick_interval_ms`` unless a consumer-provided ``sleep_hint_fn`` replaces
+ it with an adaptive "next deadline" hint (the seam the live runtime
+ scheduler's ``min(next_due - now, max_recheck)`` sleep adopts);
* :meth:`SchedulerKernel.request_wake` — thread-safe, coalescing request to
cut the current sleep short;
* :meth:`SchedulerKernel.retry_delay_ms` — bounded exponential backoff;
@@ -39,7 +42,7 @@ import logging
import time
from typing import Optional
-from src.scheduling.types import NowFn, OnTickFn
+from src.scheduling.types import NowFn, OnTickFn, SleepHintFn
logger = logging.getLogger(__name__)
@@ -68,8 +71,10 @@ class SchedulerKernel:
The loop calls ``on_tick(now_ms)`` once per tick, isolates its exceptions
(one failing tick never kills the loop; ``asyncio.CancelledError``
- propagates so :meth:`stop` stays bounded), then sleeps
- ``tick_interval_ms`` unless a :meth:`request_wake` shortens the sleep.
+ propagates so :meth:`stop` stays bounded), then sleeps — the fixed
+ ``tick_interval_ms``, or when ``sleep_hint_fn`` is injected, the hint it
+ returns for the post-tick clock — unless a :meth:`request_wake` shortens
+ the sleep.
Due-ness, next-run advancement and per-job error recording are the
consumer's own ``on_tick`` composition — the kernel stores the retry
@@ -87,11 +92,13 @@ class SchedulerKernel:
retry_max_delay_ms: int = DEFAULT_RETRY_MAX_DELAY_MS,
on_tick: Optional[OnTickFn] = None,
task_name: str = DEFAULT_TASK_NAME,
+ sleep_hint_fn: Optional[SleepHintFn] = None,
) -> None:
"""Initialize the kernel.
Args:
- tick_interval_ms: Poll interval for the background loop.
+ tick_interval_ms: Poll interval for the background loop. Also the
+ fallback sleep when ``sleep_hint_fn`` is set but raises.
now_fn: Injectable wall-clock source returning epoch milliseconds.
enabled: When false, :meth:`start` and :meth:`stop` are no-ops.
max_consecutive_failures: Failures allowed before a consumer
@@ -101,6 +108,12 @@ class SchedulerKernel:
retry_max_delay_ms: Upper bound for exponential retry backoff.
on_tick: Async callable invoked once per tick with ``now_ms``.
task_name: Name of the background ``asyncio`` task.
+ sleep_hint_fn: Optional consumer-provided "next deadline" sleep
+ hint. Called after each tick with a freshly read ``now_ms``;
+ its return value (clamped non-negative) replaces
+ ``tick_interval_ms`` as the inter-tick sleep, letting an
+ adaptive-sleep consumer keep its sleep shape. A hint that
+ raises is logged and falls back to ``tick_interval_ms``.
Raises:
ValueError: If the retry policy is invalid.
@@ -119,6 +132,7 @@ class SchedulerKernel:
self._retry_max_delay_ms = retry_max_delay_ms
self._on_tick = on_tick
self._task_name = task_name
+ self._sleep_hint_fn = sleep_hint_fn
self._loop: asyncio.AbstractEventLoop | None = None
self._task: asyncio.Task | None = None
self._wakeup: asyncio.Event | None = None
@@ -161,6 +175,11 @@ class SchedulerKernel:
"""Return the injected per-tick callback (the only one the loop calls)."""
return self._on_tick
+ @property
+ def sleep_hint_fn(self) -> Optional[SleepHintFn]:
+ """Return the injected adaptive-sleep hint, or ``None`` for fixed-tick."""
+ return self._sleep_hint_fn
+
# -- lifecycle ------------------------------------------------------------
@property
@@ -168,6 +187,15 @@ class SchedulerKernel:
"""Return whether the background loop task is active."""
return self._task is not None and not self._task.done()
+ @property
+ def task(self) -> asyncio.Task | None:
+ """Return the background loop task, or ``None`` when not started.
+
+ Read-only handle for owners that must await or inspect the loop task
+ itself (e.g. a driver coroutine parking on the scheduler's lifetime).
+ """
+ return self._task
+
def start(self) -> None:
"""Start the background loop.
@@ -224,7 +252,23 @@ class SchedulerKernel:
logger.error("scheduler kernel tick failed", exc_info=True)
if self._stopping:
break
- await self._sleep_or_wake(self._tick_interval_ms)
+ await self._sleep_or_wake(self._next_sleep_ms())
+
+ def _next_sleep_ms(self) -> int:
+ """Return the inter-tick sleep: the consumer's hint, or the fixed tick.
+
+ The hint is read against a freshly sampled clock (post-tick), so an
+ adaptive consumer computes its deadline against the same "now" shape
+ its own loop would have. A raising hint is logged and demoted to the
+ fixed tick — a buggy hint slows the loop down but never kills it.
+ """
+ if self._sleep_hint_fn is None:
+ return self._tick_interval_ms
+ try:
+ return max(0, self._sleep_hint_fn(self._now_fn()))
+ except Exception:
+ logger.error("scheduler kernel sleep hint failed; using fixed tick", exc_info=True)
+ return self._tick_interval_ms
async def _sleep_or_wake(self, sleep_ms: int) -> None:
wakeup = self._wakeup
diff --git a/agent/src/scheduling/types.py b/agent/src/scheduling/types.py
index 22e36cc0f..2fad19e20 100644
--- a/agent/src/scheduling/types.py
+++ b/agent/src/scheduling/types.py
@@ -44,3 +44,15 @@ NowFn = Callable[[], int]
#: kernel isolates exceptions per tick (one failing tick never kills the
#: loop); ``asyncio.CancelledError`` propagates so ``stop()`` stays bounded.
OnTickFn = Callable[[int], Awaitable[None]]
+
+#: Consumer-provided "next deadline" sleep hint, in epoch-ms and duration-ms.
+#: Called by the kernel after each tick with a freshly read ``now_ms``; the
+#: return value replaces the fixed ``tick_interval_ms`` as the inter-tick
+#: sleep (clamped to be non-negative). This is the seam that lets an
+#: adaptive-sleep consumer — one that sleeps until the earliest job deadline
+#: rather than polling on a fixed cadence — adopt the kernel without giving
+#: up its sleep shape. The kernel never interprets the number: bounding the
+#: sleep (e.g. a max re-check cap) is the consumer's own composition. A hint
+#: that raises is logged and falls back to ``tick_interval_ms`` so a buggy
+#: hint cannot kill the loop.
+SleepHintFn = Callable[[int], int]
diff --git a/agent/tests/scheduling/test_kernel_sleep_hint.py b/agent/tests/scheduling/test_kernel_sleep_hint.py
new file mode 100644
index 000000000..2ebe36d1c
--- /dev/null
+++ b/agent/tests/scheduling/test_kernel_sleep_hint.py
@@ -0,0 +1,180 @@
+"""Tests for the kernel's adaptive-sleep extension (``sleep_hint_fn``) and the
+read-only ``task`` property — the seam the live runtime scheduler adopts in
+step 2 of the scheduler unification.
+
+House style (see test_kernel.py): async scenarios are driven with
+``asyncio.run`` — no pytest-asyncio in this repo — with an injected ``now_fn``
+instead of the wall clock, ``asyncio.sleep(0)`` yield loops or
+``asyncio.Event`` handshakes instead of real waiting, and
+``asyncio.wait_for`` timeouts so a wedged kernel fails the test instead of
+hanging the suite.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import itertools
+
+import pytest
+
+from src.scheduling.kernel import SchedulerKernel
+
+
+def test_sleep_hint_replaces_the_fixed_tick() -> None:
+ """A 60s fixed tick would never reach the second tick inside the timeout;
+ the hint shortens the inter-tick sleep to 1ms."""
+ ticks: list[int] = []
+
+ async def scenario() -> None:
+ second = asyncio.Event()
+
+ async def on_tick(now_ms: int) -> None:
+ ticks.append(now_ms)
+ if len(ticks) >= 2:
+ second.set()
+
+ kernel = SchedulerKernel(
+ tick_interval_ms=60_000,
+ now_fn=lambda: 1000,
+ on_tick=on_tick,
+ sleep_hint_fn=lambda now_ms: 1,
+ )
+ kernel.start()
+ await asyncio.wait_for(second.wait(), timeout=2.0)
+ await asyncio.wait_for(kernel.stop(), timeout=5.0)
+
+ asyncio.run(scenario())
+
+ assert len(ticks) >= 2
+
+
+def test_sleep_hint_receives_a_fresh_post_tick_now() -> None:
+ """The hint is sampled against a freshly read clock, after the tick."""
+ clock = itertools.count(1000, 1000)
+ tick_nows: list[int] = []
+ hint_nows: list[int] = []
+
+ async def scenario() -> None:
+ second = asyncio.Event()
+
+ async def on_tick(now_ms: int) -> None:
+ tick_nows.append(now_ms)
+ if len(tick_nows) >= 2:
+ second.set()
+
+ def hint(now_ms: int) -> int:
+ hint_nows.append(now_ms)
+ return 1
+
+ kernel = SchedulerKernel(
+ tick_interval_ms=60_000, now_fn=lambda: next(clock), on_tick=on_tick, sleep_hint_fn=hint
+ )
+ kernel.start()
+ await asyncio.wait_for(second.wait(), timeout=2.0)
+ await asyncio.wait_for(kernel.stop(), timeout=5.0)
+
+ asyncio.run(scenario())
+
+ assert tick_nows[:2] == [1000, 3000]
+ assert hint_nows[0] == 2000
+
+
+def test_negative_sleep_hint_is_clamped_to_zero() -> None:
+ kernel = SchedulerKernel(sleep_hint_fn=lambda now_ms: -5)
+ assert kernel._next_sleep_ms() == 0
+
+
+def test_next_sleep_ms_without_a_hint_is_the_fixed_tick() -> None:
+ kernel = SchedulerKernel(tick_interval_ms=4321)
+ assert kernel.sleep_hint_fn is None
+ assert kernel._next_sleep_ms() == 4321
+
+
+def test_raising_sleep_hint_falls_back_to_the_fixed_tick() -> None:
+ def bad_hint(now_ms: int) -> int:
+ raise RuntimeError("boom")
+
+ kernel = SchedulerKernel(tick_interval_ms=999, sleep_hint_fn=bad_hint)
+ assert kernel._next_sleep_ms() == 999
+
+
+def test_raising_sleep_hint_does_not_kill_the_loop() -> None:
+ ticks: list[int] = []
+
+ async def scenario() -> None:
+ third = asyncio.Event()
+
+ async def on_tick(now_ms: int) -> None:
+ ticks.append(now_ms)
+ if len(ticks) >= 3:
+ third.set()
+
+ def bad_hint(now_ms: int) -> int:
+ raise RuntimeError("boom")
+
+ kernel = SchedulerKernel(tick_interval_ms=1, on_tick=on_tick, sleep_hint_fn=bad_hint)
+ kernel.start()
+ await asyncio.wait_for(third.wait(), timeout=5.0)
+ assert kernel.is_running
+ await asyncio.wait_for(kernel.stop(), timeout=5.0)
+
+ asyncio.run(scenario())
+
+ assert len(ticks) >= 3
+
+
+def test_sleep_hint_fn_is_exposed_read_only() -> None:
+ def hint(now_ms: int) -> int:
+ return 7
+
+ kernel = SchedulerKernel(sleep_hint_fn=hint)
+ assert kernel.sleep_hint_fn is hint
+ with pytest.raises(AttributeError):
+ kernel.sleep_hint_fn = None # read-only property
+
+
+def test_task_property_tracks_the_loop_lifecycle() -> None:
+ async def scenario() -> None:
+ kernel = SchedulerKernel(tick_interval_ms=60_000)
+ assert kernel.task is None
+ kernel.start()
+ assert kernel.task is not None
+ assert not kernel.task.done()
+ await asyncio.wait_for(kernel.stop(), timeout=5.0)
+ assert kernel.task is None
+
+ asyncio.run(scenario())
+
+
+def test_wakeup_still_shortens_a_hinted_sleep() -> None:
+ """request_wake cuts a long hinted sleep short — the hint does not
+ disarm the wakeup path."""
+ ticks: list[int] = []
+
+ async def scenario() -> None:
+ second = asyncio.Event()
+
+ async def on_tick(now_ms: int) -> None:
+ ticks.append(now_ms)
+ if len(ticks) >= 2:
+ second.set()
+
+ kernel = SchedulerKernel(
+ tick_interval_ms=60_000,
+ now_fn=lambda: 1000,
+ on_tick=on_tick,
+ sleep_hint_fn=lambda now_ms: 60_000,
+ )
+ kernel.start()
+ for _ in range(1000):
+ await asyncio.sleep(0)
+ if ticks:
+ break
+ assert ticks, "first tick did not run"
+ kernel.request_wake()
+ await asyncio.wait_for(second.wait(), timeout=2.0)
+ await asyncio.wait_for(kernel.stop(), timeout=5.0)
+
+ asyncio.run(scenario())
+
+ assert len(ticks) >= 2