# Usage observability

Mục tiêu: biết Pi session đang tiêu hao token/context/cost như nào mà không phải hỏi model bằng ngôn ngữ tự nhiên.

## Trong Pi TUI

Pi có sẵn footer hiển thị token/cache usage, cost, context usage, model hiện tại. Khi cần chi tiết hơn, chạy:

```text
/session
```

Piagent package thêm command:

```text
/usage
/context preflight
/context compact
/usage logs
/usage live
/usage efficiency
```

Agent cũng có thể gọi tool:

```text
piagent_usage_snapshot
piagent_context_preflight
```

`/usage` hiển thị:

- session file;
- session id/name;
- cwd;
- model;
- live context usage hiện tại;
- active branch entries / total entries;
- lệnh để lấy exact token/cost totals từ terminal khác.

`/context preflight` hiển thị:

- workflow đang định chạy;
- live context;
- estimated input tokens;
- projected context;
- recommendation: `ok`, `watch`, `compact`, hoặc `fresh-session`;
- fresh workflow commands nếu session hiện tại quá nặng.

`/context compact` gọi Pi compaction với hướng dẫn giữ lại decisions, blockers, changed files, verify command, và next action.

`/usage logs` không tail realtime. Nó chỉ hiển thị policy compact và vài capture mới nhất khi tool output quá dài. Capture nằm trong `.pi/piagent-state/tool-results/`, đã qua redaction trước khi ghi, để Agent Watch/report đọc offline mà Pi TUI không phải nhồi full terminal log vào transcript. Alias `/logs` vẫn chạy.

`/usage efficiency` đọc local Context Engine telemetry và hiện công thức
`contextWasteScore`: duplicate reads, duplicate output, tool-schema share,
low-confidence retrieval, và active-tool excess. Score này phải đi cùng task
gate/verify result; nó không tự kết luận model hoặc nhân viên làm tốt/xấu.

Giới hạn kỹ thuật: extension command context expose `ctx.getContextUsage()`, phù hợp để biết context window đang dùng bao nhiêu. Exact billed totals như `input`, `output`, `cacheRead`, `cacheWrite`, `cost` là API của Pi `/session` và RPC `get_session_stats`.

## Từ terminal khác

Nếu đang có một Pi session chạy ở project khác, mở terminal mới:

```bash
piagent-usage /path/to/project
```

Hoặc dùng script trực tiếp:

```bash
bash scripts/pi-session-stats.sh /path/to/project
```

Script sẽ:

1. tìm session `.jsonl` mới nhất có header `cwd` khớp project path;
2. gọi Pi RPC `get_session_stats`;
3. in JSON gồm messages, token totals, cost và context usage.

Ví dụ output:

```json
{
  "tokens": {
    "input": 121095,
    "output": 8088,
    "cacheRead": 2023936,
    "cacheWrite": 0,
    "total": 2153119
  },
  "cost": 1.860083,
  "contextUsage": {
    "tokens": 102996,
    "contextWindow": 272000,
    "percent": 37.866176470588236
  }
}
```

## Usage lịch sử / report tuần

`piagent-usage /path/to/project` chỉ trả exact stats của session mới nhất. Để xem tổng usage đã lưu trên máy, kể cả session đã end hoặc subagent runs:

```bash
piagent-usage --history /path/to/project
piagent-usage --history /path/to/project --days 7
piagent-usage --history --all-projects --days 7 --csv
piagent-usage --history --all-projects --since 2026-07-20 --until 2026-07-26 --json
```

History mode đọc trực tiếp `~/.pi/agent/sessions/**/*.jsonl`, cộng usage từ từng assistant message:

- `input`, `output`, `cacheRead`, `cacheWrite`, `reasoning`, `totalTokens`;
- `cost.total`;
- số user messages, assistant messages, tool calls, tool results;
- session name từ `session_info.name`, dùng để Agent Watch/report đối chiếu task;
- breakdown theo project và top sessions.

Để session name rõ ngay trong report, mở Pi bằng:

```bash
pi --name "ABC-123 Short task name"
```

Hoặc đổi tên phiên đang mở trong Pi:

```text
/name ABC-123 Short task name
```

Alias ngắn `/setname ABC-123 Short task name` vẫn chạy. Nếu tắt nhầm terminal/app, vào lại project rồi dùng `pi --continue` cho phiên gần nhất, hoặc `pi --resume` để chọn theo session name/id. Trong Pi có thể gõ `/resume` để xem reminder ngắn.

Mặc định history mode **bao gồm subagent session files** vì đó là usage thật của máy. Dùng `--no-subagents` khi chỉ muốn parent/main sessions.

Format hỗ trợ:

| Format | Lệnh |
|---|---|
| Human table | `piagent-usage --history <project>` |
| JSON | `piagent-usage --history <project> --json` |
| CSV | `piagent-usage --history <project> --csv` |
| Markdown | `piagent-usage --history <project> --markdown` |

## Cách đọc số

| Field | Ý nghĩa |
|---|---|
| `input` | Token input thật gửi vào model. |
| `output` | Token model sinh ra. |
| `cacheRead` | Token đọc từ provider prompt cache. Số này có thể rất lớn nhưng không tương đương fresh input cost. |
| `cacheWrite` | Token ghi vào cache. |
| `total` | Tổng theo Pi stats. |
| `cost` | Cost Pi tính theo pricing metadata của model/provider. |
| `contextUsage.tokens` | Context window hiện đang bị chiếm bao nhiêu token. |
| `contextUsage.percent` | Phần trăm context window hiện tại. |

## Khi nào cần compact

Xem `contextUsage.percent`:

- `< 50%`: bình thường.
- `50–70%`: bắt đầu tránh đọc file lớn không cần thiết.
- `70–82%`: chạy `/context compact` trước task dài tiếp theo.
- `> 82%`: dùng `/fresh task`, `/fresh scout`, hoặc `/fresh be-to-fe` cho work mới.
- Sau compaction, `contextUsage.tokens` có thể là `null` cho đến khi có assistant response mới.

Nếu user paste full mandatory-flow boilerplate, platform input guard sẽ collapse về workflow command ngắn. Nếu prompt quá dài thật, platform có thể lưu intake vào `.pi/task-inbox/` local gitignored rồi replay bằng fresh workflow command.

Tool output dài cũng bị compact theo cùng triết lý: chat giữ preview, audit/report giữ capture local. Nếu verify fail và preview chưa đủ, chạy lại command targeted hơn thay vì đổ full log vào session.

## Khi nào ghi benchmark

Sau một task cần so sánh workflow/model bằng số liệu:

```bash
bash scripts/quality-benchmark.sh /path/to/project --record \
  --scenario bounded-source-fix \
  --surface pi \
  --result pass \
  --tokens <total-from-piagent-usage> \
  --cost <cost-from-piagent-usage> \
  --verify "<verify-command>"
```

Không dùng ước lượng ký tự để claim tiết kiệm token. Dùng `/session`, RPC `get_session_stats`, hoặc `piagent-usage`.