# 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 只留下結果而非完整軌跡 |
| `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，也能由此取消 |
| `POST` | `/v1/session/:id/confirm/:confirm_hash` | 回覆待決的工具確認：`{approve, remember?, allow_turn?, abort?, reason?, password?}`。確認已被回覆或已過期時回 410。核准帶有 `restricted` 路徑的確認必須來自 loopback（否則 403），並以 `password` 通過作業系統密碼驗證（失敗回 401）；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）任務。仍在執行中的任務會被排除——執行中的 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 |
| `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 |