agentdeck-sdk 3.1.0__py3-none-any.whl

agentdeck/adapters/tools/mcp/source.py

@@ -0,0 +1,47 @@
+"""``ToolSourcePort`` over the MCP server registry.
+
+An invocable names the servers it wants in ``InvocableSpec.metadata``; this hands back the
+ones that are connected, the names of the ones that are not, and the banner that makes a
+model report the gap. Unknown, unconfigured and unreachable all resolve the same way — a
+:class:`ToolSet` — because MCP being down degrades a run, never fails it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agentdeck.adapters.tools.mcp.wiring import mcp_status_banner, resolve_agent_mcp_status
+from agentdeck.core.ports.tools import ToolSet, ToolSourcePort
+
+if TYPE_CHECKING:
+    from agentdeck.core.invocable import InvocableSpec
+
+MCP_SERVER_NAMES_KEY = "mcp_server_names"
+"""``InvocableSpec.metadata`` key holding the MCP server names an invocable declares."""
+
+
+class MCPToolSource(ToolSourcePort):
+    """The project's MCP servers, as one tool source.
+
+    Stateless: the servers themselves live in :class:`MCPLifecycle`, which the composition
+    root connects at startup and closes at shutdown — resolving never connects, so it is
+    safe to call while building a prompt. Not free, though: on a cold cache the first call
+    materialises process settings, which reads the config files off disk.
+    """
+
+    def resolve(self, spec: InvocableSpec) -> ToolSet:
+        declared = spec.metadata.get(MCP_SERVER_NAMES_KEY) or ()
+        if isinstance(declared, str):  # a lone name, not a list of characters
+            declared = (declared,)
+        # metadata is free-form, so nothing has checked these are strings yet; a name that
+        # isn't one is reported missing rather than exploding somewhere further in.
+        declared = tuple(str(name) for name in declared)
+        available, missing = resolve_agent_mcp_status(declared)
+        return ToolSet(
+            tools=tuple(available),
+            unavailable=tuple(missing),
+            notice=mcp_status_banner(missing),
+        )
+
+
+__all__ = ["MCP_SERVER_NAMES_KEY", "MCPToolSource"]

agentdeck/adapters/tools/mcp/transport.py

@@ -0,0 +1,234 @@
+"""``MCPServerStreamableHttp`` hardened for real deployments.
+
+Adds what the SDK leaves out: connect-time retry, and — after an MCP server
+restart drops our session id — detection of the resulting mid-session 404 plus
+a transparent re-``initialize`` + replay, so tool calls self-heal without a
+harness restart.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import AsyncExitStack, suppress
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import httpx
+from agents.mcp import MCPServerStreamableHttp
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+logger = logging.getLogger(__name__)
+
+_T = TypeVar("_T")
+
+
+class MCPServerStreamableHttpResilient(MCPServerStreamableHttp):
+    """HTTP MCP client that retries connect and recovers a dropped session.
+
+    Recovery splits by whether the connection is still there:
+
+    * A live-connection hiccup (read timeout, protocol blip, 5xx) is retried on
+      the **same session** — cheap, no rebuild (SDK ``max_retry_attempts``).
+    * A **gone** connection — a dropped session id (404) or an unreachable server
+      (:meth:`_connection_gone`) — skips that retry and escalates at once to a
+      fresh ``connect()`` + replay (:meth:`_with_recovery`), the only thing that
+      fixes a new-session-needed restart or a torn-down stream. Connect itself
+      retries transient errors; auth / bad-URL 404 stay fatal (:meth:`_is_transient`).
+
+    The SDK wraps transport failures in ``UserError`` (``__cause__`` is the real
+    error), so the predicates walk the cause chain.
+    """
+
+    TRANSIENT_HTTPX_EXCEPTIONS: tuple[type[BaseException], ...] = (
+        httpx.ConnectError,
+        httpx.ConnectTimeout,
+        httpx.ReadTimeout,
+        httpx.RemoteProtocolError,
+    )
+    # The connection itself is unavailable — a same-session retry can't help, only a
+    # reconnect can. (``ReadTimeout``/``RemoteProtocolError`` are NOT here: the
+    # connection is alive, the request just hiccuped, so retrying it is worth it.)
+    CONNECTION_GONE_EXCEPTIONS: tuple[type[BaseException], ...] = (
+        httpx.ConnectError,
+        httpx.ConnectTimeout,
+    )
+    FATAL_STATUS_CODES: frozenset[int] = frozenset({401, 403, 404})
+    # A mid-session 404 means a dropped session id (restart), not a bad URL.
+    SESSION_LOST_STATUS_CODES: frozenset[int] = frozenset({404})
+
+    def __init__(
+        self,
+        *args: Any,
+        connect_max_attempts: int = 3,
+        connect_backoff_base_seconds: float = 1.0,
+        max_retry_attempts: int = 5,  # same-session retry for live hiccups; gone conns skip it
+        retry_backoff_seconds_base: float = 1.0,
+        reconnect_max_attempts: int = 2,
+        reconnect_backoff_base_seconds: float = 0.5,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            *args,
+            max_retry_attempts=max_retry_attempts,
+            retry_backoff_seconds_base=retry_backoff_seconds_base,
+            **kwargs,
+        )
+        self.connect_max_attempts = connect_max_attempts
+        self.connect_backoff_base_seconds = connect_backoff_base_seconds
+        self.reconnect_max_attempts = reconnect_max_attempts
+        self.reconnect_backoff_base_seconds = reconnect_backoff_base_seconds
+
+    async def connect(self) -> None:
+        last_exc: BaseException | None = None
+        for attempt in range(1, self.connect_max_attempts + 1):
+            try:
+                await super().connect()
+                if attempt > 1:
+                    logger.info("MCP connect succeeded for %s on attempt %d", self.name, attempt)
+                return
+            except BaseException as exc:
+                last_exc = exc
+                if not self._is_transient(exc):
+                    raise
+            backoff = self.connect_backoff_base_seconds * (2 ** (attempt - 1))
+            logger.warning(
+                "MCP connect to %s failed (attempt %d/%d) — retrying in %.1fs",
+                self.name,
+                attempt,
+                self.connect_max_attempts,
+                backoff,
+            )
+            await asyncio.sleep(backoff)
+        if last_exc is None:  # only reachable if the loop ran zero times (attempts < 1)
+            raise RuntimeError(f"MCP connect to {self.name} made no attempt")
+        raise last_exc
+
+    @classmethod
+    def _is_transient(cls, exc: BaseException) -> bool:
+        """Retryable connect-time transport error? Walks the cause chain."""
+        seen: set[int] = set()
+        current: BaseException | None = exc
+        while current is not None and id(current) not in seen:
+            seen.add(id(current))
+            if isinstance(current, httpx.HTTPStatusError):
+                return current.response.status_code not in cls.FATAL_STATUS_CODES
+            if isinstance(current, cls.TRANSIENT_HTTPX_EXCEPTIONS):
+                return True
+            current = current.__cause__ or current.__context__
+        return False
+
+    @classmethod
+    def _is_session_lost(cls, exc: BaseException) -> bool:
+        """Mid-session 404 (server dropped our session id)? Walks the cause chain."""
+        seen: set[int] = set()
+        current: BaseException | None = exc
+        while current is not None and id(current) not in seen:
+            seen.add(id(current))
+            if isinstance(current, httpx.HTTPStatusError):
+                return current.response.status_code in cls.SESSION_LOST_STATUS_CODES
+            current = current.__cause__ or current.__context__
+        return False
+
+    @classmethod
+    def _connection_gone(cls, exc: BaseException) -> bool:
+        """Connection unavailable — dropped session id (404) or unreachable server.
+
+        These must NOT be retried on the same session (there's nothing live to retry);
+        recovery reconnects instead. A live-connection hiccup returns False.
+        """
+        seen: set[int] = set()
+        current: BaseException | None = exc
+        while current is not None and id(current) not in seen:
+            seen.add(id(current))
+            if isinstance(current, httpx.HTTPStatusError):
+                if current.response.status_code in cls.SESSION_LOST_STATUS_CODES:
+                    return True
+            elif isinstance(current, cls.CONNECTION_GONE_EXCEPTIONS):
+                return True
+            current = current.__cause__ or current.__context__
+        return False
+
+    async def _run_with_retries(self, func: Callable[[], Awaitable[_T]]) -> _T:
+        """Same-session retry for live hiccups; skip it when the connection is gone.
+
+        A dead session / unreachable server (:meth:`_connection_gone`) surfaces at
+        once so :meth:`_with_recovery` reconnects instead of retrying a connection
+        that isn't there. Everything else keeps the SDK's backoff policy.
+        """
+        attempts = 0
+        while True:
+            try:
+                return await func()
+            except Exception as exc:
+                if self._connection_gone(exc):
+                    raise
+                attempts += 1
+                if self.max_retry_attempts != -1 and attempts > self.max_retry_attempts:
+                    raise
+                await asyncio.sleep(self.retry_backoff_seconds_base * (2 ** (attempts - 1)))
+
+    async def _reconnect(self) -> None:
+        """Drop the stale session and re-run ``initialize`` for a fresh session id."""
+        with suppress(Exception):  # dead transport teardown is best-effort
+            await self.cleanup()  # aclose()s the old streams and nulls self.session
+        self.exit_stack = AsyncExitStack()  # cleanup aclosed the old one
+        await self.connect()
+
+    async def _with_recovery(self, call: Callable[[], Awaitable[_T]]) -> _T:
+        """Run ``call``; only when the connection is *gone* re-initialize and replay.
+
+        Bounded + backed off. Fires on :meth:`_connection_gone` (dropped session id or
+        unreachable server) — a server restart or a torn-down stream. A live-connection
+        hiccup is NOT recovered here; it already had its same-session retry in
+        :meth:`_run_with_retries` and is re-raised.
+        """
+        try:
+            return await call()
+        except BaseException as exc:
+            if not self._connection_gone(exc):
+                raise
+        last: BaseException | None = None
+        for attempt in range(1, self.reconnect_max_attempts + 1):
+            logger.warning(
+                "MCP %s: connection lost (server restart/outage?) — re-initializing (attempt %d/%d)",
+                self.name,
+                attempt,
+                self.reconnect_max_attempts,
+            )
+            try:
+                await self._reconnect()
+                result = await call()
+            except BaseException as exc:
+                last = exc
+                if not self._connection_gone(exc):
+                    raise
+            else:
+                logger.info("MCP %s: connection recovered on attempt %d", self.name, attempt)
+                return result
+            await asyncio.sleep(self.reconnect_backoff_base_seconds * (2 ** (attempt - 1)))
+        if last is None:  # only reachable if reconnect_max_attempts < 1
+            raise RuntimeError(f"MCP {self.name} recovery made no attempt")
+        logger.error("MCP %s: connection recovery failed after %d attempts", self.name, self.reconnect_max_attempts)
+        raise last
+
+    # ``run_context`` / ``agent`` / return types are the SDK's; typed ``Any`` here so
+    # these thin recovery wrappers need no import block just to restate them.
+    async def list_tools(self, run_context: Any = None, agent: Any = None) -> Any:
+        return await self._with_recovery(
+            lambda: super(MCPServerStreamableHttpResilient, self).list_tools(run_context, agent)
+        )
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> Any:
+        return await self._with_recovery(
+            lambda: super(MCPServerStreamableHttpResilient, self).call_tool(tool_name, arguments, meta)
+        )
+
+
+__all__ = ["MCPServerStreamableHttpResilient"]

agentdeck/adapters/tools/mcp/wiring.py

@@ -0,0 +1,63 @@
+"""Wiring MCP servers into agents, and the strict-protocol banner.
+
+Turns an agent's declared server names into the SDK instances to attach, and —
+when some are unavailable — a prompt banner that makes the model report the gap
+instead of fabricating an answer.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agentdeck.adapters.tools.mcp.lifecycle import MCPLifecycle
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from agents.mcp import MCPServer
+
+
+def resolve_agent_mcp_status(names: Iterable[str]) -> tuple[list[MCPServer], list[str]]:
+    """Split declared names into ``(available_servers, missing_names)``.
+
+    "Missing" = unknown to the registry or its connect failed. ``authoring.compile.compile_agent``
+    feeds the missing list to :func:`mcp_status_banner`.
+    """
+    available: list[MCPServer] = []
+    missing: list[str] = []
+    for name in names:
+        server = MCPLifecycle.resolve_or_pending(name)
+        if server is None or not MCPLifecycle.is_available(name):
+            missing.append(name)
+        else:
+            available.append(server)
+    return available, missing
+
+
+def resolve_agent_mcp_servers(names: Iterable[str]) -> list[MCPServer]:
+    """The available servers for ``names`` (missing ones dropped)."""
+    return resolve_agent_mcp_status(names)[0]
+
+
+def mcp_status_banner(missing: Sequence[str]) -> str:
+    """Strict-protocol banner prepended to an agent's instructions when servers are down.
+
+    Empty when nothing is missing — keeps the happy-path prompt bit-identical so
+    prompt-cache hits are unaffected.
+    """
+    if not missing:
+        return ""
+    names = ", ".join(f"`{n}`" for n in missing)
+    return (
+        "## Runtime MCP status\n\n"
+        f"The following MCP server(s) you depend on are UNAVAILABLE: {names}.\n"
+        "Tools from those servers are NOT exposed to you in this turn.\n"
+        "If the user's request requires those tools, reply with exactly:\n\n"
+        "    error: mcp_unavailable: <server-name>\n\n"
+        "and stop. Do not invent results. Do not retry. Do not call other "
+        "tools as a substitute unless the user explicitly asks for an "
+        "alternative.\n\n---\n\n"
+    )
+
+
+__all__ = ["mcp_status_banner", "resolve_agent_mcp_servers", "resolve_agent_mcp_status"]

agentdeck/authoring/__init__.py

@@ -0,0 +1,22 @@
+"""The v3 authoring surface: declare agents and workflows, compile to ``InvocableSpec``.
+
+``Deck`` (composition) and the Runtime (execution) are elsewhere — this package only turns
+declarations into what an engine runs.
+"""
+
+from agentdeck.authoring.agent import Agent, AgentDeclaration
+from agentdeck.authoring.interrupts import InterruptResult
+from agentdeck.authoring.nodes import AgentNode, LoadFileNode
+from agentdeck.authoring.timers import sleep_until
+from agentdeck.authoring.workflow import Workflow, WorkflowDeclaration
+
+__all__ = [
+    "Agent",
+    "AgentDeclaration",
+    "AgentNode",
+    "InterruptResult",
+    "LoadFileNode",
+    "Workflow",
+    "WorkflowDeclaration",
+    "sleep_until",
+]

agentdeck/authoring/agent.py

@@ -0,0 +1,169 @@
+"""``Agent``: the one construction API for an SDK agent, plus the declaration it can start from.
+
+v1's ``BaseAgent`` (a class users subclassed) is renamed ``AgentDeclaration`` here — it is a
+declarative *input* to ``Agent(...)``, never something invoked on its own (ruling 10,
+plan-phase4-deck.md). ``Agent`` instances are immutable: a ``Deck`` compiles them once at
+``build()``, and mutating one afterwards must have no effect on what was already compiled
+(ruling 3) — immutability makes that true by construction rather than by convention.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+    from agents.agent_output import AgentOutputSchemaBase
+    from agents.lifecycle import AgentHooks
+
+_UNSET: Any = object()
+
+
+class AgentDeclaration:
+    """Reusable defaults for :class:`Agent`.
+
+    Subclass and set class attributes to build a shareable base:
+
+        class BookingBase(AgentDeclaration):
+            instructions = "You handle bookings."
+
+        booking = Agent(base=BookingBase, name="booking", tools=[...])
+
+    Never constructed or run directly — it exists only to be named as ``Agent(base=...)``.
+    """
+
+    name: ClassVar[str | None] = None
+    instructions: ClassVar[str | Callable[..., Any]] = ""
+    handoff_description: ClassVar[str | None] = None
+    model: ClassVar[str | None] = None
+    model_settings: ClassVar[Mapping[str, Any]] = {}
+    tools: ClassVar[Sequence[Any]] = ()
+    handoffs: ClassVar[Sequence[Any]] = ()
+    output_type: ClassVar[type[Any] | AgentOutputSchemaBase | None] = None
+    hooks: ClassVar[AgentHooks | None] = None
+    skills: ClassVar[Sequence[str]] = ()
+    mcp: ClassVar[Sequence[str]] = ()
+
+
+class Agent:
+    """A declarative agent: name, instructions, tools, and the names of the skills/MCP
+    servers/workflows it depends on — resolved against the owning :class:`~agentdeck.Deck`'s
+    catalog at ``build()``, never at construction time, so an ``Agent`` built alone (with no
+    ``Deck`` yet) never fails for referencing something it cannot see yet.
+
+    ``base=`` is keyword-only by construction: every parameter here follows a bare ``*``, so
+    ``Agent(SomeDeclaration, name=...)`` is a ``TypeError`` rather than a silently-accepted
+    positional base. A value explicitly passed here always wins over ``base``'s, including an
+    explicit empty value — omission, not falsiness, is what defers to the base.
+
+    ``instructions=`` takes a plain string, or a callable ``build()`` compiles into the SDK's
+    dynamic-instructions shape — one declaring a ``Context[...]`` parameter receives the run's
+    environment, and **only what it returns** reaches the model. ``hooks=`` stays an Agents SDK
+    ``AgentHooks`` object; a hook method that declares ``Context[...]`` first is bridged the
+    same way, and one that does not is passed through untouched.
+
+    ``tools=`` takes plain functions — ``build()`` compiles each one, which is what lets a
+    parameter annotated ``Context[...]`` be injected without ever appearing in the schema the
+    model sees. An already-built Agents SDK tool object is still accepted and passed straight
+    through as engine-native, introspected by nothing here. A callable whose signature cannot be
+    read is refused at ``build()``, naming the agent and the callable.
+    """
+
+    __slots__ = (
+        "name",
+        "instructions",
+        "handoff_description",
+        "model",
+        "model_settings",
+        "tools",
+        "handoffs",
+        "output_type",
+        "hooks",
+        "skills",
+        "mcp",
+    )
+
+    # Typed alongside `__slots__` so a type checker can see these as real attributes — the
+    # values are set via `object.__setattr__` in `__init__`, which a bare `self.x = ...` a
+    # checker infers attributes from would not need, but immutability (see `__setattr__`
+    # below) does.
+    name: str
+    instructions: str | Callable[..., Any]
+    handoff_description: str | None
+    model: str | None
+    model_settings: dict[str, Any]
+    tools: tuple[Any, ...]
+    handoffs: tuple[Any, ...]
+    output_type: type[Any] | AgentOutputSchemaBase | None
+    hooks: AgentHooks | None
+    skills: tuple[str, ...]
+    mcp: tuple[str, ...]
+
+    def __init__(
+        self,
+        *,
+        base: type[AgentDeclaration] | None = None,
+        name: str = _UNSET,
+        instructions: str | Callable[..., Any] = _UNSET,
+        handoff_description: str | None = _UNSET,
+        model: str | None = _UNSET,
+        model_settings: Mapping[str, Any] = _UNSET,
+        tools: Sequence[Any] = _UNSET,
+        handoffs: Sequence[Any] = _UNSET,
+        output_type: type[Any] | AgentOutputSchemaBase | None = _UNSET,
+        hooks: AgentHooks | None = _UNSET,
+        skills: Sequence[str] = _UNSET,
+        mcp: Sequence[str] = _UNSET,
+    ) -> None:
+        source = base if base is not None else AgentDeclaration
+        resolved_name = source.name if name is _UNSET else name
+        if not resolved_name and base is not None:
+            # A subclassed declaration that never set `name` names itself after its class,
+            # the same convenience v1's `cls.name or cls.__name__` gave a `BaseAgent` subclass.
+            resolved_name = base.__name__
+        if not resolved_name:
+            raise ValueError("Agent(name=...) is required (directly, or via base=).")
+        object.__setattr__(self, "name", resolved_name)
+        object.__setattr__(self, "instructions", source.instructions if instructions is _UNSET else instructions)
+        object.__setattr__(
+            self,
+            "handoff_description",
+            source.handoff_description if handoff_description is _UNSET else handoff_description,
+        )
+        object.__setattr__(self, "model", source.model if model is _UNSET else model)
+        object.__setattr__(
+            self, "model_settings", dict(source.model_settings if model_settings is _UNSET else model_settings)
+        )
+        object.__setattr__(self, "tools", tuple(source.tools if tools is _UNSET else tools))
+        object.__setattr__(self, "handoffs", tuple(source.handoffs if handoffs is _UNSET else handoffs))
+        object.__setattr__(self, "output_type", source.output_type if output_type is _UNSET else output_type)
+        object.__setattr__(self, "hooks", source.hooks if hooks is _UNSET else hooks)
+        object.__setattr__(self, "skills", tuple(source.skills if skills is _UNSET else skills))
+        object.__setattr__(self, "mcp", tuple(source.mcp if mcp is _UNSET else mcp))
+
+    def build(self) -> Any:
+        """Compile to an SDK-native ``agents.Agent``, standalone (no catalog).
+
+        Thin wrapper over :func:`agentdeck.authoring.compile.compile_agent` for the common
+        case — an agent with no handoffs, or none needing a catalog to resolve. A ``Deck``
+        calls ``compile_agent``/``link_handoffs`` directly instead, since it has the catalog.
+        """
+        from agentdeck.authoring.compile import compile_agent
+
+        return compile_agent(self)
+
+    async def run(self, message: Any = None, **runner_options: Any) -> Any:
+        """One-shot headless run (no event log); returns the SDK ``RunResult``."""
+        from agentdeck.authoring.runners.agent import HeadlessRunner
+
+        return await HeadlessRunner.from_agent(self.build(), **runner_options).run(message)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        raise AttributeError(f"Agent is immutable; build a new one instead of setting {key!r}.")
+
+    def __repr__(self) -> str:
+        return f"Agent(name={self.name!r})"
+
+
+__all__ = ["Agent", "AgentDeclaration"]