Skip to content

Commit d34a300

Browse files
brettchienclaude
andcommitted
docs(adr): consolidate push-notifications into the agent-event-stream ADR
Fold the earlier push-notifications draft into this single event canon (§2.4): skin↔core MCP resources/subscribe Phase-1 client wiring (reader acts on id-less notifications; drop the 5s poll), poll-as-reconciliation-backstop invariant, and user-facing OS notifications as a downstream consumer of the same EventHub — with the ECS RUNNING→unhealthy asymmetry cross-referenced. Header notes the consolidation. Supersedes #12. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 0212f4a commit d34a300

1 file changed

Lines changed: 27 additions & 0 deletions

File tree

docs/adr/agent-event-stream.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@
1010
reconcile-loop half of ADR-4 is a sibling that can build on this.
1111
- **Builds on:** [ADR-1](./agent-lifecycle.md) (6-state vocabulary),
1212
[ADR-2](./deployment-control-plane.md) (read/write model + MCP surface).
13+
- **Consolidates:** the earlier *push-notifications* draft — its skin↔core
14+
subscription phasing, the poll-as-reconciliation-backstop invariant, and the
15+
user-facing-notification consumer fold into §2.4 here (single event canon).
1316

1417
> In the context of front-ends and agents needing to **know when an Instance
1518
> changes** (a task dies, a service goes impaired, a probe fails), facing the
@@ -112,6 +115,30 @@ sources ──AgentEvent──▶ EventHub ──▶ pull: deploy_events(list)
112115
- The **webhook** sink is the *only* path that reaches an operator while **no
113116
MCP client is connected** (see §5).
114117

118+
### 2.4 Delivery, phasing & the reconciliation backstop
119+
(Folds the *push-notifications* draft into this ADR.)
120+
121+
- **Skin ↔ core, Phase 1 (client wiring).** Today the desktop `McpClient` reader
122+
correlates replies **by `id` only**; unsolicited `notifications/resources/updated`
123+
land inertly in the MCP pane. Phase 1 makes the reader **act on id-less
124+
notifications** — forward `resources/updated` to the frontend as an event — and
125+
**removes the skin's 5 s `deploy_list` poll**. The roster becomes an MCP
126+
resource (`oab://deployments/{cluster}`, ADR-2 shape) the skin
127+
`resources/subscribe`s.
128+
- **Poll is the reconciliation backstop, not the primary path.** Push delivery is
129+
**best-effort**; a low-frequency full resync (on subscribe/reconnect + every N
130+
minutes) repairs missed or out-of-order events so state never silently drifts.
131+
In Phase 1 the core MAY still poll AWS internally; once `EcsEventSource::subscribe`
132+
(§3) lands, steady-state ECS polling drops to ~zero and the resync stays only as
133+
the backstop.
134+
- **User-facing notifications are a downstream consumer**, not a bespoke channel:
135+
OS/desktop alerts ("tell me when orca goes `Unhealthy`") subscribe to the same
136+
`EventHub` stream that drives the roster; the §2.3 webhook sink covers the
137+
no-client-connected case. **Caveat (from §1):** on ECS the `RUNNING`→unhealthy
138+
flip is *not* event-emitted, so that specific alert rides the reconcile/probe
139+
path, not the stream — the abstraction must not promise every transition is
140+
push-observable on every platform.
141+
115142
## 3. Scope (now)
116143

117144
- **ECS adapter first** (per ADR-2 §10 "ECS driver first"): wire

0 commit comments

Comments
 (0)