docs(03-01): complete agent registry plan
- SUMMARY.md with 2 tasks, 15 files, 30 tests (23 unit + 7 IT) - STATE.md: Phase 3 position, agent registry decisions - ROADMAP.md: Phase 3 progress 1/2 plans - REQUIREMENTS.md: AGNT-01, AGNT-02, AGNT-03 marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
hsiegeln
133
.planning/phases/03-agent-registry-sse-push/03-01-SUMMARY.md
Normal file
133
.planning/phases/03-agent-registry-sse-push/03-01-SUMMARY.md
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
phase: 03-agent-registry-sse-push
|
||||
plan: 01
|
||||
subsystem: agent-registry
|
||||
tags: [concurrenthashmap, lifecycle, heartbeat, rest-api, spring-scheduled]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 01-ingestion-pipeline
|
||||
provides: IngestionBeanConfig pattern, @Scheduled pattern, ProtocolVersionInterceptor
|
||||
provides:
|
||||
- AgentRegistryService with register/heartbeat/lifecycle/command management
|
||||
- AgentInfo record with wither-style immutable state transitions
|
||||
- AgentCommand record with delivery status tracking
|
||||
- AgentEventListener interface for SSE bridge (Plan 02)
|
||||
- POST /api/v1/agents/register endpoint
|
||||
- POST /api/v1/agents/{id}/heartbeat endpoint
|
||||
- GET /api/v1/agents endpoint with ?status= filter
|
||||
- AgentLifecycleMonitor with LIVE->STALE->DEAD transitions
|
||||
- AgentRegistryConfig with all timing properties
|
||||
affects: [03-02-sse-push, 04-security]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: [immutable-record-with-wither, compute-if-present-atomic-swap, agent-lifecycle-state-machine]
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/agent/AgentInfo.java
|
||||
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/agent/AgentState.java
|
||||
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/agent/AgentCommand.java
|
||||
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/agent/CommandStatus.java
|
||||
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/agent/CommandType.java
|
||||
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/agent/AgentRegistryService.java
|
||||
- cameleer3-server-core/src/main/java/com/cameleer3/server/core/agent/AgentEventListener.java
|
||||
- cameleer3-server-core/src/test/java/com/cameleer3/server/core/agent/AgentRegistryServiceTest.java
|
||||
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/config/AgentRegistryConfig.java
|
||||
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/config/AgentRegistryBeanConfig.java
|
||||
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/agent/AgentLifecycleMonitor.java
|
||||
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/controller/AgentRegistrationController.java
|
||||
- cameleer3-server-app/src/test/java/com/cameleer3/server/app/controller/AgentRegistrationControllerIT.java
|
||||
modified:
|
||||
- cameleer3-server-app/src/main/java/com/cameleer3/server/app/Cameleer3ServerApplication.java
|
||||
- cameleer3-server-app/src/main/resources/application.yml
|
||||
|
||||
key-decisions:
|
||||
- "AgentInfo as Java record with wither-style methods for immutable ConcurrentHashMap swapping"
|
||||
- "Dead threshold measured from staleTransitionTime, not lastHeartbeat (matches requirement precisely)"
|
||||
- "spring.mvc.async.request-timeout=-1 set now for SSE support in Plan 02"
|
||||
|
||||
patterns-established:
|
||||
- "Immutable record + ConcurrentHashMap.compute for thread-safe state transitions"
|
||||
- "AgentEventListener interface in core module as bridge to SSE layer in app module"
|
||||
|
||||
requirements-completed: [AGNT-01, AGNT-02, AGNT-03]
|
||||
|
||||
# Metrics
|
||||
duration: 15min
|
||||
completed: 2026-03-11
|
||||
---
|
||||
|
||||
# Phase 3 Plan 1: Agent Registry Summary
|
||||
|
||||
**In-memory agent registry with ConcurrentHashMap, LIVE/STALE/DEAD lifecycle via @Scheduled, and REST endpoints for registration/heartbeat/listing**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 15 min
|
||||
- **Started:** 2026-03-11T17:26:34Z
|
||||
- **Completed:** 2026-03-11T17:41:24Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 15
|
||||
|
||||
## Accomplishments
|
||||
- Agent registry domain model with 5 types (AgentInfo, AgentState, AgentCommand, CommandStatus, CommandType)
|
||||
- Full lifecycle management: register, heartbeat, LIVE->STALE->DEAD transitions with configurable thresholds
|
||||
- Command queue with PENDING/DELIVERED/ACKNOWLEDGED/EXPIRED status tracking and event listener bridge
|
||||
- REST endpoints: POST /register, POST /{id}/heartbeat, GET /agents with ?status= filter
|
||||
- 23 unit tests + 7 integration tests all passing
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1 (RED): Failing tests for agent registry** - `4cd7ed9` (test)
|
||||
2. **Task 1 (GREEN): Implement agent registry service** - `61f3902` (feat)
|
||||
3. **Task 2: Controllers, config, lifecycle monitor, integration tests** - `0372be2` (feat)
|
||||
|
||||
_Note: Task 1 used TDD with separate RED/GREEN commits_
|
||||
|
||||
## Files Created/Modified
|
||||
- `AgentInfo.java` - Immutable record with wither-style methods for atomic state transitions
|
||||
- `AgentState.java` - LIVE, STALE, DEAD lifecycle enum
|
||||
- `AgentCommand.java` - Command record with delivery status tracking
|
||||
- `CommandStatus.java` - PENDING, DELIVERED, ACKNOWLEDGED, EXPIRED enum
|
||||
- `CommandType.java` - CONFIG_UPDATE, DEEP_TRACE, REPLAY enum
|
||||
- `AgentRegistryService.java` - Core registry: register, heartbeat, lifecycle, commands
|
||||
- `AgentEventListener.java` - Interface for SSE bridge (Plan 02 integration point)
|
||||
- `AgentRegistryConfig.java` - @ConfigurationProperties for all timing settings
|
||||
- `AgentRegistryBeanConfig.java` - @Configuration wiring AgentRegistryService
|
||||
- `AgentLifecycleMonitor.java` - @Scheduled lifecycle check and command expiry
|
||||
- `AgentRegistrationController.java` - REST endpoints for agents
|
||||
- `AgentRegistryServiceTest.java` - 23 unit tests
|
||||
- `AgentRegistrationControllerIT.java` - 7 integration tests
|
||||
- `Cameleer3ServerApplication.java` - Added AgentRegistryConfig to @EnableConfigurationProperties
|
||||
- `application.yml` - Added agent-registry config section and spring.mvc.async.request-timeout
|
||||
|
||||
## Decisions Made
|
||||
- Used Java record with wither-style methods for AgentInfo instead of mutable class -- ConcurrentHashMap.compute provides atomic swapping without needing synchronized fields
|
||||
- Dead threshold measured from staleTransitionTime field (not lastHeartbeat) to match the "5 minutes after going STALE" requirement precisely
|
||||
- Set spring.mvc.async.request-timeout=-1 proactively for SSE support needed in Plan 02
|
||||
- Command queue uses ConcurrentLinkedQueue per agent for lock-free command management
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
- DiagramRenderControllerIT has a pre-existing flaky failure (EmptyResultDataAccess in seedDiagram) unrelated to Phase 3 changes. Logged in deferred-items.md.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- AgentRegistryService ready for SSE integration via AgentEventListener interface
|
||||
- Plan 02 (SSE Push) can wire SseConnectionManager as AgentEventListener implementation
|
||||
- All agent endpoints under /api/v1/agents/ already covered by ProtocolVersionInterceptor
|
||||
|
||||
---
|
||||
*Phase: 03-agent-registry-sse-push*
|
||||
*Completed: 2026-03-11*
|
||||
Reference in New Issue
Block a user