[sarah-chitty-1]

What and why

In a multi-day task the agent needs a realistic way to come back later. Today it only hears from the world when the user sim writes, or when a hook wakes it for every world event. Real assistants don't work like that: they set their own reminders, and they get pushed only through real channels (a saved-search alert, a text).

This adds the gateway side of that, opt-in per task:

• urn:agentenv:wakeups/v1 (env/gateway/wakeups.py): once a task turns it on, the agent gets three gateway tools: schedule_check(note, at | every, until), list_scheduled_checks and cancel_scheduled_check. They run on the env's virtual clock. Caps: at most 10 active checks, and repeats no shorter than 1 hour; both are configurable.
• notify_agent trigger action: a designer-declared notification on a named channel ({"type": "notify_agent", "channel": "Curbfinch alert", "text": "..."}). It's queued for the agent, not sent as the user. Only the text length is logged.
• Routes /wakeups/config|state|take|clear. A harness or post-turn hook reads what's due through take. state exposes next_check_at, so a runner can jump the clock to it.
• configure_wakeups task step: turns the wakeups on for one env. It goes after sync_env_clock and before prompt_agent.
• register_env_triggers refuses notify_agent on a gateway that lacks the feature.

Nothing changes for tasks that don't use it. The tools exist only after configure_wakeups. The extension is added last on the card, and the new trigger action is opt-in. /wakeups/config returns 409 if a backing server already serves a tool with one of these names.

The design and the decisions behind it are in Linear FD-4433. The post-turn hook that wakes the agent is in a follow-up PR stacked on #265.

How it was tested

• PYTHONPATH=src:packages/agentenv-protocol/src python -m pytest tst/unit/env/gateway/wakeups_test.py tst/unit/task_step/test_configure_wakeups.py tst/unit/task_step/test_register_env_triggers.py tst/unit/env/gateway/gateway_card_test.py: 118 passed.
• Full unit suite compared with clean main in the same venv: no new failures. The pre-existing ones are the optional extras: openenv, drivers, mcp_cli_builder.
• An end-to-end run on a real local gateway is in the follow-up PR (test_agent_wakeups_hook_local.py).
• Before building, a model probe (18 runs across Opus, GPT and Gemini) checked that models use schedule_check sensibly. They scheduled every 3–24 h, never ran away, and never mistook a labelled notification for the person.

@earakely-scale

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no actionable issues remain.

Summary

Adds opt-in scheduled checks and trigger notifications on the gateway’s virtual clock.

• Agents can schedule checks that arrive when their virtual time is due.
• Trigger rules can queue labelled messages for the agent.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Task[configure_wakeups] --> Config[Enable check tools]
  Agent[Agent] --> Schedule[schedule_check]
  Config --> Schedule
  Schedule --> Queue[Wakeups]
  Trigger[notify_agent trigger] --> Queue
  Clock[Virtual clock] --> Queue
  Queue --> State[wakeups/state]
  Queue --> Take[wakeups/take]
  State --> Runner[Runner or hook]
  Runner --> Take
  Take --> Message[Due checks and notifications]

Loading

_{Reviews (6) · Last reviewed commit: "Merge branch 'main' of github.com:scalea..." · Reviewed by Greptile}