failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,52 @@
+---
+title: "מדדי ביצוע"
+description: "ראה את הרגע בו המודלים, הכלים או ה-hooks מאטים או מרימים את החשבון, ותופסו עיכוב זנב לפני שהמשתמשים שלך ירגישו זאת."
+---
+
+
+ראה את הרגע בו המודלים, הכלים או ה-hooks מאטים או מרימים את החשבון, ותופסו עיכוב זנב לפני שהמשתמשים שלך ירגישו זאת. שלוש דפים ייעודיים הופכים תזמוני גולמיים ל-p50, p95, ו-p99 שתוכל לקרוא בחטף.
+
+![דף Models המציג מפת חום של latency, קו אחוזון ומספרים לפי מודל של טוקנים, עלות וחלון context](/agenteye/images/models.png)
+*דף Models: מפת חום של latency, קו אחוזון וטוקנים לפי מודל, עלות משוערת ומילוי חלון context.*
+
+## הפסק להתיר לממוצעים להסתיר את ההרצות הגרועות שלך
+
+מספר latency ממוצע הוא משכנע וחסר תועלת: הוא משטח על אותה קריאה אחת מחמישים שתלויה ומעוררת את ה-on-call שלך בשעתיים בלילה. דפי Models, Tools ו-Hooks מסרבים לעשות זאת. לכל אחד אותו צורה, כך שתלמד את זה פעם אחת:
+
+- **sparkline בן 24 תאים** עבור הטרנד בחטף: האם זה הולך להחמיר?
+- **פס חיויים** עם p50, p95, ו-p99 latency, כך שההרצה הטיפוסית והזנב יושבים זה ליד זה.
+- **מפת חום של latency**, 24 תאי זמן לפי דלי latency, שמציגה *מתי* הקריאות האטות התקבצו.
+- **קו אחוזון**: קו p50 עם סרטי צל p25 ל-p75 ו-p10 ל-p90 ונקודות p99, כך שההתפשטות נשארת גלויה במקום להיות ממוצעת.
+
+crosshair ריחוף משותף קושר את מפת החום והקו, כך שעיכוב זנב מיישר שורה בזמן על שניהם במקום להסתתר מאחורי שורת ממוצע אחת. מצא את כל שלוש הדפים בקטע **observe** של הלוח הבקרה שלך, כל אחד בהיקף הארגון שלך וניתן לסינון לפי טווח תאריכים, סביבה, agent וsession.
+
+## Models: ראה בדיוק מה כל מודל עולה לך
+
+דף Models (המוצג למעלה) עונה על שתי השאלות שכל חשבון מעלה: איזה מודל, וכמה. על גבי התצוגה latency המשותפת, הוא מוסיף **צריכת טוקנים לפי מודל**, **עלות משוערת** ו**מילוי חלון context**, כך שגדילה בלתי מבוקרת של prompt וcompaction קרוב יותר גלויים לפני שהם תופסים אותך בפתיעה.
+
+Failproof AI Observability מזהה מזהי מודל נפוצים באופן אוטומטי. אם חלון נראה לא תקין, או שאתה מריץ מודל פרטי משלך, תקן אותו או הוסף אחד תחת **Settings**, ב**model context windows**, וקריאות המילוי עוקבות.
+
+## Tools: הבחן בין האיטי לשבור
+
+קריאת tool יכולה להיות איטית, או שהיא יכולה להיכשל בשקט, ואתה רוצה לדעת איזה מהם בעוד שניות, לא אחרי שחפרת דרך יומנים.
+
+![דף Tools המציג את מפת החום של latency המשותפת וקו האחוזון ליד פירוק הצלחה וכישלון וקו התפלגות כלי](/agenteye/images/tools.png)
+*דף Tools: אותה מפת חום וקו אחוזון, בתוספת פירוק הצלחה וכישלון וקו התפלגות כלי.*
+
+לצד התצוגה latency המשותפת, דף Tools מוסיף **פירוק הצלחה וכישלון** ו**קו התפלגות כלי**, כך שתראה בחטף אילו כלים אתה מסתמך עליהם הכי הרבה ואילו אוכלים את תקציב השגיאות שלך.
+
+## Hooks: אתר את ה-hook והטריגר המדויקים
+
+כאשר lifecycle hook משך run, "hooks הם איטיים" אינו משהו שאתה יכול לפעול לפיו. דף Hooks מקבל אותך לזה שחשוב.
+
+![דף Hooks המציג latency מפורק לפי שם hook ואירוע טריגר על מפת החום והקו האחוזון המשותפים](/agenteye/images/hooks.png)
+*דף Hooks: latency מפורק לפי שם hook ואירוע טריגר.*
+
+על אותה מפת חום של latency וקו אחוזון, דף Hooks מפרק את הפעילות לפי **שם hook** ו**אירוע טריגר**, כך שתנחת על ה-hook האחד ואירוע אחד שצריכים תשומת לב.
+
+## קשור
+
+- [Event stream](/he/agenteye/event-stream): השביל החי וקידוד הצבע של כל אירוע.
+- [Sessions](/he/agenteye/sessions): צבור אירועים לשורה אחת לכל ריצה ופתח את גרף ההוצאה לפועל שלה.
+- [Error tracking](/he/agenteye/error-tracking): משטח triage אחד לכל מה שהלוח הבקרה צובע אדום.
+- [Dashboards](/he/agenteye/dashboards): צפייה rolled-up על פני הצי שלך.

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

@@ -0,0 +1,332 @@
+---
+title: ארכיטקטורה
+description: "כיצד מטפל ה-hook, טעינת ההגדרות והערכת המדיניות פועלים באופן פנימי"
+icon: sitemap
+---
+
+מסמך זה מסביר כיצד failproofai עובד באופן פנימי: כיצד מערכת ה-hook יוצרת intercept לקריאות כלים של Agent, כיצד הגדרות נטענות ומשולבות, כיצד מדיניות מוערכות, וכיצד ה-dashboard עוקב אחרי פעילות agent.
+
+---
+
+## סקירה כללית
+
+ל-failproofai שתי תת-מערכות עצמאיות:
+
+1. **מטפל Hook** - תת-תהליך CLI מהיר ש-Claude Code משדר בכל קריאת כלי agent. מעריך מדיניות וחוזר החלטה.
+2. **Agent Monitor (Dashboard)** - יישום אינטרנט Next.js לניטור הפעלות של agent וניהול מדיניות.
+
+שתי התת-מערכות חולקות קבצי הגדרות ב-`~/.failproofai/` ובדירקטוריון `.failproofai/` של הפרויקט, אך הן פועלות כתהליכים נפרדים ותקשרות רק דרך מערכת הקבצים.
+
+---
+
+## מטפל Hook
+
+### אינטגרציה עם Claude Code
+
+כאשר אתה מריץ `failproofai policies --install`, הוא כותב ערכים כאלה ל-`~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code אז משדר את `failproofai --hook PreToolUse` כתת-תהליך לפני כל קריאת כלי, ומעביר payload JSON ב-stdin.
+
+### פורמט 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" }
+}
+```
+
+עבור אירועי `PostToolUse`, ה-payload מכיל גם `tool_result` עם הפלט של הכלי.
+
+המטפל אוכף מגבלת stdin של 1 MB. Payloads שחוצים זה מושלכים וכל המדיניות מאפשרת באופן משתמע.
+
+### פורמט תגובה
+
+**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 (כל אירוע פרט ל-Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**אירוע Stop instruct:**
+- קוד יציאה: `2`
+- סיבה כתובה ל-stderr (לא stdout)
+
+**Allow:**
+- קוד יציאה: `0`
+- stdout ריק
+
+**Allow עם הודעה:**
+
+`allow(message)` מאפשר למדיניות לשלוח הקשר מידע חוזר ל-Claude גם כשהפעולה מותרת. מטפל ה-hook כותב את ה-JSON הבא ל-**stdout** (לא קובץ הגדרות — זו התגובה של המטפל ל-Claude Code, בדיוק כמו תגובות deny ו-instruct לעיל):
+
+```json
+// כתוב ל-stdout על ידי תהליך מטפל ה-hook
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- קוד יציאה: `0` (הפעולה מותרת)
+- כאשר מספר מדיניות חוזרות `allow` עם הודעה, ההודעות שלהן משולבות עם newlines לתוך מחרוזת `additionalContext` יחידה
+- אם אף מדיניות לא מספקת הודעה, stdout ריק (כמו קודם)
+
+### צינור עיבוד
+
+`src/hooks/handler.ts` מיישם את הצינור המלא:
+
+```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
+```
+
+כל התהליך רץ תחת 100ms עבור payloads טיפוסיים ללא קריאות LLM.
+
+---
+
+## טעינת הגדרות
+
+`src/hooks/hooks-config.ts` מיישם טעינת הגדרות בתלת-scope.
+
+```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)
+```
+
+לוגיקת merge:
+- `enabledPolicies` - איחוד מבודד בכל שלושת הקבצים
+- `policyParams` - לכל מדיניות, הקובץ הראשון שמגדיר אותו מנצח לחלוטין
+- `customPoliciesPath` - הקובץ הראשון שמגדיר אותו מנצח
+- `llm` - הקובץ הראשון שמגדיר אותו מנצח
+
+ה-dashboard של האינטרנט משתמש ב-`readHooksConfig()` (global only) לקריאה וכתיבה, מכיוון שהוא לא משדר עם project cwd.
+
+---
+
+## הערכת מדיניות
+
+`src/hooks/policy-evaluator.ts` מריץ מדיניות בסדר.
+
+עבור כל מדיניות:
+
+1. חפש את סכימת `params` של המדיניות (אם יש לה כזה).
+2. קרא את `policyParams[policy.name]` מהגדרה המוזגת.
+3. מזג ערכים שסופקו על ידי המשתמש על פני ברירות מחדל של סכימה כדי לייצר `ctx.params`.
+4. קרא את `policy.fn(ctx)` עם ההקשר שנפתר.
+5. אם התוצאה היא `deny`, עצור מיד והחזר החלטה זו.
+6. אם התוצאה היא `instruct`, צבור את ההודעה והמשך.
+7. אם התוצאה היא `allow`, המשך למדיניות הבאה.
+
+לאחר שכל המדיניות פעלות:
+- אם כל `deny` הוחזר, פלוט את תגובת ה-deny.
+- אם כל `instruct` הוחזרו נאספו, פלוט תגובת instruct יחידה עם כל ההודעות משולבות.
+- אחרת, פלוט תגובה allow (stdout ריק, exit 0).
+
+---
+
+## מדיניות מובנית
+
+`src/hooks/builtin-policies.ts` מגדיר את כל 39 המדיניות המובנות כאובייקטי `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;
+}
+```
+
+מדיניות המקבלת `params` מצהירה `PolicyParamsSchema` עם סוגים וברירות מחדל לכל פרמטר. מעריך המדיניות משדר ערכים שנפתרו ל-`ctx.params` לפני קריאה ל-`fn`. פונקציות מדיניות קוראות `ctx.params` ללא null-guarding מכיוון שברירות מחדל תמיד מוחלות קודם.
+
+התאמת דפוס בתוך מדיניות משתמשת בתוקנים מפוענחי פקודה (argv), לא התאמה של מחרוזות גולמיות. זה מונע עקיפה דרך הזרקת מפעילים של shell (למשל דפוס עבור `sudo systemctl status *` לא יכול להיות מעוקף על ידי הוספת `; rm -rf /` לפקודה).
+
+---
+
+## מדיניות מותאמת אישית
+
+`src/hooks/custom-hooks-registry.ts` מיישם רג'יסטרי תומך `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` טוען את קובץ המדיניות של המשתמש:
+
+1. קרא את `customPoliciesPath` מההגדרות; דלג אם חסר.
+2. פתור לנתיב מוחלט; בדוק שהקובץ קיים.
+3. כתוב מחדש את כל ה-`from "failproofai"` imports לנתיב dist בפועל כך `customPolicies` מתחזר לרג'יסטרי `globalThis` זהה.
+4. כתוב מחדש transitive local imports רקורסיבי כדי להבטיח תאימות ESM.
+5. כתוב קבצי `.mjs` זמניים ו-`import()` את קובץ הערך.
+6. קרא `getCustomHooks()` כדי לאחזר hooks רשומים.
+7. נקה את כל קבצים זמניים בבלוק `finally`.
+
+בכל שגיאה (קובץ לא נמצא, שגיאת תחביר, כשל בייבוא), השגיאה מתועדת ל-`~/.failproofai/hook.log` והמטעין מחזיר מערך ריק. מדיניות מובנית לא מושפעת.
+
+מדיניות מותאמת אישית מוערכת לאחר כל המדיניות המובנות. מדיניות מותאמת אישית `deny` עדיין מקצרת מדיניויות מותאמות אישיות נוספות (אך כל המובנות כבר רצו בנקודה זו).
+
+---
+
+## ניתוח פעילות
+
+לאחר כל אירוע hook, המטפל משדר שורת JSONL ל-`~/.failproofai/hook-activity/current.jsonl`, שמסתובבת ל-`page-<timestamp>-<seq>.jsonl` ברגע שהוא מגיע לעמוד:
+
+```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
+}
+```
+
+שורה אחת לכל מדיניות שהחזירה החלטה שאינה allow. החלטות Allow לא מתועדות (כדי להשאיר את הקובץ קטן).
+
+---
+
+## ארכיטקטורת Dashboard
+
+ה-dashboard הוא יישום **Next.js 16** המשתמש ב-App Router עם React Server Components ו-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)
+```
+
+**זרימת נתונים:**
+
+- רכיבי עמוד קוראים `lib/projects.ts` ו-`lib/log-entries.ts` כדי לקרוא נתוני project/session ישירות ממערכת הקבצים (אין שכבת API לקריאות).
+- עמוד Policies משתמש ב-Server Actions לכל המוטציות (toggle, params update, install/remove).
+- מצפה ההפעלה מפענח את פורמט הטרנסקריפט JSONL של Claude ומעביר ציר הזמן של הודעות וקריאות כלים.
+
+**החלטות עיצוב מרכזיות:**
+
+- אין מסד נתונים - כל מצב קבוע הוא בקבצים רגילים (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions לתוך מוטציות - אין צורך ב-REST API עבור פעולות CRUD.
+- React Server Components עבור עמודי קריאה - טעינה ראשונית מהירה יותר, אין חבילה של client עבור fetch נתונים.
+- רכיבי client רק כאשר נדרשת אינטראקטיביות (toggles מדיניות, חיפוש פעילות, צופה יומן).
+
+---
+
+## פריסת קבצים
+
+```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
+```