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 輸入歷史 |
pending/ |
待決的 ask_user / confirm metadata，每個 task hash 一份 JSON |
其餘全部移入 ~/.config/agenvoy/.store/history.db：
| SQLite 表 | 內容 |
|---|---|
session |
顯示名稱、self_id、人格、模型、reasoning 等級、rule |
note + note_fts5 |
操作者筆記與其 trigram 全文索引（v0.35.3） |
messages + messages_fts5 |
完整訊息封存與其全文索引 |
action_history |
已完成的執行與其工具結果 |
file_history |
工具改動過的每個檔案的版本紀錄 |
usage |
各模型 token 花費，保留 28 天 |
向量、工具快取、錯誤記憶與執行中任務存活訊號存於 ToriiDB（.store/db_0 ... db_3）。舊版 bot.json / bot.md / config.json / status.json / usage.log 於 daemon 啟動時遷移進 SQLite，之後不再寫入。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。
Agent 人格
每個 session 有自己的人格，存放於 session 資料列而非檔案：
| 欄位 | 說明 |
|---|---|
name |
顯示名稱 |
self_id |
正規化為小寫，最多 32 個 ASCII 字母、數字、_ 或 -；非空值須跨 session 唯一（重複回 409）；作為 subagents self_id 參數的查找鍵 |
rule |
人格內文，每一輪渲染進 system prompt 的 ## Bot Persona 區塊 |
model / reasoning |
Session 模型與 reasoning 等級；model: "" 重設為 auto |
以 TUI /bot 或 GET / POST /v1/session/:id 編輯——單一端點涵蓋整個 session 物件，POST 為部分更新。
Agent routing
兩種方式決定由哪個 agent 處理任務：
1. 自動 — dispatcher LLM 分析輸入，並透過 ResolveAgent() 挑選最合適的 provider。
啟動順序：exec.Prepare（TUI 專屬排除、/skill-name 匹配）→ exec.Start（具名 skill 解析、agent 解析、載入 session）→ Execute。具名 skill 被排除或找不到時，該次執行直接失敗。
:self-id 一次性覆寫前綴已移除；要交給具名 session 請用 subagents(self_id=...)，或以 /sessions 切換 session。
2. subagents 工具 — agent 於執行期間 in-process（無 HTTP）呼叫另一個 agent，從 parent ctx 繼承 AllowAll 與 WorkDir。
Subagent 在只收集（collection-only）憲章下執行——負責蒐集與回報，不巢狀、不寫入。排除集由三部分組成：
| 來源 | 排除項目 |
|---|---|
| 憲章基礎 | subagents、edit_file、generate*（萬用字元） |
| TUI 專屬 tool / skill | configs/jsons/tui_tools.json 所列項目，例如 extension-upload、extension-install |
呼叫端的 exclude_tools |
母 agent 傳入的任何項目 |
ask_user 不被排除——subagent 可透過共用的 pending registry 向使用者提問。Subagent 的待決提問也會發布到所屬的母 session，leg 會等待該次續行並回傳已回答後的結果。同時最多 3 條 subagent 並行執行（maxConcurrentSubagents）；第 4 條在等待空位時，自身的 MaxSubagentTimeoutMin（30 分鐘）timeout 已在倒數，因此大量 fan-out 應以 3 為單位分批派送。每筆結果帶有用量前綴，並匯總進母 session 的總計。
Permission mode
| Mode | 行為 |
|---|---|
single-confirm |
每個非 ReadOnly 工具呼叫都需使用者確認（TUI 預設值） |
always-allow |
工具自動執行；LLM 被指示對七類真正不可逆的操作先呼叫 ask_user |
在 always-allow 下仍需明確 ask_user 的七類不可逆操作：
- 檔案系統 ——
rm -rf/rm -r、刪除目錄或非本次任務產生的既有檔案 - 資料庫 ——
DROP DATABASE/DROP TABLE/TRUNCATE、無WHERE的DELETE/UPDATE、任何正式環境 DSN - Git ——
reset --hard、對 main/master 的push --force、刪除共用分支、clean -fdx - 系統 ——
chmod 777/chown -R、/etc//usr//System底下的修改、launchctl / systemd 變更、sudo 提權 - 覆寫 —— 未讀取過的非空既有檔案、
.env/ 憑證 / lock 檔 /.git/index - 雲端與基礎設施 ——
gcloud/aws/kubectl delete、terraform destroy - 行程 ——
shutdown/reboot、對系統服務 PID 執行kill -9
一般寫入（edit_file、build 與測試指令、git status / add / commit、唯讀 shell）直接執行。此閘門由 system prompt（configs/prompts/system_prompt/permission/always_allow.md）強制，而非硬編碼的 Go 端 filter。
Per-session 併發
MaxSessionTasks（NumCPU × 4）限制單一 session 可同時執行的 Execute() 呼叫數。任務會先發布 ToriiDB online marker 並登記取消函式，才去競爭並行空位，因此排隊中的任務仍可見、可取消，而不是隱形地卡住。marker 的 TTL 為 60 秒、每 55 秒續期，被砍掉或崩潰的行程靠過期自行下線，不需檢查 PID。此值為套件常數，不從 config.json 讀取。
取消執行
取消是逐任務而非逐 session：POST /v1/session/:id/cancel/:task_hash 停止單一執行中的任務（{"cancelled": true}）；該 task hash 不在本行程執行中時，會記錄一筆取消事件並回傳 {"cancelled": false, "stale": true}。原本的 once_id 識別碼已改為 task hash。工具確認另以 POST /v1/session/:id/confirm/:confirm_hash 回覆，confirm_hash 取自確認事件。刻意不提供「全部取消」的變體，因此可在不影響同 session 其他任務的前提下丟棄某個長跑任務。在 TUI 中，執行期間按 Esc 會對當前任務開啟取消確認 popup。
續行中斷的工作
停在 ask_user 或確認上的執行會留下待決任務。GET /v1/session/:id/task 只列出真正可續行者：執行中的 run 每 55 秒刷新 ToriiDB 的 action:<session_id>:<task_hash>（TTL 60 秒），因此被關閉視窗或被砍行程遺留的任務會在一分鐘內出現在清單中，而仍在處理中的任務不會。以 POST .../resume 回答，或以 DELETE .../:task_hash 丟棄。TUI 中對應 /pending。
已完成的執行同樣可查：GET /v1/session/:id/task/history 以 task_hash、end_at、objective、model、reasoning 列出（可選 keyword 過濾），GET .../:task_hash/history 以 content 回傳單次執行的完整 action 記錄。