agentbyte 0.45.0__tar.gz → 0.47.0__tar.gz

{agentbyte-0.45.0 → agentbyte-0.47.0}/.gitignore

@@ -72,6 +72,9 @@ data/flatfiles/*
 *.sqlite-shm
 *.writer.lock
 
+# Per-project runtime state (eval history, checkpoints) written by agentbyte
+.agentbyte/
+
 # Optimization reports written by notebooks (report.md, report.json, trace.json)
 optim-reports/
 

{agentbyte-0.45.0 → agentbyte-0.47.0}/CHANGELOG.md

@@ -6,6 +6,51 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [0.47.0] - 2026-10-06
+
+### Added
+
+- MCP tool bridge (spec 0013, `mcp` extra): `agentbyte.tools.mcp` with `MCPClientManager`, `MCPTool`
+  and `create_mcp_tools()` over the official MCP SDK (v2).
+- WebUI MCP Playground: connect to MCP servers, browse capabilities and tools, call tools, read app
+  resources, and answer pending inputs from the Playground. It is off by default
+  (`AgentbyteWebUIServer(mcp_playground=True)`) because it can launch subprocesses and make outbound
+  connections on request.
+- A2A 1.0 adapters (spec 0013, `a2a` extra): `AgentByteExecutor`, `create_a2a_app`,
+  `agent_card_from_agent` to serve an agent, and `A2ATool` to call one, as thin adapters over the
+  official `a2a-sdk` 1.x. Human approval maps to `input-required` and resumes on the same task.
+- `agentbyte serve`: a localhost-only development command for serving an agent over A2A.
+- `DistributedContextManager` and two `examples/distributed/` patterns.
+
+### Changed
+
+- Local SQLite state now lives under `.agentbyte/` instead of the working-directory root. The default
+  evaluation history is `.agentbyte/eval/default/eval.sqlite` (was `./eval.sqlite`) for
+  `agentbyte eval`, `agentbyte optim` and `agentbyte webui --eval-catalog`, and examples and notebooks use
+  one folder per project (`.agentbyte/eval/<project>/eval.sqlite` with its `.writer.lock` beside it).
+  `SQLiteEvalRunStore` (writers) and `SQLiteCheckpointStore` create the parent directories on open.
+  Explicit paths, `--history PATH` and `:memory:` behave as before. Existing history files are not moved
+  automatically: pass `--history` or move them into the new folder.
+
+### Removed
+
+- **Breaking:** the hand-written A2A 0.3 client, server, models and errors (`agentbyte.a2a` from the
+  unreleased 0.6.0/0.7.0 development phases) are gone, with no 0.3 compatibility. Use the A2A 1.0
+  adapters above; authentication is left to host Starlette middleware or SDK interceptors.
+
+## [0.46.0] - 2026-10-05
+
+### Added
+
+- Evaluation UI: read-only optimization pages (spec 0068 phase 3). The Evaluations home page lists
+  stored optimization runs (suite, optimizer, seed → best, cost); `#/evals/optimizations/<id>`
+  renders the report — proposed changes as seed/best text, per-task outcomes, remaining failures
+  with the judge's reasoning, reflector diagnoses and edits, candidates, cost — with Copy markdown
+  and Download report.md.
+- `GET /api/eval/optimizations?suite=` and `GET /api/eval/optimizations/{id}` (`{run, report,
+  markdown}`). They read the history store directly, so runs recorded for suites outside the
+  server's catalog (e.g. notebook suites) are shown.
+
 ## [0.45.0] - 2026-10-05
 
 ### Added

{agentbyte-0.45.0 → agentbyte-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.45.0
+Version: 0.47.0
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -10,6 +10,10 @@ Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic-settings>=2.13.0
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: a2a
+Requires-Dist: a2a-sdk[http-server]<2,>=1.2; extra == 'a2a'
+Requires-Dist: fastapi>=0.135.2; extra == 'a2a'
+Requires-Dist: uvicorn[standard]>=0.44.0; extra == 'a2a'
 Provides-Extra: all
 Requires-Dist: aioboto3>=15.5.0; extra == 'all'
 Requires-Dist: aiosqlite>=0.22.1; extra == 'all'
@@ -40,6 +44,8 @@ Provides-Extra: gunicorn
 Requires-Dist: fastapi>=0.135.2; extra == 'gunicorn'
 Requires-Dist: gunicorn>=23.0.0; extra == 'gunicorn'
 Requires-Dist: uvicorn[standard]>=0.44.0; extra == 'gunicorn'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0.0; extra == 'mcp'
 Provides-Extra: openai
 Requires-Dist: openai>=1.107.1; extra == 'openai'
 Provides-Extra: optim
@@ -77,7 +83,7 @@ Description-Content-Type: text/markdown
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.45.0**
+Current release: **0.47.0**
 
 ## Building an Agent
 
@@ -318,10 +324,17 @@ uv add "agentbyte[openai,sqlite]"
 | `optim` | `gepa` | `optimize_with_gepa()` |
 | `viz` | `graphviz` | `WorkflowVisualizer.to_dot()` |
 | `research` | `beautifulsoup4`, `html2text`, `arxiv`, `youtube-transcript-api` | `agentbyte.tools.research_tools` |
-| `all` | every extra above | Everything |
+| `mcp` | `mcp` (SDK v2) | `agentbyte.tools.mcp`: MCP tool bridge (`MCPClientManager`, `MCPTool`, `create_mcp_tools()`); also enables the WebUI MCP Playground routes |
+| `a2a` | `a2a-sdk[http-server]` 1.x, `agentbyte[webui]` | `agentbyte.a2a`: A2A 1.0 adapters on the official SDK — `create_a2a_app` / `AgentByteExecutor` to serve an agent, `A2ATool` to call one, `agentbyte serve` for local dev |
+| `all` | every extra above except `mcp`/`a2a`* | Everything except the MCP/A2A protocol bridges |
+
+*`mcp` and `a2a` are deliberately excluded from `all`: both let an agent reach outside the
+process (subprocess tools, outbound HTTP to arbitrary agents) and are opt-in rather than
+bundled by default. Install them explicitly: `pip install "agentbyte[mcp,a2a]"`.
 
 Contributors working in this repository install every extra plus the local tooling groups
-(`test`, `dev`, `experiment`):
+(`test`, `dev`, `experiment`) — this always includes `mcp`/`a2a` regardless of the `all`
+composite above, since `--all-extras` syncs every defined extra individually:
 
 ```bash
 uv sync --all-extras --all-groups
@@ -342,7 +355,7 @@ No API key needed: three demo agents, a team and a workflow on a fake model clie
 
 ```bash
 uv run python examples/webui/in_memory.py                          # http://127.0.0.1:8070
-uv run python examples/webui/in_memory.py --eval-history eval.sqlite   # plus Evaluations
+uv run python examples/webui/in_memory.py --eval-history .agentbyte/eval/default/eval.sqlite   # plus Evaluations
 ```
 
 With your OpenAI or Azure OpenAI credentials, the preset agents, teams and workflow:
@@ -350,7 +363,7 @@ With your OpenAI or Azure OpenAI credentials, the preset agents, teams and workf
 ```bash
 uv sync --extra webui --extra openai        # or --extra azureopenai
 uv run python examples/webui/presets_webui.py                      # http://127.0.0.1:8080
-uv run python examples/webui/presets_webui.py --eval-history eval.sqlite
+uv run python examples/webui/presets_webui.py --eval-history .agentbyte/eval/default/eval.sqlite
 ```
 
 Both launchers accept `--port`, `--no-open`, `--eval-history PATH` and `--eval-catalog CATALOG`
@@ -368,7 +381,7 @@ uv run agentbyte eval ui --catalog examples/eval/workbench_catalog.py      # htt
 
 - `--catalog` takes a `.py` file or a module path (`myapp.evaluations`); add `:name` only when the
   file defines more than one registry. Without `--catalog` it serves the built-in smoke suite.
-- Runs are stored in `./eval.sqlite` unless you pass `--history PATH`. Only one process can write
+- Runs are stored in `./.agentbyte/eval/default/eval.sqlite` unless you pass `--history PATH`. Only one process can write
   a history file: stop the UI before `agentbyte eval run` on the same file, or use another file.
 - The same catalog works in the terminal: `uv run agentbyte eval run capitals --catalog examples/eval/workbench_catalog.py`.
 - To serve agents and Evaluations together: `agentbyte webui --dir my_entities --eval-catalog myapp/evaluations.py`.
@@ -399,7 +412,7 @@ uv run agentbyte webui --dir my_entities --eval-catalog myapp/evaluations.py   #
 from agentbyte.webui import serve
 
 serve(entities=[agent], port=8080)
-serve(entities=[agent], eval_registry=registry, eval_history="eval.sqlite")   # with Evaluations
+serve(entities=[agent], eval_registry=registry, eval_history=".agentbyte/eval/default/eval.sqlite")   # with Evaluations
 ```
 
 ### Quick Troubleshooting

{agentbyte-0.45.0 → agentbyte-0.47.0}/README.md

@@ -2,7 +2,7 @@
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.45.0**
+Current release: **0.47.0**
 
 ## Building an Agent
 
@@ -243,10 +243,17 @@ uv add "agentbyte[openai,sqlite]"
 | `optim` | `gepa` | `optimize_with_gepa()` |
 | `viz` | `graphviz` | `WorkflowVisualizer.to_dot()` |
 | `research` | `beautifulsoup4`, `html2text`, `arxiv`, `youtube-transcript-api` | `agentbyte.tools.research_tools` |
-| `all` | every extra above | Everything |
+| `mcp` | `mcp` (SDK v2) | `agentbyte.tools.mcp`: MCP tool bridge (`MCPClientManager`, `MCPTool`, `create_mcp_tools()`); also enables the WebUI MCP Playground routes |
+| `a2a` | `a2a-sdk[http-server]` 1.x, `agentbyte[webui]` | `agentbyte.a2a`: A2A 1.0 adapters on the official SDK — `create_a2a_app` / `AgentByteExecutor` to serve an agent, `A2ATool` to call one, `agentbyte serve` for local dev |
+| `all` | every extra above except `mcp`/`a2a`* | Everything except the MCP/A2A protocol bridges |
+
+*`mcp` and `a2a` are deliberately excluded from `all`: both let an agent reach outside the
+process (subprocess tools, outbound HTTP to arbitrary agents) and are opt-in rather than
+bundled by default. Install them explicitly: `pip install "agentbyte[mcp,a2a]"`.
 
 Contributors working in this repository install every extra plus the local tooling groups
-(`test`, `dev`, `experiment`):
+(`test`, `dev`, `experiment`) — this always includes `mcp`/`a2a` regardless of the `all`
+composite above, since `--all-extras` syncs every defined extra individually:
 
 ```bash
 uv sync --all-extras --all-groups
@@ -267,7 +274,7 @@ No API key needed: three demo agents, a team and a workflow on a fake model clie
 
 ```bash
 uv run python examples/webui/in_memory.py                          # http://127.0.0.1:8070
-uv run python examples/webui/in_memory.py --eval-history eval.sqlite   # plus Evaluations
+uv run python examples/webui/in_memory.py --eval-history .agentbyte/eval/default/eval.sqlite   # plus Evaluations
 ```
 
 With your OpenAI or Azure OpenAI credentials, the preset agents, teams and workflow:
@@ -275,7 +282,7 @@ With your OpenAI or Azure OpenAI credentials, the preset agents, teams and workf
 ```bash
 uv sync --extra webui --extra openai        # or --extra azureopenai
 uv run python examples/webui/presets_webui.py                      # http://127.0.0.1:8080
-uv run python examples/webui/presets_webui.py --eval-history eval.sqlite
+uv run python examples/webui/presets_webui.py --eval-history .agentbyte/eval/default/eval.sqlite
 ```
 
 Both launchers accept `--port`, `--no-open`, `--eval-history PATH` and `--eval-catalog CATALOG`
@@ -293,7 +300,7 @@ uv run agentbyte eval ui --catalog examples/eval/workbench_catalog.py      # htt
 
 - `--catalog` takes a `.py` file or a module path (`myapp.evaluations`); add `:name` only when the
   file defines more than one registry. Without `--catalog` it serves the built-in smoke suite.
-- Runs are stored in `./eval.sqlite` unless you pass `--history PATH`. Only one process can write
+- Runs are stored in `./.agentbyte/eval/default/eval.sqlite` unless you pass `--history PATH`. Only one process can write
   a history file: stop the UI before `agentbyte eval run` on the same file, or use another file.
 - The same catalog works in the terminal: `uv run agentbyte eval run capitals --catalog examples/eval/workbench_catalog.py`.
 - To serve agents and Evaluations together: `agentbyte webui --dir my_entities --eval-catalog myapp/evaluations.py`.
@@ -324,7 +331,7 @@ uv run agentbyte webui --dir my_entities --eval-catalog myapp/evaluations.py   #
 from agentbyte.webui import serve
 
 serve(entities=[agent], port=8080)
-serve(entities=[agent], eval_registry=registry, eval_history="eval.sqlite")   # with Evaluations
+serve(entities=[agent], eval_registry=registry, eval_history=".agentbyte/eval/default/eval.sqlite")   # with Evaluations
 ```
 
 ### Quick Troubleshooting

{agentbyte-0.45.0 → agentbyte-0.47.0}/pyproject.toml

@@ -66,6 +66,14 @@ research = [
     "arxiv>=2.1",
     "youtube-transcript-api>=0.6",
 ]
+mcp = [
+    "mcp>=2.0.0,<3",
+]
+# A2A 1.0 via the official SDK; uvicorn (webui) runs `agentbyte serve`.
+a2a = [
+    "a2a-sdk[http-server]>=1.2,<2",
+    "agentbyte[webui]",
+]
 all = [
     "agentbyte[openai,azureopenai,aws,otel,webui,gunicorn,sql,tiktoken,optim,viz,research]",
 ]

agentbyte-0.47.0/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.47.0"
+VERSION = __version__

agentbyte-0.47.0/src/agentbyte/a2a/__init__.py

@@ -0,0 +1,47 @@
+"""A2A 1.0 adapters on the official SDK (`a2a-sdk`), plus distributed-context helpers.
+
+Import from this package explicitly; no parent package re-exports it. The SDK owns
+the protocol (wire format, transports, task store, streaming); AgentByte adds only:
+
+- `AgentByteExecutor` — serve an AgentByte agent as an SDK `AgentExecutor`
+- `create_a2a_app` / `agent_card_from_agent` — a ready Starlette app and default card
+- `A2ATool` — call a remote A2A agent as a native tool, over an SDK `Client`
+
+No authentication is built in: hosts add Starlette middleware on the server and SDK
+interceptors on the client. SDK-backed names need the ``a2a`` extra and are imported
+lazily, so `DistributedContextManager` works with the base install.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from agentbyte.a2a.app import agent_card_from_agent, create_a2a_app
+    from agentbyte.a2a.distributed_context import DistributedContextManager
+    from agentbyte.a2a.executor import AgentByteExecutor
+    from agentbyte.a2a.tool import A2ATool
+
+_EXPORTS = {
+    "A2ATool": "agentbyte.a2a.tool",
+    "AgentByteExecutor": "agentbyte.a2a.executor",
+    "DistributedContextManager": "agentbyte.a2a.distributed_context",
+    "agent_card_from_agent": "agentbyte.a2a.app",
+    "create_a2a_app": "agentbyte.a2a.app",
+}
+
+__all__ = [
+    "A2ATool",
+    "AgentByteExecutor",
+    "DistributedContextManager",
+    "agent_card_from_agent",
+    "create_a2a_app",
+]
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module 'agentbyte.a2a' has no attribute {name!r}")
+    return getattr(importlib.import_module(module), name)

agentbyte-0.47.0/src/agentbyte/a2a/app.py

@@ -0,0 +1,98 @@
+"""Agent Card and ASGI app helpers around the official A2A 1.0 SDK.
+
+`create_a2a_app()` adds no authentication: pass the host's own Starlette
+middleware (e.g. `AuthenticationMiddleware`). The SDK scopes tasks to the
+authenticated user name; without auth every caller shares one anonymous owner,
+which is only acceptable on localhost.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from typing import Any
+from urllib.parse import urlsplit
+
+from agentbyte._optional import MissingExtraError
+from agentbyte.a2a.executor import AgentByteExecutor
+
+try:
+    from a2a.server.request_handlers import DefaultRequestHandler
+    from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
+    from a2a.server.tasks import InMemoryTaskStore, TaskStore
+    from a2a.types import (
+        AgentCapabilities,
+        AgentCard,
+        AgentInterface,
+        AgentSkill,
+    )
+    from a2a.utils.constants import PROTOCOL_VERSION_1_0, TransportProtocol
+    from starlette.applications import Starlette
+    from starlette.middleware import Middleware
+except ImportError as exc:
+    raise MissingExtraError("agentbyte.a2a (missing a2a-sdk)", "a2a", name="a2a") from exc
+
+TEXT_AND_JSON = ["text/plain", "application/json"]
+
+
+def agent_card_from_agent(agent: Any, *, url: str, version: str = "1.0.0") -> AgentCard:
+    """Build a default A2A 1.0 card: one JSON-RPC interface at `url`, one skill.
+
+    The card advertises no security scheme. To advertise one, set
+    `card.security_schemes` / `card.security_requirements` on the returned
+    protobuf, and enforce it with the host's middleware.
+    """
+    description = agent.description or agent.name
+    return AgentCard(
+        name=agent.name,
+        description=description,
+        version=version,
+        supported_interfaces=[AgentInterface(
+            url=url,
+            protocol_binding=TransportProtocol.JSONRPC.value,
+            protocol_version=PROTOCOL_VERSION_1_0,
+        )],
+        capabilities=AgentCapabilities(streaming=True, push_notifications=False),
+        default_input_modes=TEXT_AND_JSON,
+        default_output_modes=TEXT_AND_JSON,
+        skills=[AgentSkill(
+            id=agent.name, name=agent.name, description=description, tags=[],
+            examples=list(getattr(agent, "example_tasks", None) or []),
+        )],
+    )
+
+
+def create_a2a_app(
+    agent: Any,
+    *,
+    url: str,
+    agent_card: AgentCard | None = None,
+    task_store: TaskStore | None = None,
+    middleware: Sequence[Middleware] = (),
+    max_contexts: int = 1024,
+) -> Starlette:
+    """Serve `agent` over A2A 1.0 JSON-RPC as a Starlette app.
+
+    Routes: `/.well-known/agent-card.json` and the JSON-RPC endpoint at `url`'s
+    path. `task_store` defaults to the SDK's in-memory store; native agent
+    conversation state is always process-local (see `AgentByteExecutor`).
+    """
+    card = agent_card or agent_card_from_agent(agent, url=url)
+    handler = DefaultRequestHandler(
+        agent_executor=AgentByteExecutor(agent, max_contexts=max_contexts),
+        task_store=task_store or InMemoryTaskStore(),
+        agent_card=card,
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncIterator[None]:
+        try:
+            yield
+        finally:
+            await handler.aclose()
+
+    routes = [
+        *create_agent_card_routes(card),
+        *create_jsonrpc_routes(handler, rpc_url=urlsplit(url).path or "/"),
+    ]
+    return Starlette(routes=routes, middleware=list(middleware), lifespan=lifespan)

agentbyte-0.47.0/src/agentbyte/a2a/distributed_context.py

@@ -0,0 +1,180 @@
+"""Owner-scoped, process-local artifact references with host-controlled resolution."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, replace
+
+
+@dataclass(frozen=True)
+class _Reference:
+    uri: str
+    expires_at: float
+
+
+class DistributedContextManager:
+    """Track references for one authenticated owner on one event loop.
+
+    The host supplies ``resolver(owner_id, uri)`` and is responsible for URI
+    allowlisting, authorization, transport limits and external storage lifecycle.
+    No URI is fetched implicitly. Use a separate manager per owner; never derive
+    owner_id from untrusted task input. Cached reads bypass the resolver until
+    cache expiry, so authorization revocation must call invalidate or unregister.
+
+    Registrations expire after ``artifact_ttl``; cached UTF-8 text has a separate
+    TTL and LRU byte/entry limits. Oversized text is rejected. Failures and
+    cancellations are not cached or retried. Concurrent misses resolve separately.
+    Invalidation during a resolve rejects its result with KeyError. All state is
+    lost on restart; clear/unregister never delete external artifacts.
+    """
+
+    def __init__(
+        self,
+        *,
+        owner_id: str,
+        resolver: Callable[[str, str], Awaitable[str]],
+        max_artifacts: int = 1024,
+        max_cache_entries: int = 128,
+        max_cache_bytes: int = 8 * 1024 * 1024,
+        max_content_bytes: int = 1024 * 1024,
+        artifact_ttl: float = 3600,
+        cache_ttl: float = 60,
+        resolve_timeout: float = 30,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        """Configure finite positive limits; clock must be monotonic."""
+        self._validate_text(owner_id, "owner_id")
+        for name, value in (
+            ("max_artifacts", max_artifacts),
+            ("max_cache_entries", max_cache_entries),
+            ("max_cache_bytes", max_cache_bytes),
+            ("max_content_bytes", max_content_bytes),
+        ):
+            if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+                raise ValueError(f"{name} must be a positive integer")
+        for value in (artifact_ttl, cache_ttl, resolve_timeout):
+            self._validate_ttl(value)
+        if not callable(resolver):
+            raise TypeError("resolver must be an async callable")
+        self._owner_id = owner_id
+        self._resolver = resolver
+        self._max_artifacts = max_artifacts
+        self._max_cache_entries = max_cache_entries
+        self._max_cache_bytes = max_cache_bytes
+        self._max_content_bytes = max_content_bytes
+        self._artifact_ttl = artifact_ttl
+        self._cache_ttl = cache_ttl
+        self._resolve_timeout = resolve_timeout
+        self._clock = clock
+        self._references: dict[str, _Reference] = {}
+        self._cache: OrderedDict[str, tuple[str, float, int]] = OrderedDict()
+        self._cache_bytes = 0
+
+    @property
+    def owner_id(self) -> str:
+        """The host-authenticated scope of this manager (read-only)."""
+        return self._owner_id
+
+    @staticmethod
+    def _validate_text(value: str, name: str) -> None:
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError(f"{name} must be nonempty text")
+
+    @staticmethod
+    def _validate_ttl(value: float) -> None:
+        if isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+            raise ValueError("TTL and timeout must be finite and positive")
+
+    def _drop_cache(self, key: str) -> None:
+        cached = self._cache.pop(key, None)
+        if cached is not None:
+            self._cache_bytes -= cached[2]
+
+    def _prune(self) -> None:
+        now = self._clock()
+        for key, reference in list(self._references.items()):
+            if reference.expires_at <= now:
+                del self._references[key]
+                self._drop_cache(key)
+        for key, (_, expires_at, _) in list(self._cache.items()):
+            if expires_at <= now:
+                self._drop_cache(key)
+
+    def register_artifact(self, key: str, uri: str, *, ttl: float | None = None) -> None:
+        """Register/replace an opaque URI; replacement invalidates cached reads.
+
+        At registration capacity, raise ValueError instead of evicting references.
+        ``ttl`` overrides the default lifetime starting at registration time.
+        """
+        self._validate_text(key, "key")
+        self._validate_text(uri, "uri")
+        lifetime = self._artifact_ttl if ttl is None else ttl
+        self._validate_ttl(lifetime)
+        self._prune()
+        if key not in self._references and len(self._references) >= self._max_artifacts:
+            raise ValueError("Artifact registration capacity reached")
+        self._drop_cache(key)
+        self._references[key] = _Reference(uri, self._clock() + lifetime)
+
+    async def resolve(self, key: str) -> str:
+        """Resolve registered text, raising KeyError for absent/stale references.
+
+        Resolver exceptions propagate unchanged; TimeoutError bounds each fetch.
+        A resolved payload exceeding max_content_bytes raises ValueError. Payloads
+        larger than the cache byte budget are returned without caching.
+        """
+        self._prune()
+        reference = self._references[key]
+        if key in self._cache:
+            self._cache.move_to_end(key)
+            return self._cache[key][0]
+        async with asyncio.timeout(self._resolve_timeout):
+            content = await self._resolver(self._owner_id, reference.uri)
+        self._prune()
+        if self._references.get(key) is not reference:
+            raise KeyError(key)
+        if not isinstance(content, str):
+            raise TypeError("Artifact resolver must return str")
+        size = len(content.encode("utf-8"))
+        if size > self._max_content_bytes:
+            raise ValueError("Resolved artifact exceeds max_content_bytes")
+        if size <= self._max_cache_bytes:
+            self._drop_cache(key)
+            while self._cache and (
+                len(self._cache) >= self._max_cache_entries
+                or self._cache_bytes + size > self._max_cache_bytes
+            ):
+                self._drop_cache(next(iter(self._cache)))
+            self._cache[key] = (
+                content,
+                min(reference.expires_at, self._clock() + self._cache_ttl),
+                size,
+            )
+            self._cache_bytes += size
+        return content
+
+    def invalidate(self, key: str) -> bool:
+        """Forget fetched content and reject in-flight reads, retaining the URI."""
+        self._prune()
+        self._drop_cache(key)
+        reference = self._references.get(key)
+        if reference is None:
+            return False
+        self._references[key] = replace(reference)
+        return True
+
+    def unregister(self, key: str) -> bool:
+        """Remove a reference/cache entry and reject its in-flight reads."""
+        self._prune()
+        self._drop_cache(key)
+        return self._references.pop(key, None) is not None
+
+    def clear(self) -> None:
+        """Forget all local references/content and reject all in-flight reads."""
+        self._references.clear()
+        self._cache.clear()
+        self._cache_bytes = 0