ms-tau-sdk 2.0.20.dev71__tar.gz → 2.0.21.dev72__tar.gz

{ms_tau_sdk-2.0.20.dev71 → ms_tau_sdk-2.0.21.dev72}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2.0.21 — 2026-10-21
+
+- **Hosted Tasks can be sent, read and listed with their Messages
+  ([#111](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/111), ADR 0002).** On the platform,
+  a Task-mode `message:send` and GetTask answered HTTP 500 whenever the answer included the Task's
+  Messages. The platform stores a Task Message with the role `user` or `agent` and snake-case
+  fields such as `message_id`, and the SDK read it as one of its own binding Messages. The
+  platform client now translates every Task Message it reads, in a Task's `latest_message` and
+  `history` and in the Message tail, into a binding Message. The Task and context IDs come from
+  the Task the Message belongs to, and fields only the platform keeps, such as the request hash and
+  the requester, are left out. A2A callers get `ROLE_USER` and `ROLE_AGENT` as before.
+  - The platform's wake-up for a submitted hosted Task runs it again; the runtime had refused it
+    with HTTP 409 because it could not read the Task's requester Message.
+  - On the platform, `historyLength` returns the latest Messages instead of the first ones.
+  - `list_task_messages()` takes the Task and a `history_length` instead of a Task UID, `limit`
+    and `offset`.
+
+- **A Task-mode `message:send` that fails after its Task was accepted names the Task
+  ([#111](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/111), ADR 0002).** It answered a
+  bare HTTP 500 that looked as if nothing had happened, although the Task existed and could
+  already run. It now answers HTTP 500 `INTERNAL` with an `ErrorInfo` whose reason is
+  `ACCEPTED_TASK_STATE_UNAVAILABLE` and whose metadata gives the `taskId` and `contextId`, and
+  JSON-RPC answers `-32603` with the same `ErrorInfo`. The caller reads the Task with GetTask
+  instead of sending the Message again. See the
+  [runtime contract](docs/reference/runtime-contract.md#task-terminalization-and-failure).
+
 ## 2.0.20 — 2026-10-19
 
 - **ADR 0024 records the requirements for file attachments in chat.** The proposed

{ms_tau_sdk-2.0.20.dev71 → ms_tau_sdk-2.0.21.dev72}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 2.0.20.dev71
+Version: 2.0.21.dev72
 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.20.dev71 → ms_tau_sdk-2.0.21.dev72}/pyproject.toml

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

{ms_tau_sdk-2.0.20.dev71 → ms_tau_sdk-2.0.21.dev72}/src/ms_tau_sdk/api/a2a.py

@@ -8,7 +8,7 @@ import json
 import re
 import time
 import uuid
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Iterator
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from enum import StrEnum
@@ -448,6 +448,83 @@ def _message_limit_json_rpc_error(request_id: object, limit_seconds: float) -> d
     }
 
 
+class _AcceptedTaskUnanswered(Exception):
+    """A Task was accepted, but the answer that describes it could not be prepared."""
+
+    def __init__(self, task: AgentTask) -> None:
+        super().__init__(f"Task {task.task_id} was accepted, but its state could not be returned")
+        self.task_id = task.task_id
+        self.context_id = task.context_id
+
+
+@contextlib.contextmanager
+def _naming_accepted_task(task: AgentTask) -> Iterator[None]:
+    """Name ``task`` when the request fails after the Task was accepted.
+
+    The Task exists and may already run, so a bare server error would suggest that nothing
+    happened and invite the caller to send the Message again.
+    """
+
+    try:
+        yield
+    except Exception as error:
+        logger.error(
+            "a2a.task.answer_failed",
+            message="A Task was accepted, but the answer that describes it could not be prepared",
+            task_uid=task.uid,
+            task_id=task.task_id,
+            error_type=type(error).__name__,
+        )
+        raise _AcceptedTaskUnanswered(task) from error
+
+
+def _accepted_task_text(error: _AcceptedTaskUnanswered) -> str:
+    return (
+        f"Task {error.task_id} was accepted, but its state could not be returned. "
+        "Read it with GetTask instead of sending the Message again."
+    )
+
+
+def _accepted_task_error_info(error: _AcceptedTaskUnanswered) -> dict[str, Any]:
+    return {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "reason": "ACCEPTED_TASK_STATE_UNAVAILABLE",
+        "domain": "mainsequence.ai",
+        # ErrorInfo metadata values are strings.
+        "metadata": {"taskId": error.task_id, "contextId": error.context_id},
+    }
+
+
+def _accepted_task_rest_error(error: _AcceptedTaskUnanswered) -> JSONResponse:
+    return JSONResponse(
+        status_code=500,
+        media_type="application/a2a+json",
+        content={
+            "error": {
+                "code": 500,
+                "status": "INTERNAL",
+                "message": _accepted_task_text(error),
+                "details": [_accepted_task_error_info(error)],
+            }
+        },
+    )
+
+
+def _accepted_task_json_rpc_error(
+    request_id: object,
+    error: _AcceptedTaskUnanswered,
+) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": {
+            "code": -32603,
+            "message": _accepted_task_text(error),
+            "data": [_accepted_task_error_info(error)],
+        },
+    }
+
+
 def _without_push_notification_capability(
     agent_card: dict[str, Any] | None,
 ) -> dict[str, Any] | None:
@@ -631,7 +708,7 @@ async def _task_with_history(
 ) -> AgentTask:
     if history_length == 0:
         return task.model_copy(update={"history": None})
-    history = await client.list_task_messages(task.uid, limit=history_length, offset=0)
+    history = await client.list_task_messages(task, history_length=history_length)
     return task.model_copy(update={"history": history})
 
 
@@ -2376,6 +2453,8 @@ async def message_send(
         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]
+    except _AcceptedTaskUnanswered as error:
+        return _accepted_task_rest_error(error)  # type: ignore[return-value]
 
 
 async def _message_send(
@@ -2392,7 +2471,8 @@ async def _message_send(
     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.
+    transport answers in its own form. A Task-mode request that fails after its Task was accepted
+    raises ``_AcceptedTaskUnanswered``, which each transport answers with the Task named.
     """
     platform_limit = config.a2a_message_limit_seconds
     deadline = (
@@ -2447,48 +2527,14 @@ async def _message_send(
             continued_message,
             **_presented_assertion(caller_assertion),
         )
-        if config.local_mode:
-            task = await _persist_local_recovery_contract(
-                client,
-                task,
-                output_contract=output_contract,
-                provenance=provenance,
-            )
-        await _schedule_task_accelerator(
-            client,
-            manager,
-            task,
-            prompt=prompt,
-            output_contract=output_contract,
-            max_output_bytes=config.max_turn_output_bytes,
-            provenance=provenance,
-            config=config,
-            caller=_request_caller(caller_assertion),
-        )
-        if return_immediately:
-            task = await _task_with_history(client, task, history_length=history_length)
-            return {"task": _task_payload(task, history_length=history_length)}
-        task = await _wait_for_task_return_state(
-            client,
-            task,
-            poll_interval_seconds=config.a2a_task_event_poll_interval_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)}
-    if response_kind is ResponseKind.TASK:
-        caller_assertion = _task_caller_assertion(request, config)
-        creation = await _create_backend_task(
-            client,
-            message=message,
-            task_id=_task_id(body),
-            local_mode=config.local_mode,
-            output_contract=output_contract,
-            provenance=provenance,
-            caller_assertion=caller_assertion,
-        )
-        task = creation.task
-        if creation.created:
+        with _naming_accepted_task(task):
+            if config.local_mode:
+                task = await _persist_local_recovery_contract(
+                    client,
+                    task,
+                    output_contract=output_contract,
+                    provenance=provenance,
+                )
             await _schedule_task_accelerator(
                 client,
                 manager,
@@ -2511,31 +2557,68 @@ async def _message_send(
             )
             task = await _task_with_history(client, task, history_length=history_length)
             return {"task": _task_payload(task, history_length=history_length)}
+    if response_kind is ResponseKind.TASK:
+        caller_assertion = _task_caller_assertion(request, config)
+        creation = await _create_backend_task(
+            client,
+            message=message,
+            task_id=_task_id(body),
+            local_mode=config.local_mode,
+            output_contract=output_contract,
+            provenance=provenance,
+            caller_assertion=caller_assertion,
+        )
+        task = creation.task
+        if creation.created:
+            with _naming_accepted_task(task):
+                await _schedule_task_accelerator(
+                    client,
+                    manager,
+                    task,
+                    prompt=prompt,
+                    output_contract=output_contract,
+                    max_output_bytes=config.max_turn_output_bytes,
+                    provenance=provenance,
+                    config=config,
+                    caller=_request_caller(caller_assertion),
+                )
+                if return_immediately:
+                    task = await _task_with_history(client, task, history_length=history_length)
+                    return {"task": _task_payload(task, history_length=history_length)}
+                task = await _wait_for_task_return_state(
+                    client,
+                    task,
+                    poll_interval_seconds=config.a2a_task_event_poll_interval_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)}
         # An existing Task with this ID is answered only to a caller who may address its session.
         await _require_task_session_access(client, task, checked=requested_context_id)
-        if config.local_mode and task.status == "submitted":
-            recovered_prompt, recovered_contract, recovered_provenance = (
-                _recovery_execution_contract(task, config)
-            )
-            await _schedule_task_accelerator(
-                client,
-                manager,
-                task,
-                prompt=recovered_prompt,
-                output_contract=recovered_contract,
-                max_output_bytes=config.max_turn_output_bytes,
-                provenance=recovered_provenance,
-                config=config,
-            )
-        if not return_immediately and task.status not in TASK_RETURN_STATES:
-            task = await _wait_for_task_return_state(
-                client,
-                task,
-                poll_interval_seconds=config.a2a_task_event_poll_interval_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)}
+        with _naming_accepted_task(task):
+            if config.local_mode and task.status == "submitted":
+                recovered_prompt, recovered_contract, recovered_provenance = (
+                    _recovery_execution_contract(task, config)
+                )
+                await _schedule_task_accelerator(
+                    client,
+                    manager,
+                    task,
+                    prompt=recovered_prompt,
+                    output_contract=recovered_contract,
+                    max_output_bytes=config.max_turn_output_bytes,
+                    provenance=recovered_provenance,
+                    config=config,
+                )
+            if not return_immediately and task.status not in TASK_RETURN_STATES:
+                task = await _wait_for_task_return_state(
+                    client,
+                    task,
+                    poll_interval_seconds=config.a2a_task_event_poll_interval_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:
@@ -2845,6 +2928,8 @@ async def json_rpc(
                 )
             except _MessageLimitExceeded as error:
                 return _message_limit_json_rpc_error(request_id, error.limit_seconds)
+            except _AcceptedTaskUnanswered as error:
+                return _accepted_task_json_rpc_error(request_id, error)
         elif method in {"SendStreamingMessage", "message/stream"}:
             _response_kind(
                 params,

{ms_tau_sdk-2.0.20.dev71 → ms_tau_sdk-2.0.21.dev72}/src/ms_tau_sdk/backend/client.py

@@ -23,6 +23,7 @@ from ms_tau_sdk.errors import (
     LocalModeUnsupportedError,
     SessionNotFoundError,
 )
+from ms_tau_sdk.protocols.a2a_roles import platform_message_to_binding
 from ms_tau_sdk.settings import TauSDKSettings
 
 from .assertions import ASSERTION_HEADER
@@ -172,6 +173,30 @@ def _backend_rejection_log_fields(detail: object) -> dict[str, object]:
     return fields
 
 
+def _binding_message(task: AgentTask, record: Mapping[str, Any]) -> dict[str, Any]:
+    try:
+        return platform_message_to_binding(
+            record,
+            context_id=task.context_id,
+            task_id=task.task_id,
+        )
+    except ValueError as error:
+        raise BackendError(
+            f"Backend Task {task.task_id} has an invalid Message: {error}"
+        ) from error
+
+
+def _with_binding_messages(task: AgentTask) -> AgentTask:
+    """Return ``task`` with the Messages the platform stores as Main Sequence binding Messages."""
+
+    update: dict[str, Any] = {}
+    if task.latest_message is not None:
+        update["latest_message"] = _binding_message(task, task.latest_message)
+    if task.history is not None:
+        update["history"] = [_binding_message(task, record) for record in task.history]
+    return task.model_copy(update=update) if update else task
+
+
 class MainSequenceClient:
     def __init__(
         self,
@@ -970,7 +995,7 @@ class MainSequenceClient:
             headers={ASSERTION_HEADER: caller_assertion} if caller_assertion else None,
         )
         return AgentTaskCreateResult(
-            task=AgentTask.model_validate(data),
+            task=_with_binding_messages(AgentTask.model_validate(data)),
             created=status_code == 201,
         )
 
@@ -979,7 +1004,10 @@ class MainSequenceClient:
         path = AGENT_TASKS + (f"?{query}" if query else "")
         data = await self._request("GET", path, idempotent=True)
         values = data.get("results", []) if isinstance(data, dict) else data
-        return TypeAdapter(list[AgentTask]).validate_python(values or [])
+        return [
+            _with_binding_messages(task)
+            for task in TypeAdapter(list[AgentTask]).validate_python(values or [])
+        ]
 
     async def get_task_by_protocol_id(
         self,
@@ -1008,25 +1036,26 @@ class MainSequenceClient:
             f"{AGENT_TASKS}{task_uid}/{query}",
             idempotent=True,
         )
-        return AgentTask.model_validate(data)
+        return _with_binding_messages(AgentTask.model_validate(data))
 
     async def list_task_messages(
         self,
-        task_uid: str,
+        task: AgentTask,
         *,
-        limit: int = 100,
-        offset: int = 0,
+        history_length: int,
     ) -> list[dict[str, Any]]:
-        query = urlencode({"limit": max(0, min(int(limit), 100)), "offset": max(0, int(offset))})
+        """Return the latest ``history_length`` Messages of ``task``, oldest first."""
+
+        query = urlencode({"history_length": max(0, min(int(history_length), 100))})
         data = await self._request(
             "GET",
-            f"{agent_task_operation(task_uid, 'messages')}?{query}",
+            f"{agent_task_operation(task.uid, 'messages')}?{query}",
             idempotent=True,
         )
         values = data.get("results", []) if isinstance(data, dict) else data
         if not isinstance(values, list) or any(not isinstance(item, dict) for item in values):
             raise BackendError("Backend Task-message response is invalid")
-        return [dict(item) for item in values]
+        return [_binding_message(task, item) for item in values]
 
     async def get_task_snapshot(self, task_uid: str) -> AgentTaskSnapshot:
         data = await self._request(
@@ -1034,7 +1063,8 @@ class MainSequenceClient:
             agent_task_operation(task_uid, "snapshot"),
             idempotent=True,
         )
-        return AgentTaskSnapshot.model_validate(data)
+        snapshot = AgentTaskSnapshot.model_validate(data)
+        return snapshot.model_copy(update={"task": _with_binding_messages(snapshot.task)})
 
     async def get_task_snapshot_by_protocol_id(self, task_id: str) -> AgentTaskSnapshot:
         task = await self.get_task_by_protocol_id(task_id)
@@ -1262,7 +1292,7 @@ class MainSequenceClient:
             idempotent=True,
             headers={ASSERTION_HEADER: caller_assertion} if caller_assertion else None,
         )
-        return AgentTask.model_validate(data)
+        return _with_binding_messages(AgentTask.model_validate(data))
 
     async def cancel_task(self, task_uid: str) -> AgentTask:
         data = await self._request(
@@ -1271,4 +1301,4 @@ class MainSequenceClient:
             json={},
             idempotent=True,
         )
-        return AgentTask.model_validate(data)
+        return _with_binding_messages(AgentTask.model_validate(data))

{ms_tau_sdk-2.0.20.dev71 → ms_tau_sdk-2.0.21.dev72}/src/ms_tau_sdk/backend/local.py

@@ -2590,20 +2590,14 @@ class LocalDevelopmentBackend(MainSequenceClient):
 
     async def list_task_messages(
         self,
-        task_uid: str,
+        task: AgentTask,
         *,
-        limit: int = 100,
-        offset: int = 0,
+        history_length: int,
     ) -> list[dict[str, Any]]:
         def operation() -> list[dict[str, Any]]:
             with closing(self._connect()) as connection:
-                self._task_row(connection, task_uid)
-                return self._task_messages(
-                    connection,
-                    task_uid,
-                    limit=limit,
-                    offset=offset,
-                )
+                self._task_row(connection, task.uid)
+                return self._task_messages(connection, task.uid, limit=history_length)
 
         return await self._run(operation)
 

{ms_tau_sdk-2.0.20.dev71 → ms_tau_sdk-2.0.21.dev72}/src/ms_tau_sdk/protocols/a2a_roles.py

@@ -1,4 +1,4 @@
-"""Role translation between A2A v1 and the Main Sequence Tau binding."""
+"""Role translation between A2A v1, the Main Sequence Tau binding, and platform storage."""
 
 from __future__ import annotations
 
@@ -19,11 +19,22 @@ class A2AProtocolRole(StrEnum):
     AGENT = "ROLE_AGENT"
 
 
+class PlatformMessageRole(StrEnum):
+    """Direction-neutral roles of a Task Message the platform stores."""
+
+    USER = "user"
+    AGENT = "agent"
+
+
 _TO_BINDING = {
     A2AProtocolRole.USER.value: A2AMessageDirection.REQUESTER.value,
     A2AProtocolRole.AGENT.value: A2AMessageDirection.RESPONDER.value,
 }
 _TO_PROTOCOL = {value: key for key, value in _TO_BINDING.items()}
+_FROM_PLATFORM = {
+    PlatformMessageRole.USER.value: A2AMessageDirection.REQUESTER.value,
+    PlatformMessageRole.AGENT.value: A2AMessageDirection.RESPONDER.value,
+}
 
 
 def _validate_message_shape(message: Mapping[str, object]) -> None:
@@ -60,6 +71,36 @@ def message_to_protocol(message: Mapping[str, object]) -> dict[str, object]:
     return {**message, "role": _TO_PROTOCOL[role]}
 
 
+def platform_message_to_binding(
+    record: Mapping[str, object],
+    *,
+    context_id: str,
+    task_id: str,
+) -> dict[str, object]:
+    """Translate a Task Message the platform stores into a Main Sequence binding Message.
+
+    The platform stores the role ``user`` or ``agent`` and snake-case fields. The Task that owns
+    the Message supplies its context and Task IDs. Fields only the platform keeps, such as the
+    request hash and the requester, are left out.
+    """
+
+    role = str(record.get("role") or "")
+    if role not in _FROM_PLATFORM:
+        raise ValueError("Platform Task Message role must be user or agent")
+    message: dict[str, object] = {
+        "messageId": record.get("message_id"),
+        "contextId": context_id,
+        "taskId": task_id,
+        "role": _FROM_PLATFORM[role],
+        "parts": record.get("parts"),
+        "metadata": record.get("metadata", {}),
+        "extensions": record.get("extensions", []),
+        "referenceTaskIds": record.get("reference_task_ids", []),
+    }
+    _validate_message_shape(message)
+    return message
+
+
 def has_a2a_direction(
     message: Mapping[str, object],
     direction: A2AMessageDirection,
@@ -72,7 +113,9 @@ def has_a2a_direction(
 __all__ = [
     "A2AMessageDirection",
     "A2AProtocolRole",
+    "PlatformMessageRole",
     "has_a2a_direction",
     "message_to_binding",
     "message_to_protocol",
+    "platform_message_to_binding",
 ]