Add 5 pi extensions: pi-subagents, pi-crew, rpiv-pi, pi-interactive-shell, pi-intercom
This commit is contained in:
@@ -0,0 +1,819 @@
|
||||
# Phase 8 — Operator Experience: Interactive Mailbox, Health Pane, Smart Notifications
|
||||
|
||||
> Tiếp nối tự nhiên của Phase 7 (UI Optimization). Mục tiêu: biến dashboard từ "viewer" thành "operator console" — actions thực hiện được trực tiếp từ UI, không phải toggle CLI. Path X chosen (Phase 8 = Theme A, Phase 9 = Theme B+C Observability+Reliability deferred).
|
||||
|
||||
**Open Questions Resolution (Q1-Q6 đã chốt — xem Section 7 chi tiết):**
|
||||
- Q1=(b) Có preview compose pane | Q2=(c) Sink JSONL khi `telemetry.enabled` | Q3=(b) Cross-day quiet-hours wrap
|
||||
- Q4=(c) Full action menu R/K/D trên health pane | Q5=(c) Confirm chỉ destructive | Q6=(a) ESC discard + confirm-if-long guard
|
||||
|
||||
## 0. Implementation Status
|
||||
|
||||
- [x] 8.0 Foundation: keybinding contract + action dispatcher + RunActionResult shape + ConfirmOverlay primitive
|
||||
- [x] 8.1.A Mailbox detail overlay (passive list view, no actions yet)
|
||||
- [x] 8.1.B Mailbox ack action (hotkey `A` trên message đang chọn)
|
||||
- [x] 8.1.C Mailbox nudge action (hotkey `N` + agent picker)
|
||||
- [x] 8.1.D Mailbox compose action (hotkey `C` + form overlay) — Q6: ESC discard + confirm-if-long (>50 chars)
|
||||
- [x] 8.1.E Mailbox compose preview pane (key `P` toggle, render markdown read-only) — Q1
|
||||
- [x] 8.1.F Mailbox ackAll destructive action (hotkey `Shift+X`) — Q5: requires confirm overlay
|
||||
- [x] 8.2.A Heartbeat aggregator (`heartbeat-aggregator.ts`)
|
||||
- [x] 8.2.B Health pane (pane index `5`) trong dashboard
|
||||
- [x] 8.2.C Auto-recovery prompt (stuck worker > N minutes → toast + confirm) — throttled 5min/run
|
||||
- [x] 8.2.D Health pane action menu — `R` recovery (foreground only), `K` kill stale workers, `D` diagnostic export — Q4
|
||||
- [x] 8.3.A Notification router (severity classifier + dedup window)
|
||||
- [x] 8.3.B Notification quiet-hours (cross-day wrap parser) + batching config — Q3
|
||||
- [x] 8.3.C Toast badge counter trong widget/powerbar (đếm số notification chưa ack)
|
||||
- [x] 8.3.D Notification JSONL sink rotate 7 ngày, gated bởi `telemetry.enabled` — Q2
|
||||
- [x] 8.4 Wire `register.ts` + `commands.ts`
|
||||
- [x] 8.5 Tests: unit + integration
|
||||
|
||||
## 1. Roadmap-Level Decisions
|
||||
|
||||
| # | Decision | Chosen | Rationale |
|
||||
|---|---|---|---|
|
||||
| D1 | Mailbox actions chạy trực tiếp hay dispatch về team API? | **Dispatch** qua `handleTeamTool({action:"api", config:{operation:...}})` | Tận dụng API hiện có (`ack-message`, `send-message`, `nudge-agent`); zero state-machine duplication; locks/events được giữ nguyên |
|
||||
| D2 | Overlay form vs inline edit? | **Overlay form** (modal-like, anchor center) | Dashboard sidebar quá hẹp cho text input; overlay tách biệt focus; ESC dễ cancel |
|
||||
| D3 | Health pane là pane mới (`5`) hay tab trong progress? | **Pane mới `5`** | Tránh pollute progress pane; cho user toggle độc lập; consistent với existing 1-4 |
|
||||
| D4 | Notification sink: optional opt-in hay default-on? | **Default-on khi `telemetry.enabled !== false`** (Q2=c) | Đồng nhất pattern Phase 6 telemetry; debug-friendly; user opt-out qua telemetry config chung. Path: `<crewRoot>/state/notifications/{YYYY-MM-DD}.jsonl`, rotate 7 ngày |
|
||||
| D5 | Quiet-hours format + cross-day? | **HH:MM-HH:MM trong config local timezone, support cross-day wrap** (Q3=b) | Single range `"22:00-07:00"` parser tự nhận diện wrap-around; intuitive vs multi-range array |
|
||||
| D6 | Compose-form fields scope? | **Phase 8: from/to/body/taskId + preview pane** (Q1=b) | Preview key `P` toggle render markdown read-only; thread/attachment defer Phase 9 |
|
||||
| D7 | Action mới có break keybinding cũ? | **No** — phím mới: `A/N/C/P/Shift+X` (mailbox), `R/K/D` (health), `H/X` (notification); phím hiện hành (`s/u/a/i/d/m/e/o/v/r/p/1-4/k/j`) giữ nguyên (lowercase `r` vẫn = reload root, uppercase `R` = recovery in health pane only) | Backward-compat; context-scoped uppercase |
|
||||
| D8 | Mailbox detail panel: inline expand hay separate overlay? | **Separate overlay** (mở khi nhấn Enter trên pane mailbox) | Pane chính giữ nguyên density; overlay scrollable |
|
||||
| D9 | Health pane action mode: prompt-only vs full menu? | **Full action menu (Q4=c)**: `R` recovery (foreground-only), `K` kill stale workers, `D` diagnostic export | Operator power-user toolkit; async runs `R/K` disabled with hint; `D` cực hữu ích cho bug report |
|
||||
| D10 | Foundation 8.0: tách RunActionDispatcher hay inline? | **Tách module** `src/ui/run-action-dispatcher.ts` | Reuse cho overlay con; dễ test; không bloat dashboard |
|
||||
| D11 | Compose ESC behavior? | **Discard + confirm-if-long** (Q6=a) | ESC không lưu draft; nếu body > 50 ký tự → confirm overlay `Y=discard, N=continue editing`; defer draft persistence Phase 9 |
|
||||
| D12 | Confirm overlay: per-action ad-hoc hay reusable primitive? | **Reusable primitive** `src/ui/overlays/confirm-overlay.ts` | Q5=c destructive (ackAll/recovery/diagnostic-export-with-secrets) cần consistent UX; reuse cho mọi confirm |
|
||||
| D13 | Auto-recovery throttle window? | **5 phút/run/condition-type** | Tránh notification storm khi run dead lâu; `recovery_dead_workers` riêng biệt với `recovery_missing_heartbeat` |
|
||||
| D14 | Diagnostic export `D` format & destination? | **JSON + redact secrets** vào `<crewRoot>/artifacts/{runId}/diagnostic-{timestamp}.json` | Self-contained snapshot (manifest + tasks + recent events + heartbeat summary); confirm before write nếu artifact-dir đã có file diag cũ < 1 phút |
|
||||
| D15 | Preview pane render scope (Q1=b)? | **Read-only markdown render**: bold/italic/code-block/list — no images/links | Đủ cho operator đọc nội dung trước khi gửi; không cần markdown engine đầy đủ; reuse từ existing transcript-viewer markdown helper nếu có |
|
||||
|
||||
## 2. Phase Breakdown
|
||||
|
||||
### Phase 8.0 — Foundation (2 dev-day, +0.5 cho ConfirmOverlay)
|
||||
|
||||
**File mới:**
|
||||
- `src/ui/run-action-dispatcher.ts` — wrapper gọi `handleTeamTool` với `runId` + `operation`, normalize result thành `{ ok, message, data }`.
|
||||
- `src/ui/keybinding-map.ts` — central registry mapping `data` (raw stdin) → action name; export `KEY_RESERVED` để overlay con check conflict.
|
||||
- `src/ui/overlays/confirm-overlay.ts` — **(Q5)** reusable confirm primitive, anchor center, auto-focus `N` (safe default), Y/Enter=confirm, N/ESC=cancel. ~80 LOC.
|
||||
|
||||
**Sửa:**
|
||||
- `src/ui/run-dashboard.ts` — refactor `handleInput` dùng `keybinding-map`; không thay đổi behavior cũ.
|
||||
|
||||
**Skeleton:**
|
||||
|
||||
```ts
|
||||
// run-action-dispatcher.ts
|
||||
import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
|
||||
import { handleTeamTool } from "../extension/team-tool.ts";
|
||||
|
||||
export interface RunActionResult {
|
||||
ok: boolean;
|
||||
message: string;
|
||||
data?: unknown;
|
||||
}
|
||||
|
||||
export async function dispatchMailboxAck(ctx: ExtensionContext, runId: string, messageId: string): Promise<RunActionResult> {
|
||||
try {
|
||||
const r = await handleTeamTool({ action: "api", runId, config: { operation: "ack-message", messageId } }, ctx);
|
||||
return { ok: r.metadata?.status === "ok", message: r.text, data: r };
|
||||
} catch (error) {
|
||||
return { ok: false, message: error instanceof Error ? error.message : String(error) };
|
||||
}
|
||||
}
|
||||
|
||||
export async function dispatchMailboxNudge(ctx: ExtensionContext, runId: string, agentId: string, message: string): Promise<RunActionResult> { /* ... */ }
|
||||
export async function dispatchMailboxCompose(ctx: ExtensionContext, runId: string, payload: { from: string; to: string; body: string; taskId?: string; direction: "inbox" | "outbox" }): Promise<RunActionResult> { /* ... */ }
|
||||
export async function dispatchMailboxAckAll(ctx: ExtensionContext, runId: string): Promise<RunActionResult> { /* read-mailbox → loop ack-message */ }
|
||||
export async function dispatchHealthRecovery(ctx: ExtensionContext, runId: string): Promise<RunActionResult> { /* foreground-interrupt API */ }
|
||||
export async function dispatchKillStaleWorkers(ctx: ExtensionContext, runId: string): Promise<RunActionResult> { /* mark dead heartbeats; emit event */ }
|
||||
export async function dispatchDiagnosticExport(ctx: ExtensionContext, runId: string): Promise<RunActionResult> { /* read-manifest + list-tasks + read-events limit=200 + heartbeat summary → write artifact */ }
|
||||
```
|
||||
|
||||
```ts
|
||||
// keybinding-map.ts (Q4 + Q5 expanded)
|
||||
export const DASHBOARD_KEYS = {
|
||||
close: ["q", "\u001b"],
|
||||
select: ["\r", "\n", "s"],
|
||||
pane: { agents: ["1"], progress: ["2"], mailbox: ["3"], output: ["4"], health: ["5"] },
|
||||
// Mailbox detail overlay context
|
||||
mailbox: { ack: ["A"], nudge: ["N"], compose: ["C"], preview: ["P"], ackAll: ["X"], openDetail: ["\r", "\n"] },
|
||||
// Health pane context (Q4=c full menu)
|
||||
health: { recovery: ["R"], killStale: ["K"], diagnosticExport: ["D"] },
|
||||
// Notification context
|
||||
notification: { dismissAll: ["H"] }, // 'H' for Hush
|
||||
} as const;
|
||||
```
|
||||
|
||||
```ts
|
||||
// confirm-overlay.ts
|
||||
export interface ConfirmOptions {
|
||||
title: string;
|
||||
body?: string;
|
||||
dangerLevel?: "low" | "medium" | "high"; // colors theme accent
|
||||
defaultAction?: "confirm" | "cancel"; // default "cancel"
|
||||
}
|
||||
export class ConfirmOverlay {
|
||||
constructor(private opts: ConfirmOptions, private done: (confirmed: boolean) => void, private theme: unknown) {}
|
||||
render(width: number): string[] { /* anchor-center box, dim Y/N hint */ }
|
||||
handleInput(data: string): void {
|
||||
if (data === "y" || data === "Y" || data === "\r" || data === "\n") return this.done(true);
|
||||
if (data === "n" || data === "N" || data === "\u001b" || data === "q") return this.done(false);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Tests:**
|
||||
- `test/unit/run-action-dispatcher.test.ts` (7 test cases — 4 mailbox dispatchers + 3 health dispatchers, mock `handleTeamTool`).
|
||||
- `test/unit/confirm-overlay.test.ts` (4 cases: render, Y confirms, N cancels, default cancel safety).
|
||||
|
||||
---
|
||||
|
||||
### Phase 8.1 — Mailbox Interactivity
|
||||
|
||||
#### 8.1.A Mailbox detail overlay (1 dev-day)
|
||||
|
||||
**File mới:**
|
||||
- `src/ui/overlays/mailbox-detail-overlay.ts` — class `MailboxDetailOverlay` implement Pi UI custom widget; render 2-column (inbox | outbox); ↑/↓ select; Enter expand body; ESC/q close.
|
||||
|
||||
**Cập nhật:**
|
||||
- `src/ui/dashboard-panes/mailbox-pane.ts` — line cuối cùng đổi từ "use /team-api ..." thành `"Press Enter on mailbox pane to open detail (A=ack, N=nudge, C=compose)"`.
|
||||
- `src/ui/run-dashboard.ts` — khi `activePane === "mailbox"` và user nhấn Enter, return `{action: "mailbox-detail"}` thay vì close.
|
||||
- `src/extension/registration/commands.ts` — handle `selection.action === "mailbox-detail"` → mở `MailboxDetailOverlay` qua `ctx.ui.custom`.
|
||||
|
||||
**Skeleton:**
|
||||
|
||||
```ts
|
||||
export class MailboxDetailOverlay {
|
||||
private inbox: MailboxMessage[] = [];
|
||||
private outbox: MailboxMessage[] = [];
|
||||
private selected = 0;
|
||||
private side: "inbox" | "outbox" = "inbox";
|
||||
constructor(private opts: { runId: string; cwd: string; ctx: ExtensionContext; done: (sel?: MailboxAction) => void; theme: unknown }) {
|
||||
this.refresh();
|
||||
}
|
||||
private refresh(): void { /* read mailbox via team api */ }
|
||||
render(width: number): string[] { /* 2-col layout, highlight selected */ }
|
||||
handleInput(data: string): void { /* arrow nav, A/N/C dispatch via this.opts.done */ }
|
||||
}
|
||||
|
||||
export interface MailboxAction {
|
||||
type: "ack" | "nudge" | "compose" | "reply";
|
||||
messageId?: string;
|
||||
agentId?: string;
|
||||
}
|
||||
```
|
||||
|
||||
**Tests:** `test/unit/mailbox-detail-overlay.test.ts` — 4 cases (render empty, render with items, key navigation, action dispatch).
|
||||
|
||||
#### 8.1.B Ack action (0.75 dev-day)
|
||||
|
||||
**Logic:** trong `MailboxDetailOverlay.handleInput`, key `A` (uppercase, để tránh conflict với `a`=artifacts ở dashboard root) → `done({type:"ack", messageId: selectedMessage.id})`.
|
||||
|
||||
**Update `commands.ts`:** sau khi overlay close, nếu action.type === "ack" → call `dispatchMailboxAck(ctx, runId, action.messageId!)` → toast result.
|
||||
|
||||
**Acceptance:** ack thành công → mailbox pane re-render với attention count giảm trong < 250ms (snapshot cache invalidate khi `crew.mailbox.acknowledged` event).
|
||||
|
||||
#### 8.1.C Nudge action (0.75 dev-day)
|
||||
|
||||
**Logic:** key `N` → mở agent picker overlay (reuse pattern từ existing `LiveRunSidebar`); chọn xong → message input → dispatch `dispatchMailboxNudge`.
|
||||
|
||||
**File mới:** `src/ui/overlays/agent-picker-overlay.ts` (nhỏ, 80-120 LOC).
|
||||
|
||||
**Acceptance:** nudge → `crew.mailbox.message` event fire → snapshot invalidate → mailbox pane attention count tăng đúng.
|
||||
|
||||
#### 8.1.D Compose form (1.25 dev-day)
|
||||
|
||||
**File mới:** `src/ui/overlays/mailbox-compose-overlay.ts` — form 4 field (from/to/body/taskId), Tab navigation, Enter submit, ESC cancel.
|
||||
|
||||
**Behavior chi tiết (Q6=a):**
|
||||
- Tab/Shift+Tab: cycle giữa các field.
|
||||
- Body multi-line: Ctrl+Enter → newline; Enter trên field body với content non-empty → submit.
|
||||
- ESC khi body ≤ 50 ký tự → discard immediately, close overlay.
|
||||
- ESC khi body > 50 ký tự → mở `ConfirmOverlay` với title `"Discard draft?"` body `"Body has N chars. Y=discard, N=continue editing"`. Cancel default = continue editing (safe).
|
||||
- Submit validate: body required (non-whitespace), to required, from default `"operator"` if empty.
|
||||
- Direction toggle: Tab vào checkbox `[ ] Send to outbox` → Space toggle.
|
||||
|
||||
**Logic dispatch:** `dispatchMailboxCompose` với `direction` từ checkbox (default `"inbox"` — operator gửi vào inbox của run).
|
||||
|
||||
**Tests:** `test/unit/mailbox-compose-overlay.test.ts` — 8 cases (render, tab nav, ESC short discard, ESC long → confirm overlay, confirm overlay cancel = stay editing, confirm overlay confirm = discard, Enter submit, validation empty body, validation empty to).
|
||||
|
||||
#### 8.1.E Compose preview pane (0.75 dev-day) — Q1=b
|
||||
|
||||
**File mới:** `src/ui/overlays/mailbox-compose-preview.ts` — read-only render markdown của body field hiện tại; share state với `mailbox-compose-overlay.ts`.
|
||||
|
||||
**Layout:** compose overlay split horizontal khi preview active — 60% form / 40% preview pane (pane render markdown read-only, không cho focus).
|
||||
|
||||
**Render scope (D15):** bold (`**`), italic (`*`), code-block (`` ``` ``), inline code (`` ` ``), unordered list (`-`), numbered list (`1.`), heading (`#`/`##`/`###`). Skip images/links (out of scope; render link text only).
|
||||
|
||||
**Behavior:**
|
||||
- Key `P` toggle preview on/off (state in compose overlay).
|
||||
- Preview cập nhật real-time khi body thay đổi (debounce 100ms để tránh re-render mỗi keystroke).
|
||||
- Khi preview active, header help line update: `"P close preview · Tab cycle · Enter submit · ESC discard"`.
|
||||
|
||||
**Skeleton:**
|
||||
|
||||
```ts
|
||||
// mailbox-compose-preview.ts
|
||||
export function renderComposePreview(body: string, width: number, theme: CrewTheme): string[] {
|
||||
const tokens = tokenizeMarkdown(body); // simple tokenizer ~80 LOC
|
||||
return tokens.flatMap((t) => renderToken(t, width, theme));
|
||||
}
|
||||
|
||||
function tokenizeMarkdown(body: string): MdToken[] { /* line-by-line scan */ }
|
||||
type MdToken = { type: "heading" | "code-block" | "list-item" | "paragraph"; level?: number; text: string };
|
||||
```
|
||||
|
||||
**Tests:** `test/unit/mailbox-compose-preview.test.ts` — 6 cases (plain text, bold/italic, code block, list, heading, mixed content).
|
||||
|
||||
#### 8.1.F Mailbox ackAll (0.5 dev-day) — Q5=c destructive
|
||||
|
||||
**Logic:** trong `MailboxDetailOverlay.handleInput`, key `Shift+X` (raw stdin `"X"` uppercase) → mở `ConfirmOverlay`:
|
||||
- Title: `"Acknowledge all N unread messages?"`
|
||||
- Body: `"This cannot be undone. Y=ack all, N=cancel."`
|
||||
- DangerLevel: `"medium"`.
|
||||
|
||||
Confirm `Y` → `dispatchMailboxAckAll(ctx, runId)` (dispatcher loop ack-message từng id) → toast result `"Acknowledged N messages."`.
|
||||
|
||||
**Acceptance:** ackAll trong run với 10 unread → all marked acknowledged trong < 2s; mailbox pane attention → 0; emit 10x `crew.mailbox.acknowledged` event.
|
||||
|
||||
**Tests:** `test/unit/mailbox-detail-overlay.test.ts` thêm 3 cases (Shift+X opens confirm, confirm Y dispatches loop, confirm N stays).
|
||||
|
||||
---
|
||||
|
||||
### Phase 8.2 — Health Pane & Recovery
|
||||
|
||||
#### 8.2.A Heartbeat aggregator (1 dev-day)
|
||||
|
||||
**File mới:** `src/ui/heartbeat-aggregator.ts`
|
||||
|
||||
```ts
|
||||
export interface HeartbeatSummary {
|
||||
runId: string;
|
||||
totalTasks: number;
|
||||
healthy: number; // alive=true, lastSeenAt < threshold
|
||||
stale: number; // lastSeenAt > stale threshold (default 60s)
|
||||
dead: number; // lastSeenAt > dead threshold (default 5min) hoặc alive=false
|
||||
missing: number; // task running nhưng no heartbeat record
|
||||
worstStaleMs: number;
|
||||
}
|
||||
|
||||
export function summarizeHeartbeats(snapshot: RunUiSnapshot, opts?: { staleMs?: number; deadMs?: number; now?: number }): HeartbeatSummary { /* ... */ }
|
||||
```
|
||||
|
||||
**Tests:** `test/unit/heartbeat-aggregator.test.ts` — 6 cases (all healthy, mixed, all dead, missing record, custom threshold, edge `lastSeenAt=now`).
|
||||
|
||||
#### 8.2.B Health pane (0.75 dev-day)
|
||||
|
||||
**File mới:** `src/ui/dashboard-panes/health-pane.ts`
|
||||
|
||||
```ts
|
||||
export function renderHealthPane(snapshot: RunUiSnapshot | undefined, opts?: { staleMs?: number; deadMs?: number; isForeground?: boolean }): string[] {
|
||||
if (!snapshot) return ["Health pane: snapshot unavailable"];
|
||||
const summary = summarizeHeartbeats(snapshot, opts);
|
||||
const lines: string[] = [
|
||||
`Health: ${summary.healthy}/${summary.totalTasks} healthy · stale=${summary.stale} · dead=${summary.dead} · missing=${summary.missing}`,
|
||||
];
|
||||
if (summary.worstStaleMs > 0) lines.push(`Worst stale: ${Math.round(summary.worstStaleMs / 1000)}s ago`);
|
||||
// Q4=c: show full action menu hint
|
||||
const actionHints: string[] = [];
|
||||
if ((summary.dead > 0 || summary.missing > 0) && opts?.isForeground !== false) actionHints.push("R recovery");
|
||||
if (summary.dead > 0 || summary.stale > 0) actionHints.push("K kill stale");
|
||||
actionHints.push("D diagnostic export");
|
||||
if (actionHints.length > 0) lines.push(`Actions: ${actionHints.join(" · ")}`);
|
||||
if (summary.dead > 0 && opts?.isForeground === false) lines.push("(Async run: R/K disabled — use kill <pid> manually)");
|
||||
return lines;
|
||||
}
|
||||
```
|
||||
|
||||
**Update `run-dashboard.ts`:**
|
||||
- Thêm `"health"` vào type `Pane`.
|
||||
- Key `5` → `activePane = "health"`.
|
||||
- Switch case render `renderHealthPane` với `isForeground` từ `selectedRun.async ? false : true`.
|
||||
- Trong `handleInput`: nếu `activePane === "health"`:
|
||||
- `R` → emit `{action: "health-recovery", runId}` (handler sẽ check foreground + ConfirmOverlay).
|
||||
- `K` → emit `{action: "health-kill-stale", runId}` (handler ConfirmOverlay if dead > 5).
|
||||
- `D` → emit `{action: "health-diagnostic-export", runId}` (handler check existing diag < 1min → confirm overwrite).
|
||||
- Header help line update: `"1 agents 2 progress 3 mailbox 4 output 5 health • s/u/a/i actions • R/K/D health"`.
|
||||
|
||||
**Tests:** `test/unit/health-pane.test.ts` — 6 cases (no snapshot, all healthy → only D hint, dead foreground → R+K+D, dead async → only D + warning, mixed states, foreground false hint visible).
|
||||
|
||||
#### 8.2.C Auto-recovery toast (0.5 dev-day) — Q4 simplified
|
||||
|
||||
**Logic:** `RenderScheduler.tick` callback (đã có) gọi `summarizeHeartbeats`; nếu `dead > 0` hoặc `missing > 0` lần đầu → fire toast qua `notification-router` (8.3.A) với severity `"warning"`:
|
||||
- Title: `"Run {runId} has {N} dead workers"`.
|
||||
- Body: `"Open dashboard → 5 health → R recovery / K kill stale / D diagnostic"`.
|
||||
|
||||
**Throttle (D13):** dedup id = `recovery_dead_workers_${runId}` — router dedup 5 phút/run/condition-type. Riêng `recovery_missing_heartbeat` có id khác để alert song song nếu cả hai cùng xảy ra.
|
||||
|
||||
**Tests:** `test/integration/health-recovery.test.ts` — simulate stale heartbeat, verify single toast emitted; emit lần 2 trong window → drop; emit lần 2 sau 5min → fire lại.
|
||||
|
||||
#### 8.2.D Health action handlers (1.5 dev-day) — Q4=c full menu
|
||||
|
||||
**Update `src/extension/registration/commands.ts`:** handle 3 new actions từ dashboard:
|
||||
|
||||
```ts
|
||||
// pseudo-code
|
||||
if (selection.action === "health-recovery") {
|
||||
const run = manifestCache.get(selection.runId);
|
||||
if (run?.async) { ctx.ui.notify("Recovery only available for foreground runs.", "warning"); return; }
|
||||
const confirmed = await openConfirmOverlay(ctx, { title: "Interrupt foreground run?", body: "Tasks will be marked failed. Y=interrupt, N=cancel.", dangerLevel: "high" });
|
||||
if (!confirmed) return;
|
||||
const r = await dispatchHealthRecovery(ctx, selection.runId);
|
||||
ctx.ui.notify(r.message, r.ok ? "info" : "error");
|
||||
}
|
||||
|
||||
if (selection.action === "health-kill-stale") {
|
||||
const summary = summarizeHeartbeats(snapshotCache.get(selection.runId)!);
|
||||
if (summary.dead + summary.stale > 5) {
|
||||
const confirmed = await openConfirmOverlay(ctx, { title: `Kill ${summary.dead + summary.stale} stale workers?`, dangerLevel: "medium" });
|
||||
if (!confirmed) return;
|
||||
}
|
||||
const r = await dispatchKillStaleWorkers(ctx, selection.runId);
|
||||
ctx.ui.notify(r.message, r.ok ? "info" : "error");
|
||||
}
|
||||
|
||||
if (selection.action === "health-diagnostic-export") {
|
||||
// D14: check existing diag in last 1min
|
||||
const diagDir = path.join(run.artifactsRoot, "diagnostic");
|
||||
const recentDiag = listRecentDiagnostic(diagDir, 60_000);
|
||||
if (recentDiag) {
|
||||
const confirmed = await openConfirmOverlay(ctx, { title: "Recent diagnostic exists", body: `File ${recentDiag} created < 1min ago. Overwrite?`, defaultAction: "cancel" });
|
||||
if (!confirmed) return;
|
||||
}
|
||||
const r = await dispatchDiagnosticExport(ctx, selection.runId);
|
||||
ctx.ui.notify(`Diagnostic exported to ${r.data}`, r.ok ? "info" : "error");
|
||||
}
|
||||
```
|
||||
|
||||
**File mới:** `src/runtime/diagnostic-export.ts` — collect manifest + tasks + recent events (limit 200) + heartbeat summary + agent status snapshot; redact secrets từ env/config (block list: `*token*`, `*key*`, `*password*`, `*secret*`); write JSON vào `<crewRoot>/artifacts/{runId}/diagnostic-{ISO-timestamp}.json`.
|
||||
|
||||
**Skeleton:**
|
||||
|
||||
```ts
|
||||
// diagnostic-export.ts
|
||||
export interface DiagnosticReport {
|
||||
runId: string;
|
||||
exportedAt: string;
|
||||
manifest: TeamRunManifest;
|
||||
tasks: TeamTaskState[];
|
||||
recentEvents: TeamEvent[];
|
||||
heartbeat: HeartbeatSummary;
|
||||
agents: { taskId: string; status: AgentStatus }[];
|
||||
envRedacted: Record<string, string>; // env vars with secrets masked as "***"
|
||||
}
|
||||
|
||||
export async function exportDiagnostic(ctx: ExtensionContext, runId: string): Promise<{ path: string; report: DiagnosticReport }> { /* ... */ }
|
||||
|
||||
function redactSecrets(obj: unknown): unknown { /* recursive replace values where key matches block list */ }
|
||||
```
|
||||
|
||||
**Tests:**
|
||||
- `test/unit/diagnostic-export.test.ts` — 5 cases (basic export, secret redaction, missing run errors, file path generation, JSON validity).
|
||||
- Smoke: export → open file → verify đầy đủ field + 0 secrets.
|
||||
|
||||
---
|
||||
|
||||
### Phase 8.3 — Smart Notifications
|
||||
|
||||
#### 8.3.A Notification router (1 dev-day)
|
||||
|
||||
**File mới:** `src/extension/notification-router.ts`
|
||||
|
||||
```ts
|
||||
export type Severity = "info" | "warning" | "error" | "critical";
|
||||
|
||||
export interface NotificationDescriptor {
|
||||
id?: string; // dedup key; nếu cùng id trong window → drop
|
||||
severity: Severity;
|
||||
source: string; // "run-completed" | "subagent-stuck" | "health" | ...
|
||||
runId?: string;
|
||||
title: string;
|
||||
body?: string;
|
||||
timestamp?: number;
|
||||
}
|
||||
|
||||
export interface NotificationRouterOptions {
|
||||
dedupWindowMs?: number; // default 30000
|
||||
batchWindowMs?: number; // default 0 (no batching by default)
|
||||
quietHours?: string; // "22:00-07:00" local
|
||||
severityFilter?: Severity[]; // default: ["warning", "error", "critical"]
|
||||
sink?: (n: NotificationDescriptor) => void; // optional file/stream sink
|
||||
}
|
||||
|
||||
export class NotificationRouter {
|
||||
constructor(private opts: NotificationRouterOptions = {}, private deliver: (n: NotificationDescriptor) => void) {}
|
||||
enqueue(n: NotificationDescriptor): void { /* dedup check, severity filter, quiet-hours skip, batch buffer, sink */ }
|
||||
flush(): void { /* deliver batched */ }
|
||||
dispose(): void { /* clear timers */ }
|
||||
}
|
||||
```
|
||||
|
||||
**Wrap `sendFollowUp`:** trong `register.ts`, thay 2 call sites `sendFollowUp(...)` thành `notificationRouter.enqueue({...})`. Router decides có deliver qua `sendFollowUp` hay không.
|
||||
|
||||
**Tests:** `test/unit/notification-router.test.ts` — 8 cases (dedup, severity filter, quiet hours mock clock, batch, sink invocation, dispose cleanup).
|
||||
|
||||
#### 8.3.B Quiet-hours + batching config (0.75 dev-day) — Q3=b cross-day wrap
|
||||
|
||||
**Update `src/schema/config-schema.ts`:**
|
||||
```ts
|
||||
notifications: Type.Optional(Type.Object({
|
||||
enabled: Type.Optional(Type.Boolean()),
|
||||
severityFilter: Type.Optional(Type.Array(Type.Union([Type.Literal("info"), Type.Literal("warning"), Type.Literal("error"), Type.Literal("critical")]))),
|
||||
dedupWindowMs: Type.Optional(Type.Integer({ minimum: 1000 })),
|
||||
batchWindowMs: Type.Optional(Type.Integer({ minimum: 0 })),
|
||||
quietHours: Type.Optional(Type.String({ pattern: "^\\d{2}:\\d{2}-\\d{2}:\\d{2}$" })),
|
||||
sinkRetentionDays: Type.Optional(Type.Integer({ minimum: 1, maximum: 90 })), // Q2=c, default 7
|
||||
})),
|
||||
```
|
||||
|
||||
**Update `src/config/defaults.ts`:** sane defaults (`severityFilter: ["warning","error","critical"]`, `dedupWindowMs: 30_000`, `batchWindowMs: 0`, `sinkRetentionDays: 7`).
|
||||
|
||||
**Update `src/config/config.ts`:** parse + merge giống các section khác.
|
||||
|
||||
**Cross-day parser (Q3=b):** trong `notification-router.ts`, helper isolated cho easy testing:
|
||||
|
||||
```ts
|
||||
// notification-router.ts (excerpt)
|
||||
export function parseHHMMRange(range: string): { startMin: number; endMin: number } {
|
||||
const [s, e] = range.split("-").map((part) => {
|
||||
const [hh, mm] = part.split(":").map(Number);
|
||||
return hh * 60 + mm;
|
||||
});
|
||||
return { startMin: s, endMin: e };
|
||||
}
|
||||
|
||||
export function isInQuietHours(range: string, now: Date = new Date()): boolean {
|
||||
const { startMin, endMin } = parseHHMMRange(range);
|
||||
const cur = now.getHours() * 60 + now.getMinutes();
|
||||
if (startMin === endMin) return false; // empty range
|
||||
// Q3=b: cross-day wrap when start > end
|
||||
return startMin <= endMin
|
||||
? (cur >= startMin && cur < endMin)
|
||||
: (cur >= startMin || cur < endMin);
|
||||
}
|
||||
```
|
||||
|
||||
**Tests:** `test/unit/notification-router.test.ts` thêm 4 cases parser:
|
||||
- `"09:00-17:00"` ở 12:00 → quiet (true).
|
||||
- `"09:00-17:00"` ở 22:00 → not quiet (false).
|
||||
- `"22:00-07:00"` ở 23:30 → quiet (cross-day true).
|
||||
- `"22:00-07:00"` ở 03:00 → quiet (cross-day true).
|
||||
- `"22:00-07:00"` ở 12:00 → not quiet (false).
|
||||
- Edge: `"00:00-23:59"` ở 12:00 → quiet (always-quiet within day).
|
||||
- Edge: `"00:00-00:00"` → always not quiet (empty range).
|
||||
|
||||
#### 8.3.C Toast badge integration (0.75 dev-day)
|
||||
|
||||
**Logic:** `NotificationRouter.deliver` → ngoài `sendFollowUp`, cộng `unreadCount++` trong `widgetState.notificationCount`. Reset khi user mở mailbox detail hoặc nhấn `H` (Hush — dismiss-all notifications visible badge).
|
||||
|
||||
**Update `crew-widget.ts`:** model render thêm `🔔${count}` nếu `count > 0`. Để tránh emoji compatibility issue → fallback `[!${count}]` khi terminal không support emoji (detect qua `process.env.TERM`).
|
||||
|
||||
**Update `powerbar-publisher.ts`:** segment `pi-crew-active` text append ` 🔔${count}` (hoặc fallback) khi active.
|
||||
|
||||
**Tests:** `test/unit/widget-notification-badge.test.ts` — 5 cases (no count, count=1, count>9, dismiss reset, terminal fallback).
|
||||
|
||||
#### 8.3.D Notification JSONL sink (0.5 dev-day) — Q2=c
|
||||
|
||||
**File mới:** `src/extension/notification-sink.ts`
|
||||
|
||||
**Logic:** khi config `telemetry.enabled !== false`, NotificationRouter delivery cũng gọi `sink.write(descriptor)`. Sink writes vào `<crewRoot>/state/notifications/{YYYY-MM-DD}.jsonl` (1 file/day, append-only).
|
||||
|
||||
**Rotation:** start-of-day check (lazy, khi write đầu tiên) → delete files cũ hơn `notifications.sinkRetentionDays` (default 7).
|
||||
|
||||
**Skeleton:**
|
||||
|
||||
```ts
|
||||
// notification-sink.ts
|
||||
export interface NotificationSink {
|
||||
write(n: NotificationDescriptor): void;
|
||||
dispose(): void;
|
||||
}
|
||||
|
||||
export function createJsonlSink(crewRoot: string, retentionDays: number): NotificationSink {
|
||||
const dir = path.join(crewRoot, "state", "notifications");
|
||||
let lastRotateDate = "";
|
||||
return {
|
||||
write(n) {
|
||||
const today = new Date().toISOString().slice(0, 10);
|
||||
if (today !== lastRotateDate) {
|
||||
rotateOldFiles(dir, retentionDays);
|
||||
lastRotateDate = today;
|
||||
}
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
fs.appendFileSync(path.join(dir, `${today}.jsonl`), JSON.stringify({ ...n, timestamp: n.timestamp ?? Date.now() }) + "\n");
|
||||
},
|
||||
dispose() { /* no-op */ },
|
||||
};
|
||||
}
|
||||
|
||||
function rotateOldFiles(dir: string, retentionDays: number): void {
|
||||
if (!fs.existsSync(dir)) return;
|
||||
const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
|
||||
for (const file of fs.readdirSync(dir)) {
|
||||
if (!file.endsWith(".jsonl")) continue;
|
||||
const stat = fs.statSync(path.join(dir, file));
|
||||
if (stat.mtimeMs < cutoff) fs.unlinkSync(path.join(dir, file));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Wire trong `register.ts`:** instantiate sink khi `telemetry.enabled !== false`, pass vào `NotificationRouter` options. Dispose trong `cleanupRuntime`.
|
||||
|
||||
**Tests:** `test/unit/notification-sink.test.ts` — 5 cases (write basic, daily rotation, retention prune, no rotation cùng ngày, telemetry disabled = no-op).
|
||||
|
||||
---
|
||||
|
||||
### Phase 8.4 — Wiring (0.75 dev-day)
|
||||
|
||||
**Update `src/extension/register.ts`:**
|
||||
- Instantiate `NotificationRouter` cùng cấp với `runSnapshotCache`; check `loadConfig.telemetry?.enabled !== false` để decide có pass `JsonlSink` không.
|
||||
- Pass router vào `subagentManager` callback (line 64-86) thay vì gọi trực tiếp `sendFollowUp`.
|
||||
- Pass router vào `RenderScheduler` callback cho 8.2.C auto-recovery alert.
|
||||
- Pass `getRunSnapshotCache` + `notificationRouter` vào `commands.ts` deps.
|
||||
- Dispose router + sink trong `cleanupRuntime`.
|
||||
|
||||
**Update `src/extension/registration/commands.ts`:**
|
||||
- Handle `selection.action === "mailbox-detail"` → mở `MailboxDetailOverlay`, dispatch action result, toast.
|
||||
- Handle `selection.action === "health-recovery" | "health-kill-stale" | "health-diagnostic-export"` (Q4=c) — flow chi tiết 8.2.D.
|
||||
- Pass `getRunSnapshotCache` cho overlay (cần để re-render sau action).
|
||||
- Pass `confirmOverlayFactory` để các handler reuse `ConfirmOverlay`.
|
||||
|
||||
---
|
||||
|
||||
### Phase 8.5 — Tests + Validation (2 dev-day)
|
||||
|
||||
**Unit (mới ~52 cases):**
|
||||
- `run-action-dispatcher.test.ts` (7)
|
||||
- `confirm-overlay.test.ts` (4)
|
||||
- `mailbox-detail-overlay.test.ts` (7 — bao gồm 3 cases ackAll Shift+X)
|
||||
- `mailbox-compose-overlay.test.ts` (8)
|
||||
- `mailbox-compose-preview.test.ts` (6) — Q1
|
||||
- `agent-picker-overlay.test.ts` (4)
|
||||
- `heartbeat-aggregator.test.ts` (6)
|
||||
- `health-pane.test.ts` (6) — Q4 expanded
|
||||
- `diagnostic-export.test.ts` (5) — Q4
|
||||
- `notification-router.test.ts` (8 + 4 quiet-hours parser cases = 12) — Q3
|
||||
- `notification-sink.test.ts` (5) — Q2
|
||||
- `widget-notification-badge.test.ts` (5)
|
||||
|
||||
**Integration (mới ~6 cases):**
|
||||
- `test/integration/mailbox-action-roundtrip.test.ts` — open dashboard → ack → snapshot invalidate → count giảm.
|
||||
- `test/integration/mailbox-ackall-confirm.test.ts` — ackAll trigger ConfirmOverlay → confirm → loop ack 10 messages.
|
||||
- `test/integration/notification-dedup.test.ts` — emit cùng event 5 lần trong 30s → 1 toast.
|
||||
- `test/integration/notification-quiet-hours.test.ts` — set quietHours `"22:00-07:00"`, mock now=23:30 → 0 toast; mock now=12:00 → 1 toast.
|
||||
- `test/integration/notification-sink-rotation.test.ts` — write 8 days → oldest file deleted on day 8.
|
||||
- `test/integration/health-recovery-foreground.test.ts` — foreground run dead → R action → ConfirmOverlay → confirm → foreground-interrupt fired.
|
||||
- `test/integration/health-diagnostic-export.test.ts` — D action → diagnostic file written với secrets redacted; emit lần 2 trong 1min → ConfirmOverlay overwrite.
|
||||
|
||||
**Acceptance trước commit:**
|
||||
- `npm test` ≥ 351 unit (current 299 + 52), 35 integration (current 29 + 6); 0 fail. Verified current suite: 351 unit + 44 integration.
|
||||
- `npm run typecheck` clean.
|
||||
- Manual smoke coverage (8 scenarios — mục 6) captured as automated smoke in `test/integration/phase8-smoke.test.ts`.
|
||||
|
||||
## 3. Wave Organization (parallel-friendly) — Updated với Q1-Q6
|
||||
|
||||
```
|
||||
Wave 1 (parallel, 2.5 days)
|
||||
├─ 8.0 Foundation (dispatcher + keybinding-map + ConfirmOverlay)
|
||||
├─ 8.3.A NotificationRouter primitive
|
||||
└─ 8.2.A Heartbeat aggregator
|
||||
|
||||
Wave 2 (sequential, 5 days) — depends on Wave 1
|
||||
├─ 8.1.A Mailbox detail overlay
|
||||
├─ 8.1.B Ack action
|
||||
├─ 8.1.C Nudge action
|
||||
├─ 8.1.D Compose form (Q6 ESC discard + confirm-if-long)
|
||||
├─ 8.1.E Compose preview pane (Q1)
|
||||
└─ 8.1.F ackAll Shift+X destructive (Q5)
|
||||
|
||||
Wave 3 (parallel, 4 days) — depends on Wave 1
|
||||
├─ 8.2.B Health pane
|
||||
├─ 8.2.C Auto-recovery toast (throttled 5min D13)
|
||||
├─ 8.2.D Health action handlers R/K/D (Q4) + diagnostic-export module
|
||||
├─ 8.3.B Quiet-hours cross-day parser (Q3) + batching config
|
||||
├─ 8.3.C Toast badge widget/powerbar
|
||||
└─ 8.3.D JSONL sink + retention (Q2)
|
||||
|
||||
Wave 4 (sequential, 2.75 days)
|
||||
├─ 8.4 Wire register.ts + commands.ts (router, sink, action handlers)
|
||||
└─ 8.5 Tests + smoke validation (52 unit + 6 integration mới)
|
||||
```
|
||||
|
||||
**Total estimate: 14-18 dev-days** (vs Phase 7 baseline 18 days). Effort tăng 3.35 day so với plan gốc 11-14d do Q1-Q6 chosen options enrich scope. Phase 8 vẫn smaller hơn Phase 7 vì chủ yếu UI overlay + event router, không động state machine.
|
||||
|
||||
## 4. Files Affected — Updated với Q1-Q6
|
||||
|
||||
### New (24 files)
|
||||
| Path | Purpose | Est LOC |
|
||||
|---|---|---|
|
||||
| `src/ui/run-action-dispatcher.ts` | Wrapper team-tool calls (7 dispatchers) | ~140 |
|
||||
| `src/ui/keybinding-map.ts` | Key registry (mailbox/health/notification scopes) | ~70 |
|
||||
| `src/ui/overlays/confirm-overlay.ts` | **(Q5)** Reusable confirm primitive | ~80 |
|
||||
| `src/ui/overlays/mailbox-detail-overlay.ts` | 2-col mailbox view + ackAll | ~250 |
|
||||
| `src/ui/overlays/mailbox-compose-overlay.ts` | Compose form + ESC guard | ~210 |
|
||||
| `src/ui/overlays/mailbox-compose-preview.ts` | **(Q1)** Markdown preview pane | ~120 |
|
||||
| `src/ui/overlays/agent-picker-overlay.ts` | Agent selector | ~110 |
|
||||
| `src/ui/heartbeat-aggregator.ts` | Heartbeat summary fn | ~70 |
|
||||
| `src/ui/dashboard-panes/health-pane.ts` | Health pane renderer with action hints | ~80 |
|
||||
| `src/extension/notification-router.ts` | Router + dedup + quiet-hours parser **(Q3)** | ~220 |
|
||||
| `src/extension/notification-sink.ts` | **(Q2)** JSONL sink + retention rotation | ~100 |
|
||||
| `src/runtime/diagnostic-export.ts` | **(Q4)** Diagnostic JSON exporter + secret redaction | ~140 |
|
||||
| `test/unit/run-action-dispatcher.test.ts` | | ~140 |
|
||||
| `test/unit/confirm-overlay.test.ts` | | ~80 |
|
||||
| `test/unit/mailbox-detail-overlay.test.ts` | | ~180 |
|
||||
| `test/unit/mailbox-compose-overlay.test.ts` | | ~180 |
|
||||
| `test/unit/mailbox-compose-preview.test.ts` | **(Q1)** | ~120 |
|
||||
| `test/unit/agent-picker-overlay.test.ts` | | ~80 |
|
||||
| `test/unit/heartbeat-aggregator.test.ts` | | ~120 |
|
||||
| `test/unit/health-pane.test.ts` | Q4 expanded scenarios | ~140 |
|
||||
| `test/unit/diagnostic-export.test.ts` | **(Q4)** | ~110 |
|
||||
| `test/unit/notification-router.test.ts` | + 4 cross-day parser cases | ~260 |
|
||||
| `test/unit/notification-sink.test.ts` | **(Q2)** | ~100 |
|
||||
| `test/unit/widget-notification-badge.test.ts` | | ~80 |
|
||||
| `test/integration/mailbox-action-roundtrip.test.ts` | | ~120 |
|
||||
| `test/integration/mailbox-ackall-confirm.test.ts` | **(Q5)** | ~100 |
|
||||
| `test/integration/notification-dedup.test.ts` | | ~90 |
|
||||
| `test/integration/notification-quiet-hours.test.ts` | **(Q3)** mock clock | ~110 |
|
||||
| `test/integration/notification-sink-rotation.test.ts` | **(Q2)** | ~110 |
|
||||
| `test/integration/health-recovery-foreground.test.ts` | **(Q4)** | ~120 |
|
||||
| `test/integration/health-diagnostic-export.test.ts` | **(Q4)** | ~120 |
|
||||
|
||||
### Modified (10 files)
|
||||
| Path | Change |
|
||||
|---|---|
|
||||
| `src/ui/run-dashboard.ts` | Refactor `handleInput` dùng keybinding-map; thêm pane "health" key `5`; help line; emit `health-recovery/health-kill-stale/health-diagnostic-export` actions (Q4) |
|
||||
| `src/ui/dashboard-panes/mailbox-pane.ts` | Update help text gợi ý A/N/C/Enter/Shift+X (ackAll) |
|
||||
| `src/ui/crew-widget.ts` | Render notification badge `🔔N` (fallback `[!N]` cho terminal không support emoji) |
|
||||
| `src/ui/powerbar-publisher.ts` | Append badge cho `pi-crew-active` segment |
|
||||
| `src/extension/register.ts` | Instantiate NotificationRouter + JsonlSink (gated bởi telemetry); wrap `sendFollowUp`; pass vào RenderScheduler + commands deps |
|
||||
| `src/extension/registration/commands.ts` | Handle `mailbox-detail` + 3 health actions (Q4); mở overlay; reuse ConfirmOverlay (Q5) |
|
||||
| `src/extension/team-tool/api.ts` | (no change) — dispatchers reuse existing operations |
|
||||
| `src/schema/config-schema.ts` | Thêm `notifications` section + `sinkRetentionDays` (Q2) |
|
||||
| `src/config/{config.ts,defaults.ts}` | Parse + default cho notifications (severityFilter, dedupWindowMs, batchWindowMs, quietHours, sinkRetentionDays) |
|
||||
| `package.json` | Bump version `0.1.33` → `0.1.34` |
|
||||
|
||||
### Docs (chỉ update khi user yêu cầu, theo project rule)
|
||||
- `docs/architecture.md` — bổ sung mục "Operator Actions", "Notification Router", "Diagnostic Export".
|
||||
|
||||
## 5. Risk Assessment — Updated với Q1-Q6
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|---|---|---|---|
|
||||
| Overlay hijack stdin của Pi UI | Med | High | Reuse pattern `LiveRunSidebar` (đã hoạt động); test với `pi-ui-compat.ts` shim |
|
||||
| Keybinding conflict với Pi global hotkeys | Low | Med | Uppercase `A/N/C/P/H/X` (mailbox), `R/K/D` (health) — context-scoped; lowercase Pi defaults không đụng |
|
||||
| Notification spam khi nhiều run concurrent | Med | Low-Med | Dedup window 30s default; severity filter excludes "info"; quiet-hours wrap (Q3) |
|
||||
| Quiet-hours cross-day parser bug | Low | Med | Q3=b: 7 unit test cases bao gồm cross-midnight; mock clock pattern |
|
||||
| MailboxDetailOverlay re-render slow | Low | Low | Reuse signature pattern từ `RunDashboard`; cache lines |
|
||||
| Race khi ack trong khi snapshot đang refresh | Low | Med | Dispatch awaits then invalidate cache; render scheduler debounce 75ms |
|
||||
| `sendFollowUp` swap break existing flow | Low | High | Wrap không thay; router default-on chỉ khi `notifications.enabled !== false`; fallback gọi `sendFollowUp` raw nếu router throws |
|
||||
| Config schema breaking change | Low | High | New section `notifications` purely optional; missing → defaults |
|
||||
| **(Q1)** Compose preview pane re-render bottleneck (debounce miss) | Low | Low | Debounce 100ms; cache last rendered tokens; tokenizer < 1ms cho 5KB body |
|
||||
| **(Q1)** Markdown tokenizer edge case (nested code in list) | Med | Low | Reuse pattern parser nếu có; 6 unit test edge cases; preview "best-effort" |
|
||||
| **(Q2)** Sink disk full / write fail | Low | Low | `appendFileSync` swallow errors qua `logInternalError`; sink failure không crash router |
|
||||
| **(Q2)** Retention prune deletes file đang được tail | Low | Low | Chỉ prune `.jsonl` cũ hơn cutoff; daily rotation đảm bảo file hôm nay không bị touch |
|
||||
| **(Q2)** PII trong notification body leak vào sink | Med | Med | Sink reuse secret redactor từ `diagnostic-export.ts` (Q4); router tag PII fields nếu cần |
|
||||
| **(Q4)** `R` recovery accidentally interrupt healthy run | Low | High | ConfirmOverlay với `dangerLevel: "high"` + default cancel; foreground-only check; clear "tasks marked failed" warning |
|
||||
| **(Q4)** `K` kill stale workers race với worker self-recovery | Low | Med | Mark dead heartbeats first → emit event → giải phóng claims; worker tự detect token mismatch sẽ exit |
|
||||
| **(Q4)** Diagnostic export ghi đè artifact dir đang dùng | Low | Med | D14: check existing diag < 1min → ConfirmOverlay overwrite; timestamp suffix unique |
|
||||
| **(Q4)** Diagnostic secret redaction miss key pattern mới | Med | High | Block list: `*token*`, `*key*`, `*password*`, `*secret*`, `*credential*`, `*auth*`; review qua test fixture với 20 key patterns |
|
||||
| **(Q5)** ConfirmOverlay default `Y` accidentally confirms destructive | Low | High | Default action = "cancel"; first focus là `[N]`; ESC = cancel; UI hint underlined N |
|
||||
| **(Q6)** ESC discard confirm fatigue (user complain phải confirm mỗi ESC) | Low | Low | Threshold 50 ký tự (configurable nếu user feedback); short body → discard ngay |
|
||||
| **(Q6)** Body multi-line Ctrl+Enter not detected on Windows | Med | Low | Test với `pi-ui-compat.ts`; fallback `Alt+Enter` if Ctrl+Enter fails detection |
|
||||
|
||||
## 6. Testing Strategy — Updated với Q1-Q6
|
||||
|
||||
**Unit-level (Wave 1-3):**
|
||||
- Mock `handleTeamTool` → assert dispatcher returns đúng `{ok, message}` cho 7 dispatchers.
|
||||
- Render overlay với fixture snapshot → assert lines layout.
|
||||
- Heartbeat aggregator: parameterized test với fixture timestamps (6 cases).
|
||||
- Health pane: 6 cases bao phủ foreground/async/healthy/dead/stale variations (Q4).
|
||||
- Notification router: mock clock (`globalThis.Date.now` override theo pattern Phase 7); 8 base cases + 4 cross-day parser (Q3).
|
||||
- Sink: rotation, retention, telemetry-disabled no-op (Q2).
|
||||
- Diagnostic export: secret redaction với 20-key fixture; JSON schema validate (Q4).
|
||||
- Confirm overlay: 4 cases verify default-cancel safety (Q5).
|
||||
- Compose preview: 6 cases markdown render (Q1).
|
||||
|
||||
**Integration (Wave 4) — 7 scenarios:**
|
||||
- `mailbox-action-roundtrip.test.ts`: open dashboard → ack → snapshot invalidate → count giảm.
|
||||
- `mailbox-ackall-confirm.test.ts` (Q5): Shift+X → ConfirmOverlay → confirm → loop ack 10 messages → all `acknowledged`.
|
||||
- `notification-dedup.test.ts`: emit 5x cùng `crew.run.failed` trong 30s → `sendFollowUp` mock called once.
|
||||
- `notification-quiet-hours.test.ts` (Q3): quiet `"22:00-07:00"` mock now=23:30 → 0 toast; mock now=12:00 → 1 toast.
|
||||
- `notification-sink-rotation.test.ts` (Q2): write 8 ngày fake mtime → oldest deleted on day 8.
|
||||
- `health-recovery-foreground.test.ts` (Q4): foreground run với 2 dead workers → R action → ConfirmOverlay confirm → `foreground-interrupt` API called → tasks marked failed.
|
||||
- `health-diagnostic-export.test.ts` (Q4): D action → file written với 0 secrets in JSON; emit lần 2 trong 1min → ConfirmOverlay overwrite.
|
||||
|
||||
**Smoke manual (8 scenarios):**
|
||||
1. Chạy `team run` 1 task foreground → mở `/team-dashboard` → key `3` mailbox → Enter → key `N` nudge → verify `events.jsonl` có `agent.nudged`.
|
||||
2. Chạy 2 run, đợi xong → verify nhận 1-2 toast (dedup).
|
||||
3. Set `notifications.quietHours = "00:00-23:59"` → verify 0 toast.
|
||||
4. **(Q1)** Compose form, gõ markdown body với bold/list/code → key `P` preview → verify render đúng.
|
||||
5. **(Q5)** ackAll trên run với 5 unread → ConfirmOverlay xuất hiện → N cancel → 0 message acked.
|
||||
6. **(Q4)** Foreground run với worker stuck > 1min → key `5` health → key `R` → ConfirmOverlay → Y → tasks failed; key `D` → diagnostic file viết.
|
||||
7. **(Q2)** Disable telemetry → run + emit notification → verify `<crewRoot>/state/notifications/` không tồn tại.
|
||||
8. **(Q6)** Compose body 100 chars → ESC → ConfirmOverlay xuất hiện → N → vẫn editing.
|
||||
|
||||
**Performance budget:**
|
||||
- Mailbox overlay first render < 50ms với 100 messages.
|
||||
- Compose preview render < 30ms với 5KB markdown body (Q1).
|
||||
- Notification router enqueue overhead < 1ms.
|
||||
- Sink write < 5ms (single append) (Q2).
|
||||
- Health pane render < 5ms cho 50 tasks.
|
||||
- Diagnostic export complete < 200ms cho run với 50 tasks + 200 events (Q4).
|
||||
|
||||
## 7. Open Questions — RESOLVED (Path X chosen)
|
||||
|
||||
| Q | Câu hỏi | Lựa chọn | Implementation reference |
|
||||
|---|---|---|---|
|
||||
| **Q1** | Compose form có cần preview render trước khi submit? | **(b) Có preview pane** | 8.1.E `mailbox-compose-preview.ts`, key `P` toggle, render markdown read-only (bold/italic/code/list/heading), debounce 100ms. D15. +0.75d |
|
||||
| **Q2** | Notification sink default ghi `<crewRoot>/state/notifications.jsonl`? | **(c) Sink khi `telemetry.enabled !== false`** | 8.3.D `notification-sink.ts`, JSONL `<crewRoot>/state/notifications/{YYYY-MM-DD}.jsonl`, rotate `sinkRetentionDays` default 7. D4. +0.5d |
|
||||
| **Q3** | Quiet-hours cross-day wrap? | **(b) Wrap parser** | 8.3.B `parseHHMMRange` + `isInQuietHours` cross-day logic; 7 unit cases bao gồm `"22:00-07:00"`. D5. +0.25d |
|
||||
| **Q4** | Health pane recovery action button inline? | **(c) Full action menu R/K/D** | 8.2.D `R` recovery (foreground-only), `K` kill stale workers, `D` diagnostic export với secret redaction; 3 confirm flows. D9, D14. +1.5d |
|
||||
| **Q5** | Ack/nudge confirm cho destructive? | **(c) Confirm chỉ destructive (ackAll/recovery/diag-overwrite)** | 8.0 `ConfirmOverlay` reusable primitive; 8.1.F ackAll Shift+X with confirm. D12. +0.25d |
|
||||
| **Q6** | Compose form persist draft khi ESC? | **(a) ESC discard + confirm-if-long** | 8.1.D ESC behavior: body ≤ 50 chars → discard; > 50 → ConfirmOverlay. Defer draft persistence Phase 9. D11. +0.1d |
|
||||
|
||||
**Tổng effort delta từ Q1-Q6: ~3.35 dev-day** → bump từ 11-14d → 14-18d.
|
||||
|
||||
**Mục tiêu Q1-Q6 đã đạt:** mọi quyết định scope-shaping đã chốt; team có thể start Wave 1 mà không bị blocked clarification giữa chừng.
|
||||
|
||||
## 8. Dependencies & Sequencing
|
||||
|
||||
```
|
||||
Phase 7 (DONE) ─────► Phase 8.0 Foundation
|
||||
│
|
||||
┌──────────┼──────────┐
|
||||
▼ ▼ ▼
|
||||
8.1 Mailbox 8.2 Health 8.3 Notif
|
||||
│ │ │
|
||||
└──────────┼──────────┘
|
||||
▼
|
||||
8.4 Wiring
|
||||
│
|
||||
▼
|
||||
8.5 Tests
|
||||
```
|
||||
|
||||
**Hard prerequisites Phase 7:** ✅ `RunSnapshotCache`, `RenderScheduler`, dashboard panes — đã có.
|
||||
|
||||
## 9. Effort Summary — Updated với Q1-Q6
|
||||
|
||||
| Wave | Items | Dev-days | Parallelizable |
|
||||
|---|---|---|---|
|
||||
| 1 | 8.0 (Foundation + ConfirmOverlay Q5) + 8.3.A (Router) + 8.2.A (Heartbeat) | 2.5 | Yes (3 streams) |
|
||||
| 2 | 8.1.A → B → C → D (Q6) → E (Q1) → F (Q5) | 5 | No (sequential UX, share overlay state) |
|
||||
| 3 | 8.2.B + 8.2.C + 8.2.D (Q4 R/K/D) + 8.3.B (Q3) + 8.3.C + 8.3.D (Q2) | 4 | Yes (5 streams) |
|
||||
| 4 | 8.4 (Wire) + 8.5 (Tests) | 2.75 | No |
|
||||
| **Total** | **17 sub-phases** | **14-18** | — |
|
||||
|
||||
**So với plan gốc:** +3.35 dev-day, +5 sub-phases, +8 file mới, +27 unit case, +4 integration case.
|
||||
|
||||
## 10. Acceptance Checklist (Wave 4 exit criteria) — Updated
|
||||
|
||||
- [x] Tất cả checkbox 8.0 → 8.5 ở mục 0 (Implementation Status) tick `[x]`.
|
||||
- [x] `npm test` ≥ **351 unit** (current 299 + 52 mới), ≥ **35 integration** (current 29 + 6 mới), 0 fail. Verified: 351 unit + 44 integration pass.
|
||||
- [x] `npm run typecheck` clean.
|
||||
- [x] Manual smoke **8 scenarios** pass (mục 6). Verified via automated smoke suite `test/integration/phase8-smoke.test.ts`.
|
||||
- [x] Performance budget thỏa: mailbox overlay <50ms, compose preview <30ms, sink write <5ms, diagnostic export <200ms. Verified microbench: mailbox 6.39ms, preview 1.61ms, health 0.29ms, sink 2.12ms, diagnostic 4.83ms.
|
||||
- [x] No regression: 299 unit + 29 integration cũ vẫn pass.
|
||||
- [x] Config breaking? **No.** Schema additive (`notifications` section optional).
|
||||
- [x] Bump `package.json` version `0.1.33` → `0.1.34`.
|
||||
- [x] Q1-Q6 implementations match decisions table mục 7.
|
||||
- [x] Secret redaction (Q4): test fixture with recursive key/value redaction pass; audit log avoids known token fixture.
|
||||
|
||||
## 11. Out of Scope (defer Phase 9+)
|
||||
|
||||
> Phase 9 plan đã được tạo riêng tại [`research-phase9-observability-reliability-plan.md`](./research-phase9-observability-reliability-plan.md).
|
||||
|
||||
- **Telemetry/Metrics backbone** (Counter/Gauge/Histogram + correlation ID + OTLP/Prometheus export) → **Phase 9 (Theme B)** per Path X plan.
|
||||
- **Run reliability** — auto-retry executor + crash recovery + deadletter + heartbeat watcher → **Phase 9 (Theme C)**.
|
||||
- Cross-run mailbox routing (operator-broadcast) — **Phase 10+**.
|
||||
- Mailbox threading / reply chains — **Phase 10+**.
|
||||
- **Compose draft persistence (Q6 b/c options)** — defer Phase 9 nếu user feedback than.
|
||||
- Multi-host run aggregation — **Phase 10+**.
|
||||
- Slack/Discord webhook sink (router supports it via custom sink, but no built-in adapter) — **Phase 10+**.
|
||||
- Markdown preview với images/links rendered (Q1 D15 skip) — **Phase 10+**.
|
||||
|
||||
### Path X roadmap summary
|
||||
|
||||
| Phase | Theme | Effort | Plan file |
|
||||
|---|---|---|---|
|
||||
| 6 | `.crew/` migration + autonomous policy | ~12d | `refactor-tasks-phase6.md` (DONE) |
|
||||
| 7 | UI Optimization | ~18d | `research-ui-optimization-plan.md` (DONE) |
|
||||
| **8** | **Operator Experience (Theme A)** | **14-18d** | **THIS FILE — ✅ DONE (verified 351 unit + 44 integration pass, version 0.1.34)** |
|
||||
| **9** | **Observability + Reliability (B+C)** | **19.5-22.5d** | `research-phase9-observability-reliability-plan.md` (post-review updated 2026-04-29) |
|
||||
| 10+ | TBD: Perf baseline, distributed | — | Future |
|
||||
|
||||
---
|
||||
|
||||
## 12. Implementation Kickoff Checklist (Pre-Wave 1)
|
||||
|
||||
Trước khi bắt đầu Wave 1, verify:
|
||||
|
||||
- [x] Phase 7 đã commit (snapshot cache + render scheduler + 4 panes). Included in `phase-8-operator-experience` release commit.
|
||||
- [x] `npm test` baseline pass (299 unit + 29 integration). Verified current suite: 351 unit + 44 integration pass.
|
||||
- [x] `npm run typecheck` clean.
|
||||
- [x] Q1-Q6 đã chốt (đã làm — table mục 7).
|
||||
- [x] Branch mới `phase-8-operator-experience` từ main.
|
||||
- [x] Read once: `src/extension/team-tool/api.ts` (đã có ack-message/send-message/nudge-agent operations — KHÔNG cần modify).
|
||||
- [x] Read once: `src/ui/run-dashboard.ts:handleInput` để hiểu pattern key dispatch hiện tại.
|
||||
- [x] Read once: `src/ui/live-run-sidebar.ts` để có template cho overlay implementation.
|
||||
|
||||
**Sẵn sàng triển khai Phase 8 Path X.**
|
||||
Reference in New Issue
Block a user