ms-tau-sdk 2.0.11.dev52__tar.gz → 2.0.12.dev53__tar.gz

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 2.0.12 — 2026-10-11
+
+- **A direct Message that runs out of time gets a typed answer
+  ([#94](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/94)).** A `message:send` answered
+  with a Message, or JSON-RPC `message/send`, whose turn reached
+  `MAINSEQUENCE_TAU_TURN_TIMEOUT_SECONDS` got a plain-text HTTP 500 "Internal Server Error". It now
+  gets HTTP 504 `application/a2a+json` with status `DEADLINE_EXCEEDED` and an `ErrorInfo` with
+  reason `MESSAGE_RESPONSE_LIMIT_EXCEEDED`, domain `mainsequence.ai` and `metadata.limitSeconds`,
+  the limit that expired. JSON-RPC returns the same `ErrorInfo` in a JSON-RPC error (`-32000`).
+  The turn is stopped as before; its work is neither rolled back nor replayed. Use Task mode for
+  longer work.
+- **A direct Message has the platform's 90-second limit.** The platform gives a direct A2A
+  Message one strict limit, 90 seconds, and passes it to the runtime it hosts in
+  `MAINSEQUENCE_A2A_MESSAGE_LIMIT_SECONDS`, a platform-set variable that users do not set. The
+  runtime enforces it for every caller, from when it receives the request and over the whole
+  request, including output-contract repair turns: the turn is stopped and the request gets the
+  504 above with the platform's limit. A shorter `MAINSEQUENCE_TAU_TURN_TIMEOUT_SECONDS` still ends
+  the turn first; no setting extends the platform's limit. A Task-mode `message:send` with
+  `returnImmediately: false` waits at most until the same limit and returns the Task, which keeps
+  running. Streams, chat, caller delivery, Task dispatch and Task turns are unchanged. Without the
+  variable, as in local mode (which refuses it), a direct Message has only the turn limit.
+- **Platform MCP tools wait for the limit the platform declares
+  ([#93](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/93), ADR 0022 amendment).** Every
+  Main Sequence MCP tool call waited `MAINSEQUENCE_TAU_BACKEND_READ_TIMEOUT_SECONDS` (60 seconds by
+  default), so an `a2a.send_message` in Message mode whose target answered after 60 seconds was
+  abandoned by the calling Agent while the platform still waited and completed the send. A
+  platform tool whose `_meta` declares its limit under `mainsequence.ai/timeout-seconds/v1`, the
+  key application tools use, is now waited for that long. A tool that declares nothing, or an
+  invalid value, keeps the session default; an invalid value is logged as
+  `runtime.mcp.invalid_timeout`. `MAINSEQUENCE_TAU_BACKEND_READ_TIMEOUT_SECONDS` now covers only
+  ordinary backend reads and platform tools without a declared limit: it has no effect on a Message
+  or any platform limit and can only shorten a wait.
+
 ## 2.0.11 — 2026-10-11
 
 - **Every MCP connection honors per-call response deadlines

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 2.0.11.dev52
+Version: 2.0.12.dev53
 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.11.dev52 → ms_tau_sdk-2.0.12.dev53}/pyproject.toml

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

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/src/ms_tau_sdk/agent_skills/tau_a2a_runtime_adapter/SKILL.md

@@ -54,6 +54,11 @@ For a deployed Agent, use the projected `a2a.send_message` MCP operation. The pl
 resolves the target `AgentSession`, waits for its runtime to become ready, and dispatches the
 message. For asynchronous work, use the returned Task handle with `a2a.wait_task`.
 
+The platform gives a direct Message (`response_kind: "message"`) 90 seconds, and no setting
+extends that limit. A target that has not answered by then stops its turn, and the send fails
+because of the limit. Send work that may take longer with `response_kind: "task"`, and do not
+resend a Message that ran out of time: the work it already did is not rolled back.
+
 For local Tau development, start `ms-tau` and wait for its local `/ready` result. The public A2A
 REST and JSON-RPC surfaces support Message and Task execution against the workspace-local SQLite
 store, including streaming, list/get/cancel/subscribe, and continuation. An A2A protocol Task does

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/src/ms_tau_sdk/agent_skills/tau_local_development/SKILL.md

@@ -35,9 +35,9 @@ The SDK looks for the CLI in `MAINSEQUENCE_CLI`, then beside the Python interpre
 CLI. Do not add token lines to `.env`. A pair found there still works, but it is deprecated and
 startup logs a warning. `mainsequence refresh-token` run in that directory removes the lines.
 
-Do not set `APP_NAME`, `FASTAPI_PUBLIC_BASE_URL`, `MAINSEQUENCE_CALLER_AUTH_MODE=assertion`, or the
-`MAINSEQUENCE_CALLER_ASSERTION_*` variables. The platform sets them when it hosts a runtime, and
-local mode refuses to start with them.
+Do not set `APP_NAME`, `FASTAPI_PUBLIC_BASE_URL`, `MAINSEQUENCE_CALLER_AUTH_MODE=assertion`, the
+`MAINSEQUENCE_CALLER_ASSERTION_*` variables or `MAINSEQUENCE_A2A_MESSAGE_LIMIT_SECONDS`. The
+platform sets them when it hosts a runtime, and local mode refuses to start with them.
 
 Set `MAINSEQUENCE_ENDPOINT` only for a non-default platform endpoint. The CLI session must be for
 the same endpoint. Local mode binds to `127.0.0.1:8787` by default. Treat an explicit public bind
@@ -118,6 +118,11 @@ To request a Task from `message:send`, send the response-kind extension header
 response. `message:stream` is always Task-oriented and does not accept `responseKind` or
 `returnImmediately`.
 
+Local mode has no platform Message limit: a direct Message ends only at
+`MAINSEQUENCE_TAU_TURN_TIMEOUT_SECONDS`. A hosted Agent answers a direct Message within the
+platform's 90 seconds or with HTTP 504 `DEADLINE_EXCEEDED`, so design work that may take longer as
+a Task.
+
 Task terminality is derived only from its A2A state. `completed`, `failed`, `canceled`, and
 `rejected` are terminal; `input_required` and `auth_required` are resumable. A normal execution
 failure produces a durable failed Task and a standard responder `status.message`. A

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/src/ms_tau_sdk/api/a2a.py

@@ -382,6 +382,72 @@ def _unsupported_operation_json_rpc_error(
     }
 
 
+class _MessageLimitExceeded(Exception):
+    """A Message-mode request reached its time limit before the Agent answered."""
+
+    def __init__(self, limit_seconds: float) -> None:
+        super().__init__(f"The Message time limit of {limit_seconds} seconds expired")
+        self.limit_seconds = limit_seconds
+
+
+def _message_limit_exceeded(context_id: str, limit_seconds: float) -> _MessageLimitExceeded:
+    logger.warning(
+        "a2a.message.limit_exceeded",
+        message="A Message-mode request reached its time limit before the Agent answered",
+        context_id=context_id,
+        limit_seconds=limit_seconds,
+    )
+    return _MessageLimitExceeded(limit_seconds)
+
+
+def _seconds_text(value: float) -> str:
+    return str(int(value)) if float(value).is_integer() else str(value)
+
+
+def _message_limit_text(limit_seconds: float) -> str:
+    return (
+        f"The Agent did not answer the Message within {_seconds_text(limit_seconds)} seconds. "
+        "Use Task mode for longer work."
+    )
+
+
+def _message_limit_error_info(limit_seconds: float) -> dict[str, Any]:
+    return {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "reason": "MESSAGE_RESPONSE_LIMIT_EXCEEDED",
+        "domain": "mainsequence.ai",
+        # ErrorInfo metadata values are strings.
+        "metadata": {"limitSeconds": _seconds_text(limit_seconds)},
+    }
+
+
+def _message_limit_rest_error(limit_seconds: float) -> JSONResponse:
+    return JSONResponse(
+        status_code=504,
+        media_type="application/a2a+json",
+        content={
+            "error": {
+                "code": 504,
+                "status": "DEADLINE_EXCEEDED",
+                "message": _message_limit_text(limit_seconds),
+                "details": [_message_limit_error_info(limit_seconds)],
+            }
+        },
+    )
+
+
+def _message_limit_json_rpc_error(request_id: object, limit_seconds: float) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": {
+            "code": -32000,
+            "message": _message_limit_text(limit_seconds),
+            "data": [_message_limit_error_info(limit_seconds)],
+        },
+    }
+
+
 def _without_push_notification_capability(
     agent_card: dict[str, Any] | None,
 ) -> dict[str, Any] | None:
@@ -744,6 +810,7 @@ async def _collect_turn(
     provenance: TurnProvenance,
     turn_uid: str | None = None,
     caller_assertion: CallerAssertion | None = None,
+    deadline: float | None = None,
 ) -> str:
     accumulator = _TurnAccumulator(max_output_bytes=max_output_bytes)
     prompt_options: dict[str, Any] = {"provenance": provenance}
@@ -751,6 +818,8 @@ async def _collect_turn(
         prompt_options["turn_uid"] = turn_uid
     if caller_assertion is not None:
         prompt_options["caller_assertion"] = caller_assertion
+    if deadline is not None:
+        prompt_options["deadline"] = deadline
     async for event in manager.prompt(context_id, prompt, **prompt_options):
         accumulator.consume(event)
     context = active_task_execution()
@@ -779,6 +848,7 @@ async def _collect_validated_turn(
     provenance: TurnProvenance,
     turn_uid: str | None = None,
     caller_assertion: CallerAssertion | None = None,
+    deadline: float | None = None,
 ) -> str:
     text = await _collect_turn(
         manager,
@@ -788,6 +858,7 @@ async def _collect_validated_turn(
         provenance=provenance,
         turn_uid=turn_uid,
         caller_assertion=caller_assertion,
+        deadline=deadline,
     )
     if not contract.enabled:
         return text
@@ -818,6 +889,7 @@ async def _collect_validated_turn(
                 max_output_bytes=max_output_bytes,
                 provenance=provenance,
                 caller_assertion=caller_assertion,
+                deadline=deadline,
             )
     raise AssertionError("strict JSON repair loop did not terminate")
 
@@ -948,6 +1020,16 @@ async def _wait_for_task_return_state(
     return current
 
 
+def _task_wait_seconds(config: TauSDKSettings, deadline: float | None) -> float:
+    """How long a request waits for its Task: the configured wait, ended by the platform's
+    Message limit when the platform sets one. Either way the Task keeps running."""
+
+    if deadline is None:
+        return config.a2a_task_wait_timeout_seconds
+    remaining = deadline - asyncio.get_running_loop().time()
+    return min(config.a2a_task_wait_timeout_seconds, remaining)
+
+
 @dataclass(frozen=True, slots=True)
 class _ClaimedTask:
     attempt_uid: str
@@ -1621,6 +1703,7 @@ async def _execute_message(
     max_output_bytes: int,
     provenance: TurnProvenance,
     caller_assertion: CallerAssertion | None = None,
+    deadline: float | None = None,
 ) -> dict[str, Any]:
     text = await _collect_validated_turn(
         manager,
@@ -1630,6 +1713,7 @@ async def _execute_message(
         max_output_bytes=max_output_bytes,
         provenance=provenance,
         caller_assertion=caller_assertion,
+        deadline=deadline,
     )
     message = _agent_message(
         context_id=context_id,
@@ -2288,6 +2372,32 @@ async def message_send(
         Header(alias="A2A-Extensions"),
     ] = None,
 ) -> dict[str, Any]:
+    try:
+        return await _message_send(body, client, manager, config, request, a2a_extensions)
+    except _MessageLimitExceeded as error:
+        return _message_limit_rest_error(error.limit_seconds)  # type: ignore[return-value]
+
+
+async def _message_send(
+    body: dict[str, Any],
+    client: MainSequenceClient,
+    manager: SessionRuntimeManager,
+    config: TauSDKSettings,
+    request: Request,
+    a2a_extensions: str | None,
+) -> dict[str, Any]:
+    """Answer one ``message:send``, for REST and JSON-RPC alike.
+
+    When the platform sets a Message limit, it runs from the moment the request arrives. It
+    bounds a Message-mode request as a whole, including output-contract repair turns, and it ends
+    the wait of a Task-mode request that does not return immediately. A Message-mode request that
+    reaches its limit, or its turn's own limit, raises ``_MessageLimitExceeded``, which each
+    transport answers in its own form.
+    """
+    platform_limit = config.a2a_message_limit_seconds
+    deadline = (
+        None if platform_limit is None else asyncio.get_running_loop().time() + platform_limit
+    )
     try:
         provenance = _a2a_turn_provenance(config, request)
     except CallerIdentityError as error:
@@ -2362,7 +2472,7 @@ async def message_send(
             client,
             task,
             poll_interval_seconds=config.a2a_task_event_poll_interval_seconds,
-            wait_timeout_seconds=config.a2a_task_wait_timeout_seconds,
+            wait_timeout_seconds=_task_wait_seconds(config, deadline),
         )
         task = await _task_with_history(client, task, history_length=history_length)
         return {"task": _task_payload(task, history_length=history_length)}
@@ -2397,7 +2507,7 @@ async def message_send(
                 client,
                 task,
                 poll_interval_seconds=config.a2a_task_event_poll_interval_seconds,
-                wait_timeout_seconds=config.a2a_task_wait_timeout_seconds,
+                wait_timeout_seconds=_task_wait_seconds(config, deadline),
             )
             task = await _task_with_history(client, task, history_length=history_length)
             return {"task": _task_payload(task, history_length=history_length)}
@@ -2422,31 +2532,52 @@ async def message_send(
                 client,
                 task,
                 poll_interval_seconds=config.a2a_task_event_poll_interval_seconds,
-                wait_timeout_seconds=config.a2a_task_wait_timeout_seconds,
+                wait_timeout_seconds=_task_wait_seconds(config, deadline),
             )
         task = await _task_with_history(client, task, history_length=history_length)
         return {"task": _task_payload(task, history_length=history_length)}
     request_message_id = str(message["messageId"])
+    context_id = str(message["contextId"])
     if config.local_mode:
         replay = await client.begin_local_conversation_message(message_to_protocol(message))
         if replay is not None:
             return {"message": replay}
-    result = await _execute_message(
-        manager,
-        context_id=str(message["contextId"]),
-        prompt=prompt,
-        output_contract=output_contract,
-        max_output_bytes=config.max_turn_output_bytes,
-        provenance=provenance,
-        caller_assertion=request_caller_assertion(request),
-    )
+    if (
+        platform_limit is not None
+        and deadline is not None
+        and asyncio.get_running_loop().time() >= deadline
+    ):
+        # The request used up the platform's limit before its turn could start, so none starts.
+        raise _message_limit_exceeded(context_id, platform_limit)
+    request_limit = asyncio.timeout_at(deadline)
+    try:
+        async with request_limit:
+            result = await _execute_message(
+                manager,
+                context_id=context_id,
+                prompt=prompt,
+                output_contract=output_contract,
+                max_output_bytes=config.max_turn_output_bytes,
+                provenance=provenance,
+                caller_assertion=request_caller_assertion(request),
+                deadline=deadline,
+            )
+    except TimeoutError as error:
+        # The platform's limit for the request or the turn's own limit expired, and the turn was
+        # stopped. The caller learns which limit.
+        raise _message_limit_exceeded(
+            context_id,
+            platform_limit
+            if platform_limit is not None and request_limit.expired()
+            else config.turn_timeout_seconds,
+        ) from error
     if config.local_mode:
         result = await client.complete_local_conversation_message(
-            str(message["contextId"]),
+            context_id,
             request_message_id,
             result,
         )
-    manager.mark_response_delivered(str(message["contextId"]))
+    manager.mark_response_delivered(context_id)
     return {"message": result}
 
 
@@ -2703,14 +2834,17 @@ async def json_rpc(
 
     try:
         if method in {"SendMessage", "message/send"}:
-            result = await message_send(
-                params,
-                client,
-                manager,
-                config,
-                request,
-                a2a_extensions,
-            )
+            try:
+                result = await _message_send(
+                    params,
+                    client,
+                    manager,
+                    config,
+                    request,
+                    a2a_extensions,
+                )
+            except _MessageLimitExceeded as error:
+                return _message_limit_json_rpc_error(request_id, error.limit_seconds)
         elif method in {"SendStreamingMessage", "message/stream"}:
             _response_kind(
                 params,

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/src/ms_tau_sdk/runtime/manager.py

@@ -1325,6 +1325,7 @@ class SessionRuntimeManager:
         turn_uid: str | None = None,
         caller_assertion: CallerAssertion | None = None,
         caller_delivery: CallerDelivery | None = None,
+        deadline: float | None = None,
     ) -> AsyncIterator[TauRuntimeEvent]:
         """Run one turn in a session.
 
@@ -1332,6 +1333,9 @@ class SessionRuntimeManager:
         request that starts the turn. It is presented only when the turn is marked active.
         ``caller_delivery`` is, instead, the caller delivery that a turn the platform starts
         resumes the session for. It is named only when the turn is marked active.
+        ``deadline`` is the event-loop time by which the request that waits for the turn must be
+        answered. The turn then ends at that deadline or at its own time limit, whichever comes
+        first, and either one stops it the same way.
         """
 
         agent_uid = await self._session_agent_uid(session_uid)
@@ -1351,6 +1355,7 @@ class SessionRuntimeManager:
                 platform_event=platform_event,
                 caller_assertion=caller_assertion,
                 caller_delivery=caller_delivery,
+                deadline=deadline,
             ):
                 yield event
 
@@ -1375,6 +1380,7 @@ class SessionRuntimeManager:
         platform_event: PlatformEvent | None = None,
         caller_assertion: CallerAssertion | None = None,
         caller_delivery: CallerDelivery | None = None,
+        deadline: float | None = None,
     ) -> AsyncIterator[TauRuntimeEvent]:
         live_turn = self._open_live_turn(session_uid, content, provenance)
         try:
@@ -1385,6 +1391,7 @@ class SessionRuntimeManager:
                 platform_event=platform_event,
                 caller_assertion=caller_assertion,
                 caller_delivery=caller_delivery,
+                deadline=deadline,
             ):
                 if live_turn is not None:
                     live_turn.observe(event)
@@ -1518,6 +1525,7 @@ class SessionRuntimeManager:
         platform_event: PlatformEvent | None = None,
         caller_assertion: CallerAssertion | None = None,
         caller_delivery: CallerDelivery | None = None,
+        deadline: float | None = None,
     ) -> AsyncIterator[TauRuntimeEvent]:
         logger.info(
             "agent.run.accepted",
@@ -1612,10 +1620,12 @@ class SessionRuntimeManager:
             model=runtime.model,
             is_streaming=True,
         )
+        limit_at = asyncio.get_running_loop().time() + self.settings.turn_timeout_seconds
+        turn_limit = asyncio.timeout_at(limit_at if deadline is None else min(limit_at, deadline))
         requester_token = bind_turn_requester(requester_binding)
         try:
             try:
-                async with asyncio.timeout(self.settings.turn_timeout_seconds):
+                async with turn_limit:
                     async for event in runtime.prompt(
                         content,
                         provenance=provenance,
@@ -1640,7 +1650,13 @@ class SessionRuntimeManager:
                 runtime.cancel(force=True)
                 raise
         except asyncio.CancelledError:
-            if not output_complete:
+            if turn_limit.expired():
+                # The request's own timer for the same deadline cancelled the turn in the same
+                # step, so the turn's limit could not report itself. It still expired.
+                terminal_status = "timed_out"
+                error_type = "TimeoutError"
+                runtime.cancel(force=True)
+            elif not output_complete:
                 terminal_status = "cancelled"
                 error_type = "CancelledError"
             raise

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/src/ms_tau_sdk/settings.py

@@ -29,6 +29,7 @@ CALLER_ASSERTION_JWKS_URL_ENV = "MAINSEQUENCE_CALLER_ASSERTION_JWKS_URL"
 RESOURCE_RELEASE_UID_ENV = "APP_NAME"
 FASTAPI_PUBLIC_BASE_URL_ENV = "FASTAPI_PUBLIC_BASE_URL"
 ORGANIZATION_ENVIRONMENT_UID_ENV = "MAINSEQUENCE_ORGANIZATION_ENVIRONMENT_UID"
+A2A_MESSAGE_LIMIT_ENV = "MAINSEQUENCE_A2A_MESSAGE_LIMIT_SECONDS"
 HOSTED_SIGNAL_ENVS = (
     RESOURCE_RELEASE_UID_ENV,
     FASTAPI_PUBLIC_BASE_URL_ENV,
@@ -138,6 +139,14 @@ class TauSDKSettings(BaseSettings):
         default=None,
         validation_alias=ORGANIZATION_ENVIRONMENT_UID_ENV,
     )
+    # The platform's limit for a direct A2A Message, which holds its request open until the Agent
+    # answers. The platform sets it when it hosts the runtime; unset means no platform limit.
+    a2a_message_limit_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        allow_inf_nan=False,
+        validation_alias=A2A_MESSAGE_LIMIT_ENV,
+    )
     local_mode: bool = Field(default=False, validation_alias="TAU_LOCAL_MODE")
     exclude_base_tools: bool = Field(default=False, validation_alias="TAU_EXCLUDE_BASE_TOOLS")
     exclude_mainsequence_mcp: bool = Field(
@@ -404,6 +413,12 @@ class TauSDKSettings(BaseSettings):
         # name a mode exactly.
         return None if value == "" else value
 
+    @field_validator("a2a_message_limit_seconds", mode="before")
+    @classmethod
+    def ignore_empty_message_limit(cls, value: object) -> object:
+        # Only an empty value counts as unset. Any other value must be a number of seconds.
+        return None if value == "" else value
+
     @field_validator("local_state_root", "state_root")
     @classmethod
     def normalize_state_roots(cls, value: Path) -> Path:
@@ -427,6 +442,11 @@ class TauSDKSettings(BaseSettings):
                     f"{CALLER_AUTH_MODE_ENV}=assertion and {', '.join(HOSTED_SIGNAL_ENVS)}: "
                     "the platform sets them only when it hosts the runtime"
                 )
+            if self.a2a_message_limit_seconds is not None:
+                raise ValueError(
+                    "TAU_LOCAL_MODE has no platform Message limit. Unset "
+                    f"{A2A_MESSAGE_LIMIT_ENV}: the platform sets it only when it hosts the runtime"
+                )
             if self.host == "0.0.0.0" and "host" not in self.model_fields_set:
                 self.host = "127.0.0.1"
         elif self.auth_mode != "runtime_credential":

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/src/ms_tau_sdk/tools/mcp_applications.py

@@ -17,7 +17,6 @@ opening the session is tried once more when it fails before the tool call is sen
 from __future__ import annotations
 
 import json
-import math
 import re
 from collections.abc import AsyncGenerator, Mapping, Sequence
 from typing import Protocol
@@ -49,16 +48,14 @@ from ms_tau_sdk.runtime.requester import (
     _TurnApplicationAccess,
 )
 from ms_tau_sdk.settings import TauSDKSettings
-from ms_tau_sdk.tools.mcp_connection import mcp_tool_result
+from ms_tau_sdk.tools.mcp_connection import TIMEOUT_META_KEY as TIMEOUT_META_KEY
+from ms_tau_sdk.tools.mcp_connection import declared_timeout, mcp_tool_result
 
 logger = structlog.get_logger(__name__)
 
 _APPLICATION_NAME = re.compile(r"^[a-z][a-z0-9_]{0,39}$")
 _RESERVED_NAMES = frozenset({"mainsequence"})
 
-TIMEOUT_META_KEY = "mainsequence.ai/timeout-seconds/v1"
-"""The ``_meta`` key under which an application tool declares how long it may run, in seconds."""
-
 
 class ApplicationConnector(Protocol):
     async def __call__(
@@ -204,25 +201,6 @@ def _retryable(error: BaseException) -> bool:
     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:
     return AgentToolResult(
         content=[TextContent(text=text)],
@@ -339,7 +317,11 @@ def _application_tools(
             try:
                 declared = next(
                     (
-                        _declared_timeout(name, tool)
+                        declared_timeout(
+                            tool,
+                            invalid_event="runtime.mcp_application.invalid_timeout",
+                            application=name,
+                        )
                         for tool in client.tools
                         if tool.name == tool_name
                     ),

{ms_tau_sdk-2.0.11.dev52 → ms_tau_sdk-2.0.12.dev53}/src/ms_tau_sdk/tools/mcp_connection.py

@@ -3,12 +3,14 @@
 from __future__ import annotations
 
 import json
+import math
 import re
 from collections.abc import Callable, Mapping
 from copy import deepcopy
 from dataclasses import dataclass
-from typing import Literal, Protocol, cast
+from typing import Any, Literal, Protocol, cast
 
+import structlog
 from mcp import types
 from tau_agent.messages import ImageContent, TextContent
 from tau_agent.tools import (
@@ -19,8 +21,39 @@ from tau_agent.tools import (
 )
 from tau_agent.types import JSONValue
 
+logger = structlog.get_logger(__name__)
+
 _INVALID_TOOL_NAME = re.compile(r"[^A-Za-z0-9_-]")
 
+TIMEOUT_META_KEY = "mainsequence.ai/timeout-seconds/v1"
+"""The ``_meta`` key under which an MCP tool declares how long it may run, in seconds."""
+
+
+def declared_timeout(
+    tool: types.Tool,
+    *,
+    invalid_event: str,
+    **log_fields: JSONValue,
+) -> float | None:
+    """Return the time limit ``tool`` declares under ``TIMEOUT_META_KEY``, in seconds.
+
+    None when it declares none. A declaration that is not a finite number greater than zero
+    counts as none, and is logged as ``invalid_event`` with the tool's name and ``log_fields``.
+    """
+
+    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(invalid_event, mcp_tool=tool.name, **log_fields)
+        return None
+    return float(value)
+
 
 class MCPConnection(Protocol):
     """The part of an MCP connection client that the adapter uses."""
@@ -34,6 +67,7 @@ class MCPConnection(Protocol):
         arguments: dict[str, object],
         *,
         meta: dict[str, object] | None = None,
+        timeout_seconds: float | None = None,
     ) -> types.CallToolResult: ...
 
     async def read_resource(self, uri: str) -> types.ReadResourceResult: ...
@@ -129,6 +163,11 @@ def _create_tool(
         and bool(getattr(annotations, "idempotentHint", False))
         else "sequential"
     )
+    # A tool that declares its time limit is waited for that long; any other tool gets the
+    # connection's default wait.
+    timeout_seconds = declared_timeout(
+        tool, invalid_event="runtime.mcp.invalid_timeout", connection=policy.prefix
+    )
 
     async def execute(
         tool_call_id: str,
@@ -145,14 +184,12 @@ def _create_tool(
         if policy.check_arguments is not None:
             policy.check_arguments(canonical_name, arguments)
         private_meta = policy.private_meta(tool) if policy.private_meta is not None else None
-        if private_meta is None:
-            result = await client.call_tool(canonical_name, dict(arguments))
-        else:
-            result = await client.call_tool(
-                canonical_name,
-                dict(arguments),
-                meta=dict(private_meta),
-            )
+        call_options: dict[str, Any] = {}
+        if private_meta is not None:
+            call_options["meta"] = dict(private_meta)
+        if timeout_seconds is not None:
+            call_options["timeout_seconds"] = timeout_seconds
+        result = await client.call_tool(canonical_name, dict(arguments), **call_options)
         return mcp_tool_result(
             canonical_name=canonical_name,
             result=result,