docs: correct the per-run cap guidance on the Deep Agents page

integrate/add-to-your-agent/deep-agents.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Deep Agents"
 description: "Charge for a capability that lives inside a Deep Agents subagent, using Nevermined x402"
 icon: "sitemap"
 frameworks: ["deepagents", "langchain", "langgraph", "python"]
 ---
@@ -11,7 +11,7 @@
 </Note>
 
 <Card title="Runnable tutorial" icon="play" href="https://github.com/nevermined-io/tutorials/tree/main/langchain-deep-agent-py">
   **`langchain-deep-agent-py`** — a freemium market-research agent on the Deep
   Agents harness, where the paid tool lives inside a subagent. Clone, fill in
   `.env`, run `poetry run buyer` to watch the free path and the paid path
   back to back.
@@ -19,7 +19,7 @@
 
 [Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview) is LangChain's agent *harness*: `create_deep_agent()` returns a compiled LangGraph graph that already has planning, a filesystem, and subagent delegation built in. You reach for it when one agent needs to plan a job and hand pieces of it to specialists.
 
 **The Nevermined integration does not change.** `@requires_payment` works on a Deep Agents tool exactly as it does on a plain LangChain one — this page is about the one property that makes that true, and the two harness behaviours you should design around.
 
 ## The delegation hop
 
@@ -32,7 +32,7 @@
 )
 ```
 
 The supervisor never handles that token. It delegates through the built-in `task` tool, and LangGraph copies `configurable` down into the subagent's own tool calls — so the decorator finds the token one hop below where it was supplied:
 
 ```
 main agent  ──task()──▶  research-sub  ──▶  market_research  [PAID]
@@ -41,7 +41,7 @@
                 config.configurable.payment_token
 ```
 
 This is the property the whole pattern rests on. A deep agent's premise is that the supervisor hands work to subagents; if payment context did not survive that hop, every paid tool would have to sit on the main agent and the harness would be useless for monetized capabilities.
 
 <Note>
   The buyer does not need to know the agent's internal topology. The contract is
@@ -120,14 +120,43 @@
   message may settle credits more than once.
 </Warning>
 
-Cap it explicitly rather than trusting the model to be frugal. Count paid calls per run, keyed on `config["configurable"]["thread_id"]` (or `run_id`), and return a plain refusal once the cap is hit:
+Cap it explicitly rather than trusting the model to be frugal — but note **where a run's identity has to come from**.
+
+LangGraph does *not* put a run id in `config["configurable"]`. A tool sees only `thread_id`, checkpoint bookkeeping, and whatever the caller passed (verified against langgraph 1.2 / deepagents 0.7). Since `thread_id` is stable for a whole conversation, keying a "per-run" cap on it silently makes it per-*conversation*: after N paid calls the tool refuses forever, however many new questions the user asks.
+
+So the **caller** declares the run — it is the only party that knows where one ends:
+
+```python
+# buyer side: a fresh nonce per run, alongside the token
+"config": {"configurable": {
+    "payment_token": token,
+    "nvm_run_id": str(uuid.uuid4()),
+}}
+```
 
 ```python
+# agent side: key on the nonce, fall back to thread_id, and say which is in force
 if not budget.try_consume(config):
-    return "BUDGET_EXHAUSTED: this run already used its paid-call allowance."
+    if budget.scope_of(config) == "run":
+        return "BUDGET_EXHAUSTED: this run already used its paid-call allowance."
+    return ("BUDGET_EXHAUSTED: this conversation already used its allowance. "
+            "Pass a per-run `nvm_run_id` to scope the cap to one request.")
 ```
 
-Refund the reservation when a call raises `PaymentRequiredError` — otherwise a user who authorizes mid-run gets fewer paid calls than they paid for.
+Two details that are easy to miss:
+
+- **Refund the reservation when a call raises `PaymentRequiredError`** — otherwise a user who authorizes mid-run gets fewer paid calls than they paid for.
+- **Bound the counter map.** The agent is a long-running server, so a plain dict keyed on run or thread grows for the life of the process. An LRU with a fixed ceiling is enough; evicting a key only refills that budget, so the worst case is a long-idle caller getting a fresh allowance rather than an over-charge.
+
+A browser chat UI whose proxy injects only the token will fall into the conversation-scoped case. That is the safe direction to fail — it under-spends, never over-spends — as long as the refusal message says so instead of promising a reset that will not happen.
+
+<Note>
+  Counting from graph state via `InjectedState` looks like a tidier
+  alternative, and it does work inside a subagent tool — but it exposes the
+  **subagent's own** isolated conversation, which resets on every `task()`
+  hop. It therefore cannot see sibling delegations within a single turn,
+  which is exactly the case the cap exists for.
+</Note>
 
 <Warning>
   **Two LLM layers can paraphrase the paid tool's output.** The subagent relays
@@ -141,7 +170,7 @@
 
 ## Version requirements
 
 `deepagents` requires the LangChain v1 stack (`langchain>=1.3.18`, `langchain-core>=1.6.1`). If your existing project pins an older `langchain-core`, give the deep agent its own virtualenv rather than upgrading around it.
 
 ```bash
 pip install deepagents "payments-py[langsmith]" langchain-openai
@@ -166,7 +195,7 @@
 | Paid tool lives on | the agent itself | a subagent, one `task()` hop away |
 | LLM layers between tool and user | 1 | 2 |
 | Paid calls per user turn | one per tool call the model makes | supervisor decides — cap it |
 | Built-in planning / filesystem / subagents | no | yes |
 | Buyer-side contract | `config.configurable.payment_token` | **identical** |
 
 Start from the [LangChain guide](/integrate/add-to-your-agent/langchain) if you want the smallest thing that works. Come here when the agent needs to plan, delegate, or manage its own context — and note that the payment integration itself does not change.
@@ -176,4 +205,4 @@
 - [LangChain integration](/integrate/add-to-your-agent/langchain) — the decorator and HTTP-middleware approaches in full.
 - [LangSmith Deployment](/integrate/add-to-your-agent/langsmith-deployment) — hosting a gated graph.
 - [`langchain-deep-agent-py`](https://github.com/nevermined-io/tutorials/tree/main/langchain-deep-agent-py) — the runnable tutorial for this page.
 - [`langchain-research-agent-py`](https://github.com/nevermined-io/tutorials/tree/main/langchain-research-agent-py) — the same freemium pattern on `create_react_agent`.