failproofai 1.0.1-beta.1 → 1.0.2-beta.0

package/.next/standalone/docs-old/vi/agenteye/telemetry.mdx

@@ -0,0 +1,52 @@
+---
+title: "Chỉ Số Hiệu Suất"
+description: "Xem ngay lập tức khi các mô hình, công cụ hoặc hook của bạn chậm lại hoặc phát sinh chi phí, và phát hiện sự tăng độ trễ ở phía đuôi trước khi người dùng của bạn cảm nhận được."
+---
+
+
+Xem ngay lập tức khi các mô hình, công cụ hoặc hook của bạn chậm lại hoặc phát sinh chi phí, và phát hiện sự tăng độ trễ ở phía đuôi trước khi người dùng của bạn cảm nhận được. Ba trang chuyên dụng biến các thời gian thô thành p50, p95 và p99 mà bạn có thể đọc ngay tại một cái nhìn.
+
+![Trang Models hiển thị sơ đồ nhiệt độ trễ, một dải phần trăm và các số liệu về token, chi phí và cửa sổ ngữ cảnh cho từng mô hình](/agenteye/images/models.png)
+*Trang Models: sơ đồ nhiệt độ trễ, dải phần trăm và số liệu token cho mỗi mô hình, chi phí ước tính và phần trăm đầy cửa sổ ngữ cảnh.*
+
+## Hãy dừng để trung bình ẩn các lần chạy tồi tệ nhất của bạn
+
+Một số lượng độ trễ trung bình là thoải mái và vô ích: nó làm mịn một lệnh gọi trong năm mươi cái bị treo và gọi trang on-call của bạn vào lúc 2 giờ sáng. Các trang Models, Tools và Hooks từ chối làm như vậy. Mỗi trang chia sẻ hình dáng giống nhau, vì vậy bạn chỉ cần học một lần:
+
+- Một **sparkline 24 thùng** cho xu hướng ngay tại một cái nhìn: điều này có đang trở nên tồi tệ hơn không?
+- Một **dải chỉ số quan trọng** với độ trễ p50, p95 và p99, vì vậy lần chạy điển hình và phía đuôi ngồi cạnh nhau.
+- Một **sơ đồ nhiệt độ trễ**, 24 thùng thời gian theo các thùng độ trễ, cho thấy *khi nào* các lệnh gọi chậm được nhóm lại.
+- Một **dải phần trăm**: một dòng p50 với các dải bóng mờ p25 đến p75 và p10 đến p90 và các chấm p99, vì vậy phạm vi vẫn hiển thị thay vì được lấy trung bình.
+
+Một chữ thập di chuột được chia sẻ liên kết sơ đồ nhiệt và dải, vì vậy một sự tăng đột ngột ở phía đuôi được xếp chồng lên nhau theo thời gian trên cả hai thay vì ẩn đằng sau một dòng giá trị trung bình duy nhất. Tìm cả ba trang trong phần **observe** trên bảng điều khiển của bạn, mỗi trang có phạm vi cho tổ chức của bạn và có thể lọc theo phạm vi ngày, môi trường, agent và phiên.
+
+## Models: xem chính xác mỗi mô hình có giá bao nhiêu cho bạn
+
+Trang Models (hiển thị ở trên) trả lời hai câu hỏi mà một hóa đơn luôn đưa ra: mô hình nào và bao nhiêu tiền. Trên cơ sở khung nhìn độ trễ được chia sẻ, nó thêm **tiêu thụ token cho mỗi mô hình**, **chi phí ước tính** và **phần trăm đầy cửa sổ ngữ cảnh**, vì vậy sự tăng trưởng của prompt bất thường và một sự nén sắp xảy ra là hiển thị trước khi chúng gây bất ngờ cho bạn.
+
+Failproof AI Observability nhận ra các ID mô hình phổ biến một cách tự động. Nếu một cửa sổ trông không đúng, hoặc bạn chạy một mô hình riêng của riêng bạn, hãy sửa nó hoặc thêm nó trong **Settings**, trong **model context windows**, và các số liệu phần trăm đầy theo sau.
+
+## Tools: phân biệt cái chậm với cái bị hỏng
+
+Một lệnh gọi công cụ có thể chậm, hoặc nó có thể đang im lặng thất bại, và bạn muốn biết cái nào trong vòng vài giây, chứ không phải sau khi đào xung quanh các bản ghi.
+
+![Trang Tools hiển thị sơ đồ nhiệt độ trễ và dải phần trăm được chia sẻ bên cạnh một sự phân tích bước đầu và thất bại và một thanh phân phối công cụ](/agenteye/images/tools.png)
+*Trang Tools: sơ đồ nhiệt và dải phần trăm giống nhau, cộng với sự phân tích bước đầu và thất bại và thanh phân phối công cụ.*
+
+Bên cạnh khung nhìn độ trễ được chia sẻ, trang Tools thêm một **sự phân tích bước đầu và thất bại** và một **thanh phân phối công cụ**, vì vậy bạn thấy ngay tại một cái nhìn những công cụ nào bạn dựa vào nhiều nhất và những công cụ nào đang tiêu thụ ngân sách lỗi của bạn.
+
+## Hooks: xác định chính xác hook và kích hoạt
+
+Khi một hook vòng đời kéo một lần chạy, "hook rất chậm" không phải là điều gì bạn có thể hành động. Trang Hooks giúp bạn đến cái hook quan trọng.
+
+![Trang Hooks hiển thị độ trễ được phân tích theo tên hook và sự kiện kích hoạt trên sơ đồ nhiệt và dải phần trăm được chia sẻ](/agenteye/images/hooks.png)
+*Trang Hooks: độ trễ được phân tích theo tên hook và sự kiện kích hoạt.*
+
+Trên cùng sơ đồ nhiệt độ trễ và dải phần trăm, trang Hooks chia hoạt động thành **tên hook** và **sự kiện kích hoạt**, vì vậy bạn hạ cánh trên hook đơn lẻ và sự kiện đơn lẻ cần được chú ý.
+
+## Liên Quan
+
+- [Event stream](/vi/agenteye/event-stream): dấu vết của từng sự kiện được mã hóa bằng màu trực tiếp.
+- [Sessions](/vi/agenteye/sessions): tổng hợp các sự kiện thành một hàng cho mỗi lần chạy và mở biểu đồ thực thi của nó.
+- [Error tracking](/vi/agenteye/error-tracking): một bề mặt phân loại duy nhất cho tất cả những gì bảng điều khiển vẽ màu đỏ.
+- [Dashboards](/vi/agenteye/dashboards): xem tổng hợp trên toàn bộ đội của bạn.

package/.next/standalone/docs-old/vi/architecture.mdx

@@ -0,0 +1,332 @@
+---
+title: Kiến trúc
+description: "Cách hook handler, config loading, và policy evaluation hoạt động bên trong"
+icon: sitemap
+---
+
+Tài liệu này giải thích cách failproofai hoạt động bên trong: cách hệ thống hook chặn các lệnh gọi tool của agent, cách cấu hình được tải và hợp nhất, cách các policy được đánh giá, và cách dashboard giám sát hoạt động của agent.
+
+---
+
+## Tổng quan
+
+failproofai có hai hệ thống độc lập:
+
+1. **Hook handler** - Một CLI subprocess nhanh mà Claude Code gọi trên mỗi lệnh gọi tool của agent. Đánh giá các policy và trả về quyết định.
+2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để giám sát các phiên làm việc của agent và quản lý các policy.
+
+Cả hai hệ thống chia sẻ các tệp cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của dự án, nhưng chúng chạy như các tiến trình riêng biệt và chỉ giao tiếp thông qua hệ thống tệp.
+
+---
+
+## Hook handler
+
+### Tích hợp với Claude Code
+
+Khi bạn chạy `failproofai policies --install`, nó ghi các mục nhập như thế này vào `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess trước mỗi lệnh gọi tool, truyền một payload JSON trên stdin.
+
+### Định dạng payload
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
+  "cwd": "/home/user/myproject",
+  "permission_mode": "default",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": { "command": "sudo apt install nodejs" }
+}
+```
+
+Đối với các sự kiện `PostToolUse`, payload cũng chứa `tool_result` với đầu ra của tool.
+
+Handler áp dụng giới hạn stdin 1 MB. Các payload vượt quá giới hạn này bị loại bỏ và tất cả các policy ngầm cho phép.
+
+### Định dạng phản hồi
+
+**Deny (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Deny (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Instruct (bất kỳ sự kiện nào trừ Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Stop event instruct:**
+- Mã thoát: `2`
+- Lý do được ghi vào stderr (không phải stdout)
+
+**Allow:**
+- Mã thoát: `0`
+- stdout trống
+
+**Allow với thông báo:**
+
+`allow(message)` cho phép một policy gửi ngữ cảnh thông tin quay lại Claude ngay cả khi thao tác được phép. Hook handler ghi JSON sau đây vào **stdout** (không phải tệp cấu hình — đây là phản hồi của handler đối với Claude Code, giống như các phản hồi deny và instruct ở trên):
+
+```json
+// Được ghi vào stdout bởi tiến trình hook handler
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Mã thoát: `0` (thao tác được phép)
+- Khi nhiều policy trả về `allow` với một thông báo, các thông báo của chúng được nối với dòng mới thành một chuỗi `additionalContext` duy nhất
+- Nếu không có policy nào cung cấp thông báo, stdout trống (giống như trước)
+
+### Quy trình xử lý
+
+`src/hooks/handler.ts` triển khai toàn bộ quy trình:
+
+```text
+stdin JSON
+  → parse payload (max 1 MB)
+  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
+  → readMergedHooksConfig(cwd)    ← merges project + local + global config
+  → register enabled builtin policies with resolved params
+  → load custom policies from customPoliciesPath (if set)
+  → register custom policies into policy registry
+  → evaluate all policies (builtins first, then custom)
+      → first deny short-circuits
+      → instruct decisions accumulate
+      → allow messages accumulate
+  → write JSON decision to stdout
+  → persist event to ~/.failproofai/hook-activity/current.jsonl
+  → exit
+```
+
+Toàn bộ quy trình chạy dưới 100ms đối với các payload điển hình mà không có cuộc gọi LLM.
+
+---
+
+## Tải cấu hình
+
+`src/hooks/hooks-config.ts` triển khai tải cấu hình ba phạm vi.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
+[2] {cwd}/.failproofai/policies-config.local.json  ← local
+[3] ~/.failproofai/policies-config.json             ← global   (lowest priority)
+```
+
+Lôgic hợp nhất:
+- `enabledPolicies` - hợp nhất loại bỏ trùng lặp trên cả ba tệp
+- `policyParams` - mỗi policy là một khóa, tệp đầu tiên định nghĩa nó sẽ thắng hoàn toàn
+- `customPoliciesPath` - tệp đầu tiên định nghĩa nó sẽ thắng
+- `llm` - tệp đầu tiên định nghĩa nó sẽ thắng
+
+Dashboard web sử dụng `readHooksConfig()` (toàn cầu chỉ) để đọc và ghi, vì nó không được gọi với project cwd.
+
+---
+
+## Đánh giá policy
+
+`src/hooks/policy-evaluator.ts` chạy các policy theo thứ tự.
+
+Đối với mỗi policy:
+
+1. Tra cứu lược đồ `params` của policy (nếu có).
+2. Đọc `policyParams[policy.name]` từ cấu hình đã hợp nhất.
+3. Hợp nhất các giá trị do người dùng cung cấp lên các giá trị mặc định của lược đồ để tạo `ctx.params`.
+4. Gọi `policy.fn(ctx)` với ngữ cảnh đã được giải quyết.
+5. Nếu kết quả là `deny`, dừng ngay lập tức và trả về quyết định đó.
+6. Nếu kết quả là `instruct`, tích lũy thông báo và tiếp tục.
+7. Nếu kết quả là `allow`, tiếp tục đến policy tiếp theo.
+
+Sau khi tất cả các policy chạy:
+- Nếu bất kỳ `deny` nào được trả về, phát ra phản hồi deny.
+- Nếu bất kỳ giá trị trả về `instruct` nào được thu thập, phát ra một phản hồi instruct duy nhất với tất cả các thông báo được nối.
+- Nếu không, phát ra phản hồi allow (stdout trống, thoát 0).
+
+---
+
+## Các policy tích hợp
+
+`src/hooks/builtin-policies.ts` định nghĩa tất cả 39 policy tích hợp như các đối tượng `BuiltinPolicyDefinition`:
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+Các policy chấp nhận `params` khai báo `PolicyParamsSchema` với các kiểu và giá trị mặc định cho mỗi tham số. Trình đánh giá policy tiêm các giá trị đã được giải quyết vào `ctx.params` trước khi gọi `fn`. Các hàm policy đọc `ctx.params` mà không cần bảo vệ null vì các giá trị mặc định luôn được áp dụng trước.
+
+So khớp mẫu bên trong các policy sử dụng các token lệnh được phân tích cú pháp (argv), không phải so khớp chuỗi thô. Điều này ngăn chặn vượt qua thông qua injection của toán tử shell (ví dụ: một mẫu cho `sudo systemctl status *` không thể bị vượt qua bằng cách thêm `; rm -rf /` vào lệnh).
+
+---
+
+## Các policy tùy chỉnh
+
+`src/hooks/custom-hooks-registry.ts` triển khai một sổ đăng ký được hỗ trợ bởi `globalThis`:
+
+```typescript
+const REGISTRY_KEY = "__failproofai_custom_hooks__";
+
+export const customPolicies = {
+  add(hook: CustomHook): void { ... }
+};
+
+export function getCustomHooks(): CustomHook[] { ... }
+export function clearCustomHooks(): void { ... }  // used in tests
+```
+
+`src/hooks/custom-hooks-loader.ts` tải tệp policy của người dùng:
+
+1. Đọc `customPoliciesPath` từ cấu hình; bỏ qua nếu không có.
+2. Giải quyết đến đường dẫn tuyệt đối; kiểm tra tệp tồn tại.
+3. Viết lại tất cả các import `from "failproofai"` thành đường dẫn dist thực tế để `customPolicies` được giải quyết thành cùng một sổ đăng ký `globalThis`.
+4. Viết lại một cách đệ quy các import cục bộ chuyển tiếp để đảm bảo tương thích ESM.
+5. Ghi các tệp `.mjs` tạm thời và `import()` tệp mục nhập.
+6. Gọi `getCustomHooks()` để truy xuất các hook được đăng ký.
+7. Dọn sạch tất cả các tệp tạm thời trong khối `finally`.
+
+Khi có bất kỳ lỗi nào (tệp không tìm thấy, lỗi cú pháp, lỗi import), lỗi được ghi vào `~/.failproofai/hook.log` và trình tải trả về một mảng trống. Các policy tích hợp không bị ảnh hưởng.
+
+Các policy tùy chỉnh được đánh giá sau tất cả các policy tích hợp. Một policy tùy chỉnh `deny` vẫn làm ngắn mạch các policy tùy chỉnh tiếp theo (nhưng tất cả các policy tích hợp đã chạy tại thời điểm đó).
+
+---
+
+## Ghi nhật ký hoạt động
+
+Sau mỗi sự kiện hook, handler thêm một dòng JSONL vào `~/.failproofai/hook-activity/current.jsonl`, được xoay thành `page-<timestamp>-<seq>.jsonl` khi nó đạt tới một trang:
+
+```json
+{
+  "timestamp": "2026-04-06T12:34:56.789Z",
+  "sessionId": "abc123",
+  "eventType": "PreToolUse",
+  "toolName": "Bash",
+  "policyName": "block-sudo",
+  "decision": "deny",
+  "reason": "sudo command blocked by failproofai",
+  "durationMs": 12
+}
+```
+
+Một dòng cho mỗi policy đã đưa ra quyết định không phải allow. Các quyết định Allow không được ghi lại (để giữ tệp nhỏ).
+
+---
+
+## Kiến trúc dashboard
+
+Dashboard là một ứng dụng **Next.js 16** sử dụng App Router với React Server Components và Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Root layout (theme, telemetry, nav)
+  projects/page.tsx           ← Server component: list all Claude projects
+  project/[name]/page.tsx     ← Server component: list sessions in a project
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Server component: render session viewer
+  policies/page.tsx           ← Client component: policy management + activity log
+  actions/
+    get-hooks-config.ts       ← Read config + policy list
+    update-hooks-config.ts    ← Toggle policy on/off
+    update-policy-params.ts   ← Update policy parameters
+    get-hook-activity.ts      ← Paginate/search activity log
+    install-hooks-web.ts      ← Install/remove hooks from the browser
+  api/
+    download/[project]/[session]/route.ts   ← Per-CLI session export (JSONL or JSON)
+```
+
+**Luồng dữ liệu:**
+
+- Các thành phần Page gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc dữ liệu dự án/phiên trực tiếp từ hệ thống tệp (không có lớp API cho các lần đọc).
+- Trang Policies sử dụng Server Actions cho tất cả các thay đổi (toggle, cập nhật params, cài đặt/loại bỏ).
+- Trình xem phiên phân tích định dạng JSONL transcript của Claude và hiển thị một dòng thời gian của các thông báo và lệnh gọi tool.
+
+**Các quyết định thiết kế chính:**
+
+- Không có cơ sở dữ liệu - tất cả trạng thái persistent nằm trong các tệp thuần (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions cho các thay đổi - không cần REST API cho các hoạt động CRUD.
+- React Server Components cho các trang đọc - tải ban đầu nhanh hơn, không có client bundle cho việc lấy dữ liệu.
+- Chỉ các thành phần client nơi cần tính tương tác (chuyển đổi policy, tìm kiếm hoạt động, trình xem nhật ký).
+
+---
+
+## Bố cục tệp
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Hook event pipeline
+│   ├── builtin-policies.ts       # 39 policy definitions
+│   ├── policy-evaluator.ts       # Policy execution engine
+│   ├── policy-registry.ts        # Policy registration and lookup
+│   ├── policy-types.ts           # TypeScript interfaces
+│   ├── hooks-config.ts           # Multi-scope config loading
+│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
+│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
+│   ├── manager.ts                # install / remove / list operations
+│   ├── install-prompt.ts         # Interactive policy selection prompt
+│   ├── hook-logger.ts            # Logging to hook.log
+│   ├── hook-activity-store.ts    # Persist activity to hook-activity/
+│   └── llm-client.ts             # LLM API client (for AI-powered policies)
+├── app/                          # Next.js dashboard (pages + server actions)
+├── lib/                          # Shared utilities
+│   ├── projects.ts               # Enumerate Claude projects from filesystem
+│   ├── log-entries.ts            # Parse Claude transcript JSONL format
+│   ├── paths.ts                  # Resolve system paths
+│   └── ...
+├── components/                   # Shared React UI components
+├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
+├── examples/                     # Example custom hook files
+└── __tests__/                    # Unit and E2E tests
+```