Context
With the rollout of the Phase 3 Wake Substrate, agents now receive [WAKE] events injected into their harnesses when A2A messages (SENT_TO_ME) or task state changes occur. The [WAKE] message typically includes a count (e.g., "1 new message").
The Problem
If multiple wake events queue up in the harness (because the agent was busy processing a previous turn), treating the wake text as exhaustive inbox state breaks idempotency. The agent might receive three separate [WAKE] inputs sequentially, when in reality there is only one message that needs processing (or three messages that were all processed on the first wake). This leads to redundant processing loops or "phantom wakes".
The Architectural Reality
Wake injection acts as a hardware interrupt—it signals "something happened, wake up and check." It is NOT the canonical state. The inbox (list_messages) is the canonical state. Furthermore, a mark_read protocol is necessary to close the loop, but executing mark_read immediately upon reading breaks future-session inbox visibility (if an agent wants to find a thread to hand off). Therefore, we adopted Option B: "Explicit-at-session-sunset only".
The Fix
Codify the "A2A Interrupt vs. Polling Protocol" in AGENTS.md and the session-sunset skill.
AGENTS.md §22 extension: Mandate that agents treat [WAKE] as an interrupt, poll for truth via list_messages({status: 'unread'}), and use internal context/history to deduplicate in-session processing. The count in the wake text is informational only..agent/skills/session-sunset/SKILL.md: Mandate that agents call mark_read on all processed messages during the session sunset sequence, ensuring the inbox is clean for the next session while preserving visibility during the current session.
Acceptance Criteria
AGENTS.md is updated with a §22 sub-variant explicitly defining the Interrupt vs Polling protocol..agent/skills/session-sunset/SKILL.md is updated to include mark_read inbox cleanup as a mandatory step in the Sunset Protocol.- A PR is opened containing these documentation updates.
Out of Scope
- Fixing underlying Zod validation bugs for harnessTargetMetadata (tracked in #10407).
- Changing the actual bridge daemon injection mechanism.
Origin Session ID: 7a2db6c6-5b4d-4870-91ea-9dfcbd4514ec
Context
With the rollout of the Phase 3 Wake Substrate, agents now receive
[WAKE]events injected into their harnesses when A2A messages (SENT_TO_ME) or task state changes occur. The[WAKE]message typically includes a count (e.g., "1 new message").The Problem
If multiple wake events queue up in the harness (because the agent was busy processing a previous turn), treating the wake text as exhaustive inbox state breaks idempotency. The agent might receive three separate
[WAKE]inputs sequentially, when in reality there is only one message that needs processing (or three messages that were all processed on the first wake). This leads to redundant processing loops or "phantom wakes".The Architectural Reality
Wake injection acts as a hardware interrupt—it signals "something happened, wake up and check." It is NOT the canonical state. The inbox (
list_messages) is the canonical state. Furthermore, amark_readprotocol is necessary to close the loop, but executingmark_readimmediately upon reading breaks future-session inbox visibility (if an agent wants to find a thread to hand off). Therefore, we adopted Option B: "Explicit-at-session-sunset only".The Fix
Codify the "A2A Interrupt vs. Polling Protocol" in
AGENTS.mdand thesession-sunsetskill.AGENTS.md§22 extension: Mandate that agents treat[WAKE]as an interrupt, poll for truth vialist_messages({status: 'unread'}), and use internal context/history to deduplicate in-session processing. The count in the wake text is informational only..agent/skills/session-sunset/SKILL.md: Mandate that agents callmark_readon all processed messages during the session sunset sequence, ensuring the inbox is clean for the next session while preserving visibility during the current session.Acceptance Criteria
AGENTS.mdis updated with a §22 sub-variant explicitly defining the Interrupt vs Polling protocol..agent/skills/session-sunset/SKILL.mdis updated to includemark_readinbox cleanup as a mandatory step in the Sunset Protocol.Out of Scope
Origin Session ID: 7a2db6c6-5b4d-4870-91ea-9dfcbd4514ec