failproofai 1.0.1 → 1.0.2-beta.0

package/.next/standalone/sdk/python/skill/references/events.md

@@ -0,0 +1,234 @@
+# Event catalog
+
+Every method lives on `failproofai_sdk.event`, is **keyword-only**, and returns `None`.
+Nothing here blocks or does I/O — the call queues the event and returns.
+
+`session_id` and `agent_id` are optional on all fifteen: omit them and they come
+from the enclosing `failproofai_sdk.session()` / `failproofai_sdk.agent()` scope. Pass them and
+your value wins. Omit `session_id` with nothing bound and you get a `TypeError`
+naming the fix; `agent_id` falls back to `"main"` and never raises. See
+`integration.md`.
+
+Emit only what fits the agent. There is no requirement to use every type, and no
+penalty for skipping one — except `agent_start`, without which the session does
+not exist at all.
+
+## The 15 events
+
+Columns: **Required** is beyond `session_id` + `agent_id`, which every event
+carries and which you rarely pass by hand.
+*Optional fields are omitted from the record entirely when left unset* — they are
+not written as `null`.
+
+| Method | Required | Optional | Notes |
+|---|---|---|---|
+| `agent_start` | — | `goal`, `parent_id` | **Creates the session.** `parent_id` is the **`agent_id` of the parent agent** — not a session id, not a run id. Pass a session id here and you get no nesting, silently. |
+| `agent_end` | — | `outcome`, `summary` | `outcome` must be `failed`/`error`/`timeout`/`rejected` to count as a failure. |
+| `agent_pause` | `pause_id` | `reason`, `user_id` | Suspends the agent (waiting for a human, throttled, user-paused) **without ending it**. Starts the paused clock for this `pause_id`. |
+| `agent_resume` | `pause_id` | `reason`, `user_id` | Emit **instead of a second `agent_start`** when a paused agent continues. `duration_ms` auto-computed — how long it was paused. |
+| `tool_use` | `tool_name`, `tool_call_id` | `input` | Starts the duration clock for this `tool_call_id`. |
+| `tool_result` | `tool_name`, `tool_call_id` | `output`, `error` | `duration_ms` auto-computed from the matching `tool_use`. |
+| `model_request` | — | `model`, `messages`, `system`, `tools`, `request_id` | `request_id` is what pairs this with its response. |
+| `model_response` | — | `model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `error` | Token counts drive spend reporting. `error` marks a failed call — a 429 or a timeout — without a separate `error` event. |
+| `error` | `error_type`, `message` | `traceback` | Always counts as an error, whatever else is set. |
+| `hook_triggered` | `hook_name`, `hook_id` | `trigger_event`, `input` | Starts the clock for this `hook_id`. |
+| `hook_completed` | `hook_name`, `hook_id` | `outcome`, `output`, `error` | `duration_ms` auto-computed. Same `outcome` rule as `agent_end`. |
+| `human_wait` | `input_id` | `prompt`, `options`, `reason` | Starts the clock for this `input_id`. |
+| `human_input` | `input_id` | `response` | `duration_ms` auto-computed — how long the human took. |
+| `human_pause` | — | `reason`, `user_id` | |
+| `human_interrupt` | — | `reason`, `user_id`, `at_step` | |
+
+## Rules that apply to every event
+
+**Payloads should be structured JSON where possible.** Serialization happens on
+a background thread. Unsupported leaves such as `datetime`, `UUID`, `Decimal`,
+`set`, `bytes`, or a Pydantic model are stringified automatically rather than
+stopping the writer. If downstream analysis needs more than that string form,
+serialize the value explicitly into a stable JSON object at the integration
+boundary.
+
+**Custom fields are free, and their *names* are unvalidated:**
+
+```python
+failproofai_sdk.event.tool_use(
+    session_id=sid, agent_id="planner",
+    tool_name="web_search", tool_call_id="toolu_01",
+    input={"query": "..."},
+    tenant="acme", retry_count=2,          # yours, kept verbatim
+)
+```
+
+A misspelled **optional** name is not an error — it is a new field. `inpt={...}`
+is accepted, stored, and invisible; nothing will tell you. When something is
+missing from a surface, suspect a typo before suspecting the platform.
+
+A misspelled **required** name is a plain `TypeError` — `tool_name` and friends
+are real parameters, so `tool_nmae="search"` fails loudly at the call site. Only
+the optional names are silent.
+
+**Five names are reserved and raise `ValueError`.** `timestamp`, `session_id`,
+`agent_id`, `type`, `environment` — passing any as a custom field. (`session_id`
+and `agent_id` are already named args, so Python raises `TypeError` first.)
+
+**`duration_ms` is yours to pass on eleven of the fifteen.** It is computed for you
+on `tool_result`, `hook_completed`, `human_input`, and `agent_resume`, and passing
+it to *those four* raises `ValueError`. On the other eleven there is no guard:
+`agent_end(..., duration_ms=5)` is accepted and stored as an ordinary custom field. Don't.
+
+The one place you *should* pass it is **`model_response`**, where nothing computes
+it for you. Time the call yourself and pass whole milliseconds as an **`int`** —
+`round(seconds * 1000)`. A float raises `ValueError` at the call site, naming the
+argument: the server reads this as an unsigned 32-bit integer and would store NULL
+for anything else, so the SDK refuses it rather than letting the duration vanish.
+The same guard covers `input_tokens` and `output_tokens`.
+
+**Set `request_id` on both model events.** The same value on the `model_request`
+and its `model_response` — a `uuid4().hex`, or the provider's own request id if it
+gives you one, so your events line up with your provider logs. It links the pair
+in the event detail view.
+
+It does **not** yet drive the timeline rail or the model latency reports: those
+still match concurrent LLM calls (a parallel fan-out, a sub-agent, a retry racing
+its original) oldest-first, and will keep bracketing the wrong pairs. **Always
+pass `duration_ms` on the `model_response` too** — that is what keeps the reported
+duration right even when the bracketing is wrong.
+
+**Correlation is a process-wide map keyed by your ids.** The SDK holds open
+starts there until their matching end arrives. Consequences, in order of how much
+they hurt:
+
+- **Per-run counters are unsafe.** `call_1`, `call_2` — common in home-grown loops
+  — collide across overlapping runs. The failure is not the missing duration the
+  docs might lead you to expect; it is a *plausible wrong number attributed to the
+  wrong run*, which is worse. Reuse your framework's id (Anthropic and OpenAI
+  tool-call ids are globally unique), or a `uuid4`. `failproofai_sdk.tool_call()`
+  generates a `uuid4` for you.
+- **`tool_call_id` and `hook_id` no longer collide with each other.** They live in
+  separate namespaces, so a `hook_completed(hook_id="x")` cannot pair with a
+  pending `tool_use(tool_call_id="x")`. The key is `<kind>:<session_id>:<id>`, so
+  each id only has to be unique *within one session, for one kind* — two sessions
+  reusing `call_1` measure independently. Reuse it twice in the SAME session and
+  the second `tool_use` overwrites the first pending entry, so the first
+  `tool_result` measures from the wrong start. (If you have read
+  older guidance saying one shared id space, that was true and is not any more —
+  the ids are namespaced by the SDK, so nothing on your side changes.)
+- **`input_id` and `pause_id` are scoped per session/agent**, so
+  `human_wait`/`human_input` and `agent_pause`/`agent_resume` cannot collide
+  across runs at all.
+- **The pair must happen in the same process.** A `tool_use` in one worker and a
+  `tool_result` in another produces two unpaired events and no duration. The same
+  goes for a human pause that resumes in a different process.
+- **The map is capped at 10,000 and evicts oldest-first**, so a long-running
+  process that leaks orphaned starts can silently lose the duration on legitimate
+  later pairs.
+
+**Timestamps are set by the SDK** at the moment you call the method — UTC,
+microsecond precision, `Z`-suffixed (`2026-07-17T09:15:22.123456Z`). You cannot
+override it (`timestamp` is reserved).
+
+**There is no event id.** Events carry no unique identifier and no sequence
+number. They are ordered by timestamp and correlated by your ids. This means
+events are not deduplicable — if you emit the same event twice, that is two
+events.
+
+## What one line looks like
+
+Each record is one line of JSON in an `event-*.jsonl` file. Key order is stable:
+identity first, then the event's own required fields, then `environment`, then
+whatever optional and custom fields you set.
+
+```json
+{"timestamp": "2026-07-17T09:15:22.123456Z", "session_id": "run-001", "agent_id": "planner", "type": "tool_use", "tool_name": "web_search", "tool_call_id": "toolu_01", "environment": "production", "input": {"query": "latest AI research"}}
+{"timestamp": "2026-07-17T09:15:23.456789Z", "session_id": "run-001", "agent_id": "planner", "type": "tool_result", "tool_name": "web_search", "tool_call_id": "toolu_01", "environment": "production", "output": {"results": ["..."]}, "duration_ms": 1334}
+```
+
+**Parse it; don't grep it.** The whitespace above is what today's writer happens
+to emit — it is not a contract. `grep '"type":"agent_start"'` finds nothing on a
+perfectly healthy integration, and reads as "my events are missing". Use
+`python -m json.tool --json-lines`, or `jq`.
+
+`environment` is always present. It is `"dev"` unless you set it — see
+`../SKILL.md` §3.
+
+## A minimal complete run
+
+The shape to aim for. `agent_start` and `agent_end` bracket everything; the pairs
+nest inside.
+
+```python
+import failproofai_sdk
+
+failproofai_sdk.configure(environment="production")
+
+sid = "run-001"
+failproofai_sdk.event.agent_start(session_id=sid, agent_id="planner", goal="answer the user's question")
+try:
+    failproofai_sdk.event.model_request(session_id=sid, agent_id="planner", model="claude-opus-4-8",
+                                 request_id="req-1",
+                                 messages=[{"role": "user", "content": "..."}])
+    failproofai_sdk.event.model_response(session_id=sid, agent_id="planner", model="claude-opus-4-8",
+                                  request_id="req-1", duration_ms=812,
+                                  stop_reason="tool_use", input_tokens=1200, output_tokens=95)
+
+    failproofai_sdk.event.tool_use(session_id=sid, agent_id="planner",
+                            tool_name="web_search", tool_call_id="toolu_01",
+                            input={"query": "..."})
+    failproofai_sdk.event.tool_result(session_id=sid, agent_id="planner",
+                               tool_name="web_search", tool_call_id="toolu_01",
+                               output={"results": ["..."]})
+# BaseException, not Exception: `asyncio.CancelledError` inherits from
+# BaseException, so `except Exception` lets a cancelled run through and the
+# session ends with an `agent_start` and no `agent_end` at all.
+except BaseException as e:
+    import traceback
+    failproofai_sdk.event.error(session_id=sid, agent_id="planner",
+                         error_type=type(e).__name__, message=str(e),
+                         traceback=traceback.format_exc())
+    failproofai_sdk.event.agent_end(session_id=sid, agent_id="planner", outcome="failed")
+    raise
+else:
+    failproofai_sdk.event.agent_end(session_id=sid, agent_id="planner",
+                             outcome="success", summary="answered from 1 search")
+```
+
+Note `outcome="failed"` in the `except` — not `"failure"`, which silently reads as
+a non-failure.
+
+Threading `sid` through by hand like this is fine for one function and miserable
+across a real codebase — which is why you do not have to. The same run, with the
+scopes doing the identity and the bracketing:
+
+```python
+with failproofai_sdk.agent("planner", session_id="run-001", goal="answer the user's question"):
+    failproofai_sdk.event.model_request(model="claude-opus-4-8", request_id="req-1", messages=[...])
+    failproofai_sdk.event.model_response(model="claude-opus-4-8", request_id="req-1", duration_ms=812,
+                                  stop_reason="tool_use", input_tokens=1200, output_tokens=95)
+    with failproofai_sdk.tool_call("web_search", input={"query": "..."}) as t:
+        t.output = {"results": ["..."]}
+```
+
+`agent_start`/`agent_end`, the `error` event, `outcome="failed"` and the tool
+timing all come for free, including on the exception path. See `integration.md`;
+on a supported framework, `frameworks.md` gets you the same events with no call
+sites at all.
+
+## Pausing and resuming — not ending
+
+When a run suspends — waiting for a human, rate-limited, user-paused — do **not**
+emit `agent_end` and then a fresh `agent_start` on the way back: that reads as two
+separate agents, and the wait counts as active work. Bracket the gap with
+`agent_pause` / `agent_resume` instead, reusing one `pause_id`:
+
+```python
+import uuid
+pause_id = str(uuid.uuid4())
+failproofai_sdk.event.agent_pause(session_id=sid, agent_id="planner",
+                           pause_id=pause_id, reason="waiting_for_user")
+#   … the run is parked; a human is deciding …
+failproofai_sdk.event.agent_resume(session_id=sid, agent_id="planner", pause_id=pause_id)
+```
+
+The agent span stays open across the pause (it is not ended); `agent_resume`
+carries the paused `duration_ms` when both halves run in the same process, and
+paused time is reported separately from active work. Persist `pause_id` if the
+resume happens in a different process so it reuses the same value.

package/.next/standalone/sdk/python/skill/references/frameworks.md

@@ -0,0 +1,314 @@
+# Framework integrations
+
+If the agent runs on LangChain/LangGraph, CrewAI, LlamaIndex or Pydantic AI, you
+do not write the instrumentation — you turn it on. The adapters ship inside the
+SDK wheel and are imported only when you ask for them.
+
+```python
+import failproofai_sdk
+from langgraph.graph import StateGraph      # import your framework FIRST
+
+failproofai_sdk.configure(environment="production")
+failproofai_sdk.instrument()                       # every supported framework already imported
+
+graph.invoke({"messages": [...]})           # sessions, tools, models, errors all appear
+```
+
+No call site changes. `graph.invoke()`, `crew.kickoff()`, `await workflow.run()`
+and `await agent.run()` are recorded exactly as they are written today.
+
+## `instrument()` / `uninstrument()`
+
+```python
+failproofai_sdk.instrument()                       # auto-detect
+failproofai_sdk.instrument("crewai")               # exactly one
+failproofai_sdk.instrument("langchain", session_id=request_id, capture_content=False)
+failproofai_sdk.uninstrument()                     # put everything back
+```
+
+- **Auto-detect reads what is already imported, not what is installed.** This is
+  deliberate — a library that imports LangChain to find out whether you use it
+  costs you a second of startup for nothing. The consequence is an ordering rule:
+  `configure()` → import the framework → `instrument()` → run. Calling
+  `instrument()` too early instruments nothing and returns `()` — no exception,
+  but it does log a warning, so check stderr when a run records nothing.
+- **It returns the names it newly instrumented**, as a tuple. Assert on it in
+  startup code if you want a loud failure: `assert failproofai_sdk.instrument()`.
+- **Instrumenting something already active is a no-op** returning `()`. Calling
+  it from two code paths, or from a reloading dev server, cannot double-record.
+- **An unknown name raises `ValueError` listing the valid ones.** A typo that
+  silently records nothing is the worst available outcome, so this one is loud.
+  Accepted spellings: `langchain` (aliases `langgraph`, `langchain_core`),
+  `crewai`, `llama_index` (`llamaindex`, `llama-index`), `pydantic_ai`
+  (`pydantic-ai`, `pydanticai`).
+- **One adapter failing does not cost you the others.** With no argument, an
+  adapter whose install fails is logged and skipped and the rest still install.
+- **Ask what is wired up** rather than guessing, when a run records nothing:
+
+  ```python
+  from failproofai_sdk.integrations import available, active
+
+  available()   # ('crewai', 'langchain', 'llama_index', 'pydantic_ai') — every adapter that ships
+  active()      # ('langchain',) — what is instrumented in THIS process right now
+  ```
+
+  An empty `active()` after you called `instrument()` is the ordering bug above:
+  the framework was not in `sys.modules` yet.
+- **`uninstrument()` never raises**, restores the original objects it replaced,
+  and closes anything still open with `outcome="cancelled"` so teardown does not
+  leave a session reported as ongoing forever.
+
+Options are keyword arguments to `instrument()`. The same dict reaches every
+adapter, so an option meant for one is ignored by the others rather than raising:
+
+| Option | Applies to | Effect |
+|---|---|---|
+| `session_id=` | langchain, crewai, pydantic_ai | Pin every run to this session id. Use it when your service already has a per-request id. |
+| `capture_content=False` | langchain, pydantic_ai | Drop prompts, messages and outputs; keep structure, durations and token counts. |
+| `capture_messages=False` | llama_index | The same, for LlamaIndex. |
+| `include_chains=("rag",)` | langchain | Record these intermediate chains by name. Default: none — see below. |
+| `graph_callbacks=False` | langchain | Turn off LangGraph interrupt/resume wiring. Default on. |
+| `steps=False` | llama_index | Stop emitting a hook pair per workflow step. Default on. |
+| `embeddings=True` | llama_index | Record embedding calls. Default off — they are high volume and low signal. |
+| `stale_after=600.0` | llama_index | Seconds before the background reaper closes a span the workflow never finished. |
+| `reaper_interval=30.0` | llama_index | How often that reaper runs. |
+
+## The rule the mappings follow
+
+> A framework construct becomes an Failproof AI **agent** if and only if it owns an
+> LLM decision loop and has its own goal. Everything else with a start and an end
+> becomes the closest kind of leaf.
+
+| Kind | Gets | Examples |
+|---|---|---|
+| owns a decision loop | `agent_start` / `agent_end` | the top-level graph, crew or workflow, and anything the framework itself calls an agent — a compiled subgraph, a CrewAI `Agent` role, a LlamaIndex `FunctionAgent` |
+| something the agent *calls* | `tool_use` / `tool_result` | function tools, retrievers, memory and knowledge queries |
+| machinery *around* the agent | `hook_triggered` / `hook_completed` (with `trigger_event`) | LangGraph nodes, LlamaIndex workflow steps, CrewAI flow methods, guardrails |
+
+**A LangGraph node is a hook, not a nested agent**, and that is the one mapping
+decision worth understanding, because it is the one you might be tempted to
+"fix". `agent_id` is the primary facet across every session; it has to stay a
+small, stable set of labels. Promote `retrieve`, `grade_documents` and
+`should_continue` to agents and you drown the real agents in the filter, and the
+session ends up labelled with whichever node happened to run first. Hook spans
+draw identically on the timeline — same lanes, same durations — and you get a
+per-node latency surface for free, with `hook_name` as its own facet.
+
+## LangChain / LangGraph
+
+Supported: `langchain-core >=1.4.7,<2`, `langgraph >=1.2,<2`.
+
+Attaches through LangChain's own callback configuration, so **every** callback
+manager the framework builds carries it — including ones created inside chains
+you never touch.
+
+| LangChain / LangGraph | Failproof AI |
+|---|---|
+| root run (the outermost chain/graph) | `agent_start` / `agent_end` |
+| LangGraph node | `hook_triggered` / `hook_completed`, `trigger_event="graph_node"` |
+| compiled subgraph | nested `agent_start` / `agent_end`, `agent_id="root/node"` |
+| tool run | `tool_use` / `tool_result` |
+| retriever run | `tool_use` / `tool_result`, output summarised |
+| chat model / LLM run | `model_request` / `model_response`, paired on `request_id` |
+| `interrupt()` | `human_wait` + `agent_pause` |
+| `Command(resume=...)` | `agent_resume` + `human_input` |
+| intermediate chains | **nothing**, unless you name them in `include_chains` |
+
+**Python 3.10 async nodes must forward `RunnableConfig`.** LangGraph cannot
+automatically propagate callback context from an async node into a child
+`ainvoke()` on Python 3.10. Without this, the child model or tool appears as a
+separate root run:
+
+```python
+from langchain_core.runnables import RunnableConfig
+
+async def plan(state, config: RunnableConfig):
+    reply = await model.ainvoke(state["messages"], config=config)
+    return {"messages": [reply]}
+```
+
+Python 3.11 and later propagate this context automatically.
+
+`session_id` resolution, in order — the first that produces a value wins:
+
+1. `instrument("langchain", session_id=...)`;
+2. `config={"metadata": {"failproofai_sdk_session_id": sid}}` on the call — the
+   documented per-call key, and the one to use in a web service;
+3. an enclosing `failproofai_sdk.session()` / `failproofai_sdk.agent()` scope;
+4. `metadata["session_id" | "conversation_id" | "thread_id"]`;
+5. the root run id.
+
+It is never synthesised from scratch. A made-up id would split one run into many
+sessions, which is a silent wrong answer rather than a loud one.
+
+Three behaviours that surprise people:
+
+- **A `GraphInterrupt` is control flow, not an error.** LangGraph raises it
+  through the same error callback as a genuine failure, so a naive integration
+  paints every human approval red and ends the run as `failed`. The adapter
+  treats the whole interrupt family as control flow and emits the HITL pairs
+  instead.
+- **Streaming never produces per-token events.** Time-to-first-token and the
+  chunk count are folded into the closing `model_response` as `fw_ttft_ms` and
+  `fw_chunks`.
+- **`agent_id` is the graph or chain name**, never a run UUID. Framework ids land
+  in `fw_run_id` / `fw_node` / `fw_thread_id`.
+
+## CrewAI
+
+Supported: `crewai >=1.13,<2` (the release where the span tree and normalised
+token usage are both present). Registers a listener on CrewAI's event bus;
+`crew.kickoff()` is unchanged.
+
+| CrewAI | Failproof AI |
+|---|---|
+| crew kickoff | `agent_start` / `agent_end`, `agent_id` = crew name |
+| agent execution | nested `agent_start` / `agent_end`, `agent_id` = the agent's **role** |
+| task | no event of its own — folded into the agent execution that runs it |
+| flow method | `hook_triggered` / `hook_completed`, `trigger_event="flow_method"` |
+| guardrail | hook pair; a tripped guardrail closes with `outcome="rejected"` |
+| tool usage | `tool_use` / `tool_result` |
+| memory / knowledge query, save, retrieval | `tool_use` / `tool_result` (`memory.query`, `knowledge.search`, …) |
+| LLM call | `model_request` / `model_response` |
+| LLM stream chunks | folded into the closing `model_response` |
+
+`agent_id` is the crew name at the top and the **agent role** underneath —
+`"researcher"`, `"editor"`. CrewAI's `agent.id` is a UUID and goes to
+`fw_agent_id`, never to `agent_id`. CrewAI runs its own internal flow inside
+every agent execution; that one is a pass-through and does not become a span.
+
+## LlamaIndex
+
+Supported: `llama-index-core >=0.14.23,<0.15`. Registers on the root dispatcher,
+so one call covers every workflow and agent in the process.
+
+| LlamaIndex | Failproof AI |
+|---|---|
+| `Workflow.run` root span | session + `agent_start` / `agent_end` |
+| nested `Workflow.run` span | nested `agent_start` / `agent_end` |
+| workflow step | `hook_triggered` / `hook_completed`, `trigger_event="workflow_step"` |
+| LLM chat start/end | `model_request` / `model_response`, paired on `request_id` |
+| `FunctionTool.call` | `tool_use` / `tool_result` |
+| retrieval start/end | `tool_use` / `tool_result`, output summarised |
+| a tool that waits for an event | `human_wait` + `agent_pause`, then `agent_resume` + `human_input` |
+| embeddings | nothing, unless `embeddings=True` |
+
+`agent_id` is the `FunctionAgent.name` when there is one and the workflow class
+name otherwise — never a span id.
+
+**Token counts are best-effort here, and deliberately so.** LlamaIndex has no
+standard usage field, so the raw usage dict always ships as `usage`, and the
+top-level `input_tokens` / `output_tokens` are set **only** when a recognised key
+is present. A model integration that names its counters something new gives you a
+populated `usage` and blank token columns. That is the honest outcome; a
+confident wrong number would be worse.
+
+**Known gap:** human-in-the-loop is captured only when the wait happens inside a
+tool — the pattern LlamaIndex documents. A plain workflow step that waits for an
+event is resolved by the runtime before anything observable happens, so there is
+no signal to key a pause on.
+
+## Pydantic AI
+
+Supported: `pydantic-ai-slim >=2.0,<3`. Every tutorial written for v1 is wrong
+for this range: `Agent(instrument=...)` was removed in 2.0. The adapter installs
+itself as a capability instead — no OpenTelemetry SDK required, and it cannot
+double-count against your own tracing.
+
+| Pydantic AI | Failproof AI |
+|---|---|
+| an agent run | `agent_start` / `agent_end` (plus `error` on failure) |
+| a model request | `model_request` / `model_response` |
+| a tool execution | `tool_use` / `tool_result` |
+| graph nodes (`UserPromptNode`, `ModelRequestNode`, `CallToolsNode`) | **nothing** |
+
+Graph nodes are Pydantic AI's own loop machinery rather than steps you wrote —
+unlike a LangGraph node — and everything they do that is worth seeing is already
+covered by the model and tool spans.
+
+`session_id` is the run's `conversation_id`, so a conversation spanning several
+runs is one session; an enclosing `failproofai_sdk.session()` / `failproofai_sdk.agent()` scope
+always wins. `agent_id` is the `Agent`'s name.
+
+**One ordering rule, because it bites:** the capability is attached when an
+`Agent` is constructed, so **agents built before `instrument()` are not
+instrumented**, and agents built while instrumented keep the capability object
+after `uninstrument()` (it turns into a pass-through and stops recording).
+Construct your agents after `instrument()`, or attach it yourself:
+
+```python
+from failproofai_sdk.integrations.pydantic_ai import FailproofAI
+
+agent = Agent("openai:gpt-5", capabilities=[FailproofAI()])
+```
+
+## Mixing adapters with hand-written events
+
+They compose, and this is the supported way to add detail an adapter cannot know
+about:
+
+```python
+failproofai_sdk.instrument("langchain")
+
+with failproofai_sdk.agent("planner", goal=question):        # your bracket
+    graph.invoke(...)                                  # adapter events land here
+    with failproofai_sdk.tool_call("billing_check") as t:     # your own tool span
+        t.output = check(user)
+```
+
+Adapter events join **that** session, with `parent_id="planner"`. An adapter
+resolves identity from its own run id first, then that run's parent chain, then
+whatever scope you have open — so a hand-written outer bracket and an adapter
+produce one tree, not two.
+
+## What every adapter guarantees
+
+- **They never raise into your agent.** Every callback is wrapped: a failure logs
+  at WARNING with a traceback, and after three failures at the same call site
+  that site disables itself at ERROR. A broken adapter costs you a log line, not
+  your agent. Set `FAILPROOFAI_SDK_STRICT=1` to make it re-raise instead — do that in
+  tests and when debugging an adapter that records nothing.
+- **Version ranges are checked at `instrument()` time.** Outside the supported
+  range: warn once, keep going. Named explicitly but not importable at all:
+  `ImportError` carrying the install command. `FAILPROOFAI_SDK_STRICT_INTEGRATIONS=1`
+  promotes every one of those warnings to an exception.
+- **Framework-native ids are namespaced `fw_*`** — `fw_run_id`, `fw_node`,
+  `fw_task_id`, `fw_agent_id`, `fw_thread_id`. Flat, never nested. This is a
+  safety rule, not a style one: custom fields are merged last, so an un-namespaced
+  extra called `tool_name` or `duration_ms` would overwrite the real field.
+- **Large payloads are truncated**, per field and per event, with a
+  `…[truncated]` marker. Prompts, retrieved documents and tool outputs are the
+  three largest strings in an agent process.
+- **Every event carries `framework`, `framework_version` and
+  `integration_version`**, so you can tell adapter output from your own.
+- **No per-token events, ever.** Streaming is folded into the closing
+  `model_response`.
+- **Timestamps are stamped when the callback fires.** Nothing is backdated, so an
+  adapter cannot import a trace that already happened.
+
+## Verifying an adapter
+
+Everything in `../SKILL.md` §5 applies unchanged — the events go to the same
+files. Four checks that are specific to adapter output:
+
+1. **The first event of each session is the root `agent_start`.** Anything
+   emitted before it can leave the session labelled by the wrong actor.
+2. **`agent_id` values are names, not UUIDs** — `"planner"`, `"researcher"`,
+   the graph name. A UUID here means something is being passed through that
+   should have gone to `fw_agent_id`.
+3. **`model_request` and `model_response` share a `request_id`**, and every
+   `model_response` carries an integer `duration_ms`.
+4. **Nothing is left open.** Every `tool_use` has a `tool_result`, every
+   `agent_start` an `agent_end`.
+
+If an adapter records nothing at all, in this order: was the framework imported
+**before** `instrument()` (auto-detect reads imported modules); did
+`instrument()` return a non-empty tuple; and does the run produce anything with
+`FAILPROOFAI_SDK_STRICT=1` set, which converts a swallowed adapter error into a raise.
+
+## A framework that is not on this list
+
+Use the shipped context managers at the framework's own boundaries —
+`failproofai_sdk.agent()` around the run, `failproofai_sdk.tool_call()` in the tool hook. See
+`integration.md`. Ask before writing a full callback adapter for an unsupported
+framework: adding one to the SDK is usually the better answer.

package/.next/standalone/sdk/python/skill/references/install.md

@@ -0,0 +1,100 @@
+# Installing the SDK
+
+```bash
+pip install failproofai-sdk        # or: uv add failproofai-sdk
+```
+
+The SDK has no dependencies, so that is all it installs. Optional extras pull in
+the **framework**, never the adapter — all four adapters ship in the box:
+
+```bash
+pip install 'failproofai-sdk[langchain]'     # also: langgraph, crewai, pydantic-ai
+pip install 'failproofai-sdk[llamaindex]'    # note: no hyphen, unlike the dist name
+```
+
+Most agents already have their framework installed and never need one of these.
+
+Then `import failproofai_sdk`. There is no token, no private index, and no wheel to
+download by hand — the distribution is on public PyPI. It has no dependencies, so
+it cannot conflict with anything already in the agent's environment.
+
+## The one thing that still goes wrong
+
+**`pip install agenteye` does not install this SDK, and can uninstall it.**
+
+`agenteye` was the SDK's distribution name inside the private monorepo, and it is
+also the name an old CLI published under. That CLI has moved to `fp-cloud-cli` (command
+`fp`), but its last release as `agenteye` — version `0.1.22` — is stranded on
+public PyPI permanently. PyPI versions cannot be withdrawn and reused, and pip
+resolves the highest version, so that build is what the name still resolves to.
+
+| You run | You get | Symptom |
+|---|---|---|
+| `pip install agenteye`, nothing installed | the stranded CLI build | `import failproofai_sdk` → `ModuleNotFoundError`; that build ships `agenteye_cli` |
+| `pip install agenteye`, SDK already present | the stranded CLI build **alongside** it | Confusing but survivable — different distribution names, so the SDK is not removed |
+| `pip install agenteye` on a pre-rename SDK (`agenteye` ≤ `0.0.1b14`) | the stranded CLI build, **replacing the SDK** | The import that worked five minutes ago stops working: same distribution name, higher version, so pip treats it as an upgrade |
+
+The last row is the dangerous one and it is why the rename happened. It fires
+*after* a working integration, when someone wants the CLI to check that events
+arrived and installs it into the agent's own environment. Nothing warns them.
+
+If you want the CLI, it is a separate distribution and installing it cannot touch
+`failproofai-sdk` — but give it its own environment anyway:
+
+```bash
+pipx install fp-cloud-cli        # or: uv tool install fp-cloud-cli   (the command is `fp`)
+```
+
+## Migrating from the old `agenteye` distribution
+
+Two changes, both mechanical:
+
+```bash
+pip uninstall agenteye
+pip install failproofai-sdk
+```
+
+```diff
+-import agenteye
+-agenteye.configure(base_dir=None, flush_interval=0.5)
+-agenteye.event.agent_start(session_id="run-001", agent_id="planner")
++import failproofai_sdk
++failproofai_sdk.configure(base_dir=None, flush_interval=0.5)
++failproofai_sdk.event.agent_start(session_id="run-001", agent_id="planner")
+```
+
+Every method name, argument, and emitted field is unchanged, and so is
+`AGENTEYE_ENVIRONMENT` — a contract with a daemon that releases separately.
+
+**Two things changed on disk.** The default spool root is now
+`~/.failproofai/custom-agents`, not `~/.agenteye`; and **`AGENTEYE_HOME` no
+longer moves the SDK's spool at all.** It used to sit above the default, so
+exporting it for `agenteye-collector` — the component that genuinely reads it —
+relocated this SDK as an unasked-for side effect. Resolution is now exactly
+`configure(base_dir=...)`, else `~/.failproofai/custom-agents` (with
+`$FAILPROOFAI_HOME` moving the umbrella, never the spool out of it).
+
+`failproofaid` watches both roots, so if that is your daemon there is nothing to
+do and already-spooled batches still get collected. If you run the older
+`agenteye-collector`, point **it** at the SDK with
+`AGENTEYE_HOME=~/.failproofai/custom-agents`, or pass `base_dir` explicitly.
+(`AGENTEYE_SPOOL_TO_FAILPROOFAI` is retired: it also required the directory to
+pre-exist, which nothing created, so it never took effect.)
+
+## Confirm what you have
+
+```bash
+python -c "import failproofai_sdk; print(failproofai_sdk.__version__)"
+```
+
+- A version string such as `0.0.1b1` → the SDK. Good.
+- `ModuleNotFoundError: No module named 'failproofai_sdk'` → not installed. If
+  `pip show agenteye` returns something, you installed the wrong name; see above.
+
+## Pinning
+
+Pin `failproofai-sdk` in your dependency file like any other package. Never leave
+an unpinned `agenteye` requirement anywhere a CI job will resolve it from PyPI —
+it will pull the stranded CLI build on the next clean install. If you are
+migrating, grep for `agenteye` in every `requirements*.txt`, `pyproject.toml`,
+`Pipfile` and Dockerfile, not just the one you remember.