ms-tau-sdk 2.0.9.dev48__tar.gz → 2.0.9.dev49__tar.gz

{ms_tau_sdk-2.0.9.dev48 → ms_tau_sdk-2.0.9.dev49}/CHANGELOG.md

@@ -9,6 +9,24 @@
   the session loads, or, before the session has loaded, the one its Agent card names (one extra
   request, only then). Local turns carry the workspace's local Agent,
   `local-agent-<workspace digest>`.
+- **Application tool calls get their own time limits, and failures say what happened
+  ([#84](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/84), ADR 0022).**
+  - A call that met an error status from the application or its gateway, such as 403, 502 or 503,
+    waited until the turn's 15-minute limit. It now ends at once with that status. The Main
+    Sequence MCP connection had the same defect and is fixed too.
+  - Each application tool declares how long it may run in its MCP `_meta` under
+    `mainsequence.ai/timeout-seconds/v1`, for example
+    `@mcp.tool(meta={"mainsequence.ai/timeout-seconds/v1": 300})`. A tool that declares nothing
+    gets the new `TAU_MCP_TOOL_TIMEOUT_SECONDS` (default `60`).
+    `MAINSEQUENCE_TAU_BACKEND_READ_TIMEOUT_SECONDS` no longer limits the call itself. To find the
+    limit, `<name>__call_tool` now reads the application's tool list before each call.
+  - The model reads what failed, for example "The orders tool rebuild_report did not answer
+    within 300 seconds." or "The orders application answered with a server error (502).", instead
+    of "could not be reached" for every failure. Details and the
+    `runtime.mcp_application.failed` log event carry `failure`, `status` and `timeout_seconds`.
+  - Opening the application's session is tried once more when it fails on the connection, a
+    time-out or a server error. A call that was sent is never sent again.
+  - See [Application tool time limits](docs/guides/application-tool-time-limits.md).
 
 ## 2.0.8 — 2026-10-08
 

{ms_tau_sdk-2.0.9.dev48 → ms_tau_sdk-2.0.9.dev49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 2.0.9.dev48
+Version: 2.0.9.dev49
 Summary: Workspace-bound Tau application primitives for Main Sequence projects
 Project-URL: Changelog, https://github.com/mainsequence-sdk/ms-tau-sdk/blob/development/CHANGELOG.md
 Project-URL: Documentation, https://github.com/mainsequence-sdk/ms-tau-sdk/tree/development/docs

{ms_tau_sdk-2.0.9.dev48 → ms_tau_sdk-2.0.9.dev49}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ms-tau-sdk"
-version = "2.0.9.dev48"
+version = "2.0.9.dev49"
 description = "Workspace-bound Tau application primitives for Main Sequence projects"
 readme = "README.md"
 requires-python = ">=3.13"

{ms_tau_sdk-2.0.9.dev48 → ms_tau_sdk-2.0.9.dev49}/src/ms_tau_sdk/agent_skills/tau_project_customization/SKILL.md

@@ -81,6 +81,16 @@ in the system prompt because a tool named `read` exists. Extensions must not reg
 this mode.
 Excluding coding tools does not sandbox extension Python code.
 
+## Application tool time limits
+
+A declared application's tool sets how long it may run, in seconds, in its MCP `_meta` under
+`mainsequence.ai/timeout-seconds/v1`; with the MCP Python SDK that is
+`@mcp.tool(meta={"mainsequence.ai/timeout-seconds/v1": 300})` in the application. Set the limit on
+the application's tool, not in the Agent. A tool that declares nothing gets
+`TAU_MCP_TOOL_TIMEOUT_SECONDS` (default `60`); set it like the tool composition settings above, in
+`harness_agent.spec.env_vars`, the process environment, or
+`TauSDKSettings(mcp_tool_timeout_seconds=...)`. No call outlives its turn.
+
 ## Invariants extensions must not replace
 
 Extensions may change effective agent capabilities, but they must not replace or bypass:

{ms_tau_sdk-2.0.9.dev48 → ms_tau_sdk-2.0.9.dev49}/src/ms_tau_sdk/backend/mcp.py

@@ -7,7 +7,7 @@ import contextvars
 from collections.abc import AsyncGenerator
 from dataclasses import dataclass
 from datetime import timedelta
-from typing import Literal, Self
+from typing import Any, Literal, Self
 
 import httpx
 from mcp import ClientSession, types
@@ -52,6 +52,7 @@ class _CallToolCommand:
     name: str
     arguments: dict[str, object]
     meta: dict[str, object] | None
+    timeout_seconds: float | None
     log_context: dict[str, object]
     result: asyncio.Future[types.CallToolResult]
 
@@ -99,10 +100,8 @@ class MCPConnectionClient:
         timeout: httpx.Timeout,
         read_timeout_seconds: float,
         read_concurrency: int,
-        read_catalog: bool = True,
     ) -> None:
         self.name = name
-        self._read_catalog = read_catalog
         self.display_name = display_name
         self.url = url
         self._http_auth = auth
@@ -113,6 +112,9 @@ class MCPConnectionClient:
         self._owner_task: asyncio.Task[None] | None = None
         self._ready: asyncio.Future[None] | None = None
         self._failure: Exception | None = None
+        # The results of the calls already handed to the session, so that a failed connection
+        # ends them as well as the calls still queued.
+        self._in_flight: set[asyncio.Future[Any]] = set()
         self.tools: tuple[types.Tool, ...] = ()
         self.resources: tuple[types.Resource, ...] = ()
         self._parallel_tool_names: frozenset[str] = frozenset()
@@ -198,8 +200,6 @@ class MCPConnectionClient:
         session: ClientSession,
         initialized: types.InitializeResult | None,
     ) -> None:
-        if not self._read_catalog:
-            return
         # Read only what the server offers; a server without resources answers "not found".
         capabilities = initialized.capabilities if initialized is not None else None
         offers_tools = capabilities is None or capabilities.tools is not None
@@ -219,14 +219,23 @@ class MCPConnectionClient:
         read_slots = asyncio.Semaphore(self._read_concurrency)
 
         async def execute(command: _CallToolCommand | _ReadResourceCommand) -> None:
+            self._in_flight.add(command.result)
             try:
                 with bound_contextvars(**command.log_context):
                     if isinstance(command, _CallToolCommand):
-                        tool_result = await session.call_tool(
-                            command.name,
-                            command.arguments,
-                            meta=command.meta,
-                        )
+                        if command.timeout_seconds is None:
+                            tool_result = await session.call_tool(
+                                command.name,
+                                command.arguments,
+                                meta=command.meta,
+                            )
+                        else:
+                            tool_result = await session.call_tool(
+                                command.name,
+                                command.arguments,
+                                read_timeout_seconds=timedelta(seconds=command.timeout_seconds),
+                                meta=command.meta,
+                            )
                         if not command.result.done():
                             command.result.set_result(tool_result)
                     else:
@@ -236,6 +245,11 @@ class MCPConnectionClient:
             except Exception as error:
                 if not command.result.done():
                     command.result.set_exception(error)
+            finally:
+                # A transport failure cancels the session's work before its cause is known; the
+                # owner task then ends this call with that cause.
+                if command.result.done():
+                    self._in_flight.discard(command.result)
 
         async def execute_read(
             command: _CallToolCommand | _ReadResourceCommand,
@@ -271,6 +285,10 @@ class MCPConnectionClient:
                 await asyncio.gather(*tuple(active_reads), return_exceptions=True)
 
     def _fail_pending_commands(self, error: Exception) -> None:
+        for result in self._in_flight:
+            if not result.done():
+                result.set_exception(error)
+        self._in_flight.clear()
         if self._commands is None:
             return
         while not self._commands.empty():
@@ -293,7 +311,10 @@ class MCPConnectionClient:
         arguments: dict[str, object],
         *,
         meta: dict[str, object] | None = None,
+        timeout_seconds: float | None = None,
     ) -> types.CallToolResult:
+        """Call one tool; ``timeout_seconds`` replaces the session's wait for its answer."""
+
         commands = self._require_commands()
         result: asyncio.Future[types.CallToolResult] = asyncio.get_running_loop().create_future()
         commands.put_nowait(
@@ -301,6 +322,7 @@ class MCPConnectionClient:
                 name=name,
                 arguments=arguments,
                 meta=meta,
+                timeout_seconds=timeout_seconds,
                 log_context=dict(get_contextvars()),
                 result=result,
             )

{ms_tau_sdk-2.0.9.dev48 → ms_tau_sdk-2.0.9.dev49}/src/ms_tau_sdk/runtime/manager.py

@@ -1152,6 +1152,8 @@ class SessionRuntimeManager:
                     create_mcp_application_tools(
                         bootstrap.mcp_applications,
                         connect=application_connector(self.settings),
+                        tool_timeout_seconds=self.settings.mcp_tool_timeout_seconds,
+                        open_timeout_seconds=self.settings.backend_read_timeout_seconds,
                     )
                 )
             tools.extend(create_task_control_tools())

{ms_tau_sdk-2.0.9.dev48 → ms_tau_sdk-2.0.9.dev49}/src/ms_tau_sdk/settings.py

@@ -242,6 +242,12 @@ class TauSDKSettings(BaseSettings):
         ge=1,
         validation_alias="MAINSEQUENCE_TAU_MCP_READ_CONCURRENCY",
     )
+    # How long an application tool may run when its tool declares no time limit (ADR 0022).
+    mcp_tool_timeout_seconds: float = Field(
+        default=60.0,
+        gt=0,
+        validation_alias="TAU_MCP_TOOL_TIMEOUT_SECONDS",
+    )
     backend_max_response_bytes: int = Field(
         default=10 * 1024 * 1024,
         gt=0,

{ms_tau_sdk-2.0.9.dev48 → ms_tau_sdk-2.0.9.dev49}/src/ms_tau_sdk/tools/mcp_applications.py

@@ -8,17 +8,22 @@ session for the call, and closes it afterwards. The token carries the delegation
 turn serves, when it serves one, and is the Agent's own otherwise; the application decides what the
 call may do. No session, token or catalog is shared between turns or people, and nothing is read
 when the session loads, because no turn is running then.
+
+Each tool declares how long it may run in its ``_meta`` (ADR 0022); a tool that declares nothing
+gets ``TAU_MCP_TOOL_TIMEOUT_SECONDS``. A failure reaches the model in plain words, and
+opening the session is tried once more when it fails before the tool call is sent.
 """
 
 from __future__ import annotations
 
 import json
+import math
 import re
 from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping, Sequence
 
 import httpx
 import structlog
-from mcp import types
+from mcp import McpError, types
 from tau_agent.messages import TextContent
 from tau_agent.tools import (
     AgentTool,
@@ -44,7 +49,10 @@ logger = structlog.get_logger(__name__)
 _APPLICATION_NAME = re.compile(r"^[a-z][a-z0-9_]{0,39}$")
 _RESERVED_NAMES = frozenset({"mainsequence"})
 
-type ApplicationConnector = Callable[[MCPApplication, bool], Awaitable[MCPConnectionClient]]
+TIMEOUT_META_KEY = "mainsequence.ai/timeout-seconds/v1"
+"""The ``_meta`` key under which an application tool declares how long it may run, in seconds."""
+
+type ApplicationConnector = Callable[[MCPApplication], Awaitable[MCPConnectionClient]]
 
 
 class _ApplicationTokenAuth(httpx.Auth):
@@ -69,33 +77,101 @@ class _ApplicationTokenAuth(httpx.Auth):
 def application_connector(settings: TauSDKSettings) -> ApplicationConnector:
     """Open an MCP session to one application for the current turn."""
 
-    async def connect(application: MCPApplication, read_catalog: bool) -> MCPConnectionClient:
+    async def connect(application: MCPApplication) -> MCPConnectionClient:
         access = await _turn_application_access(application.resource_release_uid)
         return await MCPConnectionClient(
             name=application.name,
             display_name=application.name,
             url=f"{str(access.rpc_url).rstrip('/')}/mcp",
             auth=_ApplicationTokenAuth(access),
+            # The session's wait bounds each request: the backend read timeout while the session
+            # opens, the tool's own limit for the call. The HTTP read wait never cuts a call short.
             timeout=httpx.Timeout(
                 connect=settings.backend_connect_timeout_seconds,
-                read=settings.backend_read_timeout_seconds,
+                read=settings.turn_timeout_seconds,
                 write=settings.backend_write_timeout_seconds,
                 pool=settings.backend_pool_timeout_seconds,
             ),
             read_timeout_seconds=settings.backend_read_timeout_seconds,
             read_concurrency=settings.mcp_read_concurrency,
-            read_catalog=read_catalog,
         ).open()
 
     return connect
 
 
-def _failure(name: str, error: BaseException) -> str:
+def _timed_out(error: BaseException) -> bool:
+    if isinstance(error, McpError):
+        return error.error.code == httpx.codes.REQUEST_TIMEOUT
+    return isinstance(error, httpx.TimeoutException) and not isinstance(error, httpx.ConnectTimeout)
+
+
+def _failure(
+    name: str,
+    error: BaseException,
+    *,
+    tool: str | None,
+    timeout_seconds: float,
+) -> tuple[str, dict[str, JSONValue]]:
+    """What the model reads about a failure, and its details; never the error's own text."""
+
     if isinstance(error, RequesterBindingError):
-        return "Your access for this request ended."
-    if isinstance(error, BackendError) and error.backend_status in {403, 404}:
-        return f"The {name} application is not available for this call."
-    return f"The {name} application could not be reached."
+        return "Your access for this request ended.", {"failure": "access_ended"}
+    if isinstance(error, BackendError):
+        if error.backend_status in {403, 404}:
+            return (
+                f"The {name} application is not available for this call.",
+                {"failure": "not_available"},
+            )
+        return (
+            f"Main Sequence could not provide access to the {name} application.",
+            {"failure": "access_unavailable"},
+        )
+    if _timed_out(error):
+        subject = f"The {name} tool {tool}" if tool is not None else f"The {name} application"
+        return (
+            f"{subject} did not answer within {timeout_seconds:g} seconds.",
+            {"failure": "timeout", "timeout_seconds": timeout_seconds},
+        )
+    if isinstance(error, httpx.HTTPStatusError):
+        status = error.response.status_code
+        if status >= 500:
+            text = f"The {name} application answered with a server error ({status})."
+            return text, {"failure": "server_error", "status": status}
+        if status in {401, 403}:
+            text = f"The {name} application refused this call ({status})."
+            return text, {"failure": "refused", "status": status}
+        text = f"The {name} application answered with an error ({status})."
+        return text, {"failure": "error_status", "status": status}
+    if isinstance(error, httpx.ConnectError | httpx.ConnectTimeout):
+        return f"The {name} application could not be reached.", {"failure": "unreachable"}
+    return f"The {name} application could not complete this call.", {"failure": "failed"}
+
+
+def _retryable(error: BaseException) -> bool:
+    """Whether opening the session failed in a way that a second attempt may not repeat."""
+
+    if isinstance(error, httpx.HTTPStatusError):
+        return error.response.status_code >= 500
+    return isinstance(error, httpx.TransportError) or _timed_out(error)
+
+
+def _declared_timeout(name: str, tool: types.Tool) -> float | None:
+    value = (tool.meta or {}).get(TIMEOUT_META_KEY)
+    if value is None:
+        return None
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, int | float)
+        or not math.isfinite(value)
+        or value <= 0
+    ):
+        logger.warning(
+            "runtime.mcp_application.invalid_timeout",
+            application=name,
+            mcp_tool=tool.name,
+        )
+        return None
+    return float(value)
 
 
 def _error(name: str, text: str, **details: JSONValue) -> AgentToolResult:
@@ -118,9 +194,53 @@ def _application_tools(
     application: MCPApplication,
     *,
     connect: ApplicationConnector,
+    tool_timeout_seconds: float,
+    open_timeout_seconds: float,
 ) -> list[AgentTool]:
     name = application.name
 
+    async def open_session(signal: ToolCancellationToken | None) -> MCPConnectionClient:
+        # Nothing has reached a tool while the session opens, so one more attempt is safe.
+        try:
+            return await connect(application)
+        except Exception as error:
+            if not _retryable(error) or (signal is not None and signal.is_cancelled()):
+                raise
+            logger.info(
+                "runtime.mcp_application.retried",
+                application=name,
+                error_type=type(error).__name__,
+            )
+        return await connect(application)
+
+    def failed(
+        operation: str,
+        error: BaseException,
+        *,
+        mcp_tool: str | None = None,
+        call_timeout_seconds: float | None = None,
+    ) -> AgentToolResult:
+        # A failure after the call was sent, which has a time limit by then, is the tool's;
+        # a failure while the session opens is the application's.
+        text, failure = _failure(
+            name,
+            error,
+            tool=mcp_tool if call_timeout_seconds is not None else None,
+            timeout_seconds=(
+                call_timeout_seconds if call_timeout_seconds is not None else open_timeout_seconds
+            ),
+        )
+        if mcp_tool is not None:
+            failure["mcp_tool"] = mcp_tool
+        logger.warning(
+            "runtime.mcp_application.failed",
+            application=name,
+            operation=operation,
+            error_type=type(error).__name__,
+            **failure,
+        )
+        return _error(name, text, **failure)
+
     async def list_tools(
         tool_call_id: str,
         arguments: Mapping[str, JSONValue],
@@ -131,19 +251,13 @@ def _application_tools(
         if signal is not None and signal.is_cancelled():
             return _error(name, f"Listing the {name} tools was cancelled.", cancelled=True)
         try:
-            client = await connect(application, True)
+            client = await open_session(signal)
             try:
                 tools = client.tools
             finally:
                 await client.aclose()
         except Exception as error:
-            logger.warning(
-                "runtime.mcp_application.failed",
-                application=name,
-                operation="list_tools",
-                error_type=type(error).__name__,
-            )
-            return _error(name, _failure(name, error))
+            return failed("list_tools", error)
         entries = [_tool_entry(tool) for tool in tools]
         return AgentToolResult(
             content=[
@@ -170,20 +284,28 @@ def _application_tools(
             return _error(name, "`arguments` must be an object.")
         if signal is not None and signal.is_cancelled():
             return _error(name, f"The {name} tool call was cancelled.", cancelled=True)
+        call_timeout_seconds: float | None = None
         try:
-            client = await connect(application, False)
+            client = await open_session(signal)
             try:
-                result = await client.call_tool(tool_name, dict(tool_arguments))
+                declared = next(
+                    (
+                        _declared_timeout(name, tool)
+                        for tool in client.tools
+                        if tool.name == tool_name
+                    ),
+                    None,
+                )
+                call_timeout_seconds = declared if declared is not None else tool_timeout_seconds
+                result = await client.call_tool(
+                    tool_name, dict(tool_arguments), timeout_seconds=call_timeout_seconds
+                )
             finally:
                 await client.aclose()
         except Exception as error:
-            logger.warning(
-                "runtime.mcp_application.failed",
-                application=name,
-                operation="call_tool",
-                error_type=type(error).__name__,
+            return failed(
+                "call_tool", error, mcp_tool=tool_name, call_timeout_seconds=call_timeout_seconds
             )
-            return _error(name, _failure(name, error), mcp_tool=tool_name)
         projected = mcp_tool_result(canonical_name=tool_name, result=result, display_name=name)
         details = dict(projected.details) if isinstance(projected.details, dict) else {}
         details["application"] = name
@@ -230,8 +352,14 @@ def create_mcp_application_tools(
     applications: Sequence[MCPApplication],
     *,
     connect: ApplicationConnector,
+    tool_timeout_seconds: float,
+    open_timeout_seconds: float,
 ) -> list[AgentTool]:
-    """Two tools for each declared application, in declaration order."""
+    """Two tools for each declared application, in declaration order.
+
+    ``tool_timeout_seconds`` bounds a call to a tool that declares no limit of its own;
+    ``open_timeout_seconds`` is the wait for each request that opens the session.
+    """
 
     tools: list[AgentTool] = []
     seen: set[str] = set()
@@ -242,5 +370,12 @@ def create_mcp_application_tools(
         if name in seen:
             raise ConfigurationError(f"Duplicate MCP application name: {name!r}")
         seen.add(name)
-        tools.extend(_application_tools(application, connect=connect))
+        tools.extend(
+            _application_tools(
+                application,
+                connect=connect,
+                tool_timeout_seconds=tool_timeout_seconds,
+                open_timeout_seconds=open_timeout_seconds,
+            )
+        )
     return tools