# Implementation Plan - Symphony Session History Sync

## Revision History
| Version | Date | Description | Author |
|---|---|---|---|
| v1.0 | 2026-07-04 | Initial implementation plan for cross-IDE session history sync | Antigravity Orchestrator |

---

## 1. Objectives
Bổ dung khả năng liên thông và đọc lịch sử phiên làm việc từ các công cụ/IDE khác nhau (như Claude Code, Codex, Antigravity) vào Symphony. Điều này giúp người dùng chuyển đổi mượt mà giữa các IDE mà không bị gián đoạn bối cảnh làm việc (ví dụ chuyển từ Claude Code sang Antigravity để tiếp tục phiên "Nghiên cứu tính năng video filter cho video editor").

---

## 2. User Review Required

> [!IMPORTANT]
> **Quyền truy cập thư mục hệ thống:** Để quét được lịch sử của Claude Code, Symphony cần truy cập đường dẫn `~/Library/Application Support/Claude/`. Vui lòng xác nhận rằng quyền truy cập này được cho phép trên hệ thống của bạn.

---

## 3. Open Questions

> [!WARNING]
> **Heuristics vs. LLM-based Summary:** 
> Khi phân tích lịch sử trò chuyện dài từ `audit.jsonl` của Claude Code, chúng ta có nên sử dụng heuristics (lấy N tin nhắn cuối cùng + tóm tắt Git diff) hay gọi API LLM (chẳng hạn qua Firebase AI Logic SDK / Gemini API có sẵn) để tạo một bản tóm tắt Handover chất lượng cao? 
> *Đề xuất:* Sử dụng LLM-based Summary nếu dự án có sẵn cấu hình API Key, ngược lại tự động fallback về heuristics (tóm tắt các tệp tin đã sửa và các tin nhắn cuối cùng).

---

## 4. Proposed Changes

### Component 1: Database Schema & Core Sync Engine

#### [MODIFY] [db.js](file:///Users/trungkientn/Dev/NodeJS/main-awf/symphony/core/db.js)
Thêm bảng `external_sessions` để lưu trữ thông tin về các phiên làm việc từ các công cụ khác được phát hiện hoặc liên kết.
```sql
CREATE TABLE IF NOT EXISTS external_sessions (
  id TEXT PRIMARY KEY,
  tool_name TEXT NOT NULL,      -- 'claude-code' | 'antigravity' | 'codex'
  title TEXT,
  cwd TEXT NOT NULL,
  last_activity_at DATETIME,
  summary TEXT,
  metadata TEXT DEFAULT '{}',
  created_at DATETIME DEFAULT (datetime('now'))
);
CREATE INDEX IF NOT EXISTS idx_ext_sessions_cwd ON external_sessions(cwd);
```

#### [NEW] [session-linker.js](file:///Users/trungkientn/Dev/NodeJS/main-awf/symphony/core/session-linker.js)
Tạo module cốt lõi để quét và phân tích lịch sử các phiên làm việc của Claude Code, Antigravity và Codex.
Các tính năng chính:
- `scanExternalSessions(cwd)`: Quét thư mục `~/Library/Application Support/Claude/` và các thư mục log của các công cụ khác để phát hiện các phiên làm việc có `cwd` trùng khớp.
- `readClaudeAuditLog(sessionId)`: Đọc và parse tệp `audit.jsonl` từ thư mục local-agent-mode-sessions hoặc claude-code-sessions.
- `generateHandoverSummary(sessionData)`: Phân tích log trò chuyện để tạo ra bối cảnh bàn giao (Handover Note).
- `syncTasksFromSession(sessionId)`: Đọc danh sách tasks từ Agent Mode (`.claude/tasks/`) và ánh xạ thành các tasks trong Symphony.

### Component 2: MCP Tools Integration

#### [NEW] [sessions.js](file:///Users/trungkientn/Dev/NodeJS/main-awf/symphony/mcp/tools/sessions.js)
Định nghĩa các MCP Tools mới để các AI Agent có thể truy vấn và đồng bộ trạng thái:
- `symphony_list_external_sessions`: Liệt kê các phiên làm việc ngoại vi được phát hiện trong thư mục làm việc.
- `symphony_sync_external_session`: Thực hiện đồng bộ hóa bối cảnh và tasks từ một phiên ngoại vi được chọn.

#### [MODIFY] [index.js](file:///Users/trungkientn/Dev/NodeJS/main-awf/symphony/mcp/index.js)
Đăng ký các MCP Tools mới vào Symphony MCP Server.

### Component 3: CLI Commands

#### [MODIFY] [index.js](file:///Users/trungkientn/Dev/NodeJS/main-awf/symphony/cli/index.js)
Thêm subcommand `symphony session`:
- `symphony session list`: Hiển thị danh sách các phiên làm việc được phát hiện từ các công cụ khác trên dự án này.
- `symphony session sync <session-id>`: Đồng bộ hóa thủ công một phiên làm việc, tạo ghi chú bàn giao và khôi phục các tasks/TODOs.

### Component 4: Session Restore Integration

#### [MODIFY] [SKILL.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/skills/awf-session-restore/SKILL.md)
Cập nhật Step 3 (Gather Context) trong Init Chain để tự động kiểm tra xem có phiên bàn giao (Handover Note) nào gần đây từ công cụ khác được ghi nhận trong Symphony hay không. Nếu có, tự động đưa bối cảnh này vào Silent Context để nạp vào Agent mới.

---

## 5. Verification Plan

### Automated Tests
- Tạo script giả lập tệp tin `.json` và `audit.jsonl` của Claude Code trong thư mục test.
- Viết unit test cho `session-linker.js` để kiểm tra khả năng parse chính xác `audit.jsonl` và trích xuất tin nhắn/tasks.

### Manual Verification
- Chạy lệnh CLI `symphony session list` trong workspace để kiểm tra danh sách session của Claude Code.
- Thử nghiệm đồng bộ hóa một phiên (ví dụ phiên "Sleep tracking feature analysis") và kiểm tra xem các tasks và Handover Note có được tạo thành công trong Symphony hay không.