ygo74-agent-runtime-agentframework 0.8.0__py3-none-any.whl

ygo74/agent_runtime/integrations/agentframework/progress.py

@@ -0,0 +1,313 @@
+"""Safe native tool activity and producer cleanup for the pinned SDK."""
+
+import inspect
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Any
+from uuid import uuid4
+
+from agent_framework import AgentResponseUpdate, BaseChatClient, ResponseStream
+from ygo74.agent_runtime.domains.contracts.agent_output import Notification
+from ygo74.agent_runtime.domains.contracts.stream_events import ContentEvent
+from ygo74.agent_runtime.domains.sessions.continuity_diagnostics import (
+    ContinuationReference,
+    ContinuityDiagnostics,
+)
+
+from .conversion import ConversionDecision, ConversionStatus
+
+_logger = logging.getLogger(__name__)
+_active_scope: ContextVar["NativeStreamScope | None"] = ContextVar("native_stream_scope", default=None)
+_PROVIDER_RESPONSE_METHOD = "_inner_get_response"
+
+
+class _ProviderResponseCapture:
+    """Keep provider streams reachable without inspecting SDK generator frames.
+
+    Args:
+        get_response: Bound SDK 1.18 provider method, preserving native options.
+    """
+
+    def __init__(self, get_response: Callable[..., Any]) -> None:
+        """Wrap one provider method once.
+
+        Args:
+            get_response: Original bound provider implementation.
+        """
+        self._get_response = get_response
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Capture the provider response in the current invocation only.
+
+        Args:
+            args: Native positional arguments, forwarded unchanged.
+            kwargs: Native provider-specific arguments, forwarded unchanged.
+        """
+        scope = _active_scope.get()
+        call = scope.provider_call(kwargs) if scope is not None else 0
+        result = self._get_response(*args, **kwargs)
+        if scope is None:
+            return result
+        if isinstance(result, ResponseStream):
+            scope.track(result)
+            result.with_result_hook(lambda response: scope.provider_result(response, call))
+            return result
+        if inspect.isawaitable(result):
+            return self._capture_awaited(result, scope, call)
+        return result
+
+    @staticmethod
+    async def _capture_awaited(result: Awaitable[Any], scope: "NativeStreamScope", call: int) -> Any:
+        """Support providers that resolve their response asynchronously.
+
+        Args:
+            result: Original provider awaitable.
+            scope: Invocation owning any stream it resolves.
+            call: Provider call index within the sub-run.
+        """
+        response = await result
+        if isinstance(response, ResponseStream):
+            scope.track(response)
+            response.with_result_hook(lambda final: scope.provider_result(final, call))
+        else:
+            scope.provider_result(response, call)
+        return response
+
+
+class NativeStreamScope:
+    """Own SDK provider streams hidden inside the function-invocation loop.
+
+    SDK 1.18 lacks a public ResponseStream.aclose and the function loop does not
+    close its local inner_stream on abandonment. A per-client provider-boundary
+    wrapper captures those streams during pulls. Context-local ownership avoids
+    mixing parallel sessions sharing a client; no agent is rebuilt.
+    """
+
+    def __init__(self, *, session_instance: str | None = None, turn: int = 0,
+                 subrun: int = 0, storage_default: bool = False) -> None:
+        """Initialize provider ownership and structural correlation.
+
+        Args:
+            session_instance: Runtime-generated binding instance.
+            turn: User invocation number.
+            subrun: Approval sub-run number.
+            storage_default: Native client default storage behavior.
+        """
+        self._streams: list[object] = []
+        self._session_instance = session_instance
+        self._turn, self._subrun = turn, subrun
+        self._storage_default = storage_default
+        self._calls = 0
+        self.missing_continuation = False
+        self.last_continuation: ContinuationReference | None = None
+
+    @property
+    def provider_called(self) -> bool:
+        """Whether this sub-run reached the instrumented native provider."""
+        return self._calls > 0
+
+    def provider_call(self, kwargs: dict[str, Any]) -> int:
+        """Observe effective SDK options without changing the request.
+
+        Args:
+            kwargs: Original SDK boundary arguments; content is never logged.
+        """
+        self._calls += 1
+        options = kwargs.get("options") or {}
+        ref = ContinuationReference.of(options.get("conversation_id"))
+        messages = kwargs.get("messages") or ()
+        self._record("request", self._calls, ref,
+                     provider_storage=options.get("store") if options.get("store") is not None else self._storage_default,
+                     stream=kwargs.get("stream", False), message_count=len(messages),
+                     user_message_count=sum(message.role == "user" for message in messages),
+                     assistant_message_count=sum(message.role == "assistant" for message in messages))
+        return self._calls
+
+    def provider_result(self, response: Any, call: int) -> None:
+        """Observe only successfully finalized provider responses.
+
+        Args:
+            response: SDK ChatResponse; payloads and raw provider IDs stay unread.
+            call: Provider call index.
+        """
+        ref = ContinuationReference.of(getattr(response, "conversation_id", None))
+        self.last_continuation = ref
+        self.missing_continuation = self.missing_continuation or ref.fingerprint is None
+        self._record("response", call, ref)
+
+    def _record(self, phase: str, call: int, ref: ContinuationReference,
+                **fields: str | int | bool | None) -> None:
+        """Emit safe subcall links.
+
+        Args:
+            phase: Request or finalized response.
+            call: Subcall index.
+            ref: Safe continuation metadata.
+            fields: Structural request counters/options.
+        """
+        ContinuityDiagnostics.record(
+            _logger, "native provider continuity", session_instance=self._session_instance,
+            turn=self._turn, subrun=self._subrun, provider_call=call, phase=phase,
+            provider_continuation_kind=ref.kind, provider_continuation_fingerprint=ref.fingerprint, **fields,
+        )
+
+    @staticmethod
+    def attach(client: object) -> None:
+        """Install an idempotent SDK 1.18 provider-boundary wrapper.
+
+        Args:
+            client: Existing native client; custom non-SDK clients are unchanged.
+        """
+        if isinstance(client, BaseChatClient):
+            original = getattr(client, _PROVIDER_RESPONSE_METHOD)
+            if not isinstance(original, _ProviderResponseCapture):
+                setattr(client, _PROVIDER_RESPONSE_METHOD, _ProviderResponseCapture(original))
+
+    def track(self, stream: object) -> None:
+        """Retain a provider until native sub-run cleanup.
+
+        Args:
+            stream: Provider ResponseStream created during this invocation.
+        """
+        self._streams.append(stream)
+
+    @contextmanager
+    def activate(self) -> Iterator[None]:
+        """Capture only a synchronous creation or an awaited native pull."""
+        token = _active_scope.set(self)
+        try:
+            yield
+        finally:
+            _active_scope.reset(token)
+
+    async def updates(self, producer: AsyncIterator[AgentResponseUpdate]) -> AsyncIterator[AgentResponseUpdate]:
+        """Capture provider creation while pulling, never across consumer yields.
+
+        Args:
+            producer: Native stream being consumed.
+        """
+        while True:
+            with self.activate():
+                try:
+                    update = await anext(producer)
+                except StopAsyncIteration:
+                    return
+            yield update
+
+    async def close(self, producer: object) -> None:
+        """Close all captured providers even when outer SDK cleanup fails.
+
+        Args:
+            producer: Outermost native response stream.
+        """
+        try:
+            await NativeStreamCloser.close(producer)
+        finally:
+            try:
+                for stream in reversed(self._streams):
+                    await NativeStreamCloser.close(stream)
+            finally:
+                self._streams.clear()
+
+
+class ToolProgressPolicy:
+    """Expose only admitted tool names and non-sensitive lifecycle states.
+
+    Args:
+        tool_names: Trusted declarations; unrecognized names are never exposed.
+    """
+
+    def __init__(self, tool_names: tuple[str, ...] = ()) -> None:
+        """Initialize per-sub-run activity correlation.
+
+        Args:
+            tool_names: Tool names from trusted configuration.
+        """
+        self._allowed = frozenset(tool_names)
+        self._calls: dict[str, str] = {}
+        self._completed: set[str] = set()
+
+    def observe(self, update: AgentResponseUpdate) -> tuple[ContentEvent, ...]:
+        """Return safe notices, deduplicating partial/parallel tool updates.
+
+        Args:
+            update: Native update; arguments and results are deliberately unread.
+        """
+        events = []
+        for content in update.contents:
+            call_id = content.call_id
+            if not call_id:
+                continue
+            if content.type == "function_call" and content.name in self._allowed and call_id not in self._calls:
+                self._calls[call_id] = content.name
+                events.append(ContentEvent(uuid4().hex, Notification(f"Calling {content.name}…")))
+            elif content.type == "function_result" and call_id in self._calls and call_id not in self._completed:
+                self._completed.add(call_id)
+                state = "Failed" if content.exception else "Completed"
+                events.append(ContentEvent(uuid4().hex, Notification(f"{state} {self._calls[call_id]}.")))
+        return tuple(events)
+
+
+class ConversionDiagnostics:
+    """Log reason codes with caller-generated correlation, never native payloads."""
+
+    @staticmethod
+    def record(decisions: tuple[ConversionDecision, ...], invocation_id: str) -> None:
+        """Record only structural conversion outcomes.
+
+        Args:
+            decisions: Adapter decisions without raw content.
+            invocation_id: Runtime-generated correlation identifier.
+        """
+        for decision in decisions:
+            if decision.status is not ConversionStatus.CONVERTED:
+                _logger.debug("native conversion", extra={
+                    "invocation_id": invocation_id,
+                    "conversion_status": decision.status.value,
+                    "conversion_reason": decision.reason.value,
+                })
+
+
+class NativeStreamCloser:
+    """Close SDK 1.18 producers on early exit.
+
+    SDK 1.18 ResponseStream has no public aclose. The compatibility shim walks
+    only its documented-in-source ownership fields and runs idempotent cleanup
+    hooks; it does not finalize an incomplete response as success.
+    """
+
+    @classmethod
+    async def close(cls, stream: object) -> None:
+        """Release nested ResponseStreams and their underlying async generators.
+
+        Args:
+            stream: Native producer owned by the binding.
+        """
+        seen: set[int] = set()
+        await cls._close(stream, seen)
+
+    @classmethod
+    async def _close(cls, stream: object, seen: set[int]) -> None:
+        """Visit each producer once, closing inner generators before hooks.
+
+        Args:
+            stream: Producer node.
+            seen: Identities already processed.
+        """
+        if id(stream) in seen:
+            return
+        seen.add(id(stream))
+        for name in ("_iterator", "_inner_stream", "_stream_source", "_inner_stream_source"):
+            child = getattr(stream, name, None)
+            if child is not None:
+                await cls._close(child, seen)
+        if inspect.iscoroutine(stream):
+            stream.close()
+        close: Callable[[], Any] | None = getattr(stream, "aclose", None)
+        if close is not None:
+            await close()
+        cleanup: Callable[[], Any] | None = getattr(stream, "_run_cleanup_hooks", None)
+        if cleanup is not None:
+            await cleanup()

ygo74/agent_runtime/integrations/agentframework/stream_adapter.py

@@ -0,0 +1,190 @@
+"""Per-invocation incremental SDK conversion, independent of HTTP protocols."""
+
+from __future__ import annotations
+
+import json
+
+from agent_framework import AgentResponseUpdate, Content
+from ygo74.agent_runtime.domains.contracts.agent_output import (
+    ReasoningContent,
+    Termination,
+    TerminationStatus,
+    TextContent,
+    ToolCallContent,
+    ToolExecution,
+)
+from ygo74.agent_runtime.domains.contracts.stream_events import (
+    AgentStreamEvent,
+    ContentEnd,
+    ContentEvent,
+    ContentStart,
+    TerminalEvent,
+    TextDelta,
+    ToolArgumentsDelta,
+    UsageEvent,
+)
+
+from .conversion import (
+    ConversionDecision,
+    ConversionReason,
+    ConversionStatus,
+    UpdateConversion,
+)
+from .output_adapter import NativeContentType, NativeFinishReason, _ContentMapper
+
+
+class AgentFrameworkStreamAdapter:
+    """Create one adapter per SDK invocation; call finish only after exhaustion.
+
+    Native finish reasons can terminate intermediate tool rounds, so updates
+    never emit a terminal event. The caller owns producer completion and policy.
+
+    Args:
+        expose_reasoning (bool): Whether reasoning content may be included in client-visible output.
+        tool_execution (ToolExecution): Whether tool calls are internal or delegated to the client.
+    """
+    def __init__(
+        self, *, expose_reasoning: bool = False,
+        tool_execution: ToolExecution = ToolExecution.INTERNAL,
+    ) -> None:
+        """Initialize the instance framework stream updates with supplied collaborators and configuration.
+
+        Args:
+            expose_reasoning (bool): Whether reasoning content may be included in client-visible output.
+            tool_execution (ToolExecution): Whether tool calls are internal or delegated to the client.
+        """
+        self._mapper = _ContentMapper(expose_reasoning=expose_reasoning, tool_execution=tool_execution)
+        self._active: dict[str, None] = {}
+        self._counter = 0
+        self._closed = False
+        self._termination = Termination()
+
+    def convert_update(self, update: AgentResponseUpdate) -> UpdateConversion:
+        """Translate one SDK update into correlated typed content and lifecycle events.
+
+        Args:
+            update (AgentResponseUpdate): Framework response update being translated into typed stream events.
+        """
+        # Route tool calls through their correlation path, exclude non-output roles, and translate text updates into one start followed by deltas for each active content identity.
+        if self._closed:
+            raise ValueError("cannot convert updates after finish")
+        if not isinstance(update, AgentResponseUpdate):
+            raise TypeError("update must be an AgentResponseUpdate")
+        if update.finish_reason is not None and self._termination.status is not TerminationStatus.FAILED:
+            self._termination = self._mapper.termination(update.finish_reason)
+        events: list[AgentStreamEvent] = []
+        decisions: list[ConversionDecision] = []
+        for index, content in enumerate(update.contents):
+            identity = content.id or f"{update.message_id or 'message'}:{content.type}:{index}"
+            if content.type == NativeContentType.CALL.value and content.call_id:
+                identity = f"tool:{content.call_id}"
+            if update.role is not None and update.role not in ("assistant", "tool"):
+                decisions.append(ConversionDecision(
+                    identity, content.type, ConversionStatus.EXCLUDED, ConversionReason.NON_OUTPUT_ROLE,
+                ))
+                continue
+            if content.type == NativeContentType.CALL.value:
+                self._call(content, identity, events, decisions)
+                continue
+            mapped = self._mapper.map(content, identity)
+            decisions.append(mapped.decision)
+            annotation_decision = self._mapper.annotation_decision(content, identity)
+            if annotation_decision is not None:
+                decisions.append(annotation_decision)
+            if mapped.usage is not None:
+                events.append(UsageEvent(mapped.usage))
+            if mapped.termination is not None:
+                self._termination = mapped.termination
+            if mapped.content is None:
+                continue
+            if isinstance(mapped.content, (TextContent, ReasoningContent)):
+                if identity not in self._active:
+                    initial = (ReasoningContent("", exposable=True)
+                               if isinstance(mapped.content, ReasoningContent) else TextContent(""))
+                    events.append(ContentStart(identity, initial))
+                    self._active[identity] = None
+                events.append(TextDelta(identity, mapped.content.text))
+                continue
+            if content.type == NativeContentType.RESULT.value:
+                call_identity = f"tool:{content.call_id}"
+                if call_identity in self._active:
+                    events.append(ContentEnd(call_identity))
+                    del self._active[call_identity]
+            self._counter += 1
+            events.append(ContentEvent(f"{identity}:complete-{self._counter}", mapped.content))
+        if update.finish_reason is not None and update.finish_reason not in NativeFinishReason:
+            decisions.append(ConversionDecision(
+                "update:finish", "finish_reason", ConversionStatus.UNSUPPORTED, ConversionReason.UNKNOWN_FINISH_REASON,
+            ))
+        return UpdateConversion(tuple(events), tuple(decisions))
+
+    def _call(
+        self, content: Content, identity: str,
+        events: list[AgentStreamEvent], decisions: list[ConversionDecision],
+    ) -> None:
+        """Emit a tool call start and argument fragments while keeping the framework call identity stable.
+
+        Args:
+            content (Content): The content item being interpreted or projected.
+            identity (str): Identifier required to correlate a route, content item, tool call, or user.
+            events (list[AgentStreamEvent]): The ordered typed events that describe the streamed response.
+            decisions (list[ConversionDecision]): Per-content conversion or filtering decisions returned to the caller.
+        """
+        name = content.name or self._mapper.tool_names.get(content.call_id or "")
+        if not content.call_id or not name or content.exception:
+            reason = ConversionReason.TOOL_ERROR if content.exception else ConversionReason.MISSING_TOOL_IDENTITY
+            decisions.append(ConversionDecision(identity, content.type, ConversionStatus.UNSUPPORTED, reason))
+            return
+        try:
+            arguments = (content.arguments if isinstance(content.arguments, str)
+                         else self._json_arguments(content.arguments))
+        except (ValueError, TypeError):
+            decisions.append(ConversionDecision(
+                identity, content.type, ConversionStatus.UNSUPPORTED, ConversionReason.INVALID_JSON,
+            ))
+            return
+        self._mapper.tool_names[content.call_id] = name
+        decisions.append(ConversionDecision(
+            identity, content.type, ConversionStatus.CONVERTED, ConversionReason.SUPPORTED,
+        ))
+        annotation_decision = self._mapper.annotation_decision(content, identity)
+        if annotation_decision is not None:
+            decisions.append(annotation_decision)
+        if identity not in self._active:
+            events.append(ContentStart(identity, ToolCallContent(
+                content.call_id, name, execution=self._mapper.tool_execution,
+            )))
+            self._active[identity] = None
+        if arguments:
+            events.append(ToolArgumentsDelta(identity, arguments))
+
+    @staticmethod
+    def _json_arguments(value: object) -> str:
+        """Serialize framework tool arguments to JSON text and report non-JSON values as unsupported.
+
+        Args:
+            value (object): The value being converted, checked, or serialized.
+        """
+        if value is None:
+            return ""
+        return json.dumps(_ContentMapper.json_value(value), separators=(",", ":"), allow_nan=False)
+
+    def finish(self, termination: Termination | None = None) -> tuple[AgentStreamEvent, ...]:
+        """Close active contents and emit exactly one caller-owned terminal.
+
+        Exceptions/cancellation are not success: propagate them or provide an
+        explicit failed/incomplete Termination rather than calling this on abort.
+
+        Args:
+            termination (Termination | None): Terminal outcome used to complete the result or stream.
+        """
+        if self._closed:
+            return ()
+        self._closed = True
+        events: list[AgentStreamEvent] = [ContentEnd(identity) for identity in self._active]
+        self._active.clear()
+        final = self._termination
+        if termination is not None and final.status is not TerminationStatus.FAILED:
+            final = termination
+        events.append(TerminalEvent(final))
+        return tuple(events)

ygo74/agent_runtime/integrations/agentframework/worker.py

@@ -0,0 +1,155 @@
+"""Native factory composition for the platform's managed reference worker."""
+
+import inspect
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager, AsyncExitStack
+from dataclasses import dataclass
+
+from agent_framework import Agent, InMemoryHistoryProvider, SupportsAgentRun
+from fastapi import FastAPI
+from ygo74.agent_runtime.domains.auth.agent_principal import AgentPrincipal
+from ygo74.agent_runtime.domains.contracts.agent_definition import (
+    AgentDefinition,
+    AgentFactoryContext,
+)
+from ygo74.agent_runtime.domains.endpoints.managed_worker import (
+    ManagedAgentWorker,
+    TrustedFactoryLoader,
+    WorkerSettings,
+)
+from ygo74.agent_runtime.domains.humanapproval.commands import ConfirmationCommand
+from ygo74.agent_runtime.domains.humanapproval.pending_renderer import (
+    PendingConfirmationRenderer,
+)
+from ygo74.agent_runtime.domains.humanapproval.tickets import (
+    InMemoryPendingConfirmationStore,
+    UnknownTicketError,
+)
+from ygo74.agent_runtime.domains.security.user_context import UserContext
+from ygo74.agent_runtime.domains.sessions.agent_conversation import (
+    AgentConversation,
+    ConversationPort,
+)
+
+from .binding import AgentFrameworkSession
+
+
+@dataclass(slots=True)
+class _NativeResources:
+    """Conversation scope, with no authorization inferred from native output.
+
+    Args:
+        user: Verified identity without any granted tool permissions.
+        scope: Factory dependency scope owned by this conversation.
+    """
+
+    user: UserContext
+    scope: AsyncExitStack
+
+    async def aclose(self) -> None:
+        """Close native factory dependencies exactly once."""
+        await self.scope.aclose()
+
+
+class _NoConfirmations:
+    """Reject replay commands for native agents without a ticket bridge."""
+
+    async def run(self, command: ConfirmationCommand) -> str:
+        """Refuse commands that cannot correspond to a stored ticket.
+
+        Args:
+            command: Parsed confirmation command.
+        """
+        raise UnknownTicketError(command.ticket_id)
+
+
+class AgentFrameworkWorker:
+    """Simple BYOA path: a native factory and definition, plus operator settings.
+
+    Args:
+        definition: Trusted native export and declarative identity/capabilities.
+        settings: Operator deployment/authentication/lifecycle configuration.
+        admission: Optional trusted deterministic tool-policy validation hook.
+        factory: Optional already-resolved native factory from trusted composition.
+    """
+
+    def __init__(
+        self, definition: AgentDefinition, settings: WorkerSettings, *,
+        admission: Callable[[AgentDefinition, SupportsAgentRun], None] | None = None,
+        factory: Callable[[AgentFactoryContext], object] | None = None,
+    ) -> None:
+        """Validate registration before any routes become available.
+
+        Args:
+            definition: Validated deployment definition.
+            settings: Runtime operator controls.
+            admission: Required for native tools; checks actual enforceable gates.
+            factory: Trusted DI override, never taken from request data.
+        """
+        if definition.tools and admission is None:
+            raise ValueError("native tools require an enforceable admission policy")
+        self._definition, self._settings, self._admission = definition, settings, admission
+        self._factory = factory or TrustedFactoryLoader.load(definition)
+        self.worker = ManagedAgentWorker(definition, settings, self._build)
+
+    def build_app(self) -> FastAPI:
+        """Build the platform-owned HTTP worker, not an agent-owned server."""
+        return self.worker.build_app()
+
+    async def _build(self, principal: AgentPrincipal, conversation_id: str) -> ConversationPort:
+        """Resolve a native agent with standard async dependency scopes.
+
+        Args:
+            principal: Verified caller associated with every factory dependency.
+            conversation_id: Caller-scoped history identifier.
+        """
+        if self._definition.require_email and not principal.email:
+            raise ValueError("native agent requires verified email")
+        context = AgentFactoryContext(principal, conversation_id, self._settings.deployment_id,
+                                      self._settings.identity_namespace)
+        scope = AsyncExitStack()
+        try:
+            resource = self._factory(context)
+            if inspect.isawaitable(resource):
+                resource = await resource
+            if isinstance(resource, AbstractAsyncContextManager):
+                resource = await scope.enter_async_context(resource)
+            if not isinstance(resource, SupportsAgentRun):
+                raise TypeError("native factory must return a runnable native agent or an async scope yielding one")
+            self._validate_agent(resource)
+            return AgentConversation(
+                _NativeResources(UserContext(user_id=principal.subject, session_id=conversation_id), scope),
+                AgentFrameworkSession(resource, session_id=conversation_id,
+                                      tool_names=tuple(tool.tool_name for tool in self._definition.tools)),
+                InMemoryPendingConfirmationStore(), _NoConfirmations(), conversation_id, PendingConfirmationRenderer(),
+            )
+        except BaseException:
+            await scope.aclose()
+            raise
+
+    def _validate_agent(self, agent: SupportsAgentRun) -> None:
+        """Reject undeclared native tools; declarations never grant permission.
+
+        Args:
+            agent: Factory output to check at the binding boundary.
+        """
+        if not isinstance(agent, Agent):
+            if self._admission is None:
+                raise ValueError("custom native agents require an explicit capability admission policy")
+            self._admission(self._definition, agent)
+            return
+        # Only the exact SDK history implementation has a known static surface.
+        # Other providers (including subclasses) can inject tools or middleware.
+        dynamic_context = any(type(provider) is not InMemoryHistoryProvider for provider in agent.context_providers)
+        if dynamic_context and self._admission is None:
+            raise ValueError("dynamic context providers require an explicit capability admission policy")
+        options = agent.default_options
+        native_tools = options.get("tools") or []
+        names = {getattr(tool, "name", None) for tool in native_tools}
+        declared = {tool.tool_name for tool in self._definition.tools}
+        if names != declared:
+            raise ValueError("native tools do not match admitted declarations")
+        if names and self._admission is None:
+            raise ValueError("native tools have no enforceable control point")
+        if self._admission is not None:
+            self._admission(self._definition, agent)