docs(03-02): complete SSE push plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/phases/03-agent-registry-sse-push/03-02-SUMMARY.md

@@ -0,0 +1,116 @@
+---
+phase: 03-agent-registry-sse-push
+plan: 02
+subsystem: agent-sse
+tags: [sse, server-sent-events, sseemitter, command-push, ping-keepalive, spring-scheduled]
+
+# Dependency graph
+requires:
+  - phase: 03-agent-registry-sse-push
+    provides: AgentRegistryService, AgentEventListener, AgentCommand, CommandType, AgentRegistryConfig
+provides:
+  - SseConnectionManager with per-agent SseEmitter management and event delivery
+  - AgentSseController GET /api/v1/agents/{id}/events SSE endpoint
+  - AgentCommandController with single/group/broadcast command targeting
+  - Command acknowledgement endpoint POST /{id}/commands/{commandId}/ack
+  - Ping keepalive every 15 seconds via @Scheduled
+  - Last-Event-ID header support (no replay)
+affects: [04-security]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [sse-emitter-per-agent, reference-equality-removal, async-command-delivery-via-event-listener]
+
+key-files:
+  created:
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/agent/SseConnectionManager.java
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/controller/AgentSseController.java
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/controller/AgentCommandController.java
+    - cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/AgentSseControllerIT.java
+    - cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/AgentCommandControllerIT.java
+  modified:
+    - cameleer3-server-app/src/main/java/com/cameleer3/server/app/config/WebConfig.java
+    - cameleer3-server-app/src/test/resources/application-test.yml
+
+key-decisions:
+  - "SSE events path excluded from ProtocolVersionInterceptor for EventSource client compatibility"
+  - "SseConnectionManager uses reference-equality (==) in onCompletion/onTimeout/onError to avoid removing a newer emitter"
+  - "java.net.http.HttpClient async API for SSE integration tests to avoid test thread blocking"
+
+patterns-established:
+  - "AgentEventListener bridge: core module fires event, app module @Component delivers via SSE"
+  - "CountDownLatch + async HttpClient for SSE integration test assertions"
+
+requirements-completed: [AGNT-04, AGNT-05, AGNT-06, AGNT-07]
+
+# Metrics
+duration: 32min
+completed: 2026-03-11
+---
+
+# Phase 3 Plan 2: SSE Push Summary
+
+**SSE connection manager with per-agent SseEmitter, config-update/deep-trace/replay command delivery, group/broadcast targeting, ping keepalive, and command acknowledgement**
+
+## Performance
+
+- **Duration:** 32 min
+- **Started:** 2026-03-11T17:44:10Z
+- **Completed:** 2026-03-11T18:16:10Z
+- **Tasks:** 2
+- **Files modified:** 7
+
+## Accomplishments
+- SseConnectionManager with ConcurrentHashMap-based per-agent SSE emitter management, ping keepalive, and AgentEventListener bridge
+- Three command targeting levels: single agent, group, and broadcast to all LIVE agents
+- 7 SSE integration tests (connect, 404 unknown, config-update/deep-trace/replay delivery, ping, Last-Event-ID) + 6 command controller tests
+- All 71 tests pass with mvn clean verify
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: SseConnectionManager, SSE controller, and command controller** - `5746886` (feat)
+2. **Task 2: Integration tests for SSE, commands, and full flow** - `a1909ba` (test)
+
+## Files Created/Modified
+- `SseConnectionManager.java` - Per-agent SseEmitter management, event delivery, ping keepalive via @Scheduled
+- `AgentSseController.java` - GET /{id}/events SSE endpoint with Last-Event-ID support
+- `AgentCommandController.java` - POST command endpoints (single/group/broadcast) + ack endpoint
+- `AgentSseControllerIT.java` - 7 SSE integration tests using async HttpClient
+- `AgentCommandControllerIT.java` - 6 command controller integration tests
+- `WebConfig.java` - Added SSE events path to interceptor exclusion list
+- `application-test.yml` - Added 1s ping interval for faster SSE test assertions
+
+## Decisions Made
+- Excluded SSE events path from ProtocolVersionInterceptor -- EventSource clients cannot easily add custom headers, so the SSE endpoint is exempted from protocol version checking
+- Used reference equality (==) in SseEmitter callbacks to avoid removing a newer emitter when an old one completes -- directly addresses Pitfall 3 from research
+- Used java.net.http.HttpClient async API for SSE integration tests instead of adding spring-boot-starter-webflux -- avoids new dependencies and tests true end-to-end behavior
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+- Surefire fork JVM hangs ~30s after SSE tests complete due to async HttpClient threads holding JVM open -- not a test failure, just slow shutdown. Surefire eventually kills the fork.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Full bidirectional agent communication complete: agents POST data, server pushes commands via SSE
+- Phase 4 (Security) can add JWT auth to all endpoints and Ed25519 config signing
+- All agent endpoints under /api/v1/agents/ ready for auth layer
+
+## Self-Check: PASSED
+
+- All 5 created files exist on disk
+- Commit `5746886` found in git log (Task 1)
+- Commit `a1909ba` found in git log (Task 2)
+- `mvn clean verify` passes with 71 tests, 0 failures
+
+---
+*Phase: 03-agent-registry-sse-push*
+*Completed: 2026-03-11*