# Session 與 Agent

## Session

Session 是 Agenvoy 的核心單位。每個 session 擁有自己的對話 context、記憶、agent 人格與工具配置。

儲存路徑：`~/.config/agenvoy/sessions/<sid>/`

| 檔案 | 用途 |
|---|---|
| `history.json` | 近期對話，以差量追加 |
| `summary.json` / `.summary_cursor` | 滾動摘要與其增量游標 |
| `action.log` | 工具呼叫稽核日誌。每個事件一行，格式 `[時間戳][window_hash][kind][task_hash] 內容`（`window_hash` 為寫入視窗的 hash，與事件所帶的 `window_hash` 同值）；結尾的 `task_hash` 欄位於 v1.0.2 新增，讓每一行都能追回寫它的那次執行，replay 解析器視其為選填，v1.0.2 之前的舊行仍可載入 |
| `.cmd_history` | 該 session 的 TUI 輸入歷史 |
| `claude_code_<model>.json` | v1.1.1 起，session 中每個用過的 `claude-code` 模型一份：記錄其 Claude Code session id、訊息指紋與最後回覆，讓 daemon 重啟後能 `--resume` 而非重送歷史（模型名稱中的 `@` 與 `/` 轉為 `_`） |
| `pending/` | 待決的 `ask_user` / confirm metadata，每個 task hash 一份 JSON |

其餘全部移入 `~/.config/agenvoy/.store/history.db`：

| SQLite 表 | 內容 |
|---|---|
| `session` | 顯示名稱、`self_id`、人格（`role`）、模型、reasoning 等級。v1.1.0 起人格同時寫入 `role` 欄與舊的 `rule` 欄，讀取時優先取 `role` |
| `note` + `note_fts5` | 已於 v1.0.23 隨操作者筆記一併移除；舊資料庫中殘留的表不再被讀取 |
| `messages` + `messages_fts5` | 完整訊息封存與其全文索引 |
| `action_history` | 已完成的執行與其工具結果 |
| `file_history` | 工具改動過的每個檔案的版本紀錄。自 v1.0.14 起，帶 task 的列其 unique index 為 `(dir, name, task_id, session_id)`，同一次 task 對同一檔案只記一筆 —— 它最初看到的那個版本 —— 而不是每次存檔各記一筆；migration 會刪掉已存在的重複列。`task_id` 為空的列不受影響 |
| `usage` | 各模型 token 花費，保留 28 天。自 v1.0.11 起每次送出另記 `elapsed_ms`，彙總時換算為 `output_tps`。v1.0.26 起每列另記該次回覆的 tool call id（`tool_calls`）；v1.1.0 起 `claude` 與 `claude-code` 的 `input` 含 cache write，與其他 provider 回報未快取 input 的方式一致 |

向量、工具快取、錯誤記憶與執行中任務存活訊號存於 ToriiDB（`.store/db_0` ... `db_3`）。v1.1.1 以前 daemon 啟動時會把舊版 per-session `bot.json`、`bot.md`、`config.json`、`status.json`、`usage.log`、`summary.meta.json` 與 `history/` 任務目錄遷移進 SQLite；v1.1.2 移除這些遷移，舊版安裝留下的這類檔案不再被讀取——需保留資料時請先升級到 v1.1.1 再升級。`state` 表已於 v0.35.3 移除：執行中的任務改以 ToriiDB 的 `action:<session_id>:<task_hash>` key 表示，每 55 秒續期、TTL 60 秒，被砍掉的行程靠過期自行下線，不需再檢查 PID 是否存活。

### Session prefix 與生命週期

| Prefix | 生命週期 |
|---|---|
| `cli-*` | 永久 — 本機 CLI / TUI（TUI `/new` 或 `POST /v1/session`） |
| `chat-*` | 永久 — Web / API（`POST /v1/send` 帶 `persist=true`） |
| `dc-*` | 永久（Discord channel） |
| `tg-*` | 永久（Telegram chat — per-chat，該 chat 內所有使用者共用） |
| `temp-*` | idle 30 分鐘後回收（`POST /v1/send` 與 subagent session 的預設值） |

清理透過 cron 每 30 分鐘執行一次（並於啟動時執行一次），僅針對 `temp-*` prefix — `cli-*`、`chat-*`、`dc-*` 與 `tg-*` 永不自動回收。

Prefix 同時決定確認要回送到哪個通道，也是 TUI session 選單的分組依據：偵測到至少兩組時，選單會顯示 `all` 分頁加上各 prefix 一個分頁，當前 session 排在最前。Daemon 端的 `fsnotify` watcher 會把每個新建 session 目錄的 ID 與設定名稱寫進 log。