mainsequence 9.0.20.dev62__tar.gz → 9.0.21.dev64__tar.gz

{mainsequence-9.0.20.dev62 → mainsequence-9.0.21.dev64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.20.dev62
+Version: 9.0.21.dev64
 Summary: Main Sequence SDK
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence-9.0.20.dev62 → mainsequence-9.0.21.dev64}/agent_scaffold/skills/a2a_sdk_execution/SKILL.md

@@ -33,6 +33,9 @@ internally and sends a standard A2A message.
 - Read `a2a_profile` from discovery, default to `message`, and never infer Task
   support.
 - Use `--response-kind task` only when the selected Agent advertises `task`.
+- The platform answers a direct `message` send within its Message limit, 90
+  seconds, or the send fails with `A2AMessageLimitExceededError`. No client
+  setting extends that limit; send work that can take longer as a Task.
 - Do not send or request reasoning/thinking traces; standard A2A responses expose only message parts.
 
 ## Discovery Flow
@@ -244,6 +247,12 @@ result = AgentSession.send_a2a_message(
 task = AgentSession.wait_for_a2a_task(session, task_id=result.task.id)
 ```
 
+`wait_for_a2a_task` reads the Task every `poll_interval_seconds` (default 1)
+until it reaches a final state. Once `wait_timeout_seconds` (default 900) have
+passed it raises `TimeoutError`; the Task keeps running, so read it again with
+`AgentSession.get_a2a_task` or stop it with `AgentSession.cancel_a2a_task`. Its
+`timeout` is the total budget of each read, as for the other A2A calls.
+
 For another message in the same conversation, reuse the same `session.uid`:
 
 ```python
@@ -312,7 +321,18 @@ handle for a different task or conversation.
   task` for an Agent whose discovery profile advertises it. Preserve its ID and
   follow it with the SDK task get/wait/cancel helpers.
 - Treat a result kind different from the requested kind as a protocol error.
+- `timeout` (CLI `--timeout`) is one total budget for the send, including the
+  wait for a target runtime that is still starting or waking; it can only
+  shorten waits. If the runtime does not become ready within it, the send fails
+  with `AgentRuntimeNotReadyError` ("did not become ready") and nothing was
+  sent, so sending again later is safe.
 - Do not depend on reasoning, tool traces, runtime paths, or transport metadata.
+- If a direct `message` send fails with `A2AMessageLimitExceededError` (the
+  error says the Agent did not answer within the platform's limit), the Agent
+  stopped the turn after the platform's 90-second Message limit, and work it
+  already did is not undone. Do not resend it as a Message; when the Agent
+  advertises `task`, send the work with `--response-kind task`
+  (`response_kind=A2AResponseKind.TASK`) and follow the Task.
 - If a send times out or disconnects and must be retried, reuse the same
   `--message-id` value to preserve request identity. Direct `message` sends do
   not have durable replay protection, so do not retry automatically: the first

{mainsequence-9.0.20.dev62 → mainsequence-9.0.21.dev64}/mainsequence/cli/api.py

@@ -63,7 +63,27 @@ MCP_PROTOCOL_VERSION = "2025-11-25"
 MCP_CLIENT_NAME = "mainsequence-cli"
 MCP_MAX_RESOURCE_PAGES = 100
 
-S = requests.Session()
+
+class _CliSession(requests.Session):
+    """The CLI's HTTP session.
+
+    A request sent without its own timeout gets the SDK's default request
+    budget: 5 s to connect, 120 s to read and 125 s in total, inside any budget
+    that is already running.
+    """
+
+    def request(self, method, url, **kwargs):
+        if kwargs.get("timeout") is not None:
+            return super().request(method, url, **kwargs)
+        # The CLI imports the SDK client on its first request, not when it starts.
+        from mainsequence.client._transport import DEFAULT_TIMEOUT, request_budget
+
+        with request_budget(DEFAULT_TIMEOUT) as budget:
+            kwargs["timeout"] = budget.timeout()
+            return super().request(method, url, **kwargs)
+
+
+S = _CliSession()
 S.headers.update({"Content-Type": "application/json"})
 
 
@@ -488,11 +508,13 @@ def _mcp_json_rpc(
     request_id: int,
     protocol_version: str | None = None,
 ) -> dict[str, Any]:
-    """Send one authenticated stateless MCP JSON-RPC request."""
+    """Send one authenticated stateless MCP JSON-RPC request.
 
-    access = _access_token()
-    if not access:
-        access = refresh_access()
+    The request, a token renewal after ``401`` and the resend share the SDK's
+    default request budget: 5 s to connect, 120 s to read, 125 s in total.
+    """
+    # The CLI imports the SDK client only where it needs it.
+    from mainsequence.client._transport import DEFAULT_TIMEOUT, request_budget
 
     payload = {
         "jsonrpc": "2.0",
@@ -501,24 +523,36 @@ def _mcp_json_rpc(
         "params": params,
     }
 
-    def _send(token: str) -> requests.Response:
-        headers = {
-            "Authorization": f"Bearer {token}",
-            "Content-Type": "application/json",
-            "Accept": "application/json",
-        }
-        if protocol_version is not None:
-            headers["MCP-Protocol-Version"] = protocol_version
-        return S.request(
-            "POST",
-            _full(MCP_RESOURCE_PATH),
-            headers=headers,
-            data=json.dumps(payload),
-        )
+    with request_budget(DEFAULT_TIMEOUT) as budget:
 
-    response = _send(access)
-    if response.status_code == 401:
-        response = _send(refresh_access())
+        def _send(token: str) -> requests.Response:
+            headers = {
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+            if protocol_version is not None:
+                headers["MCP-Protocol-Version"] = protocol_version
+            return S.request(
+                "POST",
+                _full(MCP_RESOURCE_PATH),
+                headers=headers,
+                data=json.dumps(payload),
+                timeout=budget.timeout(),
+            )
+
+        try:
+            access = _access_token()
+            if not access:
+                access = refresh_access()
+            response = _send(access)
+            if response.status_code == 401:
+                response = _send(refresh_access())
+        except requests.Timeout as exc:
+            raise ApiError(
+                f"MCP {method} request timed out: the platform did not answer within "
+                "the request's timeout budget."
+            ) from exc
     if response.status_code == 401:
         raise NotLoggedIn("Not logged in.")
     if not response.ok:

{mainsequence-9.0.20.dev62 → mainsequence-9.0.21.dev64}/mainsequence/cli/cli.py

@@ -1946,6 +1946,10 @@ def login(
     except ApiError as e:
         error(f"Login failed: {e}")
         raise typer.Exit(1) from e
+    except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as e:
+        # Never echo the exception: a transport error can carry request details.
+        error(f"The backend at {normalized_backend} could not be reached ({type(e).__name__}).")
+        raise typer.Exit(1) from e
     finally:
         if previous_backend_override is None:
             os.environ.pop("MAINSEQUENCE_ENDPOINT", None)
@@ -4386,9 +4390,23 @@ def agent_session_a2a_send_cmd(
     response_kind: str = typer.Option(
         "message",
         "--response-kind",
-        help="Select the A2A result contract: message or task.",
+        help=(
+            "Select the A2A result contract. message: wait for the Agent's answer "
+            "within the platform's Message limit; a Message that reaches the limit "
+            "fails and is not retried. task: get a Task back for longer work, when "
+            "the Agent advertises it."
+        ),
+    ),
+    timeout: int | None = typer.Option(
+        None,
+        "--timeout",
+        help=(
+            "Total time budget in seconds for the A2A send: waiting for the Agent "
+            "runtime to become ready, the request and the response. "
+            "Resolving a handle first is a separate request with the same budget. "
+            "It can only shorten waits; it cannot extend the platform's limits."
+        ),
     ),
-    timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
 ):
     """
     Send one standard A2A message to an existing session UID or cached handle.

{mainsequence-9.0.20.dev62 → mainsequence-9.0.21.dev64}/mainsequence/client/_transport.py

@@ -1,8 +1,10 @@
 """One bounded retry policy for SDK HTTP sessions."""
 
+import contextvars
 import math
+import threading
 import time
-from contextlib import contextmanager
+from contextlib import contextmanager, suppress
 from contextvars import ContextVar
 
 import requests
@@ -80,6 +82,78 @@ def remaining_timeout(timeout):
     return Timeout(total=remaining, connect=min(connect, remaining), read=min(read, remaining))
 
 
+def request_within_budget(method, url, *, timeout, **kwargs):
+    """Send one request, never retried, whose whole exchange ends by one deadline.
+
+    ``timeout`` has the shared transport's meaning: a number is one total budget
+    in seconds, and a ``(connect, read)`` tuple keeps those phase limits with a
+    total equal to their sum. An enclosing :func:`request_budget` can only
+    shorten it. The deadline covers connecting, sending, the response headers
+    and the whole body, so a server that keeps sending bytes slowly cannot
+    extend it.
+
+    A socket read that keeps receiving bytes never times out on its own, so the
+    exchange runs on a helper thread and the caller stops waiting at the
+    deadline. Then the response, when it has started, is shut down and
+    ``requests.Timeout`` is raised. The request may already have reached the
+    server.
+    """
+    with request_budget(timeout) as budget:
+        attempt_timeout = budget.timeout()
+        lock = threading.Lock()
+        finished = threading.Event()
+        state = {"abandoned": False, "response": None, "outcome": None}
+
+        def exchange():
+            response = None
+            try:
+                with requests.Session() as session:
+                    response = session.request(
+                        method, url, timeout=attempt_timeout, stream=True, **kwargs
+                    )
+                    with lock:
+                        state["response"] = response
+                        abandoned = state["abandoned"]
+                    if not abandoned:
+                        # Read the body here, so the caller's deadline bounds it too.
+                        _ = response.content
+                outcome = response
+            except BaseException as exc:  # handed to the waiting caller
+                outcome = exc
+            with lock:
+                state["outcome"] = outcome
+                abandoned = state["abandoned"]
+            if abandoned and response is not None:
+                response.close()
+            finished.set()
+
+        threading.Thread(
+            target=contextvars.copy_context().run,
+            args=(exchange,),
+            name="mainsequence-request-within-budget",
+            daemon=True,
+        ).start()
+        try:
+            finished.wait(budget.remaining)
+        finally:
+            with lock:
+                outcome = state["outcome"]
+                if outcome is None:
+                    state["abandoned"] = True
+                started = state["response"]
+            if outcome is None and started is not None:
+                # Wakes a read that is still waiting for bytes.
+                with suppress(OSError, RuntimeError, ValueError):
+                    started.raw.shutdown()
+        if outcome is None:
+            raise requests.Timeout(
+                "The SDK request did not finish within its total timeout budget."
+            )
+        if isinstance(outcome, BaseException):
+            raise outcome
+        return outcome
+
+
 class DeadlineHTTPAdapter(HTTPAdapter):
     def __init__(self, *, retries, backoff_factor):
         if not isinstance(retries, int) or retries < 0: