Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/agent_env/examples/advance-to-next-event/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ recorded as `triggers_still_firing`, if triggers are still running when `settle_
than treat unfinished work as nothing left to happen. Envs whose clock was never armed are left out.

Reference the hook from a `prompt_agent` step, after `sync_env_clock` (frozen: `virtual_seconds_per_real_second: 0`)
and `configure_scheduled_checks` (`"roles": ["default"]`). Delivered lines, the person's included, are labelled in UTC:
and `configure_scheduled_checks` (`"roles": ["default"]`). Delivered lines, the person's included, are labelled in
the world's time zone, the one `sync_env_clock` armed the clock in, and in UTC when it has none, as in this example:

```json
{"id": "week", "type": "prompt_agent", "prompt": "Keep an eye on curbfinch this week for an 8x10 rug.",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,10 @@ async def post_turn(turn, params):
answer = await turn.user_triggers()
if answer is not None:
return answer
t0 = min([_utc((await env.invoke(CLOCK, "state"))["t0"]) for env in envs])
states = [await env.invoke(CLOCK, "state") for env in envs]
t0 = min([_utc(state["t0"]) for state in states])
zones = {state.get("time_zone") for state in states} - {None}
zone = zones.pop() if len(zones) == 1 else "UTC" # as prompt_agent labels what it delivers
end = _end_instant(end_time, t0)
sent = _delivered_person(turn)
for jump in range(max_jumps + 1):
Expand All @@ -44,7 +47,7 @@ async def post_turn(turn, params):
turn.record({"woke_at": _iso(now), "for": due + ["person"] * len(due_person),
**({"person_at": [_iso(m["at"]) for m in due_person]} if due_person else {})})
# prompt_agent puts what came due on notifications/v1 ahead of this; [] sends only that
return {"message": _person_message(due_person) if due_person else []}
return {"message": _person_message(due_person, zone) if due_person else []}
if jump == max_jumps: # checked above: what the last jump made due still wakes the agent
return _end(turn, "max_jumps_per_turn", at=_iso(now))
nxt = await _next(envs, role, person, now, sent)
Expand Down Expand Up @@ -134,9 +137,9 @@ def _delivered_person(turn):
return sent


def _person_message(person):
"""One line per message, oldest first, each saying when it was written."""
return "\n".join(f"[{label_time(_iso(m['at']))}] {m['text']}" for m in person)
def _person_message(person, zone):
"""One line per message, oldest first, each saying when it was written, in the world's time zone."""
return "\n".join(f"[{label_time(_iso(m['at']), zone)}] {m['text']}" for m in person)


async def _advance(env, target):
Expand Down
18 changes: 11 additions & 7 deletions src/agent_env/task_step/task_steps/always_on.py
Original file line number Diff line number Diff line change
Expand Up @@ -1006,7 +1006,7 @@ async def _open(self) -> None:
opened_at = _utc(self.opening["at"])
await self._chat_user(self._opening_parts(lambda text: self._chat_part(opened_at, text, kind="opening")))
due = await take_due(self.notification_envs, self.recipient) if self.notification_envs else []
await self.wake([*delivered_parts(due),
await self.wake([*delivered_parts(due, self.zone),
*self._opening_parts(lambda text: self._user_part(opened_at, text, opening=True))],
woke_by=[f"notification:{d['channel']}" for d in due] + ["user_request"],
notifications=[{k: d.get(k) for k in ("at", "channel", "source", "source_id", "to")}
Expand Down Expand Up @@ -1144,7 +1144,7 @@ def _opening_parts(self, labelled) -> list[dict]:
def _user_part(self, at: datetime, text: str, opening: bool = False) -> dict:
first = self.person["first"]
body = re.sub(rf"^\s*{re.escape(first)}\s*:\s*", "", text)
return {"kind": "text", "text": f"[{label_time(_iso(at))}] {first}: {body}",
return {"kind": "text", "text": f"[{label_time(_iso(at), self.zone)}] {first}: {body}",
"metadata": {"agentenv": {"source": "user", "at": _iso(at), "opening": opening}}}

# ---- the graded conversation: the user's chat ----------------------------------------------------------------
Expand Down Expand Up @@ -1183,7 +1183,8 @@ async def _chat_end(self, now: datetime) -> None:
if self.reaction:
parts.append(_step_part(f"({first} {self.reaction['said']})", "user_reaction"))
parts[-1]["metadata"]["agentenv"].update(outcome=self.reaction["outcome"], at=self.reaction["at"])
parts.append({"kind": "text", "text": f"[End of run · {label_time(_iso(now))}] {self.end_note} (A note from "
when = label_time(_iso(now), self.zone)
parts.append({"kind": "text", "text": f"[End of run · {when}] {self.end_note} (A note from "
f"the run, not a message from {first}.)",
"metadata": {"agentenv": {"source": "end_marker", "end_reason": self.end_reason,
"at": _iso(now)}}})
Expand All @@ -1202,7 +1203,7 @@ async def _wake_with(self, now: datetime, lines: list[dict], replies: list[dict]
"""Wake the agent with what came due for it, then the user's lines and replies in time order, then ``notes``
(the step's own lines); ``last`` marks the run's last wake."""
due = await take_due(self.notification_envs, self.recipient) if self.notification_envs else []
parts = delivered_parts(due)
parts = delivered_parts(due, self.zone)
user_msgs = sorted([{"at": l["at"] or _iso(now), "text": l["text"], "kind": l.get("source", "user_says"),
"trigger_id": l.get("trigger_id")} for l in lines]
+ [{"at": _iso(r["deliver_at"]), "text": r["text"], "kind": "user_reply",
Expand Down Expand Up @@ -1449,7 +1450,7 @@ def _sent(self, messages: list[dict], after_nudge: bool = False, leftover: bool
sent = {"at": m.get("at"), "text": m["text"], "wake": self.wakes}
self.unread.append(sent)
self.all_messages.append(sent)
self.chat_pending.append({"kind": "text", "text": f"[{label_time(m.get('at'))}] {m['text']}",
self.chat_pending.append({"kind": "text", "text": f"[{label_time(m.get('at'), self.zone)}] {m['text']}",
"metadata": {"agentenv": {"source": "message_user", "at": m.get("at"),
"wake": self.wakes}}})

Expand Down Expand Up @@ -1701,7 +1702,8 @@ async def finish(self) -> None:
ctx.metadata.setdefault(ALWAYS_ON_KEY, {})[step.id] = record
# The graded response is the user's whole chat from the agent, each message with its pretend time; never its
# closing text, which she never saw.
self._append_prompt_response("\n\n".join(f"[{label_time(m.get('at'))}] {m['text']}" for m in self.all_messages))
self._append_prompt_response("\n\n".join(f"[{label_time(m.get('at'), self.zone)}] {m['text']}"
for m in self.all_messages))

async def _store_timeline(self, record: dict) -> None:
"""Store the run's full record, its timeline included, and give ``record`` (what stays in the run's metadata,
Expand Down Expand Up @@ -1784,14 +1786,16 @@ def render_for_judge(record: dict) -> str:
"with no known actor (made outside the env's gateway, such as on a website reached directly), each with "
"when it was seen. The user saw only the messages the assistant sent."]
wakes = [e for e in timeline if e["event"] == "wake"]
zone = (record.get("time_zone") or next((e.get("time_zone") for e in timeline if e["event"] == "start"), None)
or "UTC") # the record's own, since a tail kept when the store failed may have lost the start
for wake in wakes[:JUDGE_WAKES]:
n = wake["n"]
turn = turns.get(n) or {}
sent = (turn.get("messages_to_user") or 0) + (nudges.get(n, {}).get("messages_to_user") or 0)
calls = f" · {turn['tool_calls']} tool calls" if turn.get("tool_calls") is not None else ""
state = f" · its turn {turn['state']}" if turn.get("state") not in (None, "completed", "TaskState.completed") \
else ""
lines.append(f"- Wake {n} · {label_time(wake.get('virtual_time'))} · woken by "
lines.append(f"- Wake {n} · {label_time(wake.get('virtual_time'), zone)} · woken by "
f"{woke_by_text(wake.get('woke_by'))} · sent the user {sent} message{'s' if sent != 1 else ''}"
f"{calls}{state}")
made = changes.get(n, [])
Expand Down
33 changes: 24 additions & 9 deletions src/agent_env/task_step/task_steps/notification_delivery.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@
[Mon Feb 1, 3:00 PM UTC · your scheduled check] See if Dana replied about the 2BR on Alder St
[Mon Feb 1, 3:10 PM UTC · Curbfinch alert] New listing: 2BR on Ivy St, $3,050/mo

Times are in UTC, and say so, like everything else the agent reads about time (``get_time``, ``schedule_check``).
Times are in the task's time zone and name it (``MST``, ``CET``), so they read as the person and the computer's screen
read them; UTC when the task has none. ``get_time`` answers in a zone too, and ``schedule_check`` takes any offset.

Each delivered part carries ``metadata.agentenv``, the item without its parts (``source`` and ``source_id`` among
them), so a verifier reading the stored conversation can tell a delivered line from what the person wrote in the same
Expand All @@ -31,6 +32,7 @@
import uuid
from datetime import datetime, timezone
from typing import Any, Iterable, Optional
from zoneinfo import ZoneInfo

from agent_env.env.gateway.constants import EXT_NOTIFICATIONS_URI

Expand All @@ -39,31 +41,44 @@
_EARLIEST = datetime.min.replace(tzinfo=timezone.utc)


def label_time(at: Optional[str]) -> str:
"""'Mon Feb 1, 3:00 PM UTC'; 'now' for an item with no time (queued while the env clock was unset)."""
def label_time(at: Optional[str], zone: str = "UTC") -> str:
"""'Fri Feb 5, 5:30 PM MST' in the IANA ``zone`` ('Mon Feb 1, 3:00 PM UTC' by default), a zone with no
abbreviation named by its offset ('UTC-03'); 'now' for an item with no time (queued while the env clock was
unset)."""
if not at:
return "now"
at = _utc(at)
return f"{at.strftime('%a %b')} {at.day}, {at.strftime('%I:%M %p').lstrip('0')} UTC"
at = _utc(at).astimezone(ZoneInfo(zone))
name = at.strftime("%Z")
name = f"UTC{name}" if name[:1] in "+-" else name
return f"{at.strftime('%a %b')} {at.day}, {at.strftime('%I:%M %p').lstrip('0')} {name}"


def delivered_line(item: dict) -> str:
def labels_zone(clocks: list[dict]) -> str:
"""The zone lines are labelled in when no user names one: the one sync_env_clock gave the world, by each env's
latest arm, else UTC, as it is when the world has several. A rate change (set_env_clock_rate's entry, which has
no ``env_get_time_url``) keeps the zone its env was armed in."""
latest = {c.get("env_id"): c.get("timezone") for c in clocks if "env_get_time_url" in c}
zones = {zone for zone in latest.values() if zone}
return zones.pop() if len(zones) == 1 else "UTC"


def delivered_line(item: dict, zone: str = "UTC") -> str:
"""A taken item's text as the agent reads it: ``[when · channel]``, then its text parts."""
when = label_time(item.get("at"))
when = label_time(item.get("at"), zone)
times = item.get("times", 1)
again = f" (it came due {times} times while you were away)" if times > 1 else ""
text = "\n\n".join(p["text"] for p in item["parts"] if p.get("kind") == "text")
return f"[{when} · {item['channel']}] {text}{again}"


def delivered_parts(items: Iterable[dict]) -> list[dict]:
def delivered_parts(items: Iterable[dict], zone: str = "UTC") -> list[dict]:
"""Per taken item, oldest first: one text part, its ``delivered_line``, then any parts that aren't text, as they
are. Each carries ``metadata.agentenv``: the item without its parts, with the ``env_id`` it came from when the
item has one."""
parts = []
for item in sorted(items, key=_oldest_first):
meta = {"agentenv": {k: v for k, v in item.items() if k != "parts"}}
parts.append({"kind": "text", "text": delivered_line(item), "metadata": meta})
parts.append({"kind": "text", "text": delivered_line(item, zone), "metadata": meta})
parts.extend({**p, "metadata": meta} for p in item["parts"] if p.get("kind") != "text")
return parts

Expand Down
5 changes: 3 additions & 2 deletions src/agent_env/task_step/task_steps/prompt_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
from agent_env.entity.refs import EntityRef
from agent_env.entity.scopes import FieldScope
from agent_env.task_step.task_step import RetryConfig, TaskStep, TaskStepDependency
from agent_env.task_step.task_steps.notification_delivery import delivered_parts, next_message, take_due
from agent_env.task_step.task_steps.notification_delivery import delivered_parts, labels_zone, next_message, take_due
from agent_env.task_step.task_steps.post_turn_hooks import PostTurnHooks, run_post_turn_hooks, validate_hook_specs
from agent_env.task_step.task_steps.agent import user_sim_versions
from agent_env.task_step.task_steps.agent.user_sim_common import iso, person_of, task_zone, utc
Expand Down Expand Up @@ -614,6 +614,7 @@ async def _converse(
# What comes due for the agent's role on these envs (notifications/v1) opens its next message.
notification_envs = [d for d in context.deployed_envs if d.supports(EXT_NOTIFICATIONS_URI, "take")]
recipient = agent.role or DEFAULT_ROLE
zone = built_in[1] if built_in else labels_zone(context.metadata.get("clock_configurations") or [])
final_terminal = protocol.TerminalResponse(response_text="")
# Each turn's terminal reports only that turn's tool calls, so the conversation's count is
# their sum. None until a turn reports one, so agents that don't report it stay None.
Expand Down Expand Up @@ -752,7 +753,7 @@ def record_turn() -> None:
# The conversation goes on: what came due for the agent goes first, the user side's reply after it.
# An answer that ended it, or the last turn, takes nothing, so what is due stays queued on the env.
due = await take_due(notification_envs, recipient) if notification_envs else []
current_user_parts = next_message(delivered_parts(due), answer["message"])
current_user_parts = next_message(delivered_parts(due, zone), answer["message"])
end_after = answer.get("end_after")
if not current_user_parts: # a hook said nothing ([]) and nothing came due
logger.info(f"Turn {turn+1}: nothing to send the agent; ending multi-turn (nothing_to_send)")
Expand Down
8 changes: 8 additions & 0 deletions tst/unit/task_step/test_advance_to_next_event_hook.py
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,14 @@ async def test_the_person_s_messages_arrive_at_their_times_once_each(hook, gatew
{"end": "nothing_can_wake_the_agent"}]


@pytest.mark.asyncio
async def test_the_person_s_messages_are_labelled_in_the_zone_the_clock_was_armed_in(hook, gateway):
gateway._clock.set_time(MONDAY, rate=0, time_zone="America/Chicago")
params = {"person_messages": [{"at": "2026-03-03T15:00:00Z", "text": "I'm up"}]}
sent = await _turns(hook, _context(), params=params)
assert sent == [["[Tue Mar 3, 9:00 AM CST] I'm up"], {"end": "nothing_can_wake_the_agent"}]


@pytest.mark.asyncio
async def test_another_conversation_delivering_a_message_at_the_same_time_does_not_skip_this_one(hook, gateway):
context = _context()
Expand Down
12 changes: 9 additions & 3 deletions tst/unit/task_step/test_always_on_agent_verifier.py
Original file line number Diff line number Diff line change
Expand Up @@ -76,13 +76,13 @@ async def test_the_judge_grades_from_the_chat_and_the_run_wake_by_wake_not_the_t
await verifier.execute(ctx)

prompt = captured["prompt"]
assert "[Mon Nov 9, 2:00 PM UTC] Casa Jacarandas is $855. Book it?" in prompt and "PRIVATE" not in prompt
assert "[Mon Nov 9, 9:00 AM EST] Casa Jacarandas is $855. Book it?" in prompt and "PRIVATE" not in prompt
conversation = prompt[prompt.index("## Conversation"):prompt.index("## Trigger firings")]
assert "Linda: yes please" in conversation and "[End of run" in conversation
wakes = prompt[prompt.index("## The run, wake by wake"):]
assert "- Wake 2 · Mon Nov 9, 2:00 PM UTC · woken by the user's reply · sent the user 1 message" in wakes
assert "- Wake 2 · Mon Nov 9, 9:00 AM EST · woken by the user's reply · sent the user 1 message" in wakes
assert " - it changed: INSERT public.bookings row 1 (request 855 USD)" in wakes
assert "- Wake 3 · Tue Nov 10, 2:00 PM UTC · woken by an alert (noor 30)" in wakes
assert "- Wake 3 · Tue Nov 10, 9:00 AM EST · woken by an alert (noor 30)" in wakes
assert "## How the run ended\nNothing could wake the assistant again, and nothing was pending." in wakes
assert ctx.metadata["verifications"]["rubric"]["score"] == 1
assert verifier.to_dict() == stored # the step, shared by concurrent rollouts, is untouched
Expand Down Expand Up @@ -140,6 +140,12 @@ async def test_a_prompt_no_always_on_step_made_is_refused_when_it_is_graded(monk
await verifier.execute(ctx)


def test_the_wake_by_wake_text_is_in_the_run_s_zone_though_its_kept_tail_lost_the_start():
record = {"time_zone": "America/Denver", "timeline_tail": [
{"event": "wake", "n": 30, "virtual_time": "2027-02-06T00:30:00Z", "woke_by": ["user_reply"]}]}
assert "- Wake 30 · Fri Feb 5, 5:30 PM MST · woken by" in ao.render_for_judge(record)


def test_the_wake_by_wake_text_says_when_the_record_is_unreadable():
text = ao.render_for_judge({"object_url": "file:///nowhere/at/all.json", "end_reason": "end_time"})
assert text.startswith("## The run, wake by wake\n(The run's record could not be read:")
Expand Down
2 changes: 1 addition & 1 deletion tst/unit/task_step/test_always_on_budget.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ def agent(n, texts, rig):
assert reached["real_seconds"] == 10800
assert record["end_reason"] == "time_budget" and record["error_type"] is None
assert rig.events(ctx, "user_sim_read")[-1]["last_read"] is True
assert rig.chat(ctx)[-1]["texts"][-1].startswith("[End of run · Wed Nov 11, 2:00 PM UTC] The run was cut off by "
assert rig.chat(ctx)[-1]["texts"][-1].startswith("[End of run · Wed Nov 11, 9:00 AM EST] The run was cut off by "
"its real-time budget.")


Expand Down
2 changes: 1 addition & 1 deletion tst/unit/task_step/test_always_on_checks.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ def agent(n, texts, rig):

wake = rig.events(ctx, "wake")[1]
assert wake["virtual_time"] == "2026-11-12T14:00:00Z" and wake["woke_by"] == ["notification:your scheduled check"]
assert "[Thu Nov 12, 2:00 PM UTC · your scheduled check] book La Ola, it opens at 9" in rig.sent[1]
assert "[Thu Nov 12, 9:00 AM EST · your scheduled check] book La Ola, it opens at 9" in rig.sent[1]


@pytest.mark.parametrize("end_time,setting,on", [(None, None, False), ("PT6H", None, False), ("P5D", False, False),
Expand Down
2 changes: 1 addition & 1 deletion tst/unit/task_step/test_always_on_clock_rate.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ async def test_a_slow_contact_reply_between_turns_doesn_t_move_the_clock(monkeyp
ctx = await rig.run(rig.step(settle_timeout_seconds=0.2))

[_, alerted] = rig.events(ctx, "wake")
assert "[Mon Nov 9, 3:00 PM UTC · Gmail · Live Oak Arbor]" in alerted["parts_text"]
assert "[Mon Nov 9, 10:00 AM EST · Gmail · Live Oak Arbor]" in alerted["parts_text"]
assert alerted["virtual_time"].startswith("2026-11-09T15:00:00")
assert rig.record(ctx)["settings"]["clock"] == {"envs": [{"env_id": "world", "rate": RATE,
"frozen_between_turns": True}]}
Expand Down
4 changes: 2 additions & 2 deletions tst/unit/task_step/test_always_on_endings.py
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ async def test_a_task_s_final_line_is_hers_and_comes_with_the_notice(monkeypatch
await rig.run(rig.step(end_time="P2D", final="send me the rundown"))

texts = rig.sent[-1]
assert "[Wed Nov 11, 2:00 PM UTC] Linda: send me the rundown" in texts and DEFAULT_FINAL not in texts
assert "[Wed Nov 11, 9:00 AM EST] Linda: send me the rundown" in texts and DEFAULT_FINAL not in texts
assert texts[-1] == NOTICE and ao.WAKE_REMINDER_TEXT not in texts
assert [s["text"] for s in rig.reads[-1]["you_sent"]] == ["sort the cdmx weekend", "send me the rundown"]

Expand Down Expand Up @@ -321,7 +321,7 @@ def agent(n, texts, rig):
ctx = await rig.run(rig.step())

[response] = ctx.prompt_responses
assert response.response == "[Mon Nov 9, 2:00 PM UTC] found it: the blue house, $855"
assert response.response == "[Mon Nov 9, 9:00 AM EST] found it: the blue house, $855"
assert response.error_type == "agent_turn_timeout"
[sent] = rig.events(ctx, "message_to_user")
assert sent["leftover"] is True
Expand Down
Loading
Loading