failproofai 0.0.6-beta.2 → 0.0.6-beta.4

package/.next/standalone/docs/custom-policies.mdx

@@ -1,353 +0,0 @@
----
-title: Custom Policies
-description: "Write your own policies in JavaScript - enforce conventions, prevent drift, detect failures, integrate with external systems"
-icon: code
----
-
-Custom policies let you write rules for any agent behavior: enforce project conventions, prevent drift, gate destructive operations, detect stuck agents, or integrate with Slack, approval workflows, and more. They use the same hook event system and `allow`, `deny`, `instruct` decisions as built-in policies.
-
----
-
-## Quick example
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-customPolicies.add({
-  name: "no-production-writes",
-  description: "Block writes to paths containing 'production'",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("production")) {
-      return deny("Writes to production paths are blocked");
-    }
-    return allow();
-  },
-});
-```
-
-Install it:
-
-```bash
-failproofai policies --install --custom ./my-policies.js
-```
-
----
-
-## Two ways to load custom policies
-
-### Option 1: Convention-based (recommended)
-
-Drop `*policies.{js,mjs,ts}` files into `.failproofai/policies/` and they're automatically loaded — no flags or config changes needed. This works like git hooks: drop a file, it just works.
-
-```
-# Project level — committed to git, shared with the team
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# User level — personal, applies to all projects
-~/.failproofai/policies/my-policies.mjs
-```
-
-**How it works:**
-- Both project and user directories are scanned (union — not first-scope-wins)
-- Files are loaded alphabetically within each directory. Prefix with `01-`, `02-` to control order
-- Only files matching `*policies.{js,mjs,ts}` are loaded; other files are ignored
-- Each file is loaded independently (fail-open per file)
-- Works alongside explicit `--custom` and built-in policies
-
-<Tip>
-Convention policies are the easiest way to build a quality standard for your org. Commit `.failproofai/policies/` to git and every team member gets the same rules automatically — no per-developer setup needed. As your team discovers new failure modes, add a policy and push. Over time these become a living quality standard that keeps improving with every contribution.
-</Tip>
-
-### Option 2: Explicit file path
-
-```bash
-# Install with a custom policies file
-failproofai policies --install --custom ./my-policies.js
-
-# Replace the policies file path
-failproofai policies --install --custom ./new-policies.js
-
-# Remove the custom policies path from config
-failproofai policies --uninstall --custom
-```
-
-The resolved absolute path is stored in `policies-config.json` as `customPoliciesPath`. The file is loaded fresh on every hook event - there is no caching between events.
-
-### Using both together
-
-Convention policies and the explicit `--custom` file can coexist. Load order:
-
-1. Explicit `customPoliciesPath` file (if configured)
-2. Project convention files (`{cwd}/.failproofai/policies/`, alphabetical)
-3. User convention files (`~/.failproofai/policies/`, alphabetical)
-
----
-
-## API
-
-### Import
-
-```js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-```
-
-### `customPolicies.add(hook)`
-
-Registers a policy. Call this as many times as needed for multiple policies in the same file.
-
-```ts
-customPolicies.add({
-  name: string;                         // required - unique identifier
-  description?: string;                 // shown in `failproofai policies` output
-  match?: { events?: HookEventType[] }; // filter by event type; omit to match all
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-});
-```
-
-### Decision helpers
-
-| Function | Effect | Use when |
-|----------|--------|----------|
-| `allow()` | Permit the operation silently | The action is safe, no message needed |
-| `deny(message)` | Block the operation | The agent should not take this action |
-| `instruct(message)` | Add context without blocking | Give the agent extra context to stay on track |
-
-`deny(message)` - the message appears to Claude prefixed with `"Blocked by failproofai:"`. A single `deny` short-circuits all further evaluation.
-
-`instruct(message)` - the message is appended to Claude's context for the current tool call. All `instruct` messages are accumulated and delivered together.
-
-<Tip>
-You can append extra guidance to any `deny` or `instruct` message by adding a `hint` field in `policyParams` — no code change needed. This works for custom (`custom/`), project convention (`.failproofai-project/`), and user convention (`.failproofai-user/`) policies too. See [Configuration → hint](/configuration#hint-cross-cutting) for details.
-</Tip>
-
-### Informational allow messages
-
-`allow(message)` permits the operation **and** sends an informational message back to Claude. The message is delivered as `additionalContext` in the hook handler's stdout response — the same mechanism used by `instruct`, but semantically different: it's a status update, not a warning.
-
-| Function | Effect | Use when |
-|----------|--------|----------|
-| `allow(message)` | Permit and send context to Claude | Confirm a check passed, or explain why a check was skipped |
-
-Use cases:
-- **Status confirmations:** `allow("All CI checks passed.")` — tells Claude everything is green
-- **Fail-open explanations:** `allow("GitHub CLI not installed, skipping CI check.")` — tells Claude why a check was skipped so it has full context
-- **Multiple messages accumulate:** if several policies each return `allow(message)`, all messages are joined with newlines and delivered together
-
-```js
-customPolicies.add({
-  name: "confirm-branch-status",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    const cwd = ctx.session?.cwd;
-    if (!cwd) return allow("No working directory, skipping branch check.");
-
-    // ... check branch status ...
-    if (allPushed) {
-      return allow("Branch is up to date with remote.");
-    }
-    return deny("Unpushed changes detected.");
-  },
-});
-```
-
-### `PolicyContext` fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | The tool being called (e.g. `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | The tool's input parameters |
-| `payload` | `Record<string, unknown>` | Full raw event payload from Claude Code |
-| `session` | `SessionMetadata \| undefined` | Session context (see below) |
-
-### `SessionMetadata` fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `sessionId` | `string` | Claude Code session identifier |
-| `cwd` | `string` | Working directory of the Claude Code session |
-| `transcriptPath` | `string` | Path to the session's JSONL transcript file |
-
-### Event types
-
-| Event | When it fires | `toolInput` contents |
-|-------|--------------|----------------------|
-| `PreToolUse` | Before Claude runs a tool | The tool's input (e.g. `{ command: "..." }` for Bash) |
-| `PostToolUse` | After a tool completes | The tool's input + `tool_result` (the output) |
-| `Notification` | When Claude sends a notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks must always return `allow()`, they cannot block notifications |
-| `Stop` | When the Claude session ends | Empty |
-
----
-
-## Evaluation order
-
-Policies are evaluated in this order:
-
-1. Built-in policies (in definition order)
-2. Explicit custom policies from `customPoliciesPath` (in `.add()` order)
-3. Convention policies from project `.failproofai/policies/` (files alphabetical, `.add()` order within)
-4. Convention policies from user `~/.failproofai/policies/` (files alphabetical, `.add()` order within)
-
-<Note>
-The first `deny` short-circuits all subsequent policies. All `instruct` messages are accumulated and delivered together.
-</Note>
-
----
-
-## Transitive imports
-
-Custom policy files can import local modules using relative paths:
-
-```js
-// my-policies.js
-import { isBlockedPath } from "./utils.js";
-import { checkApproval } from "./approval-client.js";
-
-customPolicies.add({
-  name: "approval-gate",
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
-    return approved ? allow() : deny("Approval required for this command");
-  },
-});
-```
-
-All relative imports reachable from the entry file are resolved. This is implemented by rewriting `from "failproofai"` imports to the actual dist path and creating temporary `.mjs` files to ensure ESM compatibility.
-
----
-
-## Event type filtering
-
-Use `match.events` to limit when a policy fires:
-
-```js
-customPolicies.add({
-  name: "require-summary-on-stop",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    // Only fires when the session ends
-    // ctx.session.transcriptPath contains the full session log
-    return allow();
-  },
-});
-```
-
-Omit `match` entirely to fire on every event type.
-
----
-
-## Error handling and failure modes
-
-Custom policies are **fail-open**: errors never block built-in policies or crash the hook handler.
-
-| Failure | Behavior |
-|---------|----------|
-| `customPoliciesPath` not set | No explicit custom policies run; convention policies and built-ins continue normally |
-| File not found | Warning logged to `~/.failproofai/hook.log`; built-ins continue |
-| Syntax/import error (explicit) | Error logged to `~/.failproofai/hook.log`; explicit custom policies skipped |
-| Syntax/import error (convention) | Error logged; that file skipped, other convention files still load |
-| `fn` throws at runtime | Error logged; that hook treated as `allow`; other hooks continue |
-| `fn` takes longer than 10s | Timeout logged; treated as `allow` |
-| Convention directory missing | No convention policies run; no error |
-
-<Tip>
-To debug custom policy errors, watch the log file:
-
-```bash
-tail -f ~/.failproofai/hook.log
-```
-</Tip>
-
----
-
-## Full example: multiple policies
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-// Prevent agent from writing to secrets/ directory
-customPolicies.add({
-  name: "block-secrets-dir",
-  description: "Prevent agent from writing to secrets/ directory",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
-    return allow();
-  },
-});
-
-// Keep the agent on track: verify tests before committing
-customPolicies.add({
-  name: "remind-test-before-commit",
-  description: "Keep the agent on track: verify tests pass before committing",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    if (/git\s+commit/.test(cmd)) {
-      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
-    }
-    return allow();
-  },
-});
-
-// Prevent unplanned dependency changes during freeze
-customPolicies.add({
-  name: "dependency-freeze",
-  description: "Prevent unplanned dependency changes during freeze period",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
-    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
-      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
-    }
-    return allow();
-  },
-});
-
-export { customPolicies };
-```
-
----
-
-## Examples
-
-The `examples/` directory contains ready-to-run policy files:
-
-| File | Contents |
-|------|----------|
-| `examples/policies-basic.js` | Five starter policies covering common agent failure modes |
-| `examples/policies-advanced/index.js` | Advanced patterns: transitive imports, async calls, output scrubbing, and session-end hooks |
-| `examples/convention-policies/security-policies.mjs` | Convention-based security policies (block .env writes, prevent git history rewriting) |
-| `examples/convention-policies/workflow-policies.mjs` | Convention-based workflow policies (test reminders, audit file writes) |
-
-### Using explicit file examples
-
-```bash
-failproofai policies --install --custom ./examples/policies-basic.js
-```
-
-### Using convention-based examples
-
-```bash
-# Copy to project level
-mkdir -p .failproofai/policies
-cp examples/convention-policies/*.mjs .failproofai/policies/
-
-# Or copy to user level
-mkdir -p ~/.failproofai/policies
-cp examples/convention-policies/*.mjs ~/.failproofai/policies/
-```
-
-No install command needed — the files are picked up automatically on the next hook event.

package/.next/standalone/docs/dashboard.mdx

@@ -1,142 +0,0 @@
----
-title: Dashboard
-description: "Monitor agent sessions, review tool calls, and manage policies"
-icon: chart-line
----
-
-The failproofai dashboard is a local web application for monitoring your AI agent sessions and managing policies. See what your agents did while you were away.
-
----
-
-## Starting the dashboard
-
-```bash
-failproofai
-```
-
-Opens at `http://localhost:8020`.
-
-The dashboard reads directly from the filesystem - your Claude Code project folders and the failproofai config files. Nothing is written to a remote service.
-
----
-
-## Pages
-
-### Projects
-
-Lists all Claude Code projects found on your machine. Projects are discovered from `~/.claude/projects/` (or the path set by `CLAUDE_PROJECTS_PATH`).
-
-Each project shows:
-- Project name (derived from the folder path)
-- Number of sessions
-- Date of most recent session activity
-
-Click a project to see its sessions.
-
-### Sessions
-
-Lists all sessions within a project. Each session shows:
-- Session ID
-- Start and end timestamps
-- Number of tool calls
-- Hook activity count (policies that fired)
-
-Use the date range filter and session ID search to narrow the list. Sessions are paginated.
-
-Click a session to open the session viewer.
-
-### Session viewer
-
-The session viewer answers the key question for autonomous agents: what did the agent do, and did it stay on track? It shows a timeline of everything that happened in a session:
-
-- **Messages** - Claude's text responses and user prompts
-- **Tool calls** - Every tool Claude invoked, with its input and output
-- **Policy activity** - For each tool call, which policies fired and what decision they returned
-
-The stats bar at the top shows session duration, total tool calls, and a summary of hook decisions (allow / deny / instruct counts).
-
-You can export the session as a ZIP or JSONL file using the download button.
-
-### Policies
-
-A two-tab page for managing policies and reviewing activity.
-
-<Tabs>
-  <Tab title="Policies tab">
-  - Toggle individual policies on or off with a single click (writes to `~/.failproofai/policies-config.json`)
-  - Expand a policy to configure its parameters (for policies that support `policyParams`)
-  - Install or remove hooks for a given scope
-  - Set a custom policies file path
-  </Tab>
-  <Tab title="Activity tab">
-  - Full paginated history of every hook event that has fired across all sessions
-  - Search by policy name, session ID, tool name, or decision
-  - Each row shows: timestamp, policy name, decision, tool name, session ID, and the reason for deny/instruct decisions
-  </Tab>
-</Tabs>
-
----
-
-## Auto-refresh
-
-The dashboard has an auto-refresh toggle in the top navigation. When enabled, the current page refreshes periodically to show new sessions and policy activity as they appear. Essential for monitoring long-running autonomous agent sessions.
-
----
-
-## Disabling pages
-
-If you only need some parts of the dashboard, set `FAILPROOFAI_DISABLE_PAGES` to a comma-separated list of page names:
-
-```bash
-FAILPROOFAI_DISABLE_PAGES=policies failproofai
-```
-
-Valid values: `policies`, `projects`.
-
----
-
-## Theme
-
-The dashboard supports light and dark mode. Toggle via the button in the navigation bar. The preference is stored in your browser's local storage.
-
----
-
-## Configuring the projects path
-
-By default, the dashboard reads from the standard Claude Code projects directory. Override it for custom setups:
-
-```bash
-CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
-```
-
----
-
-## Accessing from a non-localhost host
-
-When running the dashboard in **dev mode** (`npm run dev`) and accessing it from a hostname other than `localhost` - for example, a custom domain, a remote IP, or a tunneled URL - you may see a warning like:
-
-```text
-⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
-```
-
-This is Next.js blocking cross-origin access to its HMR (hot module reload) websocket, which is a dev-only feature. To allow your host, use the `--allowed-origins` flag:
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com
-```
-
-For multiple hosts or IPs, pass a comma-separated list:
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
-```
-
-You can also set the `FAILPROOFAI_ALLOWED_DEV_ORIGINS` environment variable instead:
-
-```bash
-FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
-```
-
-<Note>
-This only applies to dev mode. When running `failproofai` (production mode), there is no HMR websocket and no cross-origin dev resource issue.
-</Note>