bitcoinstratigraphy-agent-yield 0.1.0__tar.gz

bitcoinstratigraphy_agent_yield-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# See https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files for more about ignoring files.
+
+# compiled output
+dist
+tmp
+out-tsc
+*.tsbuildinfo
+.expo
+.expo-shared
+
+# dependencies
+node_modules
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# misc
+/.sass-cache
+/connect.lock
+/coverage
+/libpeerconnection.log
+npm-debug.log
+yarn-error.log
+testem.log
+/typings
+
+# System Files
+.DS_Store
+Thumbs.db
+
+.cursor/rules/nx-rules.mdc
+.github/instructions/nx.instructions.md
+
+# Replit
+.cache/
+.local/
+.data/
+
+# Private enterprise audit evidence; never commit trace data.
+**/.agent-yield-state/
+/audit_trail.jsonl
+/audit_trail.jsonl.*
+
+# Enterprise SDK build output and Python bytecode.
+/sdk/python/build/
+/sdk/python/*.egg-info/
+__pycache__/
+*.pyc
+
+# Runtime provenance archives and generated verification artifacts.
+/generated-artifacts/
+
+# Private tool-integrity signing keys (standalone deployments only).
+**/.keys/

bitcoinstratigraphy_agent_yield-0.1.0/LICENSE.md

@@ -0,0 +1,12 @@
+Copyright (c) 2026 Charles R. Strogish. All Rights Reserved.
+
+This software is dual-licensed under GNU AGPL version 3 only
+(SPDX: AGPL-3.0-only), or a separately executed Commercial License from
+Charles R. Strogish (SPDX: LicenseRef-Commercial).
+
+The AGPLv3 text is available at https://www.gnu.org/licenses/agpl-3.0.html.
+The repository's LICENSE.md contains the full license text and licensing rider:
+https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp/blob/main/LICENSE.md
+
+This notice does not grant commercial licensing rights. AGPLv3 permits
+commercial use when its conditions are met.

bitcoinstratigraphy_agent_yield-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: bitcoinstratigraphy-agent-yield
+Version: 0.1.0
+Summary: One-call MCP discovery, budgeted L402 settlement and fiduciary tools for Python agents.
+Project-URL: Homepage, https://bitcoinstratigraphy.com
+Project-URL: Repository, https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp
+License-Expression: AGPL-3.0-only OR LicenseRef-Commercial
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: bech32==1.2.0
+Requires-Dist: coincurve==21.0.0
+Requires-Dist: httpx==0.28.1
+Provides-Extra: test
+Requires-Dist: pytest==9.2.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# bitcoinstratigraphy-agent-yield
+
+One-call Python onboarding for Bitcoin Stratigraphy MCP tools: HTTPX discovery,
+automatic bounded L402 retries, durable spending reservations, and the same
+stderr terminal receipts as `@bitcoinstratigraphy/agent-yield`.
+
+Install from PyPI:
+
+```sh
+pip install bitcoinstratigraphy-agent-yield
+```
+
+For local development, install from this checkout:
+
+```sh
+pip install ./packages/python-agent-yield
+```
+
+## Two-line quick starts
+
+Start with your existing `agent_config`. Its `fiduciary` policy is the explicit
+wallet authorization shown below. No wallet is created, connected or funded
+by installing or importing this package.
+
+### LangChain
+
+```python
+from bitcoinstratigraphy_agent_yield import with_fiduciary_yield
+
+agent = with_fiduciary_yield({**agent_config, "framework": "langchain"})
+```
+
+Pass `agent["tools"]` to `langchain.agents.create_agent(model=..., tools=...)`.
+Existing tools are preserved; discovered tools are native `StructuredTool`s
+with sync `.invoke()` and async `.ainvoke()`.
+
+### CrewAI
+
+```python
+from bitcoinstratigraphy_agent_yield import with_fiduciary_yield
+
+agent = with_fiduciary_yield({**agent_config, "framework": "crewai"})
+```
+
+Pass `agent["tools"]` to `crewai.Agent(role=..., goal=..., backstory=..., tools=...)`.
+They are native CrewAI `BaseTool`s. You can also wrap an existing public-tools
+CrewAI agent with `with_fiduciary_yield(existing_agent, fiduciary=policy)`;
+this returns a copy, never mutating the original agent.
+
+### AutoGen
+
+```python
+from bitcoinstratigraphy_agent_yield import with_fiduciary_yield
+
+agent = with_fiduciary_yield({**agent_config, "framework": "autogen"})
+```
+
+Pass `agent["tools"]` to `autogen_agentchat.agents.AssistantAgent(..., tools=...)`.
+These are native `autogen_core.tools.BaseTool`s, not OpenAI descriptors requiring
+a separate dispatcher. Cancellation is checked before starting execution.
+
+Framework imports are lazy. Install your chosen framework separately; the base
+wheel has **only three direct runtime dependencies**, all exactly pinned:
+HTTPX, bech32 and coincurve. No LangChain, CrewAI, AutoGen, NWC or MCP framework
+is forced on other consumers. Native adapters target the current public
+LangChain Core 1.x, CrewAI 1.x and AutoGen Core 0.7 APIs.
+
+## Explicit wallet and spending policy
+
+```python
+policy = {
+    "wallet": authorized_wallet,
+    "max_payment_sats": 500,
+    "max_total_sats": 5000,
+    "fee_reserve_sats": 10,
+    "state_directory": ".agent-yield-state",
+}
+agent_config = {"tools": existing_tools, "fiduciary": policy}
+```
+
+`authorized_wallet.pay_invoice(bolt11)` is a **synchronous** wallet adapter
+returning `{"preimage": "<64 hex characters>", "fees_paid": 0}`.
+`fees_paid` is optional integer millisatoshis. Use your wallet provider's
+authorized SDK inside the adapter; secrets never belong in prompts, source,
+HTTP headers, terminal receipts, or tool arguments. This scaffold does **not**
+implement NWC wallet transport.
+
+Without a wallet and explicit positive budgets, discovery and free tools work;
+paid execution fails closed. Optional `make_invoice(amount_msats)` returns
+`{"invoice": "<receiving BOLT11>"}` to enable automatic yield withdrawals.
+Wallet adapters must enforce their own operation timeouts and fee ceiling:
+Python cannot cancel an external payment already submitted to a wallet.
+
+`agent["fiduciary"]` exposes `.list_tools()`, `.call_tool(name, arguments)`,
+`await .acall_tool(name, arguments)`, `.recover_claim(payment_hash)`, and
+`.close()`. Framework tools are added to a configuration before constructing a
+graph/AssistantAgent; this does not retrofit private internals of running agents.
+Async execution offloads synchronous HTTP/wallet work to a worker thread.
+Cancelling the awaiting task does not reverse an in-progress wallet operation.
+Close the config's client at application shutdown. For public-tools object
+wrapping, supply an application-owned `http_client` and close it yourself.
+
+## Connection and payment guarantees
+
+- Discovers the live paginated catalog at `https://bitcoinstratigraphy.com/mcp`.
+  Handles MCP `2026-07-28`, JSON and SSE, bounded response sizes, timeout and
+  one bounded Hashcash admission retry. Discovery never pays a wallet.
+- Validates mainnet BOLT11 checksum, recoverable signature, explicit payee,
+  amount, expiry and payment hash against the HTTP JSON quote before spending.
+- Reserves invoice principal plus fee allowance in private SQLite storage
+  **before** contacting the wallet. Per-invoice and cumulative limits are
+  integer satoshis. Reservations survive threads, processes and restarts.
+  Reported excessive/invalid fees block future new payments.
+- Verifies every preimage against its invoice hash, then retries the identical
+  MCP body/ID exactly once with `Authorization: L402 macaroon:preimage`.
+  Credentials are bound to the exact invoice/request, not globally reused
+  across unrelated tools. A repeated 402 never triggers a second payment.
+- Never follows redirects or replaces caller-supplied payment credentials.
+  Supply `identity_headers(url, method, body_bytes)` for fresh NIP-98 headers;
+  it runs again for admission and paid retries. Valid Genesis Grant calls incur
+  no payment, paid-history credit, yield allocation or earned receipt.
+- Unknown payments and invalid returned proofs stay reserved. **Do not delete
+  the state directory or change directories to retry a payment.** Operators
+  must establish the payment outcome before recovery. Use private persistent
+  storage, exclude it from Git, and use one directory per wallet and policy.
+
+The SQLite ledger contains sensitive payment proofs, though never wallet keys.
+The folder is created with mode 0700 and the database with 0600. Protect and
+back up this directory. Existing directories must already be private.
+This is client-side accounting, not a replacement for server-side settlement
+ledgers or a wallet-enforced spending limit.
+
+## Terminal receipts
+
+On a successful paid execution with a receiving wallet:
+
+```text
+[Bitcoin Stratigraphy] ⚡ Thermodynamic Yield Allocated: 21 Sats (settlement pending).
+[Bitcoin Stratigraphy] ⚡ Thermodynamic Yield Earned: 21 Sats routed to agent wallet.
+```
+
+Allocated is yellow; earned is green. An earned receipt appears **only** after
+the claim API confirms `SETTLED` **and** `payment_sent: true`, never on
+allocation, free grants, pending claims, failed tools or failed payouts.
+Millisatoshi precision is preserved. Logging goes exclusively to `sys.stderr`
+to preserve MCP JSON-RPC stdout. `QUIET_STRATIGRAPHY=true` disables receipts at
+event time; logging failures never change successful tool results.
+
+Claims are best effort, not guaranteed income. `on_error({"code": ...})`
+reports recovery needs without exposing wallet/server error text.
+`on_yield_claim({"status": ..., "amount_msats": ...})` observes claim status.
+`.recover_claim(payment_hash)` replays only a persisted withdrawal request and
+never buys a new tool invoice. Recovery after a crash during receiving-invoice
+creation needs operator intervention; it does not create a second invoice.
+Claims run synchronously after paid execution, bounded by the HTTP timeout.
+
+## Development / packaging (no publication)
+
+From the repository root, using its Python environment:
+
+```sh
+uv run --no-sync python -m pytest packages/python-agent-yield
+cd packages/python-agent-yield
+uv run --no-sync python -m hatchling build -d ../../generated-artifacts/python-agent-yield
+```
+
+Or install `.[test]` inside this package, then run `python -m pytest`.
+The dedicated tests use signed synthetic invoices, `httpx.MockTransport`,
+temporary state, and fake wallets. They do not contact mainnet or move funds.
+Native LangChain/AutoGen integration tests run when those frameworks are
+installed; the CrewAI adapter has a public-API contract fixture without pulling
+CrewAI's full dependency tree into this standalone package.
+Wheel/sdist build output belongs in `generated-artifacts/`, never source control.
+Building never uploads to PyPI; publication is an explicit release step.

bitcoinstratigraphy_agent_yield-0.1.0/README.md

@@ -0,0 +1,174 @@
+# bitcoinstratigraphy-agent-yield
+
+One-call Python onboarding for Bitcoin Stratigraphy MCP tools: HTTPX discovery,
+automatic bounded L402 retries, durable spending reservations, and the same
+stderr terminal receipts as `@bitcoinstratigraphy/agent-yield`.
+
+Install from PyPI:
+
+```sh
+pip install bitcoinstratigraphy-agent-yield
+```
+
+For local development, install from this checkout:
+
+```sh
+pip install ./packages/python-agent-yield
+```
+
+## Two-line quick starts
+
+Start with your existing `agent_config`. Its `fiduciary` policy is the explicit
+wallet authorization shown below. No wallet is created, connected or funded
+by installing or importing this package.
+
+### LangChain
+
+```python
+from bitcoinstratigraphy_agent_yield import with_fiduciary_yield
+
+agent = with_fiduciary_yield({**agent_config, "framework": "langchain"})
+```
+
+Pass `agent["tools"]` to `langchain.agents.create_agent(model=..., tools=...)`.
+Existing tools are preserved; discovered tools are native `StructuredTool`s
+with sync `.invoke()` and async `.ainvoke()`.
+
+### CrewAI
+
+```python
+from bitcoinstratigraphy_agent_yield import with_fiduciary_yield
+
+agent = with_fiduciary_yield({**agent_config, "framework": "crewai"})
+```
+
+Pass `agent["tools"]` to `crewai.Agent(role=..., goal=..., backstory=..., tools=...)`.
+They are native CrewAI `BaseTool`s. You can also wrap an existing public-tools
+CrewAI agent with `with_fiduciary_yield(existing_agent, fiduciary=policy)`;
+this returns a copy, never mutating the original agent.
+
+### AutoGen
+
+```python
+from bitcoinstratigraphy_agent_yield import with_fiduciary_yield
+
+agent = with_fiduciary_yield({**agent_config, "framework": "autogen"})
+```
+
+Pass `agent["tools"]` to `autogen_agentchat.agents.AssistantAgent(..., tools=...)`.
+These are native `autogen_core.tools.BaseTool`s, not OpenAI descriptors requiring
+a separate dispatcher. Cancellation is checked before starting execution.
+
+Framework imports are lazy. Install your chosen framework separately; the base
+wheel has **only three direct runtime dependencies**, all exactly pinned:
+HTTPX, bech32 and coincurve. No LangChain, CrewAI, AutoGen, NWC or MCP framework
+is forced on other consumers. Native adapters target the current public
+LangChain Core 1.x, CrewAI 1.x and AutoGen Core 0.7 APIs.
+
+## Explicit wallet and spending policy
+
+```python
+policy = {
+    "wallet": authorized_wallet,
+    "max_payment_sats": 500,
+    "max_total_sats": 5000,
+    "fee_reserve_sats": 10,
+    "state_directory": ".agent-yield-state",
+}
+agent_config = {"tools": existing_tools, "fiduciary": policy}
+```
+
+`authorized_wallet.pay_invoice(bolt11)` is a **synchronous** wallet adapter
+returning `{"preimage": "<64 hex characters>", "fees_paid": 0}`.
+`fees_paid` is optional integer millisatoshis. Use your wallet provider's
+authorized SDK inside the adapter; secrets never belong in prompts, source,
+HTTP headers, terminal receipts, or tool arguments. This scaffold does **not**
+implement NWC wallet transport.
+
+Without a wallet and explicit positive budgets, discovery and free tools work;
+paid execution fails closed. Optional `make_invoice(amount_msats)` returns
+`{"invoice": "<receiving BOLT11>"}` to enable automatic yield withdrawals.
+Wallet adapters must enforce their own operation timeouts and fee ceiling:
+Python cannot cancel an external payment already submitted to a wallet.
+
+`agent["fiduciary"]` exposes `.list_tools()`, `.call_tool(name, arguments)`,
+`await .acall_tool(name, arguments)`, `.recover_claim(payment_hash)`, and
+`.close()`. Framework tools are added to a configuration before constructing a
+graph/AssistantAgent; this does not retrofit private internals of running agents.
+Async execution offloads synchronous HTTP/wallet work to a worker thread.
+Cancelling the awaiting task does not reverse an in-progress wallet operation.
+Close the config's client at application shutdown. For public-tools object
+wrapping, supply an application-owned `http_client` and close it yourself.
+
+## Connection and payment guarantees
+
+- Discovers the live paginated catalog at `https://bitcoinstratigraphy.com/mcp`.
+  Handles MCP `2026-07-28`, JSON and SSE, bounded response sizes, timeout and
+  one bounded Hashcash admission retry. Discovery never pays a wallet.
+- Validates mainnet BOLT11 checksum, recoverable signature, explicit payee,
+  amount, expiry and payment hash against the HTTP JSON quote before spending.
+- Reserves invoice principal plus fee allowance in private SQLite storage
+  **before** contacting the wallet. Per-invoice and cumulative limits are
+  integer satoshis. Reservations survive threads, processes and restarts.
+  Reported excessive/invalid fees block future new payments.
+- Verifies every preimage against its invoice hash, then retries the identical
+  MCP body/ID exactly once with `Authorization: L402 macaroon:preimage`.
+  Credentials are bound to the exact invoice/request, not globally reused
+  across unrelated tools. A repeated 402 never triggers a second payment.
+- Never follows redirects or replaces caller-supplied payment credentials.
+  Supply `identity_headers(url, method, body_bytes)` for fresh NIP-98 headers;
+  it runs again for admission and paid retries. Valid Genesis Grant calls incur
+  no payment, paid-history credit, yield allocation or earned receipt.
+- Unknown payments and invalid returned proofs stay reserved. **Do not delete
+  the state directory or change directories to retry a payment.** Operators
+  must establish the payment outcome before recovery. Use private persistent
+  storage, exclude it from Git, and use one directory per wallet and policy.
+
+The SQLite ledger contains sensitive payment proofs, though never wallet keys.
+The folder is created with mode 0700 and the database with 0600. Protect and
+back up this directory. Existing directories must already be private.
+This is client-side accounting, not a replacement for server-side settlement
+ledgers or a wallet-enforced spending limit.
+
+## Terminal receipts
+
+On a successful paid execution with a receiving wallet:
+
+```text
+[Bitcoin Stratigraphy] ⚡ Thermodynamic Yield Allocated: 21 Sats (settlement pending).
+[Bitcoin Stratigraphy] ⚡ Thermodynamic Yield Earned: 21 Sats routed to agent wallet.
+```
+
+Allocated is yellow; earned is green. An earned receipt appears **only** after
+the claim API confirms `SETTLED` **and** `payment_sent: true`, never on
+allocation, free grants, pending claims, failed tools or failed payouts.
+Millisatoshi precision is preserved. Logging goes exclusively to `sys.stderr`
+to preserve MCP JSON-RPC stdout. `QUIET_STRATIGRAPHY=true` disables receipts at
+event time; logging failures never change successful tool results.
+
+Claims are best effort, not guaranteed income. `on_error({"code": ...})`
+reports recovery needs without exposing wallet/server error text.
+`on_yield_claim({"status": ..., "amount_msats": ...})` observes claim status.
+`.recover_claim(payment_hash)` replays only a persisted withdrawal request and
+never buys a new tool invoice. Recovery after a crash during receiving-invoice
+creation needs operator intervention; it does not create a second invoice.
+Claims run synchronously after paid execution, bounded by the HTTP timeout.
+
+## Development / packaging (no publication)
+
+From the repository root, using its Python environment:
+
+```sh
+uv run --no-sync python -m pytest packages/python-agent-yield
+cd packages/python-agent-yield
+uv run --no-sync python -m hatchling build -d ../../generated-artifacts/python-agent-yield
+```
+
+Or install `.[test]` inside this package, then run `python -m pytest`.
+The dedicated tests use signed synthetic invoices, `httpx.MockTransport`,
+temporary state, and fake wallets. They do not contact mainnet or move funds.
+Native LangChain/AutoGen integration tests run when those frameworks are
+installed; the CrewAI adapter has a public-API contract fixture without pulling
+CrewAI's full dependency tree into this standalone package.
+Wheel/sdist build output belongs in `generated-artifacts/`, never source control.
+Building never uploads to PyPI; publication is an explicit release step.

bitcoinstratigraphy_agent_yield-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bitcoinstratigraphy-agent-yield"
+version = "0.1.0"
+description = "One-call MCP discovery, budgeted L402 settlement and fiduciary tools for Python agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "AGPL-3.0-only OR LicenseRef-Commercial"
+license-files = ["LICENSE.md"]
+dependencies = ["httpx==0.28.1", "bech32==1.2.0", "coincurve==21.0.0"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+test = ["pytest==9.2.0"]
+
+[project.urls]
+Homepage = "https://bitcoinstratigraphy.com"
+Repository = "https://github.com/CharlesStrogish/bitcoin-stratigraphy-mcp"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bitcoinstratigraphy_agent_yield"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE.md", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra"

bitcoinstratigraphy_agent_yield-0.1.0/src/bitcoinstratigraphy_agent_yield/__init__.py

@@ -0,0 +1,14 @@
+"""Frictionless, explicitly budgeted Bitcoin Stratigraphy tools for Python agents."""
+
+from .adapters import AgentTool, with_fiduciary_yield
+from .client import DEFAULT_MCP_URL, FiduciaryClient
+from .errors import FiduciaryError
+
+__all__ = [
+    "AgentTool",
+    "DEFAULT_MCP_URL",
+    "FiduciaryClient",
+    "FiduciaryError",
+    "with_fiduciary_yield",
+]
+__version__ = "0.1.0"

bitcoinstratigraphy_agent_yield-0.1.0/src/bitcoinstratigraphy_agent_yield/adapters.py

@@ -0,0 +1,172 @@
+"""Lazy, native framework adapters. No framework dependencies in the base wheel."""
+
+import copy
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .client import FiduciaryClient
+from .errors import FiduciaryError
+
+
+@dataclass(frozen=True)
+class AgentTool:
+    name: str
+    canonical_name: str
+    description: str
+    input_schema: dict
+    client: FiduciaryClient
+
+    def invoke(self, arguments=None, **kwargs):
+        return self.client.call_tool(
+            self.canonical_name, arguments if arguments is not None else kwargs
+        )
+
+    async def ainvoke(self, arguments=None, **kwargs):
+        return await self.client.acall_tool(
+            self.canonical_name, arguments if arguments is not None else kwargs
+        )
+
+
+def _argument_model(tool):
+    from pydantic import ConfigDict, create_model
+
+    # Forward the original JSON Schema to the model provider without flattening
+    # enums, nested objects, unions, or refs. MCP remains the authoritative
+    # validator; framework-side parsing must not coerce or drop arguments.
+    schema = copy.deepcopy(tool.input_schema)
+    required = schema.get("required", [])
+    fields = {
+        name: (Any, ... if name in required else None)
+        for name in schema.get("properties", {})
+    }
+    model = create_model(
+        f"{tool.name}_Args", __config__=ConfigDict(extra="allow"), **fields
+    )
+    model.model_json_schema = classmethod(
+        lambda cls, *args, **kwargs: copy.deepcopy(schema)
+    )
+    return model
+
+
+def _langchain(tool):
+    from langchain_core.tools import StructuredTool
+
+    return StructuredTool.from_function(
+        func=lambda **kwargs: tool.invoke(kwargs),
+        coroutine=lambda **kwargs: tool.ainvoke(kwargs),
+        name=tool.name,
+        description=tool.description,
+        args_schema=copy.deepcopy(tool.input_schema),
+        infer_schema=False,
+    )
+
+
+def _crewai(tool):
+    from crewai.tools import BaseTool
+
+    class FiduciaryCrewTool(BaseTool):
+        def _run(self, **kwargs):
+            return tool.invoke(kwargs)
+
+        async def _arun(self, **kwargs):
+            return await tool.ainvoke(kwargs)
+
+    return FiduciaryCrewTool(
+        name=tool.name, description=tool.description, args_schema=_argument_model(tool)
+    )
+
+
+def _autogen(tool):
+    from autogen_core.tools import BaseTool
+
+    class FiduciaryAutoGenTool(BaseTool):
+        def __init__(self):
+            super().__init__(_argument_model(tool), object, tool.name, tool.description)
+
+        @property
+        def schema(self):
+            return {
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": copy.deepcopy(tool.input_schema),
+            }
+
+        async def run(self, args, cancellation_token):
+            if cancellation_token.is_cancelled():
+                raise FiduciaryError("MCP_REQUEST_CANCELLED")
+            return await tool.ainvoke(args.model_dump(exclude_unset=True))
+
+    return FiduciaryAutoGenTool()
+
+
+def with_fiduciary_yield(agent, *, fiduciary=None, framework=None):
+    """Copy an agent config or a public-tools agent, discover, and append tools.
+
+    Configs return a dict with a ``fiduciary`` client for lifetime management.
+    Public-tools/Pydantic agents return a model_copy; their original is untouched.
+    Already-built graph/private-internals agents must be wrapped at config time.
+    """
+    is_config = isinstance(agent, Mapping)
+    if is_config:
+        options = fiduciary if fiduciary is not None else agent.get("fiduciary", {})
+        selected = framework or agent.get("framework", "custom")
+        existing = list(agent.get("tools", []))
+    else:
+        if not callable(getattr(agent, "model_copy", None)) or not hasattr(
+            agent, "tools"
+        ):
+            raise FiduciaryError("WRAP_AGENT_CONFIGURATION_NOT_PRIVATE_INTERNALS")
+        if fiduciary is None:
+            raise FiduciaryError("FIDUCIARY_CONFIGURATION_REQUIRED")
+        options = fiduciary
+        selected = framework or (
+            "crewai" if type(agent).__module__.startswith("crewai") else "custom"
+        )
+        existing = list(agent.tools or [])
+    if selected not in ("custom", "langchain", "crewai", "autogen"):
+        raise FiduciaryError("UNSUPPORTED_FRAMEWORK")
+    if not isinstance(options, Mapping):
+        raise FiduciaryError("FIDUCIARY_CONFIGURATION_REQUIRED")
+    client = FiduciaryClient(**options)
+    try:
+        tools = []
+        for index, entry in enumerate(client.list_tools()):
+            safe = f"fiduciary_{index}_{re.sub(r'[^a-zA-Z0-9_-]', '_', entry['name'])}"[
+                :64
+            ]
+            if any(
+                (
+                    item.get("name")
+                    if isinstance(item, dict)
+                    else getattr(item, "name", None)
+                )
+                == safe
+                for item in existing
+            ):
+                raise FiduciaryError("MCP_TOOL_NAME_COLLISION")
+            tool = AgentTool(
+                safe,
+                entry["name"],
+                entry.get("description") or entry["name"],
+                copy.deepcopy(entry["inputSchema"]),
+                client,
+            )
+            adapter = {
+                "langchain": _langchain,
+                "crewai": _crewai,
+                "autogen": _autogen,
+            }.get(selected)
+            tools.append(adapter(tool) if adapter else tool)
+        if is_config:
+            return {**agent, "tools": existing + tools, "fiduciary": client}
+        # CrewAI agents expose public tools but do not accept arbitrary client
+        # fields. Tool closures retain the client; no global monkeypatching.
+        return agent.model_copy(update={"tools": existing + tools})
+    except ImportError:
+        client.close()
+        raise FiduciaryError(f"INSTALL_{selected.upper()}_FOR_NATIVE_ADAPTER") from None
+    except BaseException:
+        client.close()
+        raise