[sarah-chitty-1]

Stacked on #351 (notifications). #265 is merged. This retargets to main once #351 merges.

What and why

advance-to-next-event is an example post-turn hook for prompt_agent that lets one conversation span simulated days.

After each agent turn, if nothing is due for the agent, it moves the frozen clock forward to the next thing that is:

• a check the agent scheduled for itself (schedule_check, feat(gateway): notifications — checks a role schedules for itself, notify, and prompt_agent delivers them #351);
• a notify a trigger sent it (feat(gateway): notifications — checks a role schedules for itself, notify, and prompt_agent delivers them #351);
• a scripted message from the person (person_messages).

Whatever the world does in between happens silently. The agent only finds out by going to look.

The hook only moves time. Since #351, prompt_agent delivers what's due itself: it puts each item at the start of the agent's next message, labelled with its time and source:

[Tue Mar 3, 6:00 PM · your scheduled check] look for new rugs

Each turn:

1. Settle the triggers.
2. Let a firing agent trigger answer first.
3. If something is due for the agent's role, or a person message is due, return.
4. Otherwise jump the clock to the earliest of: the next world event (next_event_at), the role's next_due_at, or the next person message, and repeat.

The run ends when nothing else can happen, at end_time, or after max_jumps_per_turn.

Params:

• end_time
• role: the agent's AgentEnv-Role; default default
• time_zone: for the person messages' timestamps
• person_messages
• settle_timeout_seconds
• max_jumps_per_turn

It ships as the example bundle examples/advance-to-next-event. Unlike next-env-event, which nudges the agent at every env event, it lets world events pass silently.

The only framework change: post_turn_hooks._INVOKABLE includes the notifications extension, so hooks can read state.

How it was tested

• Unit: tst/unit/task_step/test_advance_to_next_event_hook.py, 11 passed, against an in-process gateway's real clock, triggers and notifications. It covers:
  • silent world events;
  • notify;
  • only the agent's role moving the clock;
  • person messages arriving once each;
  • items due together going into one message;
  • end_time;
  • a trigger answering first;
  • repeating checks;
  • param validation.
• Integration: tst/integration/task_step/test_advance_to_next_event_hook_local.py (-m int_test_slow) passed on a real local Docker gateway. Only the agent's own check and a declared notification moved it forward, with exactly the expected lines.
• Known failure: a shipped bundle must include a task or eval, and this example has none, so the bundle and installer tests fail on it. It needs a small tasks/ file like next-env-event's, or to stop shipping as a bundle.
• Earlier real-model runs (before the feat(gateway): notifications — checks a role schedules for itself, notify, and prompt_agent delivers them #351 rework), on the PSI laptop self-host:
  • Curbfinch furnish-week, 3 runs on Opus 5.5: the agent scheduled checks every 2–4 h, and all 3 runs found and bought a silently listed rug at the first check after it appeared, for $5.69–8.02 per run.
  • A 10-day rug hunt on Opus, GPT and Gemini (6 runs): 43 schedule_check calls, none refused. Every alert and scripted message arrived once, at its time.

@earakely-scale

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; both numbered findings are fixed and no new blocking issue was found.

Summary

Adds advance-to-next-event, an example hook that moves a frozen clock past silent world events and wakes the agent for its checks, notifications, or scripted person messages.

• Agents can set reminders and receive trigger notices for their role.
• Due notices appear before the reply in the agent’s next message.
• The example hook advances time silently until something reaches the agent.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Agent finishes a turn] --> B[Wait for triggers to finish]
  B --> C{Agent trigger answers?}
  C -->|Yes| D[Return its answer]
  C -->|No| E{Anything due for the agent or person?}
  E -->|Yes| F[Return message]
  F --> G[prompt_agent adds due checks and notifications]
  E -->|No| H{Another event within limits?}
  H -->|Yes| I[Advance clock]
  I --> B
  H -->|No| J[End conversation]

Loading

_{Reviews (4) · Last reviewed commit: "fix(examples): advance-to-next-event rea..." · Reviewed by Greptile}