agentledger-runtime 1.0.0__py3-none-any.whl

agentledger/__init__.py

@@ -0,0 +1,183 @@
+"""AgentLedger agent runtime v1.0 stable core."""
+
+__version__ = "1.0.0"
+
+from .adapters import FrameworkAdapter, PythonFunctionAdapter, python_agent
+from .adapters_frameworks import AutoGenAdapter, CrewAIAdapter, LangChainRunnableAdapter, LlamaIndexAdapter, MethodFrameworkAdapter, OpenAIAgentsSDKAdapter, SemanticKernelAdapter
+from .approval import ApprovalDecision, ApprovalRequired
+from .adapters_langgraph import LangGraphCheckpointerAdapter, LangGraphNodeAdapter
+from .adapters_mcp import InMemoryMCPContextServer, InMemoryMCPToolServer, MCPContextAdapter, MCPResourceDescriptor, MCPToolAdapter
+from .backup import BackupCheck, BackupReadinessChecker, BackupReadinessReport
+from .blobstore import LocalBlobStore
+from .blobstore_s3 import S3BlobStore, S3BlobStoreConfig, S3DependencyMissing
+from .conformance import BlobStoreConformanceRunner, ConformanceCheck, ConformanceReport, FrameworkAdapterConformanceRunner, MediaRuntimeConformanceRunner, StateStoreConformanceRunner, WorkerConformanceRunner
+from .contract import CONTRACT_VERSION, contract_json, runtime_contract
+from .diff import DiffReport, DivergenceReport, DivergenceReporter, EvidenceDiffer
+from .context import AgentContext
+from .cost import BudgetController, BudgetExceeded, BudgetLimits, CostAttributionReport, CostAttributionReporter
+from .eval import EvidenceCheck, EvidenceCheckReport, EvidenceRegressionRunner
+from .evidence import EvidenceExporter
+from .failure import FailureAttributionReport, FailureAttributionReporter, FailureClassification, NonRetryableAgentError, RetryableAgentError, RetryPolicy
+from .failure_injection import FailureInjectionCheck, FailureInjectionReport, FailureInjectionSuite
+from .lint import BoundaryLintFinding, BoundaryLintReport, BoundaryLintRule, RuntimeBoundaryLinter, load_boundary_rules
+from .media import ArtifactLineage, EventStreamCheckpoint, MediaArtifact, MediaMetadata, StreamChunkRef
+from .media_tools import media_tool_specs, register_media_tool_conventions
+from .policy import PolicyEngine, RolePolicy
+from .protocol import BlobStoreProtocol, ModelProviderProtocol, StateStoreProtocol, ToolExecutorProtocol
+from .repro import GoldenCase, GoldenCorpus
+from .replay import ReplayEngine
+from .runtime import Runtime, SimulatedCrash
+from .retention import RetentionPlan, RetentionPlanner
+from .review import AdversarialReviewReport, AdversarialReviewRunner, ReviewCheck
+from .sandbox import BubblewrapSandboxExecutor, DisabledSandboxExecutor, DockerSandboxExecutor, E2BSandboxExecutor, FirecrackerSandboxExecutor, KubernetesSandboxExecutor, LocalSandboxExecutor, RemoteSandboxExecutor, SandboxConfig, SandboxExecutor, SandboxPolicy, SandboxResult, SandboxRouter, SandboxToolRule, SandboxUnavailable, create_sandbox_executor
+from .simple import RunResult, SimpleAgent, agent, arun, run
+from .scheduler import RecoverySummary, RuntimeScheduler
+from .storage_schema import Migration, MigrationStatus, SQLiteMigrationRunner, ddl_for, latest_schema_version, migrations_for
+from .storage_postgres import PostgresDependencyMissing, PostgresStore, PostgresStoreConfig
+from .store import SQLiteStore
+from .tools import ToolRegistry, ToolSpec, ToolValidationError, tool, validate_tool_schema
+from .trace import OTLPResource, OTLPTraceExporter, TraceExporter, TraceSpan
+from .timetravel import TimeTravelDebugger, TimeTravelFrame, TimeTravelReport
+from .worker import LocalWorker, WorkerDeploymentPlan, WorkerRunSummary, WorkerService, WorkerServiceSummary, build_worker_deployment_plan
+
+__all__ = [
+    "ApprovalDecision",
+    "ApprovalRequired",
+    "AdversarialReviewReport",
+    "AdversarialReviewRunner",
+    "ArtifactLineage",
+    "BackupCheck",
+    "BackupReadinessChecker",
+    "BackupReadinessReport",
+    "RunResult",
+    "SimpleAgent",
+    "RetentionPlan",
+    "RetentionPlanner",
+    "ReviewCheck",
+    "BubblewrapSandboxExecutor",
+    "DisabledSandboxExecutor",
+    "DockerSandboxExecutor",
+    "E2BSandboxExecutor",
+    "FirecrackerSandboxExecutor",
+    "KubernetesSandboxExecutor",
+    "RemoteSandboxExecutor",
+    "SandboxConfig",
+    "SandboxRouter",
+    "SandboxToolRule",
+    "SandboxUnavailable",
+    "create_sandbox_executor",
+    "SandboxExecutor",
+    "SandboxPolicy",
+    "SandboxResult",
+    "LocalSandboxExecutor",
+    "agent",
+    "arun",
+    "run",
+    "AgentContext",
+    "BlobStoreProtocol",
+    "BlobStoreConformanceRunner",
+    "BudgetController",
+    "BudgetExceeded",
+    "BudgetLimits",
+    "CostAttributionReport",
+    "CostAttributionReporter",
+    "BoundaryLintFinding",
+    "BoundaryLintReport",
+    "BoundaryLintRule",
+    "ConformanceCheck",
+    "ConformanceReport",
+    "CONTRACT_VERSION",
+    "__version__",
+    "EvidenceCheck",
+    "EvidenceCheckReport",
+    "EvidenceRegressionRunner",
+    "EventStreamCheckpoint",
+    "OTLPResource",
+    "OTLPTraceExporter",
+    "TraceSpan",
+    "TraceExporter",
+    "TimeTravelDebugger",
+    "TimeTravelFrame",
+    "TimeTravelReport",
+    "PostgresStoreConfig",
+    "PostgresStore",
+    "PostgresDependencyMissing",
+    "EvidenceDiffer",
+    "DiffReport",
+    "DivergenceReport",
+    "DivergenceReporter",
+    "EvidenceExporter",
+    "FailureInjectionCheck",
+    "FailureInjectionReport",
+    "FailureInjectionSuite",
+    "FailureClassification",
+    "FailureAttributionReport",
+    "FailureAttributionReporter",
+    "FrameworkAdapter",
+    "FrameworkAdapterConformanceRunner",
+    "AutoGenAdapter",
+    "CrewAIAdapter",
+    "GoldenCase",
+    "GoldenCorpus",
+    "LangGraphCheckpointerAdapter",
+    "LangGraphNodeAdapter",
+    "LangChainRunnableAdapter",
+    "LlamaIndexAdapter",
+    "LocalBlobStore",
+    "LocalWorker",
+    "MediaArtifact",
+    "MediaMetadata",
+    "media_tool_specs",
+    "MCPToolAdapter",
+    "MCPContextAdapter",
+    "MCPResourceDescriptor",
+    "InMemoryMCPToolServer",
+    "InMemoryMCPContextServer",
+    "MethodFrameworkAdapter",
+    "MediaRuntimeConformanceRunner",
+    "Migration",
+    "MigrationStatus",
+    "ModelProviderProtocol",
+    "NonRetryableAgentError",
+    "PolicyEngine",
+    "OpenAIAgentsSDKAdapter",
+    "PythonFunctionAdapter",
+    "RecoverySummary",
+    "ReplayEngine",
+    "RetryPolicy",
+    "RetryableAgentError",
+    "RolePolicy",
+    "Runtime",
+    "RuntimeBoundaryLinter",
+    "load_boundary_rules",
+    "RuntimeScheduler",
+    "SemanticKernelAdapter",
+    "S3BlobStore",
+    "S3BlobStoreConfig",
+    "S3DependencyMissing",
+    "SQLiteMigrationRunner",
+    "SQLiteStore",
+    "SimulatedCrash",
+    "StateStoreConformanceRunner",
+    "StateStoreProtocol",
+    "StreamChunkRef",
+    "ToolExecutorProtocol",
+    "ToolRegistry",
+    "ToolSpec",
+    "ToolValidationError",
+    "WorkerRunSummary",
+    "WorkerConformanceRunner",
+    "WorkerDeploymentPlan",
+    "WorkerService",
+    "WorkerServiceSummary",
+    "build_worker_deployment_plan",
+    "contract_json",
+    "ddl_for",
+    "latest_schema_version",
+    "migrations_for",
+    "python_agent",
+    "runtime_contract",
+    "register_media_tool_conventions",
+    "tool",
+    "validate_tool_schema",
+]

agentledger/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

agentledger/adapters.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from .context import AgentContext
+
+AgentCallable = Callable[[AgentContext, dict[str, Any]], Any]
+
+
+class FrameworkAdapter(ABC):
+    """Base contract for framework adapters.
+
+    Adapters map framework-specific concepts into AgentLedger's stable runtime
+    boundary. Core imports no LangGraph/CrewAI/AutoGen/etc dependencies.
+    """
+
+    name = "framework"
+
+    def map_run_spec(self, framework_run: Any) -> dict[str, Any]:
+        return {"adapter": self.name, "framework_run": repr(framework_run)}
+
+    def map_step(self, framework_step: Any) -> dict[str, Any]:
+        return {"adapter": self.name, "framework_step": repr(framework_step)}
+
+    @abstractmethod
+    def as_agent(self) -> AgentCallable:
+        """Return a callable compatible with Runtime.run_once."""
+
+
+class PythonFunctionAdapter(FrameworkAdapter):
+    """Adapter for a plain Python function or coroutine.
+
+    This proves the framework-agnostic SDK path before adding heavier optional
+    integrations.
+    """
+
+    name = "python-function"
+
+    def __init__(self, func: AgentCallable, *, role: str = "Agent"):
+        self.func = func
+        self.role = role
+
+    def map_run_spec(self, framework_run: Any = None) -> dict[str, Any]:
+        return {"adapter": self.name, "role": self.role, "function": getattr(self.func, "__name__", repr(self.func))}
+
+    def as_agent(self) -> AgentCallable:
+        async def wrapped(ctx: AgentContext, state: dict[str, Any]) -> Any:
+            result = self.func(ctx, state)
+            if inspect.isawaitable(result):
+                return await result
+            return result
+
+        return wrapped
+
+
+def python_agent(*, role: str = "Agent") -> Callable[[AgentCallable], PythonFunctionAdapter]:
+    def decorator(func: AgentCallable) -> PythonFunctionAdapter:
+        return PythonFunctionAdapter(func, role=role)
+
+    return decorator

agentledger/adapters_frameworks.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable
+
+from .adapters import AgentCallable, FrameworkAdapter
+from .context import AgentContext
+
+InputMapper = Callable[[AgentContext, dict[str, Any]], Any]
+
+
+def default_input_mapper(_ctx: AgentContext, state: dict[str, Any]) -> dict[str, Any]:
+    return dict(state)
+
+
+class MethodFrameworkAdapter(FrameworkAdapter):
+    """Dependency-free facade for framework objects with conventional methods."""
+
+    name = "method-framework"
+
+    def __init__(
+        self,
+        target: Any,
+        *,
+        role: str = "FrameworkAgent",
+        method_candidates: tuple[str, ...],
+        input_mapper: InputMapper | None = None,
+        output_key: str | None = "output",
+    ):
+        self.target = target
+        self.role = role
+        self.method_candidates = method_candidates
+        self.input_mapper = input_mapper or default_input_mapper
+        self.output_key = output_key
+
+    def map_run_spec(self, framework_run: Any = None) -> dict[str, Any]:
+        return {
+            "adapter": self.name,
+            "role": self.role,
+            "target": type(self.target).__name__,
+            "methods": list(self.method_candidates),
+        }
+
+    def as_agent(self) -> AgentCallable:
+        async def wrapped(ctx: AgentContext, state: dict[str, Any]) -> Any:
+            payload = self.input_mapper(ctx, state)
+            result = await self._invoke(payload)
+            if self.output_key is not None:
+                ctx.write_state_patch(self.output_key, result)
+            return result
+
+        return wrapped
+
+    async def _invoke(self, payload: Any) -> Any:
+        for name in self.method_candidates:
+            method = getattr(self.target, name, None)
+            if method is None:
+                continue
+            result = method(payload)
+            if inspect.isawaitable(result):
+                return await result
+            return result
+        if callable(self.target):
+            result = self.target(payload)
+            if inspect.isawaitable(result):
+                return await result
+            return result
+        raise AttributeError(f"{type(self.target).__name__} does not expose any of {self.method_candidates!r}")
+
+
+class LangChainRunnableAdapter(MethodFrameworkAdapter):
+    """Wrap a LangChain-style Runnable without importing LangChain."""
+
+    name = "langchain-runnable"
+
+    def __init__(self, runnable: Any, *, role: str = "LangChainAgent", input_mapper: InputMapper | None = None, output_key: str | None = "langchain_output"):
+        super().__init__(runnable, role=role, method_candidates=("ainvoke", "invoke"), input_mapper=input_mapper, output_key=output_key)
+
+
+class CrewAIAdapter(MethodFrameworkAdapter):
+    """Wrap a CrewAI-style Crew/Task object without importing CrewAI."""
+
+    name = "crewai"
+
+    def __init__(self, crew_or_task: Any, *, role: str = "CrewAIAgent", input_mapper: InputMapper | None = None, output_key: str | None = "crewai_output"):
+        super().__init__(crew_or_task, role=role, method_candidates=("akickoff", "kickoff", "arun", "run"), input_mapper=input_mapper, output_key=output_key)
+
+
+class AutoGenAdapter(MethodFrameworkAdapter):
+    """Wrap an AutoGen-style agent object without importing AutoGen."""
+
+    name = "autogen"
+
+    def __init__(self, agent: Any, *, role: str = "AutoGenAgent", input_mapper: InputMapper | None = None, output_key: str | None = "autogen_output"):
+        super().__init__(
+            agent,
+            role=role,
+            method_candidates=("a_generate_reply", "generate_reply", "a_run", "run", "ainvoke", "invoke"),
+            input_mapper=input_mapper,
+            output_key=output_key,
+        )
+
+
+class OpenAIAgentsSDKAdapter(MethodFrameworkAdapter):
+    """Wrap an OpenAI Agents SDK-style runner without importing the SDK."""
+
+    name = "openai-agents-sdk"
+
+    def __init__(self, agent_or_runner: Any, *, role: str = "OpenAIAgent", input_mapper: InputMapper | None = None, output_key: str | None = "openai_agent_output"):
+        super().__init__(
+            agent_or_runner,
+            role=role,
+            method_candidates=("arun", "run", "ainvoke", "invoke"),
+            input_mapper=input_mapper,
+            output_key=output_key,
+        )
+
+
+class LlamaIndexAdapter(MethodFrameworkAdapter):
+    """Wrap a LlamaIndex-style query/chat/retriever object without importing LlamaIndex."""
+
+    name = "llamaindex"
+
+    def __init__(self, query_engine_or_agent: Any, *, role: str = "LlamaIndexAgent", input_mapper: InputMapper | None = None, output_key: str | None = "llamaindex_output"):
+        super().__init__(
+            query_engine_or_agent,
+            role=role,
+            method_candidates=("aquery", "query", "achat", "chat", "aretrieve", "retrieve", "ainvoke", "invoke"),
+            input_mapper=input_mapper,
+            output_key=output_key,
+        )
+
+
+class SemanticKernelAdapter(MethodFrameworkAdapter):
+    """Wrap a Semantic Kernel-style kernel/function object without importing it."""
+
+    name = "semantic-kernel"
+
+    def __init__(self, kernel_or_function: Any, *, role: str = "SemanticKernelAgent", input_mapper: InputMapper | None = None, output_key: str | None = "semantic_kernel_output"):
+        super().__init__(
+            kernel_or_function,
+            role=role,
+            method_candidates=("ainvoke", "invoke", "invoke_prompt", "run_async", "run"),
+            input_mapper=input_mapper,
+            output_key=output_key,
+        )

agentledger/adapters_langgraph.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .adapters import FrameworkAdapter, PythonFunctionAdapter
+from .ids import new_id
+
+
+class LangGraphCheckpointerAdapter:
+    """Dependency-free LangGraph-style checkpointer adapter.
+
+    Runtime core does not import LangGraph. This adapter exposes the common
+    checkpointer shape (`put`, `get`, `get_tuple`, `list`, `put_writes`) using
+    plain dictionaries so optional packages can wrap it with LangGraph's exact
+    classes without changing AgentLedger state semantics.
+    """
+
+    name = "langgraph-checkpointer"
+
+    def __init__(self, runtime: Any):
+        self.runtime = runtime
+
+    def config_for_run(self, run_id: str, *, thread_id: str | None = None, checkpoint_ns: str = "") -> dict[str, Any]:
+        return {"configurable": {"agentledger_run_id": run_id, "thread_id": thread_id or run_id, "checkpoint_ns": checkpoint_ns}}
+
+    def checkpoint_from_run(self, run_id: str) -> dict[str, Any]:
+        state, state_version, session_id = self.runtime.store.load_state(run_id)
+        return {"run_id": run_id, "session_id": session_id, "state_version": state_version, "state": state}
+
+    def persist_checkpoint(self, run_id: str, checkpoint: dict[str, Any], *, reason: str = "langgraph checkpoint") -> int:
+        return self.runtime.store.apply_system_state_patch(run_id=run_id, patch={"langgraph_checkpoint": checkpoint}, reason=reason)
+
+    def put(
+        self,
+        config: dict[str, Any],
+        checkpoint: dict[str, Any],
+        metadata: dict[str, Any] | None = None,
+        new_versions: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        run_id = self._run_id_from_config(config)
+        checkpoint_id = str(checkpoint.get("id") or checkpoint.get("checkpoint_id") or new_id("lgckpt"))
+        next_config = self._with_checkpoint_id(config, checkpoint_id)
+        record = {
+            "checkpoint": {**checkpoint, "id": checkpoint_id},
+            "metadata": metadata or {},
+            "new_versions": new_versions or {},
+            "config": next_config,
+        }
+        self.runtime.store.apply_system_state_patch(
+            run_id=run_id,
+            patch={"langgraph_checkpoint": record, "langgraph_pending_writes": []},
+            reason="langgraph checkpoint put",
+        )
+        return next_config
+
+    async def aput(
+        self,
+        config: dict[str, Any],
+        checkpoint: dict[str, Any],
+        metadata: dict[str, Any] | None = None,
+        new_versions: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self.put(config, checkpoint, metadata, new_versions)
+
+    def get_tuple(self, config: dict[str, Any]) -> dict[str, Any] | None:
+        run_id = self._run_id_from_config(config)
+        state = self.runtime.store.final_state(run_id)
+        record = state.get("langgraph_checkpoint")
+        if record is None:
+            return None
+        if "checkpoint" not in record:
+            record = {"checkpoint": record, "metadata": {}, "config": config}
+        return {
+            "config": record.get("config", config),
+            "checkpoint": record.get("checkpoint"),
+            "metadata": record.get("metadata", {}),
+            "parent_config": record.get("parent_config"),
+            "pending_writes": state.get("langgraph_pending_writes", []),
+        }
+
+    async def aget_tuple(self, config: dict[str, Any]) -> dict[str, Any] | None:
+        return self.get_tuple(config)
+
+    def get(self, config: dict[str, Any]) -> dict[str, Any] | None:
+        item = self.get_tuple(config)
+        return item["checkpoint"] if item is not None else None
+
+    async def aget(self, config: dict[str, Any]) -> dict[str, Any] | None:
+        return self.get(config)
+
+    def list(self, config: dict[str, Any] | None = None, **_kwargs: Any) -> list[dict[str, Any]]:
+        if config is None:
+            return []
+        item = self.get_tuple(config)
+        return [item] if item is not None else []
+
+    async def alist(self, config: dict[str, Any] | None = None, **kwargs: Any) -> list[dict[str, Any]]:
+        return self.list(config, **kwargs)
+
+    def put_writes(self, config: dict[str, Any], writes: list[Any], task_id: str, task_path: str = "") -> None:
+        run_id = self._run_id_from_config(config)
+        state = self.runtime.store.final_state(run_id)
+        pending = list(state.get("langgraph_pending_writes", []))
+        pending.append({"task_id": task_id, "task_path": task_path, "writes": writes, "config": config})
+        self.runtime.store.apply_system_state_patch(
+            run_id=run_id,
+            patch={"langgraph_pending_writes": pending},
+            reason="langgraph pending writes",
+        )
+
+    async def aput_writes(self, config: dict[str, Any], writes: list[Any], task_id: str, task_path: str = "") -> None:
+        self.put_writes(config, writes, task_id, task_path)
+
+    def _run_id_from_config(self, config: dict[str, Any]) -> str:
+        configurable = config.get("configurable", {}) if isinstance(config, dict) else {}
+        run_id = configurable.get("agentledger_run_id") or configurable.get("run_id")
+        if not run_id:
+            raise ValueError("LangGraph config must include configurable.agentledger_run_id or configurable.run_id")
+        return str(run_id)
+
+    def _with_checkpoint_id(self, config: dict[str, Any], checkpoint_id: str) -> dict[str, Any]:
+        configurable = dict(config.get("configurable", {}))
+        configurable["checkpoint_id"] = checkpoint_id
+        return {**config, "configurable": configurable}
+
+
+class LangGraphNodeAdapter(FrameworkAdapter):
+    """Wrap a callable node as a Runtime.run_once-compatible agent."""
+
+    name = "langgraph-node"
+
+    def __init__(self, node: Any, *, role: str = "LangGraphAgent"):
+        self.node = node
+        self.role = role
+
+    def map_run_spec(self, framework_run: Any = None) -> dict[str, Any]:
+        return {"adapter": self.name, "role": self.role, "node": getattr(self.node, "__name__", repr(self.node))}
+
+    def as_agent(self):
+        return PythonFunctionAdapter(self.node, role=self.role).as_agent()

agentledger/adapters_mcp.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .tools import ToolRegistry, ToolSpec
+
+MCPCall = Callable[[str, dict[str, Any]], Any]
+MCPResourceRead = Callable[[str], Any]
+
+
+@dataclass(frozen=True)
+class MCPResourceDescriptor:
+    uri: str
+    name: str
+    mime_type: str = "application/json"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"uri": self.uri, "name": self.name, "mimeType": self.mime_type}
+
+
+class InMemoryMCPToolServer:
+    """Dependency-free MCP-style tool server fixture for examples/tests."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, tuple[dict[str, Any], MCPCall]] = {}
+
+    def add_tool(self, descriptor: dict[str, Any], handler: MCPCall) -> None:
+        self._tools[descriptor["name"]] = (descriptor, handler)
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        return [self._tools[name][0] for name in sorted(self._tools)]
+
+    def call_tool(self, name: str, args: dict[str, Any]) -> Any:
+        try:
+            _descriptor, handler = self._tools[name]
+        except KeyError as exc:
+            raise KeyError(f"MCP tool not found: {name}") from exc
+        return handler(name, args)
+
+
+class InMemoryMCPContextServer:
+    """Dependency-free MCP-style context/resource server fixture."""
+
+    def __init__(self) -> None:
+        self._resources: dict[str, tuple[MCPResourceDescriptor, MCPResourceRead]] = {}
+
+    def add_resource(self, *, uri: str, name: str, reader: MCPResourceRead, mime_type: str = "application/json") -> None:
+        self._resources[uri] = (MCPResourceDescriptor(uri=uri, name=name, mime_type=mime_type), reader)
+
+    def list_resources(self) -> list[dict[str, Any]]:
+        return [self._resources[uri][0].to_dict() for uri in sorted(self._resources)]
+
+    def read_resource(self, uri: str) -> Any:
+        try:
+            descriptor, reader = self._resources[uri]
+        except KeyError as exc:
+            raise KeyError(f"MCP resource not found: {uri}") from exc
+        return {"resource": descriptor.to_dict(), "content": reader(uri)}
+
+
+class MCPToolAdapter:
+    """Map MCP-style tool descriptors into AgentLedger ToolSpec objects.
+
+    The adapter is dependency-free: callers provide a `client_call` function that
+    knows how to invoke an MCP client. Runtime core still owns policy, ledger,
+    audit, budget, replay, and shadow semantics through ToolGateway.
+    """
+
+    name = "mcp-tool"
+
+    def __init__(self, client_call: MCPCall):
+        self.client_call = client_call
+
+    def tool_spec_from_descriptor(self, descriptor: dict[str, Any]) -> ToolSpec:
+        tool_name = descriptor["name"]
+        annotations = descriptor.get("annotations", {}) or {}
+        input_schema = descriptor.get("inputSchema") or descriptor.get("input_schema") or {}
+        side_effect = annotations.get("side_effect", "none")
+        risk_level = annotations.get("risk_level", "low")
+        idempotency_required = bool(annotations.get("idempotency_required", side_effect != "none"))
+
+        async def call(args: dict[str, Any]) -> Any:
+            result = self.client_call(tool_name, args)
+            if inspect.isawaitable(result):
+                return await result
+            return result
+
+        return ToolSpec(
+            name=tool_name,
+            func=call,
+            version=str(descriptor.get("version", "v1")),
+            input_schema=input_schema,
+            output_schema=descriptor.get("outputSchema") or descriptor.get("output_schema") or {},
+            side_effect=side_effect,
+            risk_level=risk_level,
+            idempotency_required=idempotency_required,
+        )
+
+    def register(self, registry: ToolRegistry, descriptor: dict[str, Any]) -> ToolSpec:
+        spec = self.tool_spec_from_descriptor(descriptor)
+        registry.register(spec)
+        return spec
+
+    def register_all(self, registry: ToolRegistry, descriptors: list[dict[str, Any]]) -> list[ToolSpec]:
+        return [self.register(registry, descriptor) for descriptor in descriptors]
+
+
+class MCPContextAdapter:
+    """Expose MCP-style context/resource reads through ToolGateway."""
+
+    name = "mcp-context"
+
+    def __init__(self, resource_read: Callable[[str], Any]):
+        self.resource_read = resource_read
+
+    def read_tool_spec(self, *, name: str = "mcp.context.read", risk_level: str = "low") -> ToolSpec:
+        async def call(args: dict[str, Any]) -> Any:
+            uri = args["uri"]
+            result = self.resource_read(uri)
+            if inspect.isawaitable(result):
+                return await result
+            return result
+
+        return ToolSpec(
+            name=name,
+            func=call,
+            version="v1",
+            description="Read an MCP-style context resource by URI.",
+            input_schema={
+                "type": "object",
+                "required": ["uri"],
+                "properties": {"uri": {"type": "string", "minLength": 1}},
+                "additionalProperties": False,
+            },
+            output_schema={"type": "object"},
+            side_effect="none",
+            risk_level=risk_level,
+        )
+
+    def register_read_tool(self, registry: ToolRegistry, *, name: str = "mcp.context.read", risk_level: str = "low") -> ToolSpec:
+        spec = self.read_tool_spec(name=name, risk_level=risk_level)
+        registry.register(spec)
+        return spec