failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/agenteye/python-sdk.mdx

@@ -0,0 +1,436 @@
+---
+title: "Python SDK"
+description: "See exactly what your AI agents did in production: every agent run, tool call, model request, hook, and human intervention."
+---
+
+
+See exactly what your AI agents did in production: every agent run, tool call, model request, hook, and human intervention. The Failproof AI Observability Python SDK records that trail from inside your agent code so you can debug, audit, and evaluate what happened. Use it whenever you want Failproof AI Observability to observe your agents.
+
+Under the hood, the SDK writes structured events to local JSONL files, and the collector daemon picks them up and ships them to the platform automatically. You do not manage those files yourself.
+
+> **Tip:** New to Failproof AI Observability? This page is the complete SDK event reference.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+---
+
+## Installation
+
+The SDK is distributed to customers as a private wheel rather than from a public package index. Your onboarding covers how to obtain it, install it, and pin it — talk to your Failproof AI contact if you need access.
+
+Once it is installed, confirm you have it:
+
+```bash
+python -c "import agenteye; print(agenteye.__version__)"
+```
+
+Prefer to let a coding agent do the whole integration? The [Python SDK Agent Skill](/agenteye/python-sdk-skill) knows the install path, plans the instrumentation points, writes them, and verifies the events land.
+
+---
+
+## Quick Start
+
+```python
+import agenteye
+
+agenteye.configure(environment="production")
+
+agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")
+
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    input={"query": "latest AI research"},
+)
+
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    output={"results": ["..."]},
+)
+
+agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")
+```
+
+### Instrumenting a real call
+
+In practice you wrap your existing agent code. Bracket a model call with `model_request` before and `model_response` after, so the two events span the real request and Failproof AI Observability can pair them:
+
+```python
+import anthropic
+import agenteye
+
+agenteye.configure(environment="production")
+client = anthropic.Anthropic()
+
+messages = [{"role": "user", "content": "Summarise today's incidents."}]
+
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6",
+    messages=messages,
+)
+
+reply = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=messages,
+)
+
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model=reply.model,
+    stop_reason=reply.stop_reason,
+    input_tokens=reply.usage.input_tokens,
+    output_tokens=reply.usage.output_tokens,
+    content=[block.model_dump() for block in reply.content],
+)
+```
+
+Wrap tool calls the same way with `tool_use` and `tool_result`, reusing one `tool_call_id` across the pair.
+
+Here is what those events look like once they reach the dashboard, colour-coded by type and filterable by environment, agent, and session:
+
+![The live Events stream, colour-coded by event type and filterable by environment, agent, and session](/agenteye/images/events-stream.png)
+
+---
+
+## configure()
+
+```python
+agenteye.configure(
+    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
+    flush_interval=0.5,      # float, seconds between flush cycles
+    environment=None,        # str | None. Deployment environment label
+)
+```
+
+Call once before any `event.*` call. Safe to omit; defaults work out of the box. All arguments are keyword-only; pass them by name as shown above.
+
+When `base_dir` is `None` (the default), the SDK reads `$AGENTEYE_HOME` if set,
+otherwise falls back to `~/.agenteye`. This matches the collector's own resolution,
+so a single `AGENTEYE_HOME` env var configures the shared event spool for both
+the SDK and the collector.
+
+---
+
+## Environment
+
+Label every event with a deployment environment (`production`, `staging`, `qa`, `canary`, etc.). Set it once; the SDK attaches it to every event automatically.
+
+**Option 1: via `configure()`:**
+
+```python
+agenteye.configure(environment="production")
+```
+
+**Option 2: via environment variable:**
+
+```bash
+export AGENTEYE_ENVIRONMENT=production
+```
+
+**Priority:** `configure(environment=...)` wins over the environment variable. If neither is set, defaults to `"dev"`.
+
+The environment value appears as a first-class filter in the dashboard and is stored on the server for fast queries.
+
+> **Warning:** Environment values must not contain a literal `,` comma. The dashboard filters use comma-separated multi-select on the wire (`?environment=prod,staging`), so an environment named `prod,blue` would be split into two values. Events with comma-containing environments are rejected at ingest time.
+
+---
+
+## Data and privacy
+
+The SDK records only the fields you explicitly pass. Prompts, messages, tool inputs and outputs, and model content are captured solely because you hand them to an `event.*` call. Nothing is read from your process or captured implicitly. Any field you leave unset is omitted from the event entirely; it is not written to disk.
+
+That makes redaction your choice and your responsibility. If a prompt or tool payload contains PII or secrets you would rather not store, strip or mask it before you pass it to the event method.
+
+---
+
+## Event Reference
+
+Most events come in start/end pairs that share a correlation ID: `tool_use` and `tool_result` share a `tool_call_id`, `hook_triggered` and `hook_completed` share a `hook_id`, and `human_wait` and `human_input` share an `input_id`. Emit the start event, do the work, then emit the end event with the same ID. Failproof AI Observability matches the pair and computes `duration_ms` for you, so you never pass `duration_ms` yourself.
+
+![A session's git-style execution graph beside its event timeline, reconstructed from the paired events, with the tool/model/hook breakdown panel](/agenteye/images/session-detail.png)
+
+All event methods require these two fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `session_id` | `str` | Identifies the top-level agent run |
+| `agent_id` | `str` | Identifies which agent within the session emitted the event |
+
+All methods also accept arbitrary `**kwargs` for custom metadata (see [Custom Fields](#custom-fields)).
+
+---
+
+### `event.agent_start()`
+
+Emitted when an agent begins work.
+
+```python
+agenteye.event.agent_start(
+    session_id="run-001",
+    agent_id="planner",
+    goal="answer user query",   # str | None
+    parent_id=None,             # str | None - parent agent_id for nested agents
+)
+```
+
+---
+
+### `event.agent_end()`
+
+Emitted when an agent finishes work.
+
+```python
+agenteye.event.agent_end(
+    session_id="run-001",
+    agent_id="planner",
+    outcome="success",          # str | None
+    summary="Answered query",   # str | None
+)
+```
+
+---
+
+### `event.tool_use()`
+
+Emitted when an agent invokes a tool. Pair with `tool_result`; the SDK auto-computes `duration_ms`.
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",     # str, required
+    tool_call_id="toolu_01",    # str, required - correlation key for the matching tool_result
+    input={"query": "..."},     # dict | None
+)
+```
+
+---
+
+### `event.tool_result()`
+
+Emitted when a tool returns. Correlates with `tool_use` via `tool_call_id`.
+
+```python
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",        # must match the prior tool_use
+    output={"results": ["..."]},    # Any | None
+    error=None,                     # str | None - set if the tool raised
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.model_request()`
+
+Emitted just before sending a prompt to an LLM.
+
+```python
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    messages=[                   # list[dict] | None - conversation turns
+        {"role": "user", "content": "..."},
+    ],
+    system="You are helpful.",   # Any | None - str or list of content blocks
+    tools=[                      # list[dict] | None - tool schemas offered to the model
+        {"name": "search", "input_schema": {"type": "object"}},
+    ],
+)
+```
+
+`messages` entries accept either a plain string `content` or Anthropic-style list-of-blocks `content`. Sampling params (`temperature`, `max_tokens`, etc.) can be passed as extra kwargs.
+
+---
+
+### `event.model_response()`
+
+Emitted when the LLM returns a response.
+
+```python
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    stop_reason="end_turn",     # str | None
+    input_tokens=1024,          # int | None
+    output_tokens=256,          # int | None
+    content=[                    # Any | None - str, or list of content blocks
+        {"type": "text", "text": "..."},
+    ],
+    role="assistant",            # str | None
+)
+```
+
+`content` accepts either a plain string (generic providers) or a list of Anthropic-style content blocks. Tool calls live inside `content` as `{"type": "tool_use", ...}` blocks, with no separate `tool_calls` field.
+
+---
+
+### `event.hook_triggered()`
+
+Emitted when a hook fires. Pair with `hook_completed`; the SDK auto-computes `duration_ms`.
+
+```python
+agenteye.event.hook_triggered(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",   # str, required
+    hook_id="hook-abc",         # str, required - correlation key
+    trigger_event="tool_use",   # str | None
+    input={"tool": "search"},   # Any | None
+)
+```
+
+---
+
+### `event.hook_completed()`
+
+Emitted when a hook finishes. Correlates with `hook_triggered` via `hook_id`.
+
+```python
+agenteye.event.hook_completed(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",
+    hook_id="hook-abc",         # must match the prior hook_triggered
+    outcome="allow",            # str | None
+    output=None,                # Any | None
+    error=None,                 # str | None
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.error()`
+
+Emitted when an unhandled error occurs.
+
+```python
+agenteye.event.error(
+    session_id="run-001",
+    agent_id="planner",
+    error_type="TimeoutError",  # str, required
+    message="timed out",        # str, required
+    traceback="Traceback...",   # str | None
+)
+```
+
+---
+
+## Human-in-the-Loop Events
+
+Human-in-the-loop events give you oversight over the moments where a person steps into the agent's execution (waiting for approval, providing input, pausing, or stopping the agent). They let you measure how long humans take to respond (the SDK auto-computes `duration_ms` on the paired events), audit who paused or interrupted an agent, and build approval and oversight workflows that surface in the dashboard.
+
+### `event.human_wait()`
+
+Emitted when the agent pauses execution to wait for a human to provide input. Pair with `human_input`; the SDK auto-computes `duration_ms` (how long the human took to respond).
+
+```python
+agenteye.event.human_wait(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",                          # str, required - correlation key for the matching human_input
+    prompt="Do you approve this action?",        # str | None - the question shown to the human
+    options=["approve", "reject", "defer"],      # list[str] | None - choices presented to the human
+    reason="approval_required",                  # str | None - why the agent is waiting
+)
+```
+
+### `event.human_input()`
+
+Emitted when a human provides input and the agent resumes. Correlates with `human_wait` via `input_id`. `duration_ms` is auto-computed and must not be passed by the caller.
+
+```python
+agenteye.event.human_input(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",    # str, required - must match the prior human_wait
+    response="approve",    # str | None - the human's answer (free text or selected option)
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+### `event.human_pause()`
+
+Emitted when a human actively pauses the agent (e.g. via a dashboard control). The agent is suspended but not terminated.
+
+```python
+agenteye.event.human_pause(
+    session_id="run-001",
+    agent_id="planner",
+    reason="user_requested",  # str | None
+    user_id="usr_42",         # str | None - who paused the agent
+)
+```
+
+### `event.human_interrupt()`
+
+Emitted when a human actively stops the agent mid-execution. Unlike `human_pause`, the agent's work is terminated rather than suspended.
+
+```python
+agenteye.event.human_interrupt(
+    session_id="run-001",
+    agent_id="planner",
+    reason="output_incorrect",       # str | None
+    user_id="usr_42",                # str | None - who interrupted the agent
+    at_step="tool_use:web_search",   # str | None - what the agent was doing when stopped
+)
+```
+
+---
+
+## Custom Fields
+
+Any extra keyword arguments are appended to the event after the standard fields:
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="db_query",
+    tool_call_id="toolu_02",
+    tenant_id="acme",           # custom field
+    region="us-east-1",         # custom field
+)
+```
+
+`timestamp`, `type`, and `environment` are reserved and raise `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) if passed as custom fields. `session_id` and `agent_id` are required parameters on every event method and cannot be supplied a second time; Python raises `TypeError` if you do. Set the environment with `configure(environment=...)` (or the `AGENTEYE_ENVIRONMENT` variable) instead.
+
+Keep payloads as structured JSON when you want to query their fields. Values JSON does not natively support—such as datetimes, UUIDs, decimals, sets, bytes, or model objects—are converted to strings so recording continues safely.
+
+---
+
+## How Events Are Written
+
+Events are buffered in-process and flushed to disk every `flush_interval` seconds (default 500 ms). Each flush writes one JSONL file:
+
+```text
+~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl
+```
+
+The collector watches this directory and uploads files automatically. You do not need to manage these files directly.
+
+Each file is written atomically: the SDK writes to a temporary file and then renames it into place, so the collector never sees a half-written file. A final flush also runs when your process exits, so events buffered in the last interval are not lost. If the collector is offline, events simply accumulate as files on disk and ship once it comes back.
+
+---
+
+## Next steps
+
+- [Event stream](/agenteye/event-stream): watch these events arrive live, colour-coded and filterable by environment, agent, and session.
+- [Sessions](/agenteye/sessions): see how the paired events reconstruct each agent run as an execution graph and timeline.

package/.next/standalone/docs-old/agenteye/queries.mdx

@@ -0,0 +1,56 @@
+---
+title: "Queries"
+description: "Ask any question of your agent data and get an answer in seconds."
+---
+
+
+Ask any question of your agent data and get an answer in seconds. Failproof AI Observability gives you a library of saved, ready-to-run queries over your events and evaluations, so you start from a working example instead of a blank SQL editor.
+
+![The saved-queries library: a grid of reusable queries, both built-in presets and custom ones](/agenteye/images/queries.png)
+
+*Your saved-queries library at `/<org-slug>/queries`: built-in presets sitting alongside the queries your team has saved.*
+
+## Start from a preset, not a blank page
+
+You do not have to remember table names or write SQL from scratch. The library opens with built-in presets for the questions teams ask most, sitting right next to the queries your own team has saved and named. Pick one that is close to what you want and you are most of the way to an answer.
+
+Every saved query is org-scoped and shared, so the useful ones your teammates write become yours too. Name a query and give it a description once, and anyone in your org can find it, run it, or pin its results onto a dashboard later.
+
+Find it at `/<org-slug>/queries`.
+
+## Tweak it and run it in the SQL composer
+
+Open any query and it lands in the SQL composer, where you can adjust it and see the answer immediately: no export, no round-trip, no waiting on someone else.
+
+![The SQL query composer running a saved query, with a schema sidebar and a live result grid](/agenteye/images/query-lab.png)
+
+*The SQL composer: your query on the left, a schema sidebar so you never guess a column name, and a live result grid below.*
+
+- **A schema sidebar** lays out the analytics tables and their columns, so you can shape a query without hunting for field names.
+- **A live result grid** returns rows the moment you run, so you iterate in seconds rather than guessing and re-guessing.
+- **Read-only by design.** Queries run against your event store and are validated on the server: only `SELECT` and `WITH` statements are allowed, with a statement timeout and a row cap. An exploratory query can never modify your data, and a runaway one gets stopped for you.
+
+Happy with the result? Save it back to the library so the whole team inherits it, or pin its output onto a dashboard as a line, bar, area, or pie tile.
+
+## Run them from the terminal, or let the assistant write them
+
+The same saved queries follow you wherever you work:
+
+- **From the terminal.** The `agenteye` CLI lists, runs, and saves the very same queries, so you can drop a result into a script, wire it into CI, or hand it to a coding agent.
+
+```bash
+agenteye query list                 # the same saved queries, from your terminal
+agenteye query run errs --arg prod  # run one and print the rows (add --json to pipe it)
+```
+
+  See [CLI and agents](/agenteye/cli-and-agents) for the full command set.
+
+- **From the AI assistant.** Not sure how to phrase the SQL? Ask the in-dashboard [AI assistant](/agenteye/assistant) in plain English and it will draft the query and save it to your library for you.
+
+Running a saved query is gated by the `queries:run` permission, kept separate from the permissions to create or delete queries, so you can grant read access without letting everyone rewrite the library.
+
+## Related
+
+- [Dashboards](/agenteye/dashboards): pin query results into shared, org-wide charts.
+- [AI assistant](/agenteye/assistant): ask questions in plain English and get a query back.
+- [CLI and agents](/agenteye/cli-and-agents): run and save the same queries from your terminal.

package/.next/standalone/docs-old/agenteye/security.mdx

@@ -0,0 +1,68 @@
+---
+title: "Security"
+description: "Failproof AI Observability is built to sit close to your production agents, which means it sees your prompts, tool inputs, and outputs."
+---
+
+
+Failproof AI Observability is built to sit close to your production agents, which means it sees your prompts, tool inputs, and outputs. This page explains how it keeps that data isolated, controlled, and in your hands. If you're evaluating Failproof AI Observability for a security review, start here.
+
+---
+
+## Your data stays in your environment
+
+Failproof AI Observability is self-hosted. Events, prompts, model responses, and analytics are stored in your own databases, in your own environment. Nothing is sent to a third-party SaaS for storage, and your data stays in your own cloud account.
+
+---
+
+## Tenant isolation
+
+One Failproof AI Observability instance can host many organizations, and each is isolated at the storage layer — enforced by the database, not just the UI:
+
+- An organization's operational data (users, keys, dashboards, saved queries) is scoped to that org, and cross-org reads are blocked by the database itself.
+- Every ingested event is stamped with its owning org, so one organization's events can never be read by another.
+
+Every dashboard route is scoped under an org slug (`/<org-slug>/…`).
+
+---
+
+## Sign-in
+
+Failproof AI Observability uses passwordless, email-based sign-in. There is no password to phish or leak. A user requests a one-time code (or a one-click magic link), which is emailed to them and expires quickly. Sign-in is gated by an **allowlist**: only email addresses (or domains) you permit can authenticate.
+
+![The Failproof AI Observability sign-in screen, which sends a single-use code to your email](/agenteye/images/login.png)
+
+---
+
+## Scoped access with API keys
+
+Every client authenticates with an API key that carries granular, least-privilege permissions. A collector needs only `events:add`; a dashboard or assistant key can be read-only; destructive actions (delete, regenerate) are separate grants you choose to include.
+
+![The API keys page: each key's permission grants, colour-coded by read, write, and destructive scope](/agenteye/images/api-keys.png)
+
+Keep the admin bootstrap key for setup, and issue narrow keys for everything else. See [API keys](/agenteye/api-keys).
+
+---
+
+## A read-only, approval-gated assistant
+
+The in-dashboard [AI assistant](/agenteye/assistant) answers questions over your data, but it is constrained by design:
+
+- It is **read-only by default**: its SQL runs through a guard that permits only `SELECT`/`WITH` queries, single-statement, with a row cap.
+- Anything it creates (a saved query, a dashboard) is **approval-gated**: you review and approve every write before it happens.
+- It **can never delete**.
+
+So a teammate can ask "which agents errored most this week?" and act on the answer, without the assistant being able to change or remove your data on its own.
+
+---
+
+## In transit
+
+All traffic runs over HTTPS. You terminate TLS with your own certificates, so collector-to-server and browser-to-server traffic is encrypted in transit.
+
+---
+
+## Next steps
+
+- [Overview](/agenteye/overview): how Failproof AI Observability fits together.
+- [API keys](/agenteye/api-keys): scope access for the collector, dashboard, and assistant.
+- [Observability](/agenteye/observability): what Failproof AI Observability captures from your agents.

package/.next/standalone/docs-old/agenteye/sessions.mdx

@@ -0,0 +1,57 @@
+---
+title: "Sessions & Execution Graph"
+description: "Every event from a run, rolled into one readable row and drawn as a git-style execution graph you can read in seconds."
+---
+
+
+Stop guessing why a run failed. Failproof AI Observability rolls every event from a run into one readable row, then draws the whole run as a git-style picture you can read in seconds, so you see exactly what your agent did, step by step.
+
+![The Sessions list: one row per run, across environments and agents, with status pills and evaluation score badges](/agenteye/images/sessions-list.png)
+
+*One row per run: the status pill tells you how the run ended at a glance, and a score badge rides along once an evaluator is connected.*
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Agent tracing: follow a single run step by step, from goal to tools to final answer.*
+
+---
+
+## See every run at a glance
+
+The raw event trail is the truth of every step, but when you have thousands of steps across dozens of runs, you need the run, not the step. The Sessions page rolls all of a run's events up into one row, so a day of activity becomes a scannable list instead of a firehose.
+
+Each row carries a status pill, so a failed run stands out from a healthy one before you click anything. Filter by date range, environment, agent, or session to go from "everything" to "the run I care about" in a couple of clicks.
+
+Once you connect an evaluator, every completed run is scored automatically and its latest score shows up on the row as a badge. You can filter by any score range, so "show me every low-scoring prod run this week" is a filter, not a manual review. Until you set one up, sessions still capture the full run; they just don't carry a score yet.
+
+---
+
+## Read the whole run as a picture
+
+![A session's git-style execution graph beside its event timeline, with the tool, model, and hook breakdown panel](/agenteye/images/session-detail.png)
+
+*The execution graph (left) sits beside the event timeline; the right rail breaks down the tools, models, hooks, and token spend for the run.*
+
+Click any session to open its execution graph: a git-style view of how agents, tools, hooks, and model calls unfolded over time. Parallel sub-agents each branch onto their own lane, so you can see which work ran side by side, which sub-agent stalled, and where the run went off course, without replaying it in your head from a wall of logs.
+
+The right rail gives you the per-run breakdown: which tools and models ran, which hooks fired, and what the run spent in tokens. That is the answer to "why did this run cost so much?" or "which tool is the slow one?" sitting right next to the graph that caused it.
+
+Individual events are addressable, so you can hand someone a link to one moment rather than "the session, about two thirds down". Copy the link from any event, or follow one from an [audit](/agenteye/audits) finding or an error, and the session opens with that event selected and scrolled to. This holds for very long runs too: the timeline loads a bounded window for the sake of your browser, and a link pointing past that window still finds its event rather than dropping you at the start. If the event has aged out of your retention window, the page tells you that instead of quietly selecting nothing.
+
+---
+
+## Where to find it
+
+Every dashboard page is scoped to your org (`/<org-slug>/…`). Sessions lives under **Observe** in the left sidebar, next to Events, with the date range, environment, agent, and session filters across the top of the list. Every row is one click from its full execution graph.
+
+To turn on the score badges and score-range filtering, connect an evaluator: see [Evaluations](/agenteye/evaluations).
+
+---
+
+## Related
+
+- [Event stream](/agenteye/event-stream): the raw, per-step trail every session is rolled up from.
+- [Evaluations](/agenteye/evaluations): connect an evaluator so each run gets a score badge you can filter by.
+- [Telemetry](/agenteye/telemetry): how runs get from your agent into these sessions.

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

@@ -0,0 +1,52 @@
+---
+title: "Performance Metrics"
+description: "See the instant your models, tools, or hooks slow down or run up a bill, and catch a tail-latency spike before your users ever feel it."
+---
+
+
+See the instant your models, tools, or hooks slow down or run up a bill, and catch a tail-latency spike before your users ever feel it. Three dedicated pages turn raw timings into p50, p95, and p99 you can read at a glance.
+
+![The Models page showing a latency heat-map, a percentile band, and per-model token, cost, and context-window figures](/agenteye/images/models.png)
+*The Models page: a latency heat-map, a percentile band, and per-model tokens, estimated cost, and context-window fill.*
+
+## Stop letting averages hide your worst runs
+
+An average latency number is comforting and useless: it smooths over the one call in fifty that stalls and pages your on-call at 2am. The Models, Tools, and Hooks pages refuse to do that. Each shares the same shape, so you learn it once:
+
+- A **24-bin sparkline** for the trend at a glance: is this getting worse?
+- A **vitals strip** with p50, p95, and p99 latency, so the typical run and the tail sit side by side.
+- A **latency heat-map**, 24 time bins by latency buckets, that shows *when* the slow calls clustered.
+- A **percentile band**: a p50 line with p25 to p75 and p10 to p90 shaded ribbons and p99 dots, so the spread stays visible instead of averaged away.
+
+A shared hover crosshair links the heat-map and the band, so a tail spike lines up in time across both instead of hiding behind a single mean line. Find all three pages in the **observe** section of your dashboard, each scoped to your organization and filterable by date range, environment, agent, and session.
+
+## Models: see exactly what each model costs you
+
+The Models page (shown up top) answers the two questions a bill always raises: which model, and how much. On top of the shared latency view, it adds **per-model token consumption**, **estimated cost**, and **context-window fill**, so runaway prompt growth and an impending compaction are visible before they surprise you.
+
+Failproof AI Observability recognizes common model IDs automatically. If a window looks wrong, or you run a private model of your own, correct it or add one under **Settings**, in **model context windows**, and the fill readouts follow.
+
+## Tools: tell the slow apart from the broken
+
+A tool call can be slow, or it can be quietly failing, and you want to know which one in seconds, not after digging through logs.
+
+![The Tools page showing the shared latency heat-map and percentile band beside a success and failure breakdown and a tool-distribution bar](/agenteye/images/tools.png)
+*The Tools page: the same heat-map and percentile band, plus a success and failure breakdown and a tool-distribution bar.*
+
+Alongside the shared latency view, the Tools page adds a **success and failure breakdown** and a **tool-distribution bar**, so you see at a glance which tools you lean on most and which are eating your error budget.
+
+## Hooks: pinpoint the exact hook and trigger
+
+When a lifecycle hook drags a run, "hooks are slow" is not something you can act on. The Hooks page gets you to the one that matters.
+
+![The Hooks page showing latency broken down by hook name and trigger event over the shared heat-map and percentile band](/agenteye/images/hooks.png)
+*The Hooks page: latency broken down by hook name and trigger event.*
+
+Over the same latency heat-map and percentile band, the Hooks page breaks activity down by **hook name** and **trigger event**, so you land on the single hook and the single event that need attention.
+
+## Related
+
+- [Event stream](/agenteye/event-stream): the live, colour-coded trail of every event.
+- [Sessions](/agenteye/sessions): roll events up into one row per run and open its execution graph.
+- [Error tracking](/agenteye/error-tracking): one triage surface for everything the dashboard paints red.
+- [Dashboards](/agenteye/dashboards): roll-up views across your fleet.