Session 端點
最後更新
讀取、更新、刪除 session 及其待決與已完成任務的端點。
| Method | 路徑 | 說明 |
|---|---|---|
GET | /v1/sessions | {sessions:[{id, self_id, name, state, model, count}]}，最近活動的在前。?filter= 可為 all（預設）、active（有執行中的 run）、permanent（temp- 以外）或 temporary（僅 temp-） |
GET | /v1/usage | local — 跨 session 的 24 小時 / 7 天 / 28 天總 token 用量。自 v1.0.11 起每個模型列另帶 elapsed_ms（provider 往返時間加總）與 output_tps（每秒輸出 token 數，只以有記錄耗時的列計算）。v1.1.0 起 claude 與 claude-code 列的 input 含 cache 寫入（write），因這兩個 provider 將其分開回報；v1.0.26 起每筆用量記錄另存該次回應發出的 tool call ID（此端點不回傳） |
POST | /v1/session | local — 建立 session；{prefix} 預設為 cli- |
GET POST DELETE | /v1/session/:id | local — 單一 session 的完整狀態：id、self_id、name、role、state、model、reasoning、levels、count。role（人格內文）於 v1.1.0 取代 rule；rule 仍以相同值回傳，POST 也仍接受，供舊版 client 使用。v1.1.0 起 levels 以 auto 開頭——此時由模型選擇器依工作類型逐請求決定 reasoning 等級——auto_reasoning 隨全域開關一併移除。POST 為部分更新——self_id / name / role / model / reasoning 皆選填，未帶到（或 null）的欄位不動；model: "" 重設為 auto，reasoning 必須是 levels 之一。self_id 重複回 409。DELETE 移除 session 目錄、歷史、狀態與向量。GET 另支援 ?chat=1 在 chat 附上 action log、?usage=1 在 usage 附上每模型 token 用量；兩者預設關閉，因為 log 可能很大。自 v1.0.12 起 chat 內容會先裁剪：已進入 done / canceled / error 的 task，其 tool_* 與 thinking 行、以及最後一則之外的 assistant 行都會被丟棄，讓已結束的 task 只留下結果而非完整軌跡。v1.3.0 起改為每一輪（以每行 agent_result 起算）各保留最後一則 assistant 行，而非整個 task 只留一則，因此經後續輸入或背景報告接回的 task 每輪各留一則回覆；v1.3.1 起 agent_result 行結尾另帶 reasoning=<level> |
POST | /v1/session/:id/memory | local — 由 action 決定的單一記憶操作：summary 重建滾動摘要並回傳 count；compact 丟棄較舊訊息並回傳 removed；reset 清空對話並回傳 removed，且必須帶 mode——summary 保留滾動摘要、all 一併清除 |
POST | /v1/session/:id/followup | local — v1.1.2 新增。依最近 4 則歷史訊息（每則截至 512 字）產生後續建議並回傳 {title, suggests}：最多 3 則、每則至多 32 字的建議；title 至多 32 字，只在 session 仍需要標題時產生（並同時存為 session 名稱）。空 session 回傳 {"title":"","suggests":[]}；單次呼叫上限 30 秒。v1.1.2 前建議是在 /v1/send 串流結尾以 EventSuggest 事件送出，現已不再送出——dashboard 改在執行結束後呼叫此端點 |
POST | /v1/session/:id/cancel/:task_hash | 取消單一執行中任務。該 task hash 在本行程執行中時回 {ok, cancelled:true}；否則（或傳 current）會在 session 串流記錄一筆 canceled 事件並回 {ok, cancelled:false, stale:true}。v1.2.0 起 task hash 在執行開始時就建立並註冊，從第一個事件起即可取消；TUI 的執行同樣跑在 daemon，也能由此取消。v1.3.0 起此呼叫會先停止該任務的背景工作並丟棄其 pending 紀錄，不論任務是否正在執行；v1.3.9 起被丟棄的任務會以 [Canceled] 回覆保留在對話歷史 |
POST | /v1/session/:id/confirm/:confirm_hash | 回覆待決的工具確認：{approve, remember?, allow_turn?, abort?, cancel?, reason?, password?}；自 v1.3.3 起 abort 停止任務並保留 pending 供接續，cancel 停止任務並刪除 pending（v1.3.9 起先以 [Canceled] 寫入對話歷史）。確認已被回覆或已過期時回 410。核准帶有 restricted 項目的確認——受限路徑、sudo 指令（run_command / background_command 的 argv 為 ['sudo', ...]）或 sandbox: false 的指令——必須來自 loopback（否則 403），並以 password 通過作業系統密碼驗證（失敗回 401；Linux pkg_manage 的情形隨該工具移除於 v1.3.2）；sudo ticket 仍有快取時略過驗證，確認事件以 password_cached 標示 |
GET / POST / DELETE /v1/session/:id、memory 與 followup 在 session 目錄不存在時回 404。POST /v1/session/:id/event 已移除；TUI 改經 daemon 的 Unix socket（~/.config/agenvoy/daemon.sock）收發事件。移除於 v1.2.0。待決與已完成任務
| Method | 路徑 | 說明 |
|---|---|---|
GET | /v1/session/:id/task | 以 {pending:[{task_hash, objective, has_questions}]} 列出可續行的待決（ask_user / confirm）任務；background 計數（v1.3.0）移除於 v1.3.8，因為任務不再為背景工作維持 pending。?live=1 改列出正在執行的待決任務。仍在執行中的任務會被排除——執行中的 run 每 55 秒刷新 ToriiDB 的 action:<session_id>:<task_hash>（TTL 60 秒，v0.35.3），因此視窗關閉或行程被砍留下的任務會在一分鐘內重新出現 |
GET | /v1/session/:id/task/:task_hash/questions | 單一待決任務的 {questions:[{question, detail?, options?, multi_select?, secret?}]}；任務已在別處處理掉時回 410 |
POST | /v1/session/:id/task/:task_hash/resume | {answers?}。回答待決任務並續行，最多等候 60 分鐘：回 {session_id, text} 或 {session_id, canceled:true}；任務已在別處處理掉時回 410。v1.3.0 起不帶 answers 的續行會先取得任務執行權，任務已被某個執行占用時回 409 [Conflict] pending task: running |
DELETE | /v1/session/:id/task/:task_hash | 不回答，直接丟棄待決任務；沒有該待決任務時回 404 |
GET | /v1/session/:id/task/history | local — 該 session 已完成的任務，最新在前：每列 {task_hash, end_at, objective, model, reasoning}。?keyword= 對 objective 與記錄的 action 內容過濾 |
GET | /v1/session/:id/task/:task_hash/history | local — 單一已完成任務的完整 action 記錄，以 JSON 字串放在 content。該 hash 無記錄時回 404 |