implement plan

[drzo]

Implement the plan:

CogZero Implementation Plan: Complete Features & Functionalities

Executive Summary

CogZero is a C++ Agent-Zero implementation for OpenCog integration at version 0.3.0/0.4.0. The project has Phases 1-13 completed with 161+ passing tests across 7 CTest targets. Phase 14 (Production Hardening) is planned but not started.

---

1. Current State Analysis

✅ Completed Modules (Phases 1-13)

Phase	Module	Status	Key Components
1	agentzero-core	✅ Complete	AgentZeroCore, CognitiveLoop, TaskManager, ReasoningEngine, ActionExecutor
2	agentzero-perception	✅ Complete	MultiModalSensor, PerceptualProcessor, AttentionManager, TextualSensor
3	agentzero-knowledge	✅ Complete	KnowledgeBase, PatternDiscovery, ConceptFormation, PLNRuleLibrary
4	agentzero-planning	✅ Complete	GoalHierarchy, PlanningEngine, TemporalReasoner, SpaceTimeIntegrator, MetaPlanner
5	agentzero-learning	✅ Complete	ExperienceManager, SkillAcquisition, PolicyOptimizer, MetaLearning, ASMOSESIntegrator
6	agentzero-communication	✅ Complete	LanguageProcessor, DialogueManager, AgentComms, HumanInterface, MultiAgentCoordinator
7	agentzero-memory	✅ Complete	EpisodicMemory, WorkingMemory, LongTermMemory, ContextManager
8	agentzero-tools	✅ Complete	ToolRegistry, ToolExecutor, ToolWrapper, CapabilityComposer, ResourceManager
9	Integration & Testing	✅ Complete	161+ tests (unit/e2e/integration/benchmark/regression)
10	agentzero-distributed	✅ Complete	ClusterManager, DistributedCoordinator, LoadBalancer, CoordinationProtocol
11	profiling	✅ Complete	AgentZeroProfiler (nanosecond RAII profiling)
12	Advanced Coordination	✅ Complete	RaftConsensus, ConflictResolver, MonitoringServer, Logger JSON-lines
13	CI/CD Hardening	✅ Complete	GitHub Agent cog0.md, CTest labels, comprehensive CI workflow

🔧 Standalone CLI (cog0)

• 147+ tests, zero OpenCog dependencies
• Interactive REPL with goal, task, percept, run, status, atoms, goals, infer, save, load, rule
• Script execution (--script), inline evaluation (--eval), batch mode (--batch)
• Tab-completion via readline (optional)

---

2. Outstanding Work: Phase 14 (Production Hardening)

2.1 Agent Migration — Live State Hand-off

Priority: High | Effort: 2-3 weeks

Description: Enable live migration of agent state and active tasks between cluster nodes.

Implementation Tasks:

1. Extend ClusterManager with migration protocol:
   • initiateMigration(sourceNode, targetNode, agentId)
   • receiveMigration(serializedState)
   • State checkpointing with EpisodicMemory and AtomStore serialization
2. Implement state serialization for Agent class:
   • Serialize goals, tasks, attention values, episodic memory
   • Use MessageSerializer JSON format
3. Add migration coordination with Raft leader:
   • Pause agent execution during migration window
   • Resume on target node with full state
4. Create migration tests in test_phase14_migration.cpp

Files to Modify/Create:

• include/ClusterManager.h / src/ClusterManager.cpp
• include/Agent.h — add serialize() / deserialize()
• tests/test_phase14_migration.cpp (new)

---

2.2 gRPC Agent Interface

Priority: Medium | Effort: 3-4 weeks

Description: Replace/augment CogServer TCP protocol with a typed gRPC API for inter-module communication.

Implementation Tasks:

1. Define .proto schema for agent operations:
   protobuf
   Copy code

   service AgentService {
     rpc SetGoal(GoalRequest) returns (GoalResponse);
     rpc InjectPercept(PerceptRequest) returns (PerceptResponse);
     rpc RunCycles(RunRequest) returns (stream CycleStatus);
     rpc GetStatus(Empty) returns (AgentStatus);
     rpc QueryAtoms(AtomQuery) returns (AtomList);
   }
   

2. Implement gRPC server in agentzero-core:
   • Wrap Agent API calls
   • Streaming support for cognitive cycle status
3. Create gRPC client library for external consumers
4. Add CMake option USE_GRPC with graceful fallback

Files to Create:

• proto/agent.proto
• include/GrpcAgentServer.h / src/GrpcAgentServer.cpp
• include/GrpcAgentClient.h / src/GrpcAgentClient.cpp

---

2.3 WebSocket Monitoring Dashboard

Priority: Medium | Effort: 2 weeks

Description: Upgrade MonitoringServer with WebSocket push metrics and an embedded HTML/JS frontend.

Implementation Tasks:

1. Implement WebSocket upgrade handshake (RFC 6455) in MonitoringServer:
   • Handle Upgrade: websocket header
   • Implement frame encoding/decoding
2. Add real-time push for:
   • /ws/metrics — JSON metrics every 500ms
   • /ws/atoms — Atom changes (new/modified atoms)
   • /ws/attention — Attention value updates
3. Create minimal HTML/JS dashboard at /dashboard:
   • Real-time charts (goals, tasks, memory usage)
   • Atom visualization (mini hypergraph)
   • Controls: pause/resume agent, inject percept
4. Embed dashboard assets as C++ string literals (no external files)

Files to Modify/Create:

• include/MonitoringServer.h / src/MonitoringServer.cpp
• include/WebSocketHandler.h / src/WebSocketHandler.cpp (new)
• include/DashboardAssets.h (embedded HTML/JS) (new)

---

2.4 Persistent Raft Log (RocksDB)

Priority: Low-Medium | Effort: 1-2 weeks

Description: Add RocksDB-backed persistence to RaftNode for leader state survivability.

Implementation Tasks:

1. Add optional RocksDB dependency in CMake
2. Implement RaftLogStore interface:
   • append(LogEntry) → RocksDB put
   • getRange(startIndex, endIndex) → batch read
   • truncate(index) → range delete
3. Integrate with RaftNode::appendEntries() and recovery on startup
4. Fallback to in-memory log when RocksDB unavailable

Files to Create:

• include/RaftLogStore.h / src/RaftLogStore.cpp
• Modify RaftConsensus.cpp for pluggable log store

---

2.5 TLS for MonitoringServer

Priority: Low | Effort: 1 week

Description: Optional TLS encryption for secure metric scraping in production.

Implementation Tasks:

1. Add optional mbedTLS or OpenSSL dependency
2. Implement TlsSocket wrapper:
   • Certificate loading
   • Handshake and encrypted I/O
3. Add MonitoringServer::enableTLS(certPath, keyPath)
4. Update /health endpoint to report TLS status

---

3. Placeholder/Stub Completions

3.1 High Priority Stubs (Functional Impact)

Location	Stub	Completion Effort
ToolWrapper.cpp	REST API, ROS, Python, Shell execution	2-3 days each
MessageSerializer.cpp	JSON parsing, compression, binary format	1-2 days
ProtocolManager.cpp	CogServer network server startup/shutdown	2-3 days
MetaPlanner.cpp	Spacetime temporal planning integration	2-3 days

3.2 Medium Priority Stubs

Location	Stub	Completion Effort
MessageRouter.cpp	Network discovery, route persistence	2-3 days
PLNRuleLibrary.cpp	Full URE unification	3-5 days
SpaceTimeIntegrator.cpp	Temporal data cleanup	1 day

---

4. Testing & Quality Enhancements

4.1 Additional Test Coverage

Area	Current	Target	Action
Phase 14 Migration	0	10+	New test file
gRPC Interface	0	15+	New test file
WebSocket Dashboard	0	8+	New test file
Raft Persistence	0	6+	New test file
TLS Security	0	5+	New test file

4.2 CI/CD Improvements

1. Add CodeQL security scanning — already in CI, verify coverage
2. Add macOS ARM64 (M1/M2) build matrix — currently only macos-14
3. Add Windows MinGW build variant — currently MSVC only
4. Add memory leak CI check — extend sanitizer job with leak detection assertions

---

5. Documentation Gaps

Document	Status	Action
docs/GRPC_GUIDE.md	Missing	Create with proto definitions and usage
docs/DASHBOARD_GUIDE.md	Missing	Create with WebSocket API and UI documentation
docs/MIGRATION_GUIDE.md	Missing	Create with agent migration procedures
docs/PRODUCTION_DEPLOYMENT.md	Partial	Expand with TLS, monitoring, and clustering

---

6. Recommended Implementation Order

Phase 14A — Core Production Features (4-6 weeks)

1. Agent Migration — enables elastic scaling
2. WebSocket Dashboard — enables real-time monitoring
3. Stub Completions — ToolWrapper REST/Python/Shell

Phase 14B — Enterprise Features (4-6 weeks)

1. gRPC Interface — enables polyglot clients
2. Persistent Raft Log — enables HA deployments
3. TLS for MonitoringServer — enables secure monitoring

Phase 14C — Polish (2 weeks)

1. Documentation completion
2. Additional test coverage
3. CI/CD matrix expansion

---

7. Dependencies Summary

Feature	External Dependency	Optional?
gRPC Interface	grpc (C++)	Yes
Persistent Raft Log	RocksDB	Yes
TLS	mbedTLS or OpenSSL	Yes
REST API Tool	libcurl	Yes
Python Script Tool	Python C API	Yes
ROS Behavior Bridge	ROS libraries	Yes

---

8. Key Metrics to Track

Metric	Current	Target
Test Count	161	200+
Code Coverage	~70% (estimated)	85%+
Build Time (standalone)	~30s	<20s
Response Time (routine)	<100ms	<50ms
Memory (10K atoms)	~50MB	<40MB

---

Summary

CogZero is a mature project with 13 phases complete. The remaining Phase 14 work focuses on production hardening with emphasis on:

• Live agent migration
• gRPC typed API
• Real-time monitoring dashboard
• Persistent consensus
• TLS security

The standalone cog0 CLI is fully functional for development and testing. OpenCog-dependent modules require cogutil/atomspace but gracefully fall back when unavailable.