failproofai 1.0.1 → 1.0.2-beta.1

package/.next/standalone/package.json

@@ -1,7 +1,7 @@
 {
   "name": "failproofai",
-  "version": "1.0.1",
-  "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
+  "version": "1.0.2-beta.1",
+  "description": "Observability and enforcement for AI agent harnesses. 39 built-in policies hooked into 12 of them — Claude Code, Codex, Cursor, Hermes, OpenClaw and more — blocking the tool call before it runs. Local dashboard included, no account needed.",
   "bin": {
     "failproofai": "./dist/cli.mjs",
     "failproofaid": "./bin/failproofaid-shim.mjs"
@@ -41,24 +41,30 @@
     "translate:dry-run": "bun scripts/translate-docs/cli.ts --dry-run",
     "translate:validate": "bun scripts/translate-docs/cli.ts --validate",
     "validate:mdx": "bun scripts/validate-mdx.ts",
-    "docs:audit": "bun scripts/docs-audit.ts"
+    "docs:audit": "bun scripts/docs-audit.ts",
+    "build:pack": "bun scripts/build-policy-pack.mjs"
   },
   "keywords": [
-    "claude",
-    "claude-code",
-    "claude-agents-sdk",
-    "anthropic",
-    "ai-agent",
-    "agent-reliability",
+    "agent-observability",
+    "llm-observability",
+    "agent-tracing",
     "agent-monitoring",
+    "agent-harness",
+    "guardrails",
+    "enforcement",
+    "policies",
+    "evals",
+    "ai-agent",
     "autonomous-agent",
+    "agent-reliability",
     "failure-prevention",
-    "developer-tools",
-    "devtools",
+    "claude-code",
+    "codex",
+    "hermes",
+    "openclaw",
     "cli",
     "local-first",
-    "hooks",
-    "policies"
+    "hooks"
   ],
   "author": "ExosphereHost Inc. <failproofai@exosphere.host>",
   "license": "SEE LICENSE IN LICENSE",
@@ -114,15 +120,15 @@
     "sharp": "0.35.0"
   },
   "optionalDependencies": {
-    "@failproofai/failproofaid-linux-x64": "1.0.1",
-    "@failproofai/failproofaid-linux-arm64": "1.0.1",
-    "@failproofai/failproofaid-darwin-x64": "1.0.1",
-    "@failproofai/failproofaid-darwin-arm64": "1.0.1"
+    "@failproofai/failproofaid-linux-x64": "1.0.2-beta.1",
+    "@failproofai/failproofaid-linux-arm64": "1.0.2-beta.1",
+    "@failproofai/failproofaid-darwin-x64": "1.0.2-beta.1",
+    "@failproofai/failproofaid-darwin-arm64": "1.0.2-beta.1"
   },
   "failproofaidBinaries": {
-    "linux-x64": "3969147781ba206a8a2134364a32fad30070c5ec11512e3183abca62918d7e7f",
-    "linux-arm64": "ea6bd21980ec62dde13fdb6f35cf80053e2ce43161453bd3be0154c7b7f1ebc9",
-    "darwin-x64": "7a54e3b55d7b3e7c70e1f97fa373e699a9fa11f2e6263a3b2e3291059d161470",
-    "darwin-arm64": "f926fea88f0d4b5a5e872f3a618d11a98098924d3fd9fdff3c3f2daafadd1410"
+    "linux-x64": "a8c695cfe728e56403f981bd5ea2dc838cb862bd7349354946afead12fe0c36a",
+    "linux-arm64": "674b596fe496ea51bf98864be7105fe1e34aacf0d588e35e2e3b455839837d94",
+    "darwin-x64": "c56e5f68a509ec493d6d497ce0d221ab2fb9ff493ec3dd7dca49a41de8621b1e",
+    "darwin-arm64": "73e80759bfd47c3473167f39b77bb2df3ab8fc1e891a8a3b3cefa9c1d83f6885"
   }
 }

package/.next/standalone/sdk/python/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog — `failproofai-sdk`
+
+The telemetry SDK, imported as `failproofai_sdk`. Released independently of the
+`failproofai` npm package and of its sibling `fp-cloud-cli`, so the versions here line
+up with neither.
+
+Headings are `## <version> — <YYYY-MM-DD>`, and the section matching the version
+in `failproofai_sdk/_version.py` becomes that release's GitHub Release body. A
+release whose section is missing or empty is refused before anything is built —
+see `scripts/changelog-section.py`.
+
+## 0.0.1b1 — 2026-08-24
+
+The first release under this name. Everything below describes the package as it
+now ships rather than a change against a previous `failproofai-sdk`, because
+there is no previous one.
+
+### The distribution name
+
+- **This package was `agenteye` inside the private monorepo, and that name is not
+  safe to keep.** `agenteye` on public PyPI resolves to a stranded build of a
+  different thing — an old CLI, last published there at `0.1.22` — and PyPI never
+  releases a version for reuse. Because pip resolves the highest version under a
+  name, `pip install agenteye` on a machine already running the pre-rename SDK
+  installed that CLI build *over* it: same distribution name, higher version, so
+  pip treated it as an upgrade and the working `import agenteye` stopped working.
+  Renaming to `failproofai-sdk` is what makes that unreachable.
+- **Versioning restarts at `0.0.1b1`.** The pre-rename package had reached
+  `0.0.1b14`, but that history lives entirely under `agenteye`; carrying the
+  number across would claim fourteen releases of a name that has had none.
+  `b1` is a PEP 440 pre-release, which — PyPI having no dist-tags — is the only
+  channel marker there is. See `scripts/python-version.py` for the scheme.
+- **Migrating is two mechanical changes:** `pip uninstall agenteye && pip install
+  failproofai-sdk`, then `import agenteye` → `import failproofai_sdk`. Every
+  method name, argument and emitted field is unchanged, and so is
+  `AGENTEYE_ENVIRONMENT`, which is a contract with a daemon that releases
+  separately. `skill/references/install.md` covers the whole path.
+
+### What it does
+
+- Fifteen event methods across six families, with `duration_ms` computed
+  automatically by pairing start/end events. The wire format is frozen
+  byte-for-byte by `tests/test_wire_format.py` — `to_dict()` **is** the format.
+- Four framework adapters — LangChain/LangGraph, CrewAI, LlamaIndex, Pydantic AI
+  — all shipped in the base wheel and lazy-imported. The `[langchain]`-style
+  extras pull in the *framework*, never the adapter, so most users never need one.
+- **Zero runtime dependencies, enforced rather than asserted.** This installs into
+  other people's agent processes, where any dependency of ours becomes a version
+  constraint on their application. `tests/test_zero_dependencies.py` fails if one
+  is ever declared or imported, and the release pipeline installs the built wheel
+  with `--no-deps` to prove the claim against the artifact rather than the source.
+
+### Spool location
+
+- **The default spool root is `~/.failproofai/custom-agents`**, not `~/.agenteye`.
+  It must agree exactly with `customAgentsDir()` in `src/hooks/fp-home.ts` and
+  `custom_agents_events_dir()` in `crates/fpai-collect/src/config.rs`, because a
+  disagreement means the SDK writes where no daemon reads, with **no error on
+  either side**. `tests/test_spool_contract.py` checks the Rust and the TypeScript
+  directly and never skips.
+- **`AGENTEYE_HOME` no longer moves this SDK's spool.** It used to sit above the
+  default, so exporting it for `agenteye-collector` — the component that genuinely
+  reads it — relocated the SDK as an unasked-for side effect. Resolution is now
+  `configure(base_dir=...)`, else `~/.failproofai/custom-agents`, with
+  `$FAILPROOFAI_HOME` moving the umbrella and never the spool out of it.
+- A machine that has only ever run this SDK stays indistinguishable, to every
+  other component, from one that has run nothing: the spool path is the only
+  thing created, and none of the layout landmarks the CLI's `detectLayout()`
+  reads are ever written. `tests/test_spool_creation.py` asserts the exact set of
+  paths that appear.

package/.next/standalone/sdk/python/LICENSE

@@ -0,0 +1,42 @@
+MIT License
+
+Copyright (c) 2025 ExosphereHost Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Commons Clause License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as defined
+below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under
+the License will not include, and the License does not grant to you, the right
+to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of the
+rights granted to you under the License to provide to third parties, for a
+fee or other consideration (including without limitation fees for hosting or
+consulting/support services related to the Software), a product or service
+whose value derives, entirely or substantially, from the functionality of the
+Software. Any license notice or attribution required by the License must also
+include this Commons Clause License Condition notice.
+
+Software: failproofai
+License: MIT
+Licensor: ExosphereHost Inc

package/.next/standalone/sdk/python/MANIFEST.in

@@ -0,0 +1,21 @@
+# The sdist ships `tests/`, and setuptools' default heuristic picks up only
+# top-level `test*.py` — so the suite went out WITHOUT `tests/conftest.py`,
+# `tests/__init__.py` or `tests/integrations/`.
+#
+# That is not a cosmetic omission. `conftest.py` IS the isolation layer: it
+# redirects the spool at IMPORT, straight into `os.environ`, because the
+# `atexit` flush fires long after the last fixture is torn down. Without it,
+# running the shipped suite (a distro packager, a conda-forge recipe, anyone
+# doing `pip download --no-binary :all:` then `pytest tests/`) writes tens of
+# thousands of synthetic events into the user's REAL
+# `~/.failproofai/custom-agents/events` — measured at 20,001 in one run of
+# `test_durability.py` alone — where a running daemon uploads them to a real
+# dashboard as genuine agent activity.
+#
+# So the suite ships whole or not at all. `graft` takes the whole tree,
+# including the subpackage and the conftest.
+graft tests
+include LICENSE
+include README.md
+include py.typed
+recursive-include failproofai_sdk py.typed

package/.next/standalone/sdk/python/README.md

@@ -0,0 +1,466 @@
+# failproofai-sdk
+
+The Python SDK for [Failproof AI](https://befailproof.ai) agent observability. It
+records what your agent did — tool calls, model requests, hooks, errors, waits for
+a human — as structured events, and hands them to the daemon that ships them to
+the platform.
+
+- **PyPI distribution:** `failproofai-sdk`
+- **Import name:** `failproofai_sdk`
+- **Dependencies:** none. Standard library only, so installing it constrains
+  nothing else in your environment.
+
+## Installation
+
+```bash
+pip install failproofai-sdk
+# or
+uv add failproofai-sdk
+```
+
+> **Do not `pip install agenteye`.** That distribution name is occupied on PyPI by
+> a stranded build of an old CLI, which ships a module called `agenteye_cli` and is
+> not this SDK. Installing it gives you `ModuleNotFoundError` at best, and — if
+> this SDK is already present — pip treats it as an upgrade and **removes the SDK**
+> to install the CLI. The import that worked five minutes ago then stops working.
+
+## How events reach the platform
+
+The SDK never opens a network connection. It appends events to an in-memory queue,
+and a background thread writes them to local JSONL batches:
+
+```
+your agent  →  failproofai_sdk  →  ~/.failproofai/custom-agents/events/*.jsonl  →  daemon  →  platform
+```
+
+A daemon on the same host watches that directory and uploads each batch.
+**`failproofaid` reads this root; the older `agenteye-collector` does not** — it
+resolves `$AGENTEYE_HOME` or `~/.agenteye` and nothing else, so a host running
+only that collector needs one of the three bridges in the upgrade note below, or
+its batches pile up unread. If no daemon is running, batches simply accumulate on
+disk — the SDK does not fail, and your agent does not block.
+
+## Agent frameworks
+
+If your agent runs on LangChain/LangGraph, CrewAI, LlamaIndex or Pydantic AI,
+one line captures it — runs, sub-agents, tools, model calls and their token
+counts — without threading an id through anything:
+
+```python
+import failproofai_sdk
+
+failproofai_sdk.configure(environment="production")
+failproofai_sdk.instrument()          # auto-detects what is already imported
+
+graph.invoke({"messages": [...]})     # unchanged
+```
+
+```bash
+pip install 'failproofai-sdk[langgraph]'     # or [langchain] [crewai] [llamaindex] [pydantic-ai]
+```
+
+The adapter code ships in the base wheel and imports its framework lazily, so
+the extras are a convenience — `pip install failproofai-sdk` still declares no
+dependencies at all, and `import failproofai_sdk` loads nothing outside the
+standard library. See `skill/references/frameworks.md` for the per-framework
+mapping, and `docs/` for a per-framework integration guide with runnable
+examples beside it.
+
+## Scopes
+
+The same identity layer, for code the adapters do not cover. `session_id` and
+`agent_id` are optional on every event method — omitted, they resolve from the
+enclosing scope:
+
+```python
+with failproofai_sdk.session() as sid:
+    with failproofai_sdk.agent("planner", goal=question):
+
+        with failproofai_sdk.tool_call("search", input={"q": q}) as t:
+            t.output = search(q)                 # tool_use / tool_result, timed
+
+        with failproofai_sdk.agent("writer"):     # a sub-agent; parent inferred
+            failproofai_sdk.event.model_request(model="...")
+```
+
+`agent()` brackets a run with `agent_start`/`agent_end` and records an `error`
+before the end event when the block raises — a cancellation closes it as
+`cancelled` rather than failed. Every scope works under `async with` too.
+
+Contextvars do **not** cross into a new thread, so hand work over with
+`propagate`:
+
+```python
+pool.submit(failproofai_sdk.propagate(work), item)
+```
+
+Nothing bound and nothing passed raises `TypeError` naming the fix. It is never
+a silent emit: ingest skips an event with no session and answers `200`.
+
+## Quick start
+
+```python
+import failproofai_sdk
+
+# Call once at startup. Omit to use defaults (~/.failproofai/custom-agents;
+# 500ms flush interval).
+failproofai_sdk.configure(base_dir=None, flush_interval=0.5)
+
+# Emit events via failproofai_sdk.event.<method>(...)
+failproofai_sdk.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")
+
+failproofai_sdk.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    input={"query": "latest AI research"},
+)
+
+failproofai_sdk.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",     # matches tool_use — SDK auto-computes duration_ms
+    output={"results": ["..."]},
+)
+
+failproofai_sdk.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")
+```
+
+## configure()
+
+```python
+failproofai_sdk.configure(
+    base_dir=None,        # Path | str | None. Default:
+                          #   ~/.failproofai/custom-agents (honours $FAILPROOFAI_HOME)
+    flush_interval=0.5,   # float, seconds between flush cycles
+    environment=None,     # str | None. Else $AGENTEYE_ENVIRONMENT, else "dev"
+)
+```
+
+Call once before any `event.*` call. Safe to omit — defaults work out of the box.
+When `base_dir` is `None`, the SDK spools to `~/.failproofai/custom-agents`
+(honouring `$FAILPROOFAI_HOME`, which moves the umbrella; the `custom-agents`
+segment is always appended, so the spool is always inside it).
+
+**`base_dir` is the only way to spool anywhere else.** No environment variable
+redirects it.
+
+**The default spool root moved.** It was `~/.agenteye`. The daemon this SDK ships
+beside, `failproofaid`, watches **both** roots and always has, so on a host
+running it this changes which directory the files land in and nothing else.
+Batches already sitting in `~/.agenteye/events` are not orphaned — they stay put
+and are still collected; that directory simply stops growing.
+
+> [!IMPORTANT]
+> **If you run the older `agenteye-collector`, point IT at this SDK — not the
+> other way round.** That collector resolves `$AGENTEYE_HOME` or `~/.agenteye`
+> and nothing else, so it does not watch where this SDK writes: no upload, no
+> error, and an unread spool looks exactly like an idle one.
+>
+> `AGENTEYE_HOME` used to be the way back, and is not any more — this SDK no
+> longer reads it, so exporting it moves the collector and leaves the SDK where
+> it was. Pick one of:
+>
+> * run `failproofaid` instead — it watches **both** roots, so nothing needs
+>   configuring; or
+> * set **the collector's** `AGENTEYE_HOME=~/.failproofai/custom-agents`, so it
+>   watches `~/.failproofai/custom-agents/events` — where this SDK writes; or
+> * `configure(base_dir="~/.agenteye")` in the application, which is explicit
+>   and visible at the call site.
+
+`AGENTEYE_SPOOL_TO_FAILPROOFAI` is **retired**. It selected this root, but also
+required the directory to already exist — and nothing ever created it, so the
+opt-in never fired. Anyone who set it already wanted this and now gets it.
+
+## Event reference
+
+All event methods share two required 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 |
+
+Every method also accepts arbitrary `**fields` for custom metadata (see [Custom fields](#custom-fields)).
+
+---
+
+### `event.tool_use()`
+
+Emitted when an agent invokes a tool. Pair with `tool_result` — the SDK auto-computes `duration_ms`.
+
+```python
+failproofai_sdk.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
+failproofai_sdk.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
+failproofai_sdk.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-opus-4-6",   # str | None
+    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
+failproofai_sdk.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-opus-4-6",   # str | None
+    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 — no separate `tool_calls` field.
+
+---
+
+### `event.agent_start()`
+
+Emitted when an agent begins work.
+
+```python
+failproofai_sdk.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
+failproofai_sdk.event.agent_end(
+    session_id="run-001",
+    agent_id="planner",
+    outcome="success",          # str | None
+    summary="Answered query",   # str | None
+)
+```
+
+---
+
+### `event.agent_pause()`
+
+Emitted when an agent is suspended (e.g. waiting for human input, user-requested
+pause, throttling). Does **not** end the agent — pair it with `agent_resume`, and
+the SDK auto-computes the paused `duration_ms`. Emit `agent_resume` instead of a
+second `agent_start` when the agent continues.
+
+```python
+failproofai_sdk.event.agent_pause(
+    session_id="run-001",
+    agent_id="planner",
+    pause_id="pause-abc",          # str, required — correlation key (reuse it on agent_resume)
+    reason="waiting_for_user",     # str | None
+    user_id="usr_42",              # str | None — who paused, if user-initiated
+)
+```
+
+`pause_id` is emitted on both events, so a pause always pairs to its resume — even
+when they happen in different processes (in that case `duration_ms` is omitted and
+the interval is derived downstream from the two timestamps).
+
+---
+
+### `event.agent_resume()`
+
+Emitted when a paused agent continues. Correlates with `agent_pause` via `pause_id`;
+the SDK auto-computes `duration_ms` (how long the agent was paused).
+
+```python
+failproofai_sdk.event.agent_resume(
+    session_id="run-001",
+    agent_id="planner",
+    pause_id="pause-abc",          # str, required — must match the prior agent_pause
+    reason="user_resumed",         # str | None
+    user_id="usr_42",              # str | None
+    # duration_ms is computed automatically — do not pass it
+)
+```
+
+---
+
+### `event.hook_triggered()`
+
+Emitted when a hook fires. Pair with `hook_completed` — the SDK auto-computes `duration_ms`.
+
+```python
+failproofai_sdk.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
+failproofai_sdk.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
+failproofai_sdk.event.error(
+    session_id="run-001",
+    agent_id="planner",
+    error_type="TimeoutError",  # str, required
+    message="timed out",        # str, required
+    traceback="Traceback...",   # str | None
+)
+```
+
+---
+
+## Custom fields
+
+Any extra keyword arguments are appended to the event after the standard fields:
+
+```python
+failproofai_sdk.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="db_query",
+    tool_call_id="toolu_02",
+    request_id="req-123",       # custom field
+    tenant_id="acme",           # custom field
+)
+```
+
+The field names `timestamp`, `type`, and `environment` are reserved and raise
+`ValueError` if passed as custom fields. `session_id` and `agent_id` are required
+parameters and cannot be supplied a second time. Set the environment with
+`configure(environment=...)` or `AGENTEYE_ENVIRONMENT`.
+
+Keep payloads as structured JSON when downstream queries need their fields. Values
+JSON does not natively support—such as datetimes, UUIDs, decimals, sets, bytes, or
+model objects—are converted to strings so the writer can continue flushing the batch.
+
+## JSONL output
+
+Events are buffered in-process and flushed to disk every `flush_interval` seconds (default 500ms).
+Each flush writes one JSONL file:
+
+```
+~/.failproofai/custom-agents/events/event-2026-04-01T12-00-00-000Z-48213-7.jsonl
+```
+
+Each line is one JSON object. Example:
+
+```json
+{"timestamp": "2026-04-01T12:00:00.000000Z", "session_id": "run-001", "agent_id": "planner", "type": "agent_start", "goal": "answer user query"}
+{"timestamp": "2026-04-01T12:00:00.123456Z", "session_id": "run-001", "agent_id": "planner", "type": "tool_use", "tool_name": "web_search", "tool_call_id": "toolu_01"}
+```
+
+The batch is published by writing a `.tmp` file and atomically renaming it to
+`.jsonl`, so a daemon polling the directory never reads a half-written file. The
+trailing `<pid>-<seq>` keeps two batches written in the same millisecond — by two
+threads, or by two agent processes sharing the spool — from overwriting each
+other. You do not need to manage these files directly.
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --locked --extra dev
+
+# Run the test suite
+uv run pytest tests/ -v
+
+# Run a single test
+uv run pytest tests/test_sdk.py -k duration -v
+```
+
+| Suite | What it holds |
+|---|---|
+| `test_sdk.py` | The public API — every event method, unit and on-disk |
+| `test_wire_format.py` | Golden bytes for all 15 event types, frozen |
+| `test_server_contract.py` | The keys ingest promotes to indexed columns |
+| `test_spool_contract.py` | Agreement with the daemons that read the spool |
+| `test_durability.py` | Concurrency, crash and retry paths — nothing silently lost |
+| `test_zero_dependencies.py` | The stdlib-only guarantee |
+| `test_no_customer_identifiers.py` | Nothing private ships in a public wheel |
+
+Two suites reach for sources outside this package. `test_spool_contract.py` reads
+the Rust and TypeScript in this repo and never skips; set
+`FAILPROOFAI_SDK_REQUIRE_CONTRACT=1` (CI does) so a moved file fails instead of
+skipping. Set `FP_AGENTEYE_ROOT` to an AgentEye checkout to additionally verify
+against the older collector and the live ingest handler.