mainsequence 6.0.45__tar.gz → 6.0.46__tar.gz

{mainsequence-6.0.45/mainsequence.egg-info → mainsequence-6.0.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 6.0.45
+Version: 6.0.46
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: LicenseRef-MainSequence-Proprietary

{mainsequence-6.0.45 → mainsequence-6.0.46}/agent_scaffold/skills/a2a_sdk_execution/SKILL.md

@@ -30,6 +30,9 @@ internally and sends a standard A2A message.
 - Do not expose runtime credentials in prompts, logs, or user-facing answers.
 - Do not use commands that require both target agent UID and target session UID for chat.
 - Use `--strict-dictionary` when the target answer must be machine-parseable JSON.
+- Read `a2a_profile` from discovery, default to `message`, and never infer Task
+  support.
+- Use `--response-kind task` only when the selected Agent advertises `task`.
 - Do not send or request reasoning/thinking traces; standard A2A responses expose only message parts.
 
 ## Discovery Flow
@@ -53,6 +56,7 @@ Agent's environment.
 5. Prefer the highest `combined_score` when present.
 6. If the user asked only which agents are available, summarize the candidates and stop.
    Include agent name, agent UID, and a short capability summary.
+7. Preserve the selected Agent's `a2a_profile` for request validation.
 
 ## Target Session
 
@@ -106,6 +110,15 @@ mainsequence agent session a2a send \
   --message "Summarize the current portfolio drift."
 ```
 
+For advertised asynchronous work, explicitly request a Task:
+
+```bash
+mainsequence agent session a2a send \
+  <target_agent_session_uid> \
+  --message "Run the full analysis asynchronously." \
+  --response-kind task
+```
+
 For a second message to the same target session, send another chat command
 with the same target `AgentSession` UID:
 
@@ -189,7 +202,11 @@ handle_unique_id -> AgentSession.uid -> A2A message.contextId
 Direct SDK flow:
 
 ```python
-from mainsequence.client.agent_runtime_models import Agent, AgentSession
+from mainsequence.client.agent_runtime_models import (
+    A2AResponseKind,
+    Agent,
+    AgentSession,
+)
 
 
 agent = Agent.get_by_uid(target_agent_uid)
@@ -202,7 +219,24 @@ response = AgentSession.send_a2a_message(
     session.uid,
     message="Return a JSON object with keys: summary, risk_level, next_action.",
     strict_dictionary=True,
+    response_kind=A2AResponseKind.MESSAGE,
+    a2a_profile=agent.a2a_profile,
+)
+```
+
+Use asynchronous Task mode only when discovery advertises it:
+
+```python
+if A2AResponseKind.TASK not in agent.a2a_profile.supported_response_kinds:
+    raise ValueError("The selected agent does not advertise A2A Task responses")
+
+result = AgentSession.send_a2a_message(
+    session,
+    message="Run the full analysis asynchronously.",
+    response_kind=A2AResponseKind.TASK,
+    a2a_profile=agent.a2a_profile,
 )
+task = AgentSession.wait_for_a2a_task(session, task_id=result.task.id)
 ```
 
 For another message in the same conversation, reuse the same `session.uid`:
@@ -267,12 +301,19 @@ handle for a different task or conversation.
 ## Response Handling
 
 - Parse the CLI output as the standard A2A JSON response.
-- Consume only `message.parts` from the A2A response.
+- The default `message` result is direct execution and does not create an A2A
+  Task. Consume only its documented `message.parts`.
+- A `task` result is valid only after explicitly selecting `--response-kind
+  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.
 - Do not depend on reasoning, tool traces, runtime paths, or transport metadata.
 - If a send times out or disconnects and must be retried, reuse the same
-  `--message-id` value so the target can treat it as the same logical message.
+  `--message-id` value to preserve request identity. Direct `message` sends do
+  not have durable replay protection, so do not retry automatically: the first
+  turn may already have executed. Use `task` when durable recovery is required.
 - If the CLI generated the message id and the send failed, reuse the
-  `A2A message id for exact retry` value printed with the error.
+  `A2A message id for request retry` value printed with the error.
 
 ## Deterministic Execution Path
 
@@ -282,7 +323,9 @@ handle for a different task or conversation.
 4. Create or resolve the target session with `mainsequence agent session get_or_create`.
 5. Use the returned session `uid`.
 6. Run `mainsequence agent session a2a send <target_agent_session_uid> ...`.
-7. Parse `message.parts` from the CLI output.
+7. Inspect the selected Agent's `a2a_profile` and default to `message`.
+8. Parse `message.parts`, or follow the returned Task only when Task mode was
+   explicitly selected and advertised.
 
 ## Role-Specific Behavior
 

{mainsequence-6.0.45 → mainsequence-6.0.46}/mainsequence/cli/api.py

@@ -1417,7 +1417,7 @@ def send_agent_session_a2a_message(
     message_id: str | None = None,
     strict_dictionary: bool = False,
     json_repair_attempts: int = 3,
-    return_immediately: bool = False,
+    response_kind: str = "message",
     timeout: int | None = None,
 ) -> dict[str, Any]:
     """
@@ -1437,7 +1437,7 @@ def send_agent_session_a2a_message(
                 cached_runtime_access=cached_runtime_access,
                 strict_dictionary=strict_dictionary,
                 json_repair_attempts=json_repair_attempts,
-                return_immediately=return_immediately,
+                response_kind=response_kind,
                 timeout=timeout,
             ),
         )
@@ -1463,7 +1463,7 @@ def _send_agent_session_a2a_message_with_cache(
     cached_runtime_access: dict[str, Any] | None,
     strict_dictionary: bool,
     json_repair_attempts: int,
-    return_immediately: bool,
+    response_kind: str,
     timeout: int | None,
 ):
     if cached_runtime_access is not None:
@@ -1476,7 +1476,7 @@ def _send_agent_session_a2a_message_with_cache(
         message_id=message_id,
         strict_dictionary=strict_dictionary,
         json_repair_attempts=json_repair_attempts,
-        return_immediately=return_immediately,
+        response_kind=response_kind,
         timeout=timeout,
     )
 

{mainsequence-6.0.45 → mainsequence-6.0.46}/mainsequence/cli/cli.py

@@ -3788,7 +3788,7 @@ def _agent_session_a2a_send_impl(
     strict_dictionary: bool,
     json_repair_attempts: int,
     message_id: str | None,
-    return_immediately: bool,
+    response_kind: str,
     timeout: int | None,
 ) -> None:
     try:
@@ -3806,6 +3806,9 @@ def _agent_session_a2a_send_impl(
     if json_repair_attempts < 1:
         error("--json-repair-attempts must be greater than 0.")
         raise typer.Exit(1)
+    if response_kind not in {"message", "task"}:
+        error("--response-kind must be 'message' or 'task'.")
+        raise typer.Exit(1)
     attachment_paths = list(files or [])
     attachment_media_types = list(media_types or [])
     if attachment_media_types and len(attachment_media_types) != len(attachment_paths):
@@ -3841,12 +3844,12 @@ def _agent_session_a2a_send_impl(
             message_id=effective_message_id,
             strict_dictionary=strict_dictionary,
             json_repair_attempts=json_repair_attempts,
-            return_immediately=return_immediately,
+            response_kind=response_kind,
             timeout=timeout,
         )
     except ApiError as e:
         error(str(e))
-        error(f"A2A message id for exact retry: {effective_message_id}")
+        error(f"A2A message id for request retry: {effective_message_id}")
         raise typer.Exit(1) from e
 
     typer.echo(json.dumps(response_payload, indent=2))
@@ -4991,12 +4994,12 @@ def agent_session_a2a_send_cmd(
     message_id: str | None = typer.Option(
         None,
         "--message-id",
-        help="Stable A2A message.messageId to reuse for an exact retry.",
+        help="Stable A2A message.messageId to preserve request identity across a retry.",
     ),
-    return_immediately: bool = typer.Option(
-        False,
-        "--return-immediately",
-        help="Ask the runtime to return immediately instead of waiting for final output.",
+    response_kind: str = typer.Option(
+        "message",
+        "--response-kind",
+        help="Select the A2A result contract: message or task.",
     ),
     timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
 ):
@@ -5015,7 +5018,7 @@ def agent_session_a2a_send_cmd(
         strict_dictionary=strict_dictionary,
         json_repair_attempts=json_repair_attempts,
         message_id=message_id,
-        return_immediately=return_immediately,
+        response_kind=response_kind,
         timeout=timeout,
     )
 

{mainsequence-6.0.45 → mainsequence-6.0.46}/mainsequence/client/agent_runtime_models.py

@@ -20,7 +20,11 @@ DEFAULT_AGENT_SESSION_LONG_REQUEST_TIMEOUT = (5.0, 900.0)
 DEFAULT_AGENT_RUNTIME_ACCESS_CACHE_TTL_SECONDS = 60.0
 DEFAULT_AGENT_RUNTIME_ACCESS_CACHE_EXPIRY_SKEW_SECONDS = 30.0
 STANDARD_A2A_MESSAGE_SEND_PATH = "/api/a2a/v1/message:send"
+STANDARD_A2A_TASKS_PATH = "/api/a2a/v1/tasks"
 STANDARD_A2A_CONTENT_TYPE = "application/a2a+json"
+STANDARD_A2A_RESPONSE_KIND_EXTENSION_URI = (
+    "https://mainsequence.ai/a2a/extensions/response-kind/v1"
+)
 STANDARD_A2A_OUTPUT_CONTRACT_METADATA_KEY = (
     "https://mainsequence.ai/a2a/extensions/output-contract/v1"
 )
@@ -35,6 +39,67 @@ class AgentSessionStatus(str, Enum):
     CANCELED = "canceled"
 
 
+class A2AResponseKind(str, Enum):
+    MESSAGE = "message"
+    TASK = "task"
+
+
+class AgentA2AProfile(BasePydanticModel):
+    response_kind_extension_uri: str = STANDARD_A2A_RESPONSE_KIND_EXTENSION_URI
+    supported_response_kinds: list[A2AResponseKind] = Field(
+        default_factory=lambda: [A2AResponseKind.MESSAGE]
+    )
+    default_response_kind: A2AResponseKind = A2AResponseKind.MESSAGE
+
+    @model_validator(mode="after")
+    def _validate_default(self) -> AgentA2AProfile:
+        if self.response_kind_extension_uri != STANDARD_A2A_RESPONSE_KIND_EXTENSION_URI:
+            raise ValueError("response_kind_extension_uri is not supported")
+        self.supported_response_kinds = list(dict.fromkeys(self.supported_response_kinds))
+        if not self.supported_response_kinds:
+            raise ValueError("supported_response_kinds must not be empty")
+        if A2AResponseKind.MESSAGE not in self.supported_response_kinds:
+            raise ValueError("supported_response_kinds must include 'message'")
+        if self.default_response_kind is not A2AResponseKind.MESSAGE:
+            raise ValueError("default_response_kind must be 'message'")
+        return self
+
+
+class A2ATaskStatus(BasePydanticModel):
+    model_config = ConfigDict(extra="allow")
+
+    state: str
+    timestamp: str | None = None
+    message: Any | None = None
+
+
+class A2ATask(BasePydanticModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True, serialize_by_alias=True)
+
+    kind: Literal["task"] = "task"
+    id: str
+    context_id: str = Field(alias="contextId")
+    status: A2ATaskStatus
+    artifacts: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class A2AMessageSendResult(BasePydanticModel):
+    model_config = ConfigDict(serialize_by_alias=True)
+
+    message: dict[str, Any] | None = None
+    task: A2ATask | None = None
+
+    @model_validator(mode="after")
+    def _require_exact_result(self) -> A2AMessageSendResult:
+        if (self.message is None) == (self.task is None):
+            raise ValueError("A2A message-send result must contain exactly one of message or task")
+        return self
+
+    @property
+    def response_kind(self) -> A2AResponseKind:
+        return A2AResponseKind.TASK if self.task is not None else A2AResponseKind.MESSAGE
+
+
 class AgentHarnessKind(str, Enum):
     PI = "pi"
     TAU = "tau"
@@ -56,6 +121,7 @@ class AgentSemanticSearchResult(BasePydanticModel):
         "",
         description="Short description returned by semantic search for the matched agent.",
     )
+    a2a_profile: AgentA2AProfile = Field(default_factory=AgentA2AProfile)
     project_branch_uid: str = Field(
         ...,
         description="Public UID of the ProjectBranch that owns the matched Project Coding Agent.",
@@ -278,6 +344,7 @@ class Agent(ShareableObjectMixin, BaseObjectOrm, BasePydanticModel):
         None,
         description="Optional structured agent card payload.",
     )
+    a2a_profile: AgentA2AProfile = Field(default_factory=AgentA2AProfile)
 
     llm_thinking: str
     llm_provider: str = Field(
@@ -958,7 +1025,7 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
         message_id: str | None = None,
         strict_dictionary: bool = False,
         json_repair_attempts: int = 3,
-        return_immediately: bool = False,
+        response_kind: A2AResponseKind = A2AResponseKind.MESSAGE,
     ) -> dict[str, Any]:
         normalized_message = str(message)
         if not normalized_message.strip():
@@ -970,6 +1037,10 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
             normalized_message_id = f"msg-{uuid.uuid4()}"
 
         accepted_output_modes = ["application/json"] if strict_dictionary else ["text/plain"]
+        try:
+            normalized_response_kind = A2AResponseKind(response_kind)
+        except ValueError as exc:
+            raise ValueError("response_kind must be 'message' or 'task'") from exc
         parts: list[dict[str, Any]] = [{"text": normalized_message}]
         for file_spec in files or []:
             parts.append(AgentSession._build_standard_a2a_raw_file_part(file_spec))
@@ -983,7 +1054,7 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
             },
             "configuration": {
                 "acceptedOutputModes": accepted_output_modes,
-                "returnImmediately": bool(return_immediately),
+                "responseKind": normalized_response_kind.value,
             },
         }
         if strict_dictionary:
@@ -1060,6 +1131,7 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
             "Authorization": f"Bearer {access.token.strip()}",
             "Content-Type": STANDARD_A2A_CONTENT_TYPE,
             "Accept": STANDARD_A2A_CONTENT_TYPE,
+            "A2A-Extensions": STANDARD_A2A_RESPONSE_KIND_EXTENSION_URI,
         }
         return requests.post(
             url,
@@ -1069,8 +1141,10 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
         )
 
     @staticmethod
-    def extract_a2a_message_text(payload: dict[str, Any]) -> str:
-        message = payload.get("message")
+    def extract_a2a_message_text(
+        payload: dict[str, Any] | A2AMessageSendResult,
+    ) -> str:
+        message = payload.message if isinstance(payload, A2AMessageSendResult) else payload.get("message")
         if not isinstance(message, dict):
             return ""
         parts = message.get("parts")
@@ -1092,13 +1166,38 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
         message_id: str | None = None,
         strict_dictionary: bool = False,
         json_repair_attempts: int = 3,
-        return_immediately: bool = False,
+        response_kind: A2AResponseKind = A2AResponseKind.MESSAGE,
+        a2a_profile: AgentA2AProfile | dict[str, Any] | None = None,
         timeout=None,
-    ) -> dict[str, Any]:
+    ) -> A2AMessageSendResult:
         """
         Send one standard A2A message to the runtime for this agent session.
         """
         session_uid = cls._resolve_agent_session_uid(agent_session)
+        normalized_response_kind = A2AResponseKind(response_kind)
+        resolved_profile: AgentA2AProfile | None = None
+        if a2a_profile is not None:
+            resolved_profile = (
+                a2a_profile
+                if isinstance(a2a_profile, AgentA2AProfile)
+                else AgentA2AProfile.model_validate(a2a_profile)
+            )
+        elif normalized_response_kind is A2AResponseKind.TASK:
+            session = (
+                agent_session
+                if isinstance(agent_session, AgentSession)
+                else cls.get(pk=session_uid, timeout=timeout)
+            )
+            if not session.agent_uid:
+                raise ValueError("Task response_kind requires a session with an agent_uid")
+            resolved_profile = Agent.get(pk=session.agent_uid, timeout=timeout).a2a_profile
+        if (
+            resolved_profile is not None
+            and normalized_response_kind not in resolved_profile.supported_response_kinds
+        ):
+            raise ValueError(
+                f"response_kind {normalized_response_kind.value!r} is not advertised by the agent"
+            )
         body = cls._build_standard_a2a_message_send_body(
             agent_session_uid=session_uid,
             message=message,
@@ -1106,7 +1205,7 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
             message_id=message_id,
             strict_dictionary=strict_dictionary,
             json_repair_attempts=json_repair_attempts,
-            return_immediately=return_immediately,
+            response_kind=normalized_response_kind,
         )
         access = cls._resolve_runtime_access_for_message_send(session_uid, timeout=timeout)
         response = cls._post_standard_a2a_message(
@@ -1140,7 +1239,150 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
             ) from exc
         if not isinstance(payload, dict):
             raise TypeError("Standard A2A response must be a JSON object")
-        return payload
+        try:
+            result = A2AMessageSendResult.model_validate(payload)
+        except ValueError as exc:
+            raise ApiError(
+                "Standard A2A response must contain exactly one valid message or task result.",
+                response=response,
+                payload=body,
+            ) from exc
+        if result.response_kind is not normalized_response_kind:
+            raise ApiError(
+                "Standard A2A response kind does not match the requested response_kind.",
+                response=response,
+                payload=body,
+            )
+        return result
+
+    @classmethod
+    def _request_a2a_task(
+        cls,
+        agent_session: str | AgentSession,
+        *,
+        task_id: str,
+        cancel: bool,
+        timeout=None,
+    ) -> A2ATask:
+        session_uid = cls._resolve_agent_session_uid(agent_session)
+        normalized_task_id = str(task_id or "").strip()
+        if not normalized_task_id or "/" in normalized_task_id:
+            raise ValueError("task_id must be a non-empty A2A task identifier")
+
+        def request(access: AgentSessionRuntimeAccess) -> requests.Response:
+            if access.mode != "token":
+                raise ApiError("Coding-agent runtime access is unavailable.")
+            if not isinstance(access.token, str) or not access.token.strip():
+                raise ApiError("Runtime access response is missing token.")
+            path = f"{STANDARD_A2A_TASKS_PATH}/{normalized_task_id}"
+            method = "GET"
+            if cancel:
+                path = f"{path}:cancel"
+                method = "POST"
+            request_timeout = (
+                DEFAULT_AGENT_SESSION_LONG_REQUEST_TIMEOUT if timeout is None else timeout
+            )
+            return requests.request(
+                method,
+                _join_runtime_url(access.rpc_url, path),
+                headers={
+                    "Authorization": f"Bearer {access.token.strip()}",
+                    "Accept": STANDARD_A2A_CONTENT_TYPE,
+                },
+                timeout=request_timeout,
+            )
+
+        access = cls._resolve_runtime_access_for_message_send(session_uid, timeout=timeout)
+        response = request(access)
+        if response.status_code in (401, 403):
+            cls.clear_cached_runtime_access(session_uid)
+            access = cls.resolve_runtime_access(session_uid, cache=True, timeout=timeout)
+            response = request(access)
+            if response.status_code in (401, 403):
+                cls.clear_cached_runtime_access(session_uid)
+        if not (200 <= response.status_code < 300):
+            raise_for_response(response)
+        try:
+            payload = response.json()
+        except Exception as exc:
+            raise ApiError(
+                "Standard A2A task response must be a JSON object.",
+                response=response,
+            ) from exc
+        task_payload = payload.get("task") if isinstance(payload, dict) else None
+        if not isinstance(task_payload, dict):
+            raise ApiError(
+                "Standard A2A task response must contain a task object.",
+                response=response,
+            )
+        return A2ATask.model_validate(task_payload)
+
+    @classmethod
+    def get_a2a_task(
+        cls,
+        agent_session: str | AgentSession,
+        *,
+        task_id: str,
+        timeout=None,
+    ) -> A2ATask:
+        return cls._request_a2a_task(
+            agent_session,
+            task_id=task_id,
+            cancel=False,
+            timeout=timeout,
+        )
+
+    @classmethod
+    def cancel_a2a_task(
+        cls,
+        agent_session: str | AgentSession,
+        *,
+        task_id: str,
+        timeout=None,
+    ) -> A2ATask:
+        return cls._request_a2a_task(
+            agent_session,
+            task_id=task_id,
+            cancel=True,
+            timeout=timeout,
+        )
+
+    @classmethod
+    def wait_for_a2a_task(
+        cls,
+        agent_session: str | AgentSession,
+        *,
+        task_id: str,
+        poll_interval_seconds: float = 1.0,
+        wait_timeout_seconds: float = 900.0,
+        timeout=None,
+    ) -> A2ATask:
+        if poll_interval_seconds <= 0:
+            raise ValueError("poll_interval_seconds must be greater than 0")
+        if wait_timeout_seconds <= 0:
+            raise ValueError("wait_timeout_seconds must be greater than 0")
+        deadline = time.monotonic() + wait_timeout_seconds
+        terminal_states = {
+            "completed",
+            "failed",
+            "canceled",
+            "rejected",
+            "TASK_STATE_COMPLETED",
+            "TASK_STATE_FAILED",
+            "TASK_STATE_CANCELED",
+            "TASK_STATE_REJECTED",
+        }
+        while True:
+            task = cls.get_a2a_task(
+                agent_session,
+                task_id=task_id,
+                timeout=timeout,
+            )
+            if task.status.state in terminal_states:
+                return task
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Timed out waiting for A2A task {task_id}")
+            time.sleep(poll_interval_seconds)
 
     @classmethod
     def resolve_runtime_access(
@@ -1415,7 +1657,12 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
 
 
 __all__ = [
+    "A2AMessageSendResult",
+    "A2AResponseKind",
+    "A2ATask",
+    "A2ATaskStatus",
     "Agent",
+    "AgentA2AProfile",
     "AgentRuntimeImageDrift",
     "AgentRuntimeImageDriftCheck",
     "AgentHarnessKind",

{mainsequence-6.0.45 → mainsequence-6.0.46/mainsequence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 6.0.45
+Version: 6.0.46
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: LicenseRef-MainSequence-Proprietary

{mainsequence-6.0.45 → mainsequence-6.0.46}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence"
-version = "6.0.45"
+version = "6.0.46"
 description = "Main Sequence SDK "
 readme = "README.md"
 requires-python = ">=3.13"

{mainsequence-6.0.45 → mainsequence-6.0.46}/tests/test_cli.py

@@ -6867,7 +6867,7 @@ def test_agent_session_a2a_send_always_returns_json(cli_mod, runner, monkeypatch
     assert captured["kwargs"]["message_id"] == "msg-client-1"
     assert captured["kwargs"]["strict_dictionary"] is True
     assert captured["kwargs"]["json_repair_attempts"] == 3
-    assert captured["kwargs"]["return_immediately"] is False
+    assert captured["kwargs"]["response_kind"] == "message"
     assert "omit_reasoning" not in captured["kwargs"]