polyrob 0.5.0__py3-none-any.whl

tools/user_directory.py

@@ -0,0 +1,179 @@
+"""Shared UserDirectory — surface-agnostic identity store (P2c, Singular Chat Interface).
+
+ONE identity store behind POLYROB's many surfaces (CLI / WebView / Telegram). It maps a
+raw platform id (a Telegram chat id, a CLI id, …) to a STABLE INTERNAL ``user_id``
+and provides the reverse / email lookups that out-of-band delivery
+(``cron/delivery.py``) needs — keyed on the internal id, sync.
+
+Ported (reused, not forked) from the old Telegram-only bot
+(../rob_dev_telegram_version):
+- ``modules/database/user_profiles.py`` — the ``user_profiles`` table shape
+  (``user_id TEXT PK`` + ``tg_user_id TEXT UNIQUE``), ``get_or_create_by_tg_id``,
+  and the SHA256 ``generate_user_id`` derivation.
+- ``utils/user_id_utils.py`` — ``UserIDResolver`` bidirectional tg<->internal mapping.
+
+Key differences from the old bot (deliberate):
+- The internal id is **deterministically derived** from ``(surface, raw_id)`` via
+  SHA256, so it is stable WITHOUT a prior row (the old code minted a random UUID per
+  row). A row is still upserted so the reverse lookup (internal -> chat id) works.
+- Identity is **namespaced by surface** — the same raw "12345" on telegram vs cli
+  resolves to different internal ids, so cross-surface ids never collide.
+- Sync API (no async DB layer) — ``cron/delivery.py`` calls ``get_telegram_chat_id``
+  / ``get_email`` without ``await``; SQLite + ``core/sqlite_util`` is the right shape.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from typing import Optional
+
+from core.sqlite_util import execute_retry, wal_connect
+
+logger = logging.getLogger(__name__)
+
+# Length of the hex slice used for the internal id (mirrors the old 24-char hash).
+_ID_HEX_LEN = 24
+
+
+class UserDirectory:
+    """Container-registerable identity store over a SQLite ``user_profiles`` table."""
+
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        self._ensure_table()
+
+    # --- schema --------------------------------------------------------------
+    def _ensure_table(self) -> None:
+        conn = wal_connect(self.db_path)
+        try:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS user_profiles (
+                    user_id     TEXT PRIMARY KEY,
+                    surface_id  TEXT,
+                    tg_user_id  TEXT UNIQUE,
+                    chat_id     TEXT,
+                    email       TEXT,
+                    profile     TEXT,
+                    created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                )
+                """
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_user_profiles_tg "
+                "ON user_profiles(tg_user_id)"
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    # --- id derivation -------------------------------------------------------
+    @staticmethod
+    def _derive_internal_id(surface_id: str, raw_id: str) -> str:
+        """Deterministic, stable internal id from (surface, raw_id).
+
+        SHA256 of ``surface_id:raw_id`` so the same raw id on two surfaces never
+        collides and the id is reproducible without a prior DB row.
+        """
+        seed = f"{surface_id}:{str(raw_id).strip()}".encode("utf-8")
+        digest = hashlib.sha256(seed).hexdigest()[:_ID_HEX_LEN]
+        return f"u_{digest}"
+
+    # --- public API (contracts) ---------------------------------------------
+    def get_or_create_by_tg_id(self, tg_id: str, profile: Optional[dict] = None) -> str:
+        """Return a STABLE internal ``user_id`` for a Telegram id (idempotent).
+
+        Upserts a row mapping ``tg_id`` <-> internal id, persisting ``chat_id`` (==
+        the tg id, for reverse lookup), an optional ``email`` and JSON profile blob.
+        """
+        tg_id = str(tg_id).strip()
+        user_id = self._derive_internal_id("telegram", tg_id)
+        self._upsert(
+            user_id=user_id,
+            surface_id="telegram",
+            tg_user_id=tg_id,
+            chat_id=tg_id,
+            profile=profile,
+        )
+        return user_id
+
+    def resolve_internal(self, raw_user_id: str, surface_id: str) -> str:
+        """Map a raw platform id to a stable internal ``user_id`` (idempotent).
+
+        ``surface_id == "telegram"`` is exactly ``get_or_create_by_tg_id``. Other
+        surfaces derive/persist the same way, namespaced by ``surface_id`` so the
+        same raw id on different surfaces resolves to different internal ids.
+        """
+        raw_user_id = str(raw_user_id).strip()
+        if surface_id == "telegram":
+            return self.get_or_create_by_tg_id(raw_user_id)
+        user_id = self._derive_internal_id(surface_id, raw_user_id)
+        self._upsert(
+            user_id=user_id,
+            surface_id=surface_id,
+            tg_user_id=None,
+            chat_id=raw_user_id,
+            profile=None,
+        )
+        return user_id
+
+    def get_telegram_chat_id(self, user_id: str) -> Optional[str]:
+        """Reverse lookup: internal ``user_id`` -> telegram chat id (the tg id).
+
+        Exact name/shape consumed by ``cron/delivery.py::_owner_telegram``.
+        """
+        row = execute_retry(
+            self.db_path,
+            "SELECT tg_user_id, chat_id, surface_id FROM user_profiles WHERE user_id = ?",
+            (user_id,),
+            fetch="one",
+        )
+        if not row:
+            return None
+        # Only telegram-origin rows have a meaningful tg chat id.
+        if row["surface_id"] != "telegram":
+            return None
+        return row["tg_user_id"] or row["chat_id"]
+
+    def get_email(self, user_id: str) -> Optional[str]:
+        """Read the optional email for an internal ``user_id`` (None if unset)."""
+        row = execute_retry(
+            self.db_path,
+            "SELECT email FROM user_profiles WHERE user_id = ?",
+            (user_id,),
+            fetch="one",
+        )
+        if not row:
+            return None
+        return row["email"]
+
+    # --- internals -----------------------------------------------------------
+    def _upsert(
+        self,
+        *,
+        user_id: str,
+        surface_id: str,
+        tg_user_id: Optional[str],
+        chat_id: Optional[str],
+        profile: Optional[dict],
+    ) -> None:
+        email = profile.get("email") if profile else None
+        profile_json = json.dumps(profile) if profile else None
+        # COALESCE preserves previously-set fields when a later call passes None.
+        execute_retry(
+            self.db_path,
+            """
+            INSERT INTO user_profiles (user_id, surface_id, tg_user_id, chat_id, email, profile)
+            VALUES (?, ?, ?, ?, ?, ?)
+            ON CONFLICT(user_id) DO UPDATE SET
+                surface_id = excluded.surface_id,
+                tg_user_id = COALESCE(excluded.tg_user_id, user_profiles.tg_user_id),
+                chat_id    = COALESCE(excluded.chat_id, user_profiles.chat_id),
+                email      = COALESCE(excluded.email, user_profiles.email),
+                profile    = COALESCE(excluded.profile, user_profiles.profile),
+                updated_at = CURRENT_TIMESTAMP
+            """,
+            (user_id, surface_id, tg_user_id, chat_id, email, profile_json),
+        )

tools/web_fetch/__init__.py

@@ -0,0 +1,3 @@
+from .tool import WebFetchTool
+
+__all__ = ["WebFetchTool"]

tools/web_fetch/fetcher.py

@@ -0,0 +1,144 @@
+"""Stateless, SSRF-safe single-page fetch core (no browser, no Chromium).
+
+Security model (see docs/plans/2026-06-29-web-fetch-tier1-IMPLEMENTATION-PLAN.md):
+- Auto-redirects are OFF; every hop is re-validated.
+- Each hop is validated with MCPURLValidator.validate_and_resolve(), which returns a
+  pinned IP; the connection is pinned to that IP (Host/SNI preserved) so a DNS rebind
+  between validation and connect cannot redirect the socket internally.
+- Hard caps on redirects, total time, and response bytes (read incrementally so a
+  decompression bomb is aborted before it is fully buffered).
+"""
+
+import asyncio
+import socket
+import ssl
+from dataclasses import dataclass
+from typing import Callable, Optional
+from urllib.parse import urljoin, urlparse
+
+import aiohttp
+import certifi
+from aiohttp.abc import AbstractResolver
+
+from tools.mcp.security import get_url_validator
+
+_REDIRECT_STATUS = {301, 302, 303, 307, 308}
+
+# An honest, disclosed bot UA. Many sites (e.g. Wikipedia) reject requests with no
+# User-Agent; the "Mozilla/5.0 (compatible; ...)" form is the widely-accepted shape.
+_DEFAULT_HEADERS = {
+	"User-Agent": "Mozilla/5.0 (compatible; polyrob-web-fetch/1.0; +https://github.com/theselfruleorg)",
+	"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.5",
+}
+
+
+class WebFetchError(Exception):
+	"""Raised when a fetch is blocked, oversized, or exceeds the redirect cap."""
+
+
+@dataclass
+class FetchResult:
+	final_url: str
+	status: int
+	content_type: str
+	body: bytes
+
+
+class _PinnedResolver(AbstractResolver):
+	"""Force a single host to resolve to a pre-validated IP (defeats DNS rebinding).
+
+	aiohttp connects to the ``host`` field (our pinned IP) but uses ``hostname`` for
+	TLS SNI and keeps the URL's host for the Host header, so pinning is transparent.
+	"""
+
+	def __init__(self, hostname: str, pinned_ip: str) -> None:
+		self._hostname = hostname
+		self._ip = pinned_ip
+
+	async def resolve(self, host, port=0, family=socket.AF_INET):
+		ip = self._ip if host == self._hostname else host
+		return [{"hostname": host, "host": ip, "port": port,
+		         "family": family, "proto": 0, "flags": 0}]
+
+	async def close(self) -> None:  # pragma: no cover - trivial
+		return None
+
+
+def _default_session_factory(pinned_ip: Optional[str], hostname: Optional[str]):
+	ssl_ctx = ssl.create_default_context(cafile=certifi.where())
+	if pinned_ip and hostname:
+		connector = aiohttp.TCPConnector(resolver=_PinnedResolver(hostname, pinned_ip), ssl=ssl_ctx)
+	else:
+		connector = aiohttp.TCPConnector(ssl=ssl_ctx)
+	return aiohttp.ClientSession(connector=connector)
+
+
+async def safe_fetch(
+	url: str,
+	*,
+	max_bytes: int = 10_485_760,
+	max_redirects: int = 5,
+	timeout_sec: float = 15.0,
+	validate: bool = True,
+	validator=None,
+	session_factory: Optional[Callable] = None,
+) -> FetchResult:
+	"""Fetch ``url`` with per-hop SSRF validation, IP pinning, no auto-redirects, and caps.
+
+	Args:
+		validate: when False, skip SSRF validation entirely (single-user/local only).
+		validator: an object exposing ``validate_and_resolve(url) -> (ok, err, pinned_ip)``.
+			Defaults to the shared MCP URL validator (allow_http=True). Injectable for tests.
+		session_factory: ``factory(pinned_ip) -> async-context-session`` (injectable for tests).
+	"""
+	if validate and validator is None:
+		validator = get_url_validator(allow_http=True)
+
+	current = url
+	for _hop in range(max_redirects + 1):
+		pinned_ip: Optional[str] = None
+		# WS-4 (compute posture): a NARROW exception for the agent's OWN sandbox server —
+		# a loopback URL on a host port the sandbox actually published skips SSRF
+		# validation and pins to 127.0.0.1. Empty unless the sandbox published a port
+		# (posture >= 1); never matches RFC1918 or cloud metadata (not loopback).
+		_loopback_ok = False
+		try:
+			from tools.shell.loopback_allow import is_loopback_allowed
+			_loopback_ok = is_loopback_allowed(current)
+		except Exception:
+			_loopback_ok = False
+		if validate and _loopback_ok:
+			pinned_ip = "127.0.0.1"
+		elif validate:
+			# validate_and_resolve does a BLOCKING socket.getaddrinfo; offload it to a
+			# thread so a slow/sinkhole DNS can't freeze the whole event loop (every
+			# other session/request on this worker) for the resolver timeout.
+			ok, err, pinned_ip = await asyncio.get_running_loop().run_in_executor(
+				None, validator.validate_and_resolve, current)
+			if not ok:
+				raise WebFetchError(f"blocked URL ({current}): {err}")
+		hostname = urlparse(current).hostname
+
+		if session_factory is not None:
+			session_cm = session_factory(pinned_ip)
+		else:
+			session_cm = _default_session_factory(pinned_ip, hostname)
+
+		async with session_cm as session:
+			timeout = aiohttp.ClientTimeout(total=timeout_sec)
+			async with session.get(current, allow_redirects=False, timeout=timeout, headers=_DEFAULT_HEADERS) as resp:
+				if resp.status in _REDIRECT_STATUS:
+					location = resp.headers.get("Location")
+					if not location:
+						raise WebFetchError(f"redirect with no Location ({current})")
+					current = urljoin(current, location)
+					continue
+				ctype = resp.headers.get("Content-Type", "application/octet-stream")
+				buf = bytearray()
+				async for chunk in resp.content.iter_chunked(8192):
+					buf.extend(chunk)
+					if len(buf) > max_bytes:
+						raise WebFetchError(f"response exceeds {max_bytes} bytes ({current})")
+				return FetchResult(final_url=current, status=resp.status,
+				                   content_type=ctype, body=bytes(buf))
+	raise WebFetchError(f"too many redirects (>{max_redirects})")

tools/web_fetch/render.py

@@ -0,0 +1,44 @@
+"""Pure HTML->markdown rendering + content-type classification for web_fetch."""
+
+from bs4 import BeautifulSoup
+from markdownify import markdownify
+
+SPA_SHELL_SIGNAL = (
+	"[web_fetch: this page returned almost no readable text — it is likely a "
+	"JavaScript-rendered single-page app. Use the 'browser' tool (tool_ids=['browser']) "
+	"if you need its rendered content or interaction.]"
+)
+
+_BOILERPLATE_TAGS = ("script", "style", "nav", "header", "footer", "aside", "noscript")
+_MIN_TEXT_CHARS = 200
+
+
+def classify_content(content_type: str, body: bytes) -> str:
+	"""Return ``"html"``, ``"pdf"``, or ``"binary"`` (content-type first, magic-byte fallback)."""
+	ct = (content_type or "").lower()
+	if "html" in ct or "xhtml" in ct:
+		return "html"
+	if "pdf" in ct or body[:5] == b"%PDF-":
+		return "pdf"
+	if "text/plain" in ct:
+		return "html"  # treat plain text as renderable passthrough
+	return "binary"
+
+
+def render_html_to_markdown(html: str, max_chars: int = 40_000) -> str:
+	"""Strip boilerplate, convert to markdown, head-truncate with a marker.
+
+	Returns ``SPA_SHELL_SIGNAL`` when the page has almost no readable text (likely a
+	client-rendered SPA), so the agent's escalation cue is explicit.
+	"""
+	soup = BeautifulSoup(html, "html.parser")
+	for tag in soup(_BOILERPLATE_TAGS):
+		tag.decompose()
+	if len(soup.get_text(strip=True)) < _MIN_TEXT_CHARS:
+		return SPA_SHELL_SIGNAL
+	root = soup.body or soup
+	md = markdownify(str(root)).strip()
+	if len(md) > max_chars:
+		dropped = len(md) - max_chars
+		md = md[:max_chars] + f"\n\n[... {dropped} chars truncated ...]"
+	return md

tools/web_fetch/tool.py

@@ -0,0 +1,60 @@
+"""WebFetchTool: stateless web page reader (URL -> markdown). No browser/Chromium."""
+
+import os
+from typing import Any, Dict, Optional
+
+from core.config import BotConfig
+from tools.base_tool import BaseTool
+from tools.controller.views import WebFetchAction
+from tools.web_fetch.fetcher import safe_fetch, WebFetchError
+from tools.web_fetch.render import render_html_to_markdown, classify_content
+
+
+def _allow_private_urls() -> bool:
+	return os.getenv("WEB_FETCH_ALLOW_PRIVATE_URLS", "false").strip().lower() in ("1", "true", "yes", "on")
+
+
+class WebFetchTool(BaseTool):
+	"""Fetch a URL and return clean markdown. The lightweight default web reader."""
+
+	def __init__(self, name: str, config: BotConfig, container: Optional[Any] = None):
+		super().__init__(name=name, config=config, container=container)
+		self._enabled = True
+
+	@property
+	def required_config(self) -> Dict[str, str]:
+		return {}
+
+	@BaseTool.action(
+		description=(
+			"Fetch a single web page by URL and return its main content as markdown. "
+			"Use this to READ a page you have the URL for (articles, docs, API pages). "
+			"Lightweight and fast — no browser. For SEARCH use perplexity/anysite; for "
+			"pages needing login/clicks/forms use the browser tool."
+		),
+		param_model=WebFetchAction,
+	)
+	async def fetch_url(self, params: WebFetchAction) -> str:
+		# No services/state to set up — fetch is self-contained.
+		url = (params.url or "").strip()
+		if not url:
+			return "Please provide a url to fetch."
+		try:
+			result = await safe_fetch(url, validate=not _allow_private_urls())
+		except WebFetchError as e:
+			return f"Could not fetch the page (blocked or unreachable): {e}"
+		except Exception as e:  # network/timeout — fail soft, agent can escalate to browser
+			return f"Could not fetch the page: {e}"
+
+		kind = classify_content(result.content_type, result.body)
+		if kind == "pdf":
+			return (f"[web_fetch: {result.final_url} is a PDF, not an HTML page. "
+			        f"Save it and use the filesystem document-processing tools to extract text.]")
+		if kind == "binary":
+			return (f"[web_fetch: {result.final_url} returned non-HTML content "
+			        f"({result.content_type}); cannot render as markdown.]")
+		try:
+			html = result.body.decode("utf-8", errors="replace")
+		except Exception:
+			html = result.body.decode("latin-1", errors="replace")
+		return render_html_to_markdown(html, max_chars=params.max_chars)

tools/x402/__init__.py

@@ -0,0 +1,60 @@
+"""Agent x402 paying tool package (gated; default OFF)."""
+import os
+
+
+def x402_client_enabled() -> bool:
+    return os.getenv("X402_CLIENT_ENABLED", "false").lower() == "true"
+
+
+def register_x402_tool(force: bool = False) -> bool:
+    """Register the 'x402_pay' descriptor + class IFF X402_CLIENT_ENABLED (or forced).
+
+    Mirrors tools/code_exec.register_code_exec_tool. Descriptor inserted first
+    (register_tool_class is a silent no-op for unknown names). Never in default tool_ids.
+    """
+    if not (force or x402_client_enabled()):
+        return False
+    from tools.descriptors import (
+        TOOL_DESCRIPTORS, ToolDescriptor, ToolCategory, register_tool_class,
+    )
+    from tools.x402.service import X402PayTool
+
+    if "x402_pay" not in TOOL_DESCRIPTORS:
+        TOOL_DESCRIPTORS["x402_pay"] = ToolDescriptor(
+            name="x402_pay",
+            description="Pay for paid resources via the x402 protocol (agent personal wallet)",
+            category=ToolCategory.INTEGRATION,
+            is_optional=True,
+            init_priority=80,
+        )
+    register_tool_class("x402_pay", X402PayTool)
+    return True
+
+
+def x402_invoicing_enabled() -> bool:
+    from core.env import bool_env
+    return bool_env("X402_INVOICE_ENABLED", False)
+
+
+def register_x402_invoice_tool(force: bool = False) -> bool:
+    """Register 'x402_invoice' (x402_request/x402_invoices/accounting) IFF
+    X402_INVOICE_ENABLED (agent money loop). Same shape as register_x402_tool;
+    never in default tool_ids. Distinct flag from X402_CLIENT_ENABLED — invoicing
+    (receivables) needs a treasury address, not an agent wallet."""
+    if not (force or x402_invoicing_enabled()):
+        return False
+    from tools.descriptors import (
+        TOOL_DESCRIPTORS, ToolDescriptor, ToolCategory, register_tool_class,
+    )
+    from tools.x402.invoice_tool import X402InvoiceTool
+
+    if "x402_invoice" not in TOOL_DESCRIPTORS:
+        TOOL_DESCRIPTORS["x402_invoice"] = ToolDescriptor(
+            name="x402_invoice",
+            description="Create/track x402 payment requests (invoices) + the unified accounting ledger",
+            category=ToolCategory.INTEGRATION,
+            is_optional=True,
+            init_priority=80,
+        )
+    register_tool_class("x402_invoice", X402InvoiceTool)
+    return True

tools/x402/client.py

@@ -0,0 +1,47 @@
+"""x402 client boundary. The tool depends on X402PaymentClient (an interface),
+so the official x402 SDK (RealX402Client, Task 8) is swappable and tests use a
+deterministic FakeX402Client. The signer is the agent wallet's x402 signer —
+the raw key never leaves it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Protocol
+
+from core.wallet.signer import Signer
+
+
+@dataclass(frozen=True)
+class X402Result:
+    body: str
+    paid: bool
+    amount_usd: float
+    tx_hash: Optional[str]
+    pay_to: Optional[str]
+    status_code: int
+
+
+class X402PaymentClient(Protocol):
+    async def quote(self, url: str) -> Optional[float]: ...
+    async def fetch_with_payment(
+        self, *, url: str, method: str, body: Optional[str], signer: Signer,
+        network: str, facilitator_url: str, max_amount_usd: float,
+    ) -> X402Result: ...
+
+
+class FakeX402Client:
+    """Deterministic test double."""
+
+    def __init__(self, price_usd: Optional[float], pay_to: Optional[str], paid_body: str):
+        self._price = price_usd
+        self._pay_to = pay_to
+        self._body = paid_body
+
+    async def quote(self, url: str) -> Optional[float]:
+        return self._price
+
+    async def fetch_with_payment(self, *, url, method, body, signer, network, facilitator_url, max_amount_usd) -> X402Result:
+        if self._price is None:
+            return X402Result(body=self._body, paid=False, amount_usd=0.0, tx_hash=None, pay_to=None, status_code=200)
+        return X402Result(body=self._body, paid=True, amount_usd=self._price,
+                          tx_hash="0xfake", pay_to=self._pay_to, status_code=200)

tools/x402/invoice_tool.py

@@ -0,0 +1,143 @@
+"""X402InvoiceTool — the agent invoices and accounts for itself.
+
+Three actions, all riding existing seams:
+
+- ``x402_request`` — create a payment request (invoice) from inside a session:
+  amount (ceiling-bounded), purpose, optional payer hint, expiry. Outward-facing
+  money: default-OFF flag, per-day cap, first-class ``payment_requested`` event,
+  and listed in the recommended approval set (operators add ``x402_request`` to
+  ``APPROVAL_REQUIRED_TOOLS``; at compute posture ≥2 it is auto-gated).
+- ``x402_invoices`` — list this tenant's invoices (read-only).
+- ``accounting`` — the unified ledger view (earned / spent / pending, evidence
+  from usage_records + wallet_spend events + x402 receipts). Read-only.
+
+Server-tier stores (``modules.x402``/``modules.credits``) are imported lazily at
+action time so the core agent import graph stays server-free (C3 boundary).
+"""
+from __future__ import annotations  # safe: @BaseTool.action uses explicit param_model
+
+import logging
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from tools.base_tool import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class InvoiceParams(BaseModel):
+    amount_usd: float = Field(..., gt=0, description="Invoice amount in USD (bounded by X402_INVOICE_MAX_USD)")
+    purpose: str = Field(..., min_length=3, description="What the payer is paying for (shown to them and audited)")
+    payer_hint: Optional[str] = Field(None, description="Optional payer identity/contact hint for your own records")
+    expiry_hours: float = Field(72.0, gt=0, le=24 * 30, description="Hours until the request expires (default 72)")
+    payer_surface: Optional[str] = Field(
+        None, description="If invoicing a correspondent you already contacted, their surface "
+                          "(e.g. 'email'/'telegram'); settlement is delivered to you as DATA, not a command")
+    payer_address: Optional[str] = Field(
+        None, description="The correspondent payer's address/handle on that surface (pairs with payer_surface)")
+
+
+class InvoiceListParams(BaseModel):
+    status: Optional[str] = Field(None, description="Filter: pending|completed|expired (default all)")
+
+
+class AccountingParams(BaseModel):
+    days: int = Field(7, ge=1, le=365, description="Trailing window in days (default 7)")
+
+
+def _ctx_ids(execution_context) -> tuple:
+    user_id = getattr(execution_context, "user_id", "") or ""
+    session_id = getattr(execution_context, "session_id", "") or ""
+    return user_id, session_id
+
+
+_ANON_REFUSED = ("this action requires an authenticated tenant — the execution "
+                 "context has no user_id (anonymous financial state is refused)")
+
+
+class X402InvoiceTool(BaseTool):
+    def __init__(self, name: str = "x402_invoice", config=None, container=None):
+        import types
+        super().__init__(name=name,
+                         config=config if config is not None else types.SimpleNamespace(),
+                         container=container)
+
+    def _ar(self, *, content: str = None, error: str = None):
+        from tools.controller.types import ActionResult
+        if error is not None:
+            return ActionResult(error=error)
+        return ActionResult(extracted_content=content)
+
+    @BaseTool.action(
+        "Create an x402 payment request (invoice): amount, purpose, expiry. "
+        "Returns payment instructions the payer needs (recipient/chain/amount/id).",
+        param_model=InvoiceParams)
+    async def x402_request(self, params: InvoiceParams, execution_context=None):
+        user_id, session_id = _ctx_ids(execution_context)
+        if not user_id:
+            return self._ar(error=f"x402_request refused: {_ANON_REFUSED}")
+        try:
+            from modules.x402.invoicing import create_payment_request
+            correspondent_ref = None
+            if params.payer_surface and params.payer_address:
+                correspondent_ref = {"surface": params.payer_surface,
+                                     "address": params.payer_address, "thread_id": ""}
+            inv = await create_payment_request(
+                user_id=user_id, session_id=session_id,
+                amount_usd=params.amount_usd, purpose=params.purpose,
+                payer_hint=params.payer_hint, expiry_hours=params.expiry_hours,
+                correspondent_ref=correspondent_ref,
+            )
+        except ValueError as e:
+            return self._ar(error=f"x402_request refused: {e}")
+        except Exception as e:
+            logger.error("x402_request failed: %s", e, exc_info=True)
+            return self._ar(error=f"x402_request failed: {e}")
+        return self._ar(content=(
+            f"Payment request created.\n"
+            f"  request_id: {inv['request_id']}\n"
+            f"  amount: ${inv['amount_usd']:.2f} {inv['asset'].upper()} on {inv['chain']}\n"
+            f"  pay to: {inv['recipient']}\n"
+            f"  purpose: {inv['purpose']}\n"
+            f"  expires: epoch {inv['expires_at_epoch']}\n"
+            "Share these instructions with the payer (e.g. via the message tool). "
+            "You will be woken in this session when it settles."
+        ))
+
+    @BaseTool.action("List your x402 payment requests (invoices) and their status",
+                     param_model=InvoiceListParams)
+    async def x402_invoices(self, params: InvoiceListParams, execution_context=None):
+        user_id, _ = _ctx_ids(execution_context)
+        if not user_id:
+            return self._ar(error=f"x402_invoices refused: {_ANON_REFUSED}")
+        try:
+            from modules.x402.invoicing import list_payment_requests
+            rows = await list_payment_requests(user_id=user_id, status=params.status)
+        except Exception as e:
+            return self._ar(error=f"x402_invoices failed: {e}")
+        if not rows:
+            return self._ar(content="No payment requests found.")
+        lines = ["Payment requests (newest first):"]
+        for r in rows:
+            lines.append(
+                f"  {r['request_id']}: ${float(r['amount_usd'] or 0):.2f} "
+                f"[{r['status']}] — {r.get('purpose') or '(no purpose)'} "
+                f"(created {r.get('created_at')})")
+        return self._ar(content="\n".join(lines))
+
+    @BaseTool.action(
+        "Your unified financial ledger: earned / pending / spent (LLM + wallet) "
+        "over a trailing window. Read-only, evidence-backed.",
+        param_model=AccountingParams)
+    async def accounting(self, params: AccountingParams, execution_context=None):
+        user_id, _ = _ctx_ids(execution_context)
+        if not user_id:
+            return self._ar(error=f"accounting refused: {_ANON_REFUSED}")
+        try:
+            from modules.credits.unified_ledger import build_ledger, format_ledger
+            ledger = await build_ledger(user_id, days=params.days)
+            return self._ar(content=format_ledger(ledger))
+        except Exception as e:
+            logger.error("accounting failed: %s", e, exc_info=True)
+            return self._ar(error=f"accounting failed: {e}")