# Session 端點

讀取、更新、刪除 session 及其待決與已完成任務的端點。

| Method | 路徑 | 說明 |
|---|---|---|
| `GET` | `/v1/sessions` | 列出 session 與狀態 |
| `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/event` | **local** — 對某 session 的串流發布事件 |
| `POST` | `/v1/session/:id/memory` | **local** — 由 `action` 決定的單一記憶操作：`summary` 重建滾動摘要並回傳 `count`；`compact` 丟棄較舊訊息並回傳 `removed`；`reset` 清空對話並回傳 `removed`，且必須帶 `mode`——`summary` 保留滾動摘要、`all` 一併清除 |
| `POST` | `/v1/session/:id/cancel/:task_hash` | 取消單一執行中任務。該 task hash 在本行程執行中時回 `{ok, cancelled:true}`；否則（或傳 `current`）會在 session 串流記錄一筆 canceled 事件並回 `{ok, cancelled:false, stale:true}` |
| `POST` | `/v1/session/:id/confirm/:confirm_hash` | 回覆待決的工具確認：`{approve, remember?, allow_turn?, abort?, reason?, password?}`。確認已被回覆或已過期時回 410。核准帶有 `restricted` 路徑的確認必須來自 loopback（否則 403），並以 `password` 通過作業系統密碼驗證（失敗回 401）；sudo ticket 仍有快取時略過驗證，確認事件以 `password_cached` 標示 |

## 待決與已完成任務

| Method | 路徑 | 說明 |
|---|---|---|
| `GET` | `/v1/session/:id/task` | 列出可續行的待決（`ask_user` / confirm）任務。仍在執行中的任務會被排除——執行中的 run 每 55 秒刷新 ToriiDB 的 `action:<session_id>:<task_hash>`（TTL 60 秒，v0.35.3），因此視窗關閉或行程被砍留下的任務會在一分鐘內重新出現 |
| `GET` | `/v1/session/:id/task/:task_hash/questions` | 取得待決任務的提問 |
| `POST` | `/v1/session/:id/task/:task_hash/resume` | 回答待決任務並續行 |
| `DELETE` | `/v1/session/:id/task/:task_hash` | 不回答，直接丟棄待決任務 |
| `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 |