@kienntpixon/dieu-phoi 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog — @kienntpixon/dieu-phoi
 
+## 0.2.1
+
+- **Định dạng `task_id` được kiểm:** đúng 8 ký tự `[a-z0-9]`. Một phiên thật đã tự bịa `almanac-cat-1791568325` làm root id mà không gì chặn. `plan-table --approve` (cả `--root` lẫn `task_id` từng bước), `choose --task`, `verdict --task`, `steer --task` giờ từ chối id sai: exit ≠ 0, lỗi tiếng Việt nêu id sai và gợi ý một id mới hợp lệ (`task_id "…" không hợp lệ: cần đúng 8 ký tự a-z0-9 (vd. k3f9x2ab)`), không ghi gì. `plan-table` không `--approve` chỉ cảnh báo trên stderr.
+- Lệnh mới `dieu-phoi new-id [--count n] [--json]`: in task_id mới hợp lệ, mỗi dòng một id (sinh bằng `crypto`), để điều phối viên không bao giờ tự bịa id.
+- Core (`hook.cjs`) export `isValidTaskId`, `newTaskId`, `taskIdError` — một chỗ duy nhất cho cả CLI và hook.
+- Hook không từ chối hay bỏ sự kiện: vẫn nhận dạng cũ `[A-Za-z0-9_-]{1,32}` để log/phiên cũ còn đọc được, nhưng `dispatch` có id sai định dạng mang thêm `task_id_invalid: true` (trường bổ sung, `schema` vẫn 1). `doctor` có dòng `task-ids`: CẢNH BÁO khi có dispatch như vậy trong 7 ngày gần đây.
+- Hook `SessionStart(compact)` thêm trường `systemMessage`: một dòng tiếng Việt cho người dùng, vd. `dieu-phoi: đã nạp lại trạng thái điều phối sau khi nén (6 task, 2 agent đang chạy, 2 bước chưa giao)` — cùng số đếm với dòng tiêu đề trạng thái. Phiên không có dispatch của dieu-phoi vẫn không in gì.
+
+## 0.2.0
+
+- **Nâng cấp:** **dán lại `sheet/Code.gs` và deploy bản mới TRƯỚC khi nâng CLI** — Code.gs cũ bỏ qua (làm rơi) các trường mới `session_id, orch_ctx_tokens, orch_cum_usd, orch_ctx_baseline, orch_compactions` của bản ghi được đẩy lên trong lúc chưa cập nhật; sau đó `npm i -g @kienntpixon/dieu-phoi@0.2.0` rồi `dieu-phoi setup`.
+- `plan-table --approve --root <root_task_id>`: sau khi người dùng duyệt cổng 1, ghi kế hoạch đã duyệt (tier từng bước đúng như bảng, đã áp override) vào `data/plans/<root>.json` — cục bộ, không phải sự kiện. `approval` = số lần duyệt (khác `round` của verdict); duyệt lại = +1, lần cũ vào `history`. `--approve` từ chối (không ghi gì) khi bước thiếu `task_id`, `task_id` lặp, hoặc `task_id` trùng `--root`.
+- `state` nhóm task theo kế hoạch đã duyệt: tier đã duyệt của từng bước (override sau lúc duyệt thắng), thư mục chạy theo root, bước chưa giao hiện "chưa giao (cổng 2)", task chỉ có verify không thuộc kế hoạch ghi "chỉ có verify".
+
+- Đo context của **phiên điều phối** (session chính). Helper `orchestratorUsage(transcriptPath, pricing, {cacheFile, coldMaxBytes})` trả `ctx_tokens` (input + cache_creation + cache_read + output của request cuối; gộp theo requestId, bỏ dòng `isSidechain` và `<synthetic>`), `ctx_baseline` (như vậy của request đầu), `ctx_growth` = max(0, ctx − baseline), `cum_usd` (tổng chi phí mọi request theo giá model của từng request). File thiếu/hỏng → null, không bao giờ lỗi.
+- Đọc **tăng dần**: trạng thái mỗi session ở `data/orch/<session_id>.json`; mỗi lần chỉ đọc phần byte mới, theo khối 1 MB (không đọc nguyên file). File ngắn lại / đầu file đổi → tính lại. Hook gặp transcript > 32 MB chưa có cache → chỉ đọc đầu + đuôi (ctx, baseline; `cum_usd` null), lần `ctx`/`choose` kế tiếp tính đủ. Đo trên transcript thật 176 MB: quét đủ lần đầu ~215 ms / RSS ~75 MB, các lần sau chỉ đọc phần mới.
+- Hook: `dispatch` có thêm `session_id`, `orch_ctx_tokens`, `orch_ctx_baseline`, `orch_cum_usd` (tại lúc giao việc). Trường bổ sung, `schema` vẫn 1.
+- Lệnh mới `dieu-phoi ctx [--session <id>] [--json]`: session mặc định `$CLAUDE_CODE_SESSION_ID`; trả `session_id, ctx_tokens, ctx_baseline, ctx_growth, cum_usd, compactions, soft_cap, over, advice`. `over` = độ **tăng** so với request đầu vượt trần mềm → khuyên gõ `/compact` (trạng thái điều phối được nạp lại tự động).
+- Đếm số lần nén context (dòng `compact_boundary` trong transcript chính): `compactions` trong `ctx --json`, `orch_compactions` trên `dispatch`, `compactions_total` / `compactions_max` trong `orchestration` (CLI + sink). Sau khi nén, độ tăng vẫn so với baseline gốc và không âm.
+- Lệnh mới `dieu-phoi state [--session <id>] [--json]`: trạng thái điều phối của phiên dựng lại chỉ từ `events.jsonl` (cổng, vòng, tier, các lượt, verdict, steer, thư mục chạy); bản chữ tiếng Việt ≤ 8.000 ký tự.
+- Hook xử lý `SessionStart` (matcher `compact`): phiên có dispatch của dieu-phoi → in `hookSpecificOutput.additionalContext` = dòng "dieu-phoi: ngữ cảnh vừa được nén; trạng thái điều phối hiện tại (dựng từ log):" + trạng thái; phiên khác → im lặng. `setup` đăng ký (không nhân đôi, có sao lưu), `uninstall` gỡ, `doctor` kiểm.
+- Profile có khoá `orch_ctx_soft_cap` = số token tăng cho phép (mặc định 60000; profile chỉ được hạ).
+- `choose --json` thêm `orch_ctx_tokens`, `orch_ctx_growth`, `orch_ctx_over`; bản chữ thêm một dòng cảnh báo khi vượt. Đo lỗi không làm `choose` lỗi.
+- `stats` / `stats --json` / `retro --json` (và sink `view=stats`) có `orchestration`: `sessions, ctx_p50, ctx_max, growth_p50, growth_max, orch_usd_total, sub_usd_total, orch_share` (CONTRACT, "Thước đo" mục 6). `doctor` hiện context phiên hiện tại nếu đo được.
+- `setup` tạo thư mục báo cáo **`~/.dieu-phoi/runs`** (env `DIEU_PHOI_RUNS_DIR` để đổi) và thêm vào `permissions` của settings.json (không nhân đôi, có sao lưu): `allow` `Read(~/.dieu-phoi/runs/**)` + `Edit(~/.dieu-phoi/runs/**)`, `additionalDirectories` += thư mục đó — để subagent nền ghi được báo cáo. Thư mục nằm ngoài `~/.claude` vì `.claude` là protected path (luật allow không duyệt trước việc ghi vào đó). Không thêm `Write(…)` (Claude Code bỏ qua luật đường dẫn cho Write và cảnh báo; luật Edit đã áp cho mọi công cụ ghi file). Luật của bản dev cho `~/.claude/dieu-phoi/runs` bị gỡ. `uninstall` gỡ đúng các mục này; `doctor` có dòng `run-permissions` và `runs_dir` trong `--json`.
+- `plan-table` có cột **Rubric (điểm · kiểm chứng · đảo ngược)** để người dùng thấy và duyệt đầu vào của sàn an toàn; `--json` có `score, verifiable, reversible` mỗi bước.
+- Sink: thêm cột `session_id, orch_ctx_tokens, orch_cum_usd, orch_ctx_baseline`; tab cũ tự được nối thêm cột ở bên phải ở lần ghi kế tiếp. **Cần dán lại `sheet/Code.gs` và deploy bản mới.**
+
 ## 0.1.2
 
 - `package.json` có `repository` / `homepage` / `bugs` trỏ về `https://git.pixon.cc/ai-lab/dieu-phoi`. Không đổi code.

package/README.md

@@ -8,6 +8,8 @@ Hook + CLI cho skill **dieu-phoi**: ghi lại mỗi lần Claude Code giao việ
 
 ## Cài đặt
 
+> Nâng cấp lên 0.2.0: **dán lại `sheet/Code.gs` và deploy bản mới TRƯỚC khi nâng CLI** — Code.gs cũ bỏ qua (làm rơi) các trường mới `session_id, orch_ctx_tokens, orch_cum_usd, orch_ctx_baseline, orch_compactions` của bản ghi được đẩy lên trong lúc chưa cập nhật; sau đó `npm i -g @kienntpixon/dieu-phoi@0.2.0` rồi `dieu-phoi setup`.
+
 Khuyến nghị cài toàn cục để skill gọi được `dieu-phoi …` trực tiếp:
 
 ```bash
@@ -32,17 +34,20 @@ Khởi động lại Claude Code sau khi cài. Kiểm tra bằng `dieu-phoi doct
 
 | Lệnh | Việc |
 |---|---|
-| `setup [--dept D] [--sink-url U --sink-token T] [--skill-dir P]` | cài hook, đăng ký trong settings, ghi config |
-| `doctor [--json]` | kiểm node, hook, settings, config, profile, sink |
+| `setup [--dept D] [--sink-url U --sink-token T] [--skill-dir P]` | cài hook, đăng ký `PostToolUse(Agent)` + `SubagentStop` + `SessionStart(compact)` trong settings, ghi config; tạo thư mục báo cáo `~/.dieu-phoi/runs` (env `DIEU_PHOI_RUNS_DIR` để đổi; ngoài `~/.claude` vì đó là protected path) và thêm quyền `Read`/`Edit(~/.dieu-phoi/runs/**)` + `additionalDirectories` để subagent nền ghi được báo cáo (không nhân đôi, có sao lưu); gỡ luật cũ của bản dev cho `~/.claude/dieu-phoi/runs` |
+| `doctor [--json]` | kiểm node, hook, settings, config, profile, sink; context phiên điều phối hiện tại nếu đo được (`orch-ctx`); thư mục `~/.dieu-phoi/runs` + quyền của nó, không còn luật cũ (`run-permissions`); `--json` có `runs_dir` |
 | `verdict <agent_id\|last> <pass\|fail\|timeout> [--verify tests\|lint\|review\|judgment\|none] [--reason short-kebab]` | nghiệm thu tầng agent (`by=agent`). `last` = agent hoàn thành gần nhất; từ chối (liệt kê ứng viên) nếu trong 30 phút qua có > 1 agent xong mà chưa có verdict. Được viết tắt agent_id nếu không trùng |
 | `verdict --task <task_id> <accept\|reject> [--cause quality\|scope] [--round n] [--reason R]` | nghiệm thu của **người dùng** (`by=user`). `reject` bắt buộc `--cause`: `quality` = làm sai (tính là fail), `scope` = yêu cầu đổi/thiếu (không tính cho model). `--round` mặc định tự tăng |
 | `steer <agent_id> \| --task <task_id> --kind minor\|plan\|redirect [--reason R]` | ghi **một** lần người dùng lái giữa chừng (một `steer_id`). `--task` chỉ đánh dấu agent đang chạy của task; không có agent nào đang chạy → bản ghi cấp task. `plan`/`redirect` trước verdict loại lượt đó khỏi tỉ lệ của tier (chi phí vẫn tính); steer không xoá fail đã ghi |
-| `stats [--type T] [--json]` | các ô `task_type × model/effort` theo "Thước đo" của `CONTRACT.md`: n, n_excluded, accept_rate, agent_pass_rate, chi phí/thời gian mỗi task (TB, p50, p75); bảng steer theo task_type |
-| `choose --type T --score N [--urgency U] [--reversible y\|n] [--verifiable y\|n] [--role R] [--task ID] [--override M/E \| --approved M/E] [--skill-dir P] [--seed S] [--json]` | đề xuất model + effort kèm lý do, `action`, `role`, ước tính chi phí/thời gian. `--override` cần `--task` |
-| `plan-table --file <steps.json> [--json]` | bảng phân công tiếng Việt (Bước \| Model/effort \| Lý do \| Ước tính) + tổng chi phí + thời gian đường găng. Bước lỗi (override sai) hiện \"từ chối: …\", các bước khác vẫn hiện |
+| `stats [--type T] [--json]` | các ô `task_type × model/effort` theo "Thước đo" của `CONTRACT.md`: n, n_excluded, accept_rate, agent_pass_rate, chi phí/thời gian mỗi task (TB, p50, p75); bảng steer theo task_type; tóm tắt điều phối (`orchestration`: số phiên, context p50/max, chi phí điều phối vs subagent, `orch_share`) |
+| `choose --type T --score N [--urgency U] [--reversible y\|n] [--verifiable y\|n] [--role R] [--task ID] [--override M/E \| --approved M/E] [--skill-dir P] [--seed S] [--json]` | đề xuất model + effort kèm lý do, `action`, `role`, ước tính chi phí/thời gian. `--override` cần `--task`. Kèm `orch_ctx_tokens`, `orch_ctx_growth`, `orch_ctx_over` (như `ctx`); vượt trần mềm → thêm một dòng cảnh báo |
+| `ctx [--session <id>] [--json]` | context phiên điều phối: `ctx_tokens` (request cuối), `ctx_baseline` (request đầu: system prompt + tools), `ctx_growth`, chi phí cộng dồn `cum_usd`, số lần đã nén `compactions`; `over` = `ctx_growth` > `orch_ctx_soft_cap` (profile, mặc định 60000 token tăng, chỉ được hạ). Session mặc định = `$CLAUDE_CODE_SESSION_ID`. JSON: `session_id, ctx_tokens, ctx_baseline, ctx_growth, cum_usd, compactions, soft_cap, over, advice`. Vượt trần → khuyên gõ `/compact` (trạng thái điều phối được nạp lại tự động). Đọc tăng dần qua cache `data/orch/`. Không đo được → exit 0, các số `null`, `over: false` |
+| `state [--session <id>] [--json]` | trạng thái điều phối của phiên dựng lại chỉ từ log: mỗi task — cổng (1/2/3/xong), vòng, tier, các lượt (agent, role, try, model/effort, running/done/pass/fail/timeout), verdict người dùng, steer cuối, thư mục chạy; nhóm theo kế hoạch đã duyệt (tier đã duyệt, bước "chưa giao", thư mục chạy theo root). Hook `SessionStart(compact)` tự nạp bản này vào ngữ cảnh sau `/compact` hoặc auto-compact. Bản chữ ≤ 8.000 ký tự |
+| `plan-table --file <steps.json> [--json] [--approve --root <root_task_id>]` | bảng phân công tiếng Việt (Bước \| Model/effort \| Rubric: điểm · kiểm chứng · đảo ngược \| Lý do \| Ước tính) + tổng chi phí + thời gian đường găng. Bước lỗi (override sai) hiện \"từ chối: …\", các bước khác vẫn hiện. Sau khi người dùng duyệt: `--approve --root R` ghi kế hoạch đã duyệt vào `data/plans/R.json` (cục bộ; `approval` = số lần duyệt, duyệt lại = +1, lần cũ vào `history`) và in thêm "Đã ghi kế hoạch đã duyệt (root R, lần duyệt n)". Từ chối (không ghi gì) khi bước thiếu `task_id`, `task_id` sai định dạng, `task_id` lặp, hoặc trùng `--root`; `--root` phải đúng 8 ký tự `a-z0-9` |
+| `new-id [--count n] [--json]` | in task_id mới hợp lệ (đúng 8 ký tự `a-z0-9`), mỗi dòng một id (mặc định 1, tối đa 1000; `--json`: mảng). Lấy mọi `task_id` / `root_task_id` từ đây — không tự bịa. `choose/verdict/steer --task` và `plan-table --approve` từ chối id sai định dạng (kèm gợi ý id mới); hook vẫn ghi id cũ nhưng gắn `task_id_invalid: true`, `doctor` cảnh báo |
 | `sync [--json]` | đẩy bản ghi chưa đồng bộ lên sink, lô ≤ 200, có thử lại. Bản ghi sink từ chối → `data/sync-rejected.jsonl`, `doctor` báo số lượng |
-| `retro [--json]` | tóm tắt cho vòng retro: số liệu từng ô, đếm `reason_code`, danh sách loại task |
-| `uninstall [--purge]` | gỡ hook khỏi settings (có sao lưu); `--purge` xoá cả `hook.cjs`. Dữ liệu giữ lại |
+| `retro [--json]` | tóm tắt cho vòng retro: số liệu từng ô, đếm `reason_code`, danh sách loại task, tóm tắt điều phối (`orchestration`) |
+| `uninstall [--purge]` | gỡ hook và đúng các quyền thư mục `runs` đã thêm khỏi settings (có sao lưu); `--purge` xoá cả `hook.cjs`. Dữ liệu giữ lại |
 
 ### `choose`
 
@@ -76,14 +81,15 @@ Kết quả `--json`: `{"action":"dispatch","model":"sonnet","model_id":"claude-
 
 ### `plan-table`
 
-Đầu vào: mảng JSON `[{"step":"A","type":"search","score":2},{"step":"B","type":"feature-impl","score":6,"depends_on":["A"],"verifiable":"n"}]`. Mỗi bước chạy qua `choose`; bước không có `depends_on` chạy song song. Đầu ra: bảng markdown để trình người dùng duyệt trước khi giao, kèm tổng chi phí và thời gian đường găng; `--json` cho máy đọc.
+Đầu vào: mảng JSON `[{"step":"A","type":"search","score":2},{"step":"B","type":"feature-impl","score":6,"depends_on":["A"],"verifiable":"n"}]`. Mỗi bước chạy qua `choose`; bước không có `depends_on` chạy song song. Đầu ra: bảng markdown để trình người dùng duyệt trước khi giao (cột Rubric hiện `điểm · kiểm chứng y/n · đảo ngược y/n` của từng bước — các đầu vào quyết định sàn an toàn, để người dùng bắt lỗi chấm điểm), kèm tổng chi phí và thời gian đường găng; `--json` cho máy đọc.
 
 ## Dữ liệu
 
 - Sự kiện: `~/.claude/dieu-phoi/data/events.jsonl` (`dispatch`, `complete`, `verdict`, `steer`, `override`; `schema: 1`), xem `CONTRACT.md`. File chỉ ghi nối (append-only), không bao giờ viết lại. Tiến độ đẩy lên sink nằm ở `data/sync-offset.json` (byte offset sau dòng cuối đã đẩy); trạng thái segment từng agent ở `data/segments/<agent_id>.json`.
 - Lỗi của hook: `~/.claude/dieu-phoi/hook-errors.log`.
 - Subagent nội bộ của Claude Code (không có transcript, không qua Agent tool) không được ghi; số lần bỏ qua ở `data/skipped-internal.json`. Log cũ của 0.1.0 có các `complete` rỗng loại này — `stats`/`retro` tự bỏ qua, không cần sửa file (từ 0.1.1).
-- Người dùng và phiên chỉ lưu dạng sha256 rút gọn 8 ký tự (người dùng = `git config user.email`, không có thì tên tài khoản máy).
+- Người dùng chỉ lưu dạng sha256 rút gọn 8 ký tự (`git config user.email`, không có thì tên tài khoản máy). Phiên: `session` = sha256-8; từ 0.2.0 `dispatch` có thêm `session_id` thô (mã phiên, không phải nội dung) để nối với `dieu-phoi ctx`.
+- Trạng thái đo phiên điều phối: `data/orch/<session_id>.json` (offset đã đọc, tổng chi phí, baseline — không có đường dẫn hay nội dung; quá 14 ngày tự xoá).
 - Chi phí tính theo giá API trong `pricing.json` (USD / 1M token), đếm usage một lần cho mỗi `requestId`. Hệ số ghi cache (×1.25 cho 5 phút, ×2 cho 1 giờ) là **giả định**. Model không có giá → `cost_usd: null`. Ghi đè giá trong `config.json`:
 
 ```json

package/bin/dieu-phoi.cjs

@@ -24,8 +24,14 @@ Cách dùng: dieu-phoi <lệnh> [tuỳ chọn]
          [--verifiable y|n] [--role exec|verify|plan] [--task ID]
          [--override model/effort (cần --task) | --approved model/effort] [--skill-dir P] [--seed S] [--json]
                          đề xuất model + effort, lý do, action (dispatch|ask_user), ước tính chi phí/thời gian
-  plan-table --file <steps.json> [--json]
+  ctx [--session <id>] [--json]
+                         context + chi phí của phiên điều phối (mặc định $CLAUDE_CODE_SESSION_ID) so với trần mềm
+  state [--session <id>] [--json]
+                         trạng thái điều phối của phiên dựng lại từ log (cũng được nạp tự động sau /compact)
+  plan-table --file <steps.json> [--json] [--approve --root <root_task_id>]
                          bảng phân công: Bước | Model/effort | Lý do | Ước tính + tổng + đường găng
+  new-id [--count n] [--json]
+                         in task_id mới hợp lệ (8 ký tự a-z0-9), mỗi dòng một id — không tự bịa id
   sync                   đẩy bản ghi chưa đồng bộ lên sink
   retro [--json]         tóm tắt cho vòng retro (không chứa nội dung)
   uninstall [--purge]    gỡ hook khỏi settings.json (--purge xoá cả hook.cjs; dữ liệu giữ lại)
@@ -47,7 +53,10 @@ async function main(argv) {
   }
   if (cmd === 'hook') {
     // Hook mode: never print, always exit 0.
-    try { require('../lib/commands.cjs').cmdHook(opts); } catch (e) { core.logError(null, e, 'cli-hook'); }
+    try {
+      const r = require('../lib/commands.cjs').cmdHook(opts);
+      if (r && r.out) process.stdout.write(r.out);
+    } catch (e) { core.logError(null, e, 'cli-hook'); }
     return 0;
   }
   const c = require('../lib/commands.cjs');
@@ -57,8 +66,11 @@ async function main(argv) {
     verdict: c.cmdVerdict,
     steer: c.cmdSteer,
     'plan-table': c.cmdPlanTable,
+    'new-id': c.cmdNewId,
     stats: c.cmdStats,
     choose: c.cmdChoose,
+    ctx: c.cmdCtx,
+    state: c.cmdState,
     sync: c.cmdSync,
     retro: c.cmdRetro,
     uninstall: c.cmdUninstall,