mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases 2 Wiki Activity
Files
ca4f5ec01145eb4f530eabeb43fe995e223e116a
stack/docs/scratchpads/orch-109-lifecycle.md
Jason Woltje 5d348526de feat(#71): implement graph data API 
Implemented three new API endpoints for knowledge graph visualization:

1. GET /api/knowledge/graph - Full knowledge graph
   - Returns all entries and links with optional filtering
   - Supports filtering by tags, status, and node count limit
   - Includes orphan detection (entries with no links)

2. GET /api/knowledge/graph/stats - Graph statistics
   - Total entries and links counts
   - Orphan entries detection
   - Average links per entry
   - Top 10 most connected entries
   - Tag distribution across entries

3. GET /api/knowledge/graph/:slug - Entry-centered subgraph
   - Returns graph centered on specific entry
   - Supports depth parameter (1-5) for traversal distance
   - Includes all connected nodes up to specified depth

New Files:
- apps/api/src/knowledge/graph.controller.ts
- apps/api/src/knowledge/graph.controller.spec.ts

Modified Files:
- apps/api/src/knowledge/dto/graph-query.dto.ts (added GraphFilterDto)
- apps/api/src/knowledge/entities/graph.entity.ts (extended with new types)
- apps/api/src/knowledge/services/graph.service.ts (added new methods)
- apps/api/src/knowledge/services/graph.service.spec.ts (added tests)
- apps/api/src/knowledge/knowledge.module.ts (registered controller)
- apps/api/src/knowledge/dto/index.ts (exported new DTOs)
- docs/scratchpads/71-graph-data-api.md (implementation notes)

Test Coverage: 21 tests (all passing)
- 14 service tests including orphan detection, filtering, statistics
- 7 controller tests for all three endpoints

Follows TDD principles with tests written before implementation.
All code quality gates passed (lint, typecheck, tests).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-02 15:27:00 -06:00

4.1 KiB
Raw Blame History

Issue ORCH-109: Agent lifecycle management

Objective

Implement agent lifecycle management service to manage state transitions through the agent lifecycle (spawning → running → completed/failed/killed).

Approach

Following TDD principles:

  1. Write failing tests first for all state transition scenarios
  2. Implement minimal code to make tests pass
  3. Refactor while keeping tests green

The service will:

  • Enforce valid state transitions using state machine
  • Persist agent state changes to Valkey
  • Emit pub/sub events on state changes
  • Track agent metadata (startedAt, completedAt, error)
  • Integrate with ValkeyService and AgentSpawnerService

Acceptance Criteria

  • src/spawner/agent-lifecycle.service.ts implemented
  • State transitions: spawning → running → completed/failed/killed
  • State persisted in Valkey
  • Events emitted on state changes (pub/sub)
  • Agent metadata tracked (startedAt, completedAt, error)
  • State machine enforces valid transitions only
  • Comprehensive unit tests with ≥85% coverage
  • Tests follow TDD (written first)

Implementation Details

State Machine

Valid transitions (from state.types.ts):

  • spawning → running, failed, killed
  • running → completed, failed, killed
  • completed → (terminal state)
  • failed → (terminal state)
  • killed → (terminal state)

Key Methods

  1. transitionToRunning(agentId) - Move agent from spawning to running
  2. transitionToCompleted(agentId) - Mark agent as completed
  3. transitionToFailed(agentId, error) - Mark agent as failed with error
  4. transitionToKilled(agentId) - Mark agent as killed
  5. getAgentLifecycleState(agentId) - Get current lifecycle state

Events Emitted

  • agent.running - When transitioning to running
  • agent.completed - When transitioning to completed
  • agent.failed - When transitioning to failed
  • agent.killed - When transitioning to killed

Progress

  • Read issue requirements
  • Create scratchpad
  • Write unit tests (TDD - RED phase)
  • Implement service (TDD - GREEN phase)
  • Refactor and add edge case tests
  • Verify test coverage = 100%
  • Add service to module exports
  • Verify build passes
  • Create Gitea issue
  • Close Gitea issue with completion notes

Testing

Test coverage: 100% (28 tests)

Coverage areas:

  • Valid state transitions (spawning→running→completed)
  • Valid state transitions (spawning→failed, running→failed)
  • Valid state transitions (spawning→killed, running→killed)
  • Invalid state transitions (should throw errors)
  • Event emission on state changes
  • State persistence in Valkey
  • Metadata tracking (timestamps, errors)
  • Conditional timestamp setting (startedAt, completedAt)
  • Agent not found error handling
  • List operations

Notes

  • State transition validation logic already exists in state.types.ts
  • ValkeyService provides state persistence and pub/sub
  • AgentSpawnerService manages agent sessions in memory
  • This service bridges the two by managing lifecycle + persistence

Completion Summary

Successfully implemented ORCH-109 following TDD principles:

Files Created

  1. /home/localadmin/src/mosaic-stack/apps/orchestrator/src/spawner/agent-lifecycle.service.ts - Main service implementation
  2. /home/localadmin/src/mosaic-stack/apps/orchestrator/src/spawner/agent-lifecycle.service.spec.ts - Comprehensive tests (28 tests, 100% coverage)

Files Modified

  1. /home/localadmin/src/mosaic-stack/apps/orchestrator/src/spawner/spawner.module.ts - Added service to module
  2. /home/localadmin/src/mosaic-stack/apps/orchestrator/src/spawner/index.ts - Exported service

Key Features Implemented

  • State transition enforcement via state machine
  • State persistence in Valkey
  • Pub/sub event emission on state changes
  • Metadata tracking (startedAt, completedAt, error)
  • Comprehensive error handling
  • 100% test coverage (28 tests)

Gitea Issue

  • Created: #244
  • Status: Closed
  • URL: #244

Next Steps

This service is now ready for integration with:

  • ORCH-117: Killswitch implementation (depends on this)
  • ORCH-127: E2E test for concurrent agents (depends on this)
Reference in New Issue View Git Blame Copy Permalink