cherry-studio/tasks.md

Agent and Session Database Implementation Tasks

This document outlines the implementation plan for adding agent and session management with database persistence to Cherry Studio.

Database Schema Design

Tables to Create:

1. agents Table

   • id (Primary Key)
   • name (TEXT, required)
   • description (TEXT)
   • avatar (TEXT)
   • instructions (TEXT, for System Prompt)
   • model (TEXT, model id, required)
   • tools (JSON array of enabled tool IDs)
   • knowledges (JSON array of enabled knowledge base IDs)
   • configuration (JSON, extensible settings)
   • created_at / updated_at (TIMESTAMPS)

2. sessions Table

   • id (Primary Key)
   • agent_ids (JSON array of agent IDs)
   • user_prompt (TEXT, initial user goal)
   • status (TEXT: 'running', 'completed', 'failed', 'stopped')
   • accessible_paths (JSON array of directory paths)
   • created_at / updated_at (TIMESTAMPS)

3. session_logs Table

   • id (Primary Key)
   • session_id (INTEGER, Foreign Key to sessions.id)
   • parent_id (INTEGER, Foreign Key to session_logs.id, nullable)
   • role (TEXT: 'user', 'agent')
   • type (TEXT: 'message', 'thought', 'action', 'observation')
   • content (JSON, structured data)
   • created_at (TIMESTAMP)

Implementation Tasks:

Phase 1: Database Foundation ✅ COMPLETED

• Task 1: Create database schema migration
• Task 2: Create TypeScript interfaces for all entities
• Task 3: Implement database service layer for agents
• Task 4: Implement database service layer for sessions
• Task 5: Implement database service layer for session_logs

Phase 2: Service Layer ✅ COMPLETED

• Task 6: Add IPC handlers for agent operations
• Task 7: Add IPC handlers for session operations
• Task 8: Create agent management service in main process (AgentService)
• Task 9: Create session management service in renderer process (AgentManagementService)

Phase 3: UI Integration ✅ COMPLETED

• Task 10: Update CherryAgentPage to use real data
• Task 10a: Create useAgentManagement hook
• Task 10b: Replace mock sessions with real database sessions
• Task 10c: Implement agent name editing with real persistence
• Task 11: Implement agent creation/editing modal
• Task 12: Implement agent selection and management
• Task 13: Implement session creation and switching
• Task 14: Implement enhanced session management UI with edit/delete

Phase 4: Testing and Polish

• Task 15: Add comprehensive tests for database operations
• Task 16: Add error handling and validation
• Task 17: Performance optimization for large datasets
• Task 18: Documentation and code cleanup

Completed Work Summary:

✅ Database Layer

• Schema: Created complete database schema with agents, sessions, and session_logs tables
• Queries: Implemented comprehensive SQL queries in AgentQueries
• Service: Built full CRUD AgentService with proper error handling and logging
• Database Path: Using separate agent.db database file in user data directory

✅ IPC Communication Layer

• Channels: Added 12 new IPC channels for agent/session management to IpcChannel.ts
• Handlers: Implemented typed IPC handlers in main/ipc.ts
• Types: Shared type definitions between main and renderer processes

✅ Renderer Services & Hooks

• AgentManagementService: Comprehensive service for IPC communication with proper logging
• useAgentManagement: React hook providing stateful agent/session management
• Integration: CherryAgentPage now uses real data instead of mock data

✅ Type System

• Shared Types: Moved agent types to shared location accessible by both processes
• Type Safety: Full TypeScript coverage with proper error handling
• Module Resolution: Fixed import paths and module resolution issues

Key Features Implemented:

1. Agent Management: Complete CRUD operations for agents with modal-based UI
2. Session Management: Full session lifecycle management with enhanced UI
3. Session Logging: Structured logging for session interactions
4. Real-time UI: CherryAgentPage displays live agent and session data
5. Auto-initialization: Creates default agent and session if none exist
6. Error Handling: Comprehensive error handling with user feedback
7. Modal Management: Agent and session creation/editing modals
8. Enhanced Session UI: Session list with edit/delete actions and metadata display
9. Directory Access Control: Sessions can specify accessible directories

Notes:

• Use existing libsql database connection
• Follow existing service patterns in Cherry Studio
• Ensure proper error handling and data validation
• Consider migration path for existing mock data