failproofai 1.0.1-beta.1 → 1.0.1

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

@@ -0,0 +1,52 @@
+---
+title: "パフォーマンス指標"
+description: "モデル、ツール、またはhookが遅くなったりコストが膨らんだ瞬間を即座に把握し、ユーザーが気づく前にテールレイテンシのスパイクを検出できます。"
+---
+
+
+モデル、ツール、またはhookが遅くなったりコストが膨らんだ瞬間を即座に把握し、ユーザーが気づく前にテールレイテンシのスパイクを検出できます。3つの専用ページが生のタイミングデータをp50、p95、p99に変換し、一目で読み取ることができます。
+
+![レイテンシヒートマップ、パーセンタイルバンド、モデルごとのトークン数・コスト・コンテキストウィンドウ使用率を表示するModelsページ](/agenteye/images/models.png)
+*Modelsページ：レイテンシヒートマップ、パーセンタイルバンド、モデルごとのトークン数・推定コスト・コンテキストウィンドウ使用率。*
+
+## 平均値に最悪の実行を隠させない
+
+平均レイテンシという数値は安心感を与えますが、実際には役に立ちません。50回に1回起きる、深夜2時にオンコール担当を呼び出すような停滞した呼び出しを、平均値は丸めて隠してしまうからです。Models、Tools、Hooksの各ページはそれをしません。どのページも同じ構成を持つので、一度覚えればすべてに応用できます。
+
+- **24ビンのスパークライン**でトレンドを一目確認：状況は悪化しているか？
+- p50、p95、p99レイテンシを並べた**バイタルストリップ**で、典型的な実行とテールを並べて比較。
+- 横軸に24タイムビン、縦軸にレイテンシバケットを取った**レイテンシヒートマップ**で、遅い呼び出しが*いつ*集中したかを可視化。
+- p50ラインにp25〜p75とp10〜p90のシェーディングリボン、p99ドットを重ねた**パーセンタイルバンド**で、ばらつきを平均化せず見え続けるように表示。
+
+共有ホバークロスヘアがヒートマップとバンドを連動させるため、テールスパイクが一本の平均線の陰に隠れることなく、両方で同じ時刻に揃って表示されます。3つのページはすべてダッシュボードの **observe** セクションにあり、組織スコープで日付範囲・環境・エージェント・セッションによるフィルタリングが可能です。
+
+## Models：各モデルのコストを正確に把握する
+
+Modelsページ（上図）は、請求書が常に提起する2つの問いに答えます：どのモデルで、いくらか。共有レイテンシビューに加えて、**モデルごとのトークン消費量**、**推定コスト**、**コンテキストウィンドウ使用率**が追加されるため、プロンプトの急激な肥大化や差し迫ったコンパクションを驚かされる前に把握できます。
+
+Failproof AI Observabilityは一般的なモデルIDを自動的に認識します。ウィンドウサイズが正しくない場合や独自のプライベートモデルを使用している場合は、**Settings** の **model context windows** で修正または追加してください。使用率の表示もそれに従って更新されます。
+
+## Tools：遅いものと壊れているものを見分ける
+
+ツール呼び出しは遅いこともあれば、静かに失敗していることもあります。どちらなのかを、ログを掘り返してからではなく、数秒で知る必要があります。
+
+![共有レイテンシヒートマップとパーセンタイルバンドの横に成功・失敗の内訳とツール分布バーを表示するToolsページ](/agenteye/images/tools.png)
+*Toolsページ：同じヒートマップとパーセンタイルバンド、さらに成功・失敗の内訳とツール分布バー。*
+
+共有レイテンシビューに加えて、Toolsページには**成功・失敗の内訳**と**ツール分布バー**が追加されます。これにより、最も頻繁に使われているツールと、エラーバジェットを消費しているツールが一目でわかります。
+
+## Hooks：問題のあるhookとトリガーをピンポイントで特定する
+
+ライフサイクルhookが実行を遅らせているとき、「hookが遅い」というだけでは対処できません。Hooksページは問題のある一つにたどり着く手助けをします。
+
+![共有ヒートマップとパーセンタイルバンドの上にhook名とトリガーイベントごとにレイテンシを分解表示するHooksページ](/agenteye/images/hooks.png)
+*Hooksページ：hook名とトリガーイベントごとに分解されたレイテンシ。*
+
+同じレイテンシヒートマップとパーセンタイルバンドの上で、Hooksページは**hook名**と**トリガーイベント**ごとにアクティビティを分解します。これにより、注意が必要な単一のhookと単一のイベントに直接たどり着けます。
+
+## 関連項目
+
+- [イベントストリーム](/ja/agenteye/event-stream)：すべてのイベントのリアルタイム・カラーコード付きトレイル。
+- [セッション](/ja/agenteye/sessions)：イベントを実行ごとに1行にまとめ、実行グラフを開く。
+- [エラートラッキング](/ja/agenteye/error-tracking)：ダッシュボードが赤く表示するすべての問題を一元的にトリアージするサーフェス。
+- [ダッシュボード](/ja/agenteye/dashboards)：フリート全体のロールアップビュー。

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

@@ -0,0 +1,332 @@
+---
+title: アーキテクチャ
+description: "フックハンドラー、設定読み込み、ポリシー評価の内部動作"
+icon: sitemap
+---
+
+このドキュメントでは、failproofai の内部動作について説明します。フックシステムがエージェントのツール呼び出しをどのようにインターセプトするか、設定がどのように読み込まれマージされるか、ポリシーがどのように評価されるか、そしてダッシュボードがエージェントのアクティビティをどのように監視するかについて解説します。
+
+---
+
+## 概要
+
+failproofai は独立した 2 つのサブシステムで構成されています。
+
+1. **フックハンドラー** - Claude Code がすべてのエージェントツール呼び出しに対して起動する高速な CLI サブプロセスです。ポリシーを評価して判定結果を返します。
+2. **エージェントモニター（ダッシュボード）** - エージェントセッションの監視とポリシー管理のための Next.js Web アプリケーションです。
+
+両サブシステムは `~/.failproofai/` およびプロジェクトの `.failproofai/` ディレクトリにある設定ファイルを共有しますが、それぞれ別プロセスとして動作し、ファイルシステムを通じてのみ通信します。
+
+---
+
+## フックハンドラー
+
+### 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` をサブプロセスとして起動し、JSON ペイロードを stdin 経由で渡します。
+
+### ペイロード形式
+
+```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` イベントの場合、ペイロードにはツールの出力を含む `tool_result` も含まれます。
+
+ハンドラーは stdin の上限を 1 MB に制限しています。この上限を超えるペイロードは破棄され、すべてのポリシーは暗黙的に allow となります。
+
+### レスポンス形式
+
+**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`
+- 理由は stdout ではなく stderr に書き込まれます
+
+**Allow:**
+- 終了コード: `0`
+- stdout は空
+
+**メッセージ付き Allow:**
+
+`allow(message)` を使うと、操作が許可された場合でもポリシーから Claude に情報コンテキストを送り返せます。フックハンドラーは次の JSON を **stdout** に書き込みます（設定ファイルではなく、上記の deny・instruct レスポンスと同様に、Claude Code へのハンドラーのレスポンスです）。
+
+```json
+// フックハンドラープロセスが stdout に書き込む内容
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- 終了コード: `0`（操作は許可される）
+- 複数のポリシーがメッセージ付きの `allow` を返した場合、それらのメッセージは改行で結合されて単一の `additionalContext` 文字列になります
+- ポリシーがメッセージを返さない場合、stdout は空になります（従来と同様）
+
+### 処理パイプライン
+
+`src/hooks/handler.ts` がパイプライン全体を実装しています。
+
+```text
+stdin JSON
+  → ペイロードのパース（最大 1 MB）
+  → セッションメタデータの抽出（session_id、cwd、tool_name、tool_input など）
+  → readMergedHooksConfig(cwd)    ← プロジェクト・ローカル・グローバル設定をマージ
+  → 有効な組み込みポリシーを解決済みパラメーターで登録
+  → customPoliciesPath からカスタムポリシーを読み込み（設定されている場合）
+  → カスタムポリシーをポリシーレジストリに登録
+  → すべてのポリシーを評価（組み込みが先、次にカスタム）
+      → 最初の deny で短絡評価
+      → instruct の判定を蓄積
+      → allow のメッセージを蓄積
+  → JSON 判定結果を stdout に書き込み
+  → イベントを ~/.failproofai/hook-activity/current.jsonl に永続化
+  → 終了
+```
+
+LLM 呼び出しなしで、一般的なペイロードに対して全体が 100ms 未満で完了します。
+
+---
+
+## 設定の読み込み
+
+`src/hooks/hooks-config.ts` が 3 スコープの設定読み込みを実装しています。
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← プロジェクト（最高優先度）
+[2] {cwd}/.failproofai/policies-config.local.json  ← ローカル
+[3] ~/.failproofai/policies-config.json             ← グローバル（最低優先度）
+```
+
+マージのロジック:
+- `enabledPolicies` - 3 つのファイルにわたって重複排除したユニオン
+- `policyParams` - ポリシーごとのキーで、最初に定義したファイルが全体として優先
+- `customPoliciesPath` - 最初に定義したファイルが優先
+- `llm` - 最初に定義したファイルが優先
+
+Web ダッシュボードはプロジェクトの cwd なしで起動されるため、読み書きに `readHooksConfig()`（グローバルのみ）を使用します。
+
+---
+
+## ポリシーの評価
+
+`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 は空、終了コードは 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` を宣言します。ポリシーエバリュエーターは `fn` を呼び出す前に解決済みの値を `ctx.params` に注入します。デフォルト値は常に先に適用されるため、ポリシー関数は null チェックなしで `ctx.params` を読み取れます。
+
+ポリシー内のパターンマッチングは、生の文字列マッチングではなくパース済みのコマンドトークン（argv）を使用します。これにより、シェル演算子のインジェクションによるバイパスを防ぎます（例: `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 { ... }  // テストで使用
+```
+
+`src/hooks/custom-hooks-loader.ts` はユーザーのポリシーファイルを読み込みます。
+
+1. 設定から `customPoliciesPath` を読み取り、存在しない場合はスキップします。
+2. 絶対パスに解決してファイルの存在を確認します。
+3. `from "failproofai"` のすべてのインポートを実際の dist パスに書き換え、`customPolicies` が同じ `globalThis` レジストリを参照するようにします。
+4. ESM 互換性を確保するため、推移的なローカルインポートを再帰的に書き換えます。
+5. 一時的な `.mjs` ファイルを書き出し、エントリファイルを `import()` します。
+6. `getCustomHooks()` を呼び出して登録済みフックを取得します。
+7. `finally` ブロックですべての一時ファイルを削除します。
+
+エラー（ファイルが見つからない、構文エラー、インポート失敗）が発生した場合、エラーは `~/.failproofai/hook.log` に記録され、ローダーは空の配列を返します。組み込みポリシーへの影響はありません。
+
+カスタムポリシーはすべての組み込みポリシーの後に評価されます。カスタムポリシーが `deny` を返した場合、以降のカスタムポリシーの評価は短絡されますが、その時点ですべての組み込みポリシーはすでに実行済みです。
+
+---
+
+## アクティビティログ
+
+各フックイベントの後、ハンドラーは JSONL の 1 行を `~/.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 以外の判定をしたポリシーごとに 1 行記録されます。allow の判定はファイルサイズを小さく保つためにログに記録されません。
+
+---
+
+## ダッシュボードのアーキテクチャ
+
+ダッシュボードは App Router を使用した **Next.js 16** アプリケーションで、React Server Components と Server Actions を活用しています。
+
+```text
+app/
+  layout.tsx                  ← ルートレイアウト（テーマ、テレメトリー、ナビゲーション）
+  projects/page.tsx           ← サーバーコンポーネント: すべての Claude プロジェクトを一覧表示
+  project/[name]/page.tsx     ← サーバーコンポーネント: プロジェクト内のセッションを一覧表示
+  project/[name]/session/
+    [sessionId]/page.tsx      ← サーバーコンポーネント: セッションビューアーのレンダリング
+  policies/page.tsx           ← クライアントコンポーネント: ポリシー管理 + アクティビティログ
+  actions/
+    get-hooks-config.ts       ← 設定 + ポリシーリストの読み取り
+    update-hooks-config.ts    ← ポリシーの有効/無効の切り替え
+    update-policy-params.ts   ← ポリシーパラメーターの更新
+    get-hook-activity.ts      ← アクティビティログのページネーション/検索
+    install-hooks-web.ts      ← ブラウザからのフックのインストール/削除
+  api/
+    download/[project]/[session]/route.ts   ← CLI セッションごとのエクスポート（JSONL または JSON）
+```
+
+**データフロー:**
+
+- ページコンポーネントは `lib/projects.ts` と `lib/log-entries.ts` を呼び出し、ファイルシステムから直接プロジェクト/セッションデータを読み取ります（読み取りに API レイヤーは不要）。
+- Policies ページはすべての変更操作（切り替え、パラメーター更新、インストール/削除）に Server Actions を使用します。
+- セッションビューアーは Claude の JSONL トランスクリプト形式をパースし、メッセージとツール呼び出しのタイムラインをレンダリングします。
+
+**主要な設計判断:**
+
+- データベースなし - すべての永続的な状態はプレーンファイル（`~/.failproofai/`、`~/.claude/projects/`）に保存します。
+- 変更操作には Server Actions を使用 - CRUD 操作に REST API は不要です。
+- 読み取りページには React Server Components を使用 - 初期ロードが高速で、データフェッチのクライアントバンドルが不要です。
+- クライアントコンポーネントはインタラクティブ性が必要な場合のみ使用します（ポリシーの切り替え、アクティビティ検索、ログビューアー）。
+
+---
+
+## ファイル構成
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI ルーター（hook / dashboard / install など）
+├── src/hooks/
+│   ├── handler.ts                # フックイベントパイプライン
+│   ├── builtin-policies.ts       # 39 個のポリシー定義
+│   ├── policy-evaluator.ts       # ポリシー実行エンジン
+│   ├── policy-registry.ts        # ポリシーの登録と参照
+│   ├── policy-types.ts           # TypeScript インターフェース
+│   ├── hooks-config.ts           # マルチスコープ設定読み込み
+│   ├── custom-hooks-registry.ts  # globalThis ベースのフックレジストリ
+│   ├── custom-hooks-loader.ts    # ユーザー JS フック用の ESM ローダー
+│   ├── manager.ts                # インストール/削除/一覧操作
+│   ├── install-prompt.ts         # インタラクティブなポリシー選択プロンプト
+│   ├── hook-logger.ts            # hook.log へのログ記録
+│   ├── hook-activity-store.ts    # hook-activity/ へのアクティビティ永続化
+│   └── llm-client.ts             # LLM API クライアント（AI 駆動ポリシー用）
+├── app/                          # Next.js ダッシュボード（ページ + サーバーアクション）
+├── lib/                          # 共有ユーティリティ
+│   ├── projects.ts               # ファイルシステムから Claude プロジェクトを列挙
+│   ├── log-entries.ts            # Claude トランスクリプト JSONL 形式のパース
+│   ├── paths.ts                  # システムパスの解決
+│   └── ...
+├── components/                   # 共有 React UI コンポーネント
+├── contexts/                     # React コンテキストプロバイダー（テーマ、自動更新、テレメトリー）
+├── examples/                     # カスタムフックファイルのサンプル
+└── __tests__/                    # ユニットテストおよび E2E テスト
+```