ygo74-agent-runtime-agents 0.1.0__tar.gz

ygo74_agent_runtime_agents-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: ygo74-agent-runtime-agents
+Version: 0.1.0
+Summary: Agent hosting for the ygo74 agent runtime: endpoints, discovery, sessions and human approval
+Requires-Python: >=3.12
+Requires-Dist: ygo74-agent-runtime-security==0.1.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typing-extensions>=4.12
+Provides-Extra: http
+Requires-Dist: fastapi>=0.115; extra == "http"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "http"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.24; extra == "mcp"
+Requires-Dist: httpx>=0.27; extra == "mcp"
+Requires-Dist: PyYAML>=6; extra == "mcp"

ygo74_agent_runtime_agents-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ygo74-agent-runtime-agents"
+version = "0.1.0"
+description = "Agent hosting for the ygo74 agent runtime: endpoints, discovery, sessions and human approval"
+requires-python = ">=3.12"
+
+# Everything needed to host an agent: the contracts, the capability registry, the
+# OpenAI/Anthropic endpoints, discovery, the conversation cache, the human-approval
+# domain, and the MCP *client* an agent uses to reach tools.
+dependencies = [
+  "ygo74-agent-runtime-security==0.1.0",
+  "pydantic>=2.7",
+  "typing-extensions>=4.12",
+]
+
+[project.optional-dependencies]
+# Serving the endpoints over HTTP. `fastapi` is imported defensively in
+# `domains.endpoints.fastapi_endpoints`, so a host that only needs the contracts or
+# the discovery descriptors installs none of this.
+http = [
+  "fastapi>=0.115",
+  "uvicorn[standard]>=0.30",
+]
+
+# Reaching tools through the Model Context Protocol - the client side. Only
+# `domains.mcp` needs it, and that package imports the SDK defensively for the same
+# reason `http` does.
+#
+# The upper bound is deliberate and was earned: `mcp` 2.0 moved to `httpx2` and
+# removed `streamablehttp_client`, so an unbounded floor silently installed a major
+# version this code cannot drive. Raising it is a migration, not a version bump.
+mcp = [
+  "mcp>=1.24,<2",
+  "httpx>=0.27",
+  "PyYAML>=6",
+]
+
+[tool.setuptools.packages.find]
+include = ["ygo74*"]
+namespaces = true
+
+# One marker per package this distribution alone owns. See the security
+# distribution's pyproject for why it cannot sit higher up.
+[tool.setuptools.package-data]
+"ygo74.agent_runtime.domains.configuration" = ["py.typed"]
+"ygo74.agent_runtime.domains.contracts" = ["py.typed"]
+"ygo74.agent_runtime.domains.discovery" = ["py.typed"]
+"ygo74.agent_runtime.domains.endpoints" = ["py.typed"]
+"ygo74.agent_runtime.domains.handlers" = ["py.typed"]
+"ygo74.agent_runtime.domains.humanapproval" = ["py.typed"]
+"ygo74.agent_runtime.domains.mapping" = ["py.typed"]
+"ygo74.agent_runtime.domains.mcp" = ["py.typed"]
+"ygo74.agent_runtime.domains.sessions" = ["py.typed"]
+"ygo74.agent_runtime.domains.streaming" = ["py.typed"]
+"ygo74.agent_runtime.middleware" = ["py.typed"]
+"ygo74.agent_runtime.observability" = ["py.typed"]
+"ygo74.agent_runtime.routing" = ["py.typed"]

ygo74_agent_runtime_agents-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/configuration/agent_http_settings.py

@@ -0,0 +1,120 @@
+"""How an agent is served over HTTP.
+
+Routing and posture only. No credential is read, held or logged here: a
+demonstration key is compared, never stored anywhere it could be printed, and
+tokens are validated against a published key set.
+
+Two things are deliberate.
+
+The settings are a plain ``pydantic`` model with an explicit
+:meth:`AgentHttpSettings.from_env` rather than a ``pydantic-settings`` class.
+Reading configuration is a host's business, and a library that imposed a settings
+framework on every consumer would be trading their choice for a few saved lines.
+A host already using ``pydantic-settings`` can still feed this model.
+
+And the key set is *discovered* rather than derived. Appending a path to the
+issuer only works for one provider; asking the issuer works for all of them. An
+explicit override still wins, because an operator who names a URL has a reason.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import timedelta
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import Self
+from ygo74.agent_runtime.domains.auth.oidc_discovery import OidcDiscovery
+
+DEFAULT_MAX_CONVERSATIONS = 200
+DEFAULT_IDLE_MINUTES = 30
+DEFAULT_ROLES_CLAIM_PATH = "realm_access.roles"
+
+
+class AgentHttpSettings(BaseModel):
+    """The posture one agent is served with.
+
+    Attributes:
+        api_key: Demonstration mode - one key, one caller. Ignored once an issuer
+            is configured: two ways in is one too many.
+        oidc_issuer: The identity provider tokens are validated against.
+        oidc_audience: The audience those tokens must carry.
+        jwks_url_override: A key-set URL named explicitly, which wins over
+            discovery.
+        roles_claim_path: Where roles sit in a token.
+        max_conversations: Upper bound on conversations kept in memory.
+        idle_minutes: How long an untouched conversation is kept.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    api_key: str = ""
+    oidc_issuer: str = ""
+    oidc_audience: str = ""
+    jwks_url_override: str = ""
+    roles_claim_path: str = DEFAULT_ROLES_CLAIM_PATH
+    max_conversations: int = Field(default=DEFAULT_MAX_CONVERSATIONS, ge=1)
+    idle_minutes: int = Field(default=DEFAULT_IDLE_MINUTES, ge=1)
+
+    @classmethod
+    def from_env(
+        cls,
+        prefix: str,
+        *,
+        default_audience: str = "",
+        environment: dict[str, str] | None = None,
+    ) -> Self:
+        """Read the settings of one agent from prefixed environment variables.
+
+        ``prefix`` is what distinguishes two agents served by the same process -
+        ``MAIL_AGENT_HTTP_``, ``WIKI_AGENT_HTTP_``. The key-set override is also
+        accepted as ``<prefix>JWKS_URL``, which is what an operator would guess.
+        """
+        source = environment if environment is not None else dict(os.environ)
+
+        def read(name: str, fallback: str = "") -> str:
+            return str(source.get(f"{prefix}{name}", fallback)).strip()
+
+        def read_int(name: str, fallback: int) -> int:
+            raw = read(name)
+            return int(raw) if raw else fallback
+
+        return cls(
+            api_key=read("API_KEY"),
+            oidc_issuer=read("OIDC_ISSUER"),
+            oidc_audience=read("OIDC_AUDIENCE", default_audience),
+            jwks_url_override=read("JWKS_URL") or read("JWKS_URL_OVERRIDE"),
+            roles_claim_path=read("ROLES_CLAIM_PATH", DEFAULT_ROLES_CLAIM_PATH),
+            max_conversations=read_int("MAX_CONVERSATIONS", DEFAULT_MAX_CONVERSATIONS),
+            idle_minutes=read_int("IDLE_MINUTES", DEFAULT_IDLE_MINUTES),
+        )
+
+    @property
+    def uses_oidc(self) -> bool:
+        """Whether tokens are validated against an identity provider."""
+        return bool(self.oidc_issuer)
+
+    @property
+    def identifies_a_caller(self) -> bool:
+        """Whether anything at all would establish who is calling.
+
+        A service that cannot answer this has no subject to partition state by,
+        and would serve one person's view to whoever asked first. Hosts are
+        expected to refuse to start rather than run open, which is a decision this
+        model reports rather than makes.
+        """
+        return self.uses_oidc or bool(self.api_key)
+
+    def jwks_url(self, discovery: OidcDiscovery | None = None) -> str:
+        """Where the signing keys of the issuer are published.
+
+        An explicit override wins. Otherwise the issuer is asked, through its
+        OpenID configuration document.
+        """
+        if self.jwks_url_override:
+            return self.jwks_url_override
+        return (discovery or OidcDiscovery()).jwks_url(self.oidc_issuer)
+
+    def idle_lifetime(self) -> timedelta:
+        """How long an untouched conversation is kept."""
+        return timedelta(minutes=self.idle_minutes)

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/configuration/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from ygo74.agent_runtime.domains.discovery.agent_descriptor import AgentDescriptor
+
+
+@dataclass(slots=True)
+class EndpointConfiguration:
+    route_key: str
+    enable_chat_completions: bool = False
+    enable_responses: bool = False
+    enable_anthropic_messages: bool = False
+    enable_streaming: bool = False
+    agent_descriptor: AgentDescriptor | None = None
+
+    @classmethod
+    def from_dict(cls, source: Mapping[str, Any]) -> EndpointConfiguration:
+        """Bind from a framework-native configuration section.
+
+        The optional ``agentDescriptor`` section is the declarative form of the
+        discovery single source of truth, so a host declares identity and
+        capabilities in the same settings block that enables the endpoints.
+        """
+
+        raw_descriptor = source.get("agentDescriptor")
+        return cls(
+            route_key=str(source["routeKey"]),
+            enable_chat_completions=bool(source.get("enableChatCompletions", False)),
+            enable_responses=bool(source.get("enableResponses", False)),
+            enable_anthropic_messages=bool(source.get("enableAnthropicMessages", False)),
+            enable_streaming=bool(source.get("enableStreaming", False)),
+            agent_descriptor=(
+                AgentDescriptor.from_dict(raw_descriptor) if isinstance(raw_descriptor, Mapping) else None
+            ),
+        )
+
+
+@dataclass(slots=True)
+class RuntimeConfiguration:
+    """Aggregate of every configured route, keyed for descriptor validation."""
+
+    endpoints: tuple[EndpointConfiguration, ...] = field(default_factory=tuple)
+
+    @property
+    def by_route_key(self) -> dict[str, EndpointConfiguration]:
+        return {endpoint.route_key: endpoint for endpoint in self.endpoints}
+
+    @property
+    def declared_descriptors(self) -> tuple[AgentDescriptor, ...]:
+        return tuple(
+            endpoint.agent_descriptor for endpoint in self.endpoints if endpoint.agent_descriptor is not None
+        )

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/configuration/validator.py

@@ -0,0 +1,12 @@
+from ygo74.agent_runtime.domains.configuration.models import EndpointConfiguration
+
+
+def validate_configuration(config: EndpointConfiguration) -> None:
+    if not config.route_key:
+        raise ValueError("route_key is required")
+
+    if not (config.enable_chat_completions or config.enable_responses or config.enable_anthropic_messages):
+        raise ValueError("At least one endpoint surface must be enabled")
+
+    if config.enable_streaming and not (config.enable_chat_completions or config.enable_responses or config.enable_anthropic_messages):
+        raise ValueError("Streaming requires at least one enabled endpoint")

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/contracts/capability_registry.py

@@ -0,0 +1,102 @@
+"""Registry of the capabilities an agent exposes.
+
+This is deliberately not an abstraction over an agent. It is the list of
+capabilities an orchestrator needs in order to build its own tools: a name, a
+description, an argument schema, the security posture and the coroutine that runs
+the capability.
+
+Microsoft Agent Framework, LangChain and CrewAI can each build their tools from
+this same registry, which is what keeps a set of capabilities from being written
+three times. Building the agent itself is left to each framework, in its own
+documented way.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from pydantic import BaseModel
+from ygo74.agent_runtime.domains.contracts.manifests import SkillManifest
+from ygo74.agent_runtime.domains.security.operations import ToolOperationDescriptor
+from ygo74.agent_runtime.domains.security.user_context import UserContext
+
+SkillInvocation = Callable[[BaseModel, UserContext], Awaitable[BaseModel]]
+
+
+class ResultRenderer(Protocol):
+    """Turns the typed result of a capability into the text a model reads.
+
+    Each agent renders its own results: what a search should look like in a
+    conversation is a domain decision, not a framework one. A framework adapter
+    asks for this and nothing more, which is what keeps it usable by the next
+    agent without a change.
+    """
+
+    def render(self, result: BaseModel | Sequence[BaseModel]) -> str:
+        """Render a capability result as text."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class SkillDescriptor:
+    """One capability, ready to be turned into a tool.
+
+    Attributes:
+        tool_name: Name advertised to the model.
+        description: What the capability does and what it does not do. The model
+            selects tools from this text, so it is part of the contract.
+        input_model: Schema the model must fill in. A contract, hence code.
+        operation: Security metadata driving the confirmation policy.
+        invoke: Coroutine executing the capability.
+    """
+
+    tool_name: str
+    description: str
+    input_model: type[BaseModel]
+    operation: ToolOperationDescriptor
+    invoke: SkillInvocation
+
+    def __post_init__(self) -> None:
+        """Reject a descriptor whose declared name does not match its operation."""
+        if self.tool_name != self.operation.tool_name:
+            raise ValueError(f"skill {self.tool_name!r} declares the operation of {self.operation.tool_name!r}")
+
+    @classmethod
+    def from_manifest(
+        cls,
+        manifest: SkillManifest,
+        input_model: type[BaseModel],
+        invoke: SkillInvocation,
+    ) -> SkillDescriptor:
+        """Bind a delivered manifest to the code that runs it."""
+        return cls(
+            tool_name=manifest.tool_name,
+            description=manifest.description,
+            input_model=input_model,
+            operation=manifest.operation,
+            invoke=invoke,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class SkillRegistry:
+    """The capabilities available to one agent, in the order they are offered."""
+
+    skills: Sequence[SkillDescriptor]
+
+    def skill(self, tool_name: str) -> SkillDescriptor:
+        """Return one capability by name."""
+        for descriptor in self.skills:
+            if descriptor.tool_name == tool_name:
+                return descriptor
+        raise KeyError(f"no skill named {tool_name!r} is registered")
+
+    def write_skills(self) -> tuple[SkillDescriptor, ...]:
+        """Capabilities that change external state.
+
+        Whether such a capability is actually gated depends on the confirmation
+        policy evaluated for a given caller, which lives outside the registry.
+        """
+        return tuple(descriptor for descriptor in self.skills if descriptor.operation.is_write)

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/contracts/contract_errors.py

@@ -0,0 +1,22 @@
+"""Errors raised when a request does not satisfy an agent contract.
+
+Separate from the authentication and authorization errors: nothing here says a
+caller was refused, only that what arrived cannot be answered as written.
+"""
+
+from __future__ import annotations
+
+
+class AgentContractError(Exception):
+    """Base class for a request that violates an agent contract."""
+
+
+class EmptyRequestError(AgentContractError):
+    """Raised when a request carries nothing for the agent to answer.
+
+    Reported rather than answered with silence: an agent replying to an empty
+    message would look like a model failure instead of a malformed request.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("the request carried no user message")

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/contracts/conversation.py

@@ -0,0 +1,77 @@
+"""What a serving surface needs from an agent, and nothing more.
+
+An HTTP surface should not know which agentic framework answers it, and an agent
+should not know which protocol carried the question. Between the two sits one
+port: a turn goes in, a reply comes out.
+
+Keeping it this narrow is what lets several frameworks be compared honestly.
+Microsoft Agent Framework, LangChain and CrewAI each provide an implementation;
+everything in front of it - identity, transport, session isolation - is written
+once and measured once, so a benchmark compares the frameworks rather than three
+home-grown web layers.
+
+Nothing here imports a framework or a transport.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from ygo74.agent_runtime.domains.auth.agent_principal import AgentPrincipal
+
+
+@dataclass(frozen=True, slots=True)
+class ConversationTurn:
+    """One question, from an identified person, in a named conversation.
+
+    Attributes:
+        principal: Who is asking. Established by the transport, never by the
+            message, and never carrying a credential.
+        conversation_id: What this turn continues. Supplied by the caller, so it
+            is a routing handle rather than a permission: it selects state only
+            once combined with the authenticated subject.
+        message: What the person wrote, verbatim.
+    """
+
+    principal: AgentPrincipal
+    conversation_id: str
+    message: str
+
+    @property
+    def key(self) -> tuple[str, str]:
+        """The pair that identifies this conversation's state.
+
+        The subject comes first because it is the part that was authenticated:
+        no conversation identifier can reach state belonging to someone else.
+        """
+        return (self.principal.subject, self.conversation_id)
+
+
+@dataclass(frozen=True, slots=True)
+class AgentReply:
+    """What the agent answered, and what it left waiting.
+
+    Attributes:
+        text: The answer, as the person should read it.
+        pending_confirmations: Identifiers of operations described but *not*
+            performed, awaiting an explicit answer. Empty means nothing is
+            waiting - never that everything succeeded.
+    """
+
+    text: str
+    pending_confirmations: tuple[str, ...] = ()
+
+    @property
+    def awaits_confirmation(self) -> bool:
+        """Whether this turn left something unperformed on purpose."""
+        return bool(self.pending_confirmations)
+
+
+@runtime_checkable
+class ConversationEngine(Protocol):
+    """Answers one turn of a conversation."""
+
+    async def respond(self, turn: ConversationTurn) -> AgentReply:
+        """Return the agent's answer to a turn."""
+        ...

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/contracts/error_envelope.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class ErrorEnvelope:
+    code: str
+    category: str
+    message: str
+    details: Any | None = None
+    request_id: str | None = None
+    retryable: bool | None = None

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/contracts/exchange_models.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from ygo74.agent_runtime.domains.contracts.error_envelope import ErrorEnvelope
+
+
+@dataclass(slots=True)
+class StandardExchangeRequest:
+    request_id: str
+    route_key: str
+    endpoint_type: str
+    input: Any
+    stream: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+    auth_context: dict[str, Any] | None = None
+
+
+@dataclass(slots=True)
+class StandardExchangeResponse:
+    request_id: str
+    status: str
+    output: Any | None = None
+    error: ErrorEnvelope | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/contracts/manifests.py

@@ -0,0 +1,75 @@
+"""Typed description of a skill and of an agent.
+
+A manifest is the resolved, validated form of what configuration declares:
+identity, description, security posture and, for a skill driven by a language
+model, its prompt. It carries no file format, no framework type and no callable,
+so the same manifests drive one orchestrator today and another tomorrow.
+
+What a manifest deliberately does not carry: the deterministic logic of a skill
+and the schema of its arguments. Both are contracts expressed in code.
+
+How a manifest is *loaded* - from YAML, from a database, from a service - is a
+host decision and stays outside this library.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from ygo74.agent_runtime.domains.security.operations import ToolOperationDescriptor
+
+
+class SkillManifest(BaseModel):
+    """What configuration declares about one capability.
+
+    Attributes:
+        tool_name: Name advertised to the model.
+        implementation: Key binding the manifest to the code that runs it.
+        description: What the capability does and does not do. The model selects
+            tools from this text, so it is part of the contract.
+        operation: Security metadata driving the confirmation policy.
+        mcp_tools: Logical tools the capability is allowed to use.
+        prompt: Reasoning instructions. Empty for a deterministic capability.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    tool_name: str = Field(min_length=1)
+    implementation: str = Field(min_length=1)
+    description: str = Field(min_length=1)
+    operation: ToolOperationDescriptor
+    mcp_tools: tuple[str, ...] = ()
+    prompt: str = ""
+
+    @model_validator(mode="after")
+    def _check_operation_matches(self) -> SkillManifest:
+        """Reject a manifest declaring the security posture of another tool."""
+        if self.operation.tool_name != self.tool_name:
+            raise ValueError(f"skill {self.tool_name!r} declares the operation of {self.operation.tool_name!r}")
+        return self
+
+    @property
+    def is_reasoning(self) -> bool:
+        """Whether the capability drives a language model."""
+        return bool(self.prompt)
+
+
+class AgentManifest(BaseModel):
+    """What configuration declares about one agent.
+
+    ``skills`` lists the capabilities the agent exposes, in the order they are
+    offered to the model.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str = Field(min_length=1)
+    description: str = Field(min_length=1)
+    instructions: str = Field(min_length=1)
+    skills: tuple[SkillManifest, ...] = ()
+
+    def skill(self, tool_name: str) -> SkillManifest:
+        """Return one declared capability by name."""
+        for manifest in self.skills:
+            if manifest.tool_name == tool_name:
+                return manifest
+        raise KeyError(f"agent {self.name!r} declares no skill named {tool_name!r}")

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/contracts/stream_events.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class StandardStreamingExchangeEvent:
+    request_id: str
+    sequence: int
+    event_type: str
+    delta: Any | None = None
+    final_output: Any | None = None
+    error: dict[str, Any] | None = None

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/discovery/__init__.py

@@ -0,0 +1,7 @@
+"""Agent capability discovery domain.
+
+Holds the single source of truth for agent identity and capabilities
+(:class:`AgentDescriptor`), the registry that owns uniqueness and ordering, and
+the stateless projections that render descriptors into provider-compatible and
+A2A wire shapes.
+"""

ygo74_agent_runtime_agents-0.1.0/ygo74/agent_runtime/domains/discovery/agent_access_policy.py

@@ -0,0 +1,59 @@
+"""Developer-supplied authorization policy shared by discovery and invocation.
+
+Authorization decisions still belong to the developer -- the runtime never
+invents a rule on its own -- but a single :class:`AgentAccessPolicy` is now the
+one place that decision lives, instead of being duplicated inside every
+entrypoint. The runtime calls ``is_authorized`` at two points with the same
+descriptor and the same authenticated context:
+
+- Before dispatching an invocation (``/v1/responses``, ``/v1/chat/completions``,
+  ``/v1/messages``): a denial raises :class:`AuthorizationError`, mapped to
+  HTTP 403.
+- While serving discovery (``GET /v1/models`` and ``GET /v1/models/{id}``): a
+  denied agent is filtered out of listings and its direct retrieval reports
+  404, exactly like a hidden agent, so a caller never sees an entry it would
+  immediately be denied for.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from ygo74.agent_runtime.domains.auth.auth_context import AuthenticatedUserContext
+from ygo74.agent_runtime.domains.discovery.agent_descriptor import AgentDescriptor
+
+
+@runtime_checkable
+class AgentAccessPolicy(Protocol):
+    """Contract for the single authorization rule reused across every agent-scoped route."""
+
+    def is_authorized(
+        self,
+        descriptor: AgentDescriptor,
+        auth_context: AuthenticatedUserContext | None,
+    ) -> bool:
+        """Return ``True`` when ``auth_context`` may see and invoke ``descriptor``."""
+        ...
+
+
+@dataclass(slots=True)
+class RoleRequiredAccessPolicy:
+    """Ready-made policy denying callers who lack a single required role.
+
+    Applies uniformly to every descriptor. Leave ``required_role`` empty to
+    allow any caller, including anonymous ones.
+    """
+
+    required_role: str = ""
+
+    def is_authorized(
+        self,
+        descriptor: AgentDescriptor,
+        auth_context: AuthenticatedUserContext | None,
+    ) -> bool:
+        if not self.required_role:
+            return True
+        if auth_context is None:
+            return False
+        return auth_context.has_role(self.required_role)