docs(adr): Agent Event Stream — platform-agnostic event source + notification facade - #17
Open
brettchien wants to merge 1 commit into
Open
docs(adr): Agent Event Stream — platform-agnostic event source + notification facade#17brettchien wants to merge 1 commit into
brettchien wants to merge 1 commit into
Conversation
…fication facade Proposed ADR realizing the observation half of ADR-4's reservation (ADR-2 §10: durable status store + replacement for on-demand live-observe). Introduces one `EventSource` adapter per runtime (ECS→EventBridge/SQS, k8s→watch/informer) feeding a single `EventHub` facade that serves both a pull history (deploy_events, PR #16) and a push stream (MCP notifications/resources/updated + webhook). Normalizes ECS-flavoured EcsEvent into a platform-neutral AgentEvent on the studio-cp seam. Flags the runtime asymmetry (ECS omits health-flip events; k8s emits probe failures), the push-needs-live-subscriber and competing-consumer caveats, and the open question of whether an MCP client notification wakes the agent. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Proposed ADR (
docs/adr/agent-event-stream.md) for a platform-agnostic event source + notification facade — the observation half of the ADR-4 reservation that ADR-2 §10 deferred (durable status store + a replacement for "front-ends live-observe on demand").Why now
deploy_events(merged, #16) reads an event archive but has no source wired and no live path. And each runtime exposes events differently (ECS→EventBridge, k8s→watch), so hard-wiring the ECS path intooab-mcpwould repeat the platform-specific shortcut the desktop-core-sidecar ADR fixed.The decision (one adapter + one facade)
EventSourcetrait per runtime:list()(pull/history) +subscribe()(push/live).list= CloudWatch Logs (already built —oabctl::events::fetch_ecs_eventsfrom feat(oab-mcp): add deploy_events — ECS control-plane event history #16);subscribe= SQS long-poll.list= Events API;subscribe= watch/informer (API server is the push transport — no EventBridge/SQS).AgentEvent— generalize the ECS-flavouredEcsEventon thestudio-cpseam;kindmaps onto ADR-1's 6-state where a transition matches.EventHub— one normalization + fan-out point decoupling N sources from M sinks.Notable points captured
healthStatus(aRUNNING→unhealthy flip isn't emitted); k8s does emit probe-failure events. The abstraction fixes the ECS blind spot by construction.oab-mcpis per-session stdio; SQS/watch buffers while nothing's connected (no loss) but MCP push ≠ offline alerting → webhook is the only offline path.oab-mcpand a desktop sidecar'soab-mcpon one SQS queue would steal each other's messages → SNS fan-out / single designated subscriber.Docs-only; no code. Builds on ADR-1 / ADR-2 and reuses #16 wholesale.
🤖 Generated with Claude Code