[sarah-chitty-1]

Stacked on #351 (wakeups); #265 is merged. The diff is only this PR's hook. It'll retarget to main once #351 merges.

What and why

This is a post-turn hook for prompt_agent that runs one conversation over simulated days. It wakes the agent only for what would really reach it:

1. a check the agent scheduled for itself (schedule_check, feat(gateway): wakeups — checks an agent schedules for itself, and notify_agent #351)
2. a notification a trigger sent it (notify_agent, feat(gateway): wakeups — checks an agent schedules for itself, and notify_agent #351)
3. a message the person writes at a set time (person_messages)

Everything else the world does happens silently while the agent is away. The agent finds it only if it goes and looks. Each wake line names its time and source, so nothing poses as the person:

[Tue Mar 3, 6:00 PM · your scheduled check] look for new rugs
[Wed Mar 4, 8:00 AM · Messages] Jamie: did the rug thing get sorted?

How each turn goes:

• Settle the triggers.
• Let a firing agent trigger answer first.
• Otherwise, take what's due. If nothing is due, jump the frozen clock to the earliest of: the next world event (next_event_at), the next scheduled check, or the next person message. Repeat.
• The run ends when nothing can wake the agent, at end_time, or after max_jumps_per_turn.

It's shipped as an example bundle (examples/agent-wakeups). The only framework change: post_turn_hooks._INVOKABLE now includes the wakeups extension, so hooks can call take and state.

How it was tested

• tst/unit/task_step/test_agent_wakeups_hook.py: 8 passed, run against an in-process gateway's real clock, triggers and wakeups. It covers:
  • a silent world event
  • a notify_agent wake
  • person messages arriving once each
  • items due together going into one message
  • end_time
  • a trigger answering before any jump
  • repeating checks
  • param validation
• tst/integration/task_step/test_agent_wakeups_hook_local.py (-m int_test_slow) passed in 114 s on a real local Docker gateway. The world event landed silently, and only the agent's own check and a declared notification woke it, with exactly the expected lines.
• Real-model runs: Curbfinch furnish-week on the PSI laptop self-host, three runs on Opus 5.5 at d4847a8. The clock was frozen and jumped by this hook. The rug listing was silent, and seller replies were sent with notify_agent ("Curbfinch message").
  • On turn 1 of every run, the agent called schedule_check for every 2–4 h, overnight too. It rescheduled as things changed and cancelled its checks when it was done.
  • Seller notifications woke it only on evenings with real replies. Quiet evenings caused no wake.
  • All 3 runs found and bought the silently listed $360 rug at the first check after it appeared, for $320, $310 and $300.
  • Runs 2 and 3 ended with nothing_can_wake_the_agent on Friday evening. Run 1 hit a 15-turn cap.
  • Cost per run: $5.69, $6.26 and $8.02.
  • The site read the jumped gateway clock on every call, with no re-sync needed.
• Stress test: 6 runs on Opus, GPT and Gemini, 2 each, over a 10-day Curbfinch rug hunt with a decoy listing and a day-3 change of plan.
  • 43 schedule_check calls, none refused. They used relative and absolute times, until both as an instant and as a duration, and hourly repeats. Cancelling and rescheduling worked.
  • Every alert arrived.
  • The scripted person message arrived once, at its time.
  • The step and jump limit was never hit.
  • Every run that wasn't stopped by its cost cap ended with the right reason.
  • No wakeups bugs were found. Cost was driven by the harness resending the whole 10-day transcript on every call, not by the wakeups code.

@earakely-scale

🤖 Generated with Claude Code