mainsequence 4.4.12__tar.gz → 4.4.16__tar.gz

{mainsequence-4.4.12/mainsequence.egg-info → mainsequence-4.4.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.4.12
+Version: 4.4.16
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

mainsequence-4.4.16/agent_scaffold/skills/a2a_communication/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: a2a_communication
+description: Canonical guidance for discovering agents and sending session-scoped A2A requests through Main Sequence.
+---
+
+# A2A Communication
+
+Use this skill when you need to discover another agent or send a bounded A2A
+request to an existing target `AgentSession`.
+
+## Canonical CLI Path
+
+Use the standard A2A CLI send command. The CLI resolves the target runtime
+internally and sends a standard A2A message.
+
+## When To Use
+
+- When the user asks which agents can help.
+- When another agent may be better suited to answer or assist.
+- Before sending a request to an existing target agent session.
+- When a request explicitly arrives through the A2A channel.
+
+## Core Rules
+
+- A2A communication is scoped to an `AgentSession` UID.
+- Use the target `AgentSession` UID for chat.
+- 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.
+- Do not send or request reasoning/thinking traces; standard A2A responses expose only message parts.
+
+## Discovery Flow
+
+1. Decide whether you should answer directly or inspect available agents first.
+2. Build a bounded discovery prompt with the requested capability and expected output shape.
+3. Run:
+
+```bash
+mainsequence agent search "<discoveryPrompt>" --limit 10 --json
+```
+
+4. Treat the CLI output as authoritative.
+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, stable unique id, and a short capability summary.
+
+## Target Session
+
+Use an existing target `AgentSession` UID. If the target session UID is not
+available, get it from the active task context or ask for it before sending A2A
+messages.
+
+## Send A2A Chat
+
+For JSON-shaped answers, use:
+
+```bash
+mainsequence agent session a2a send \
+  <target_agent_session_uid> \
+  --message "Return a JSON object with keys: summary, risk_level, next_action." \
+  --strict-dictionary
+```
+
+For plain text answers, use:
+
+```bash
+mainsequence agent session a2a send \
+  <target_agent_session_uid> \
+  --message "Summarize the current portfolio drift."
+```
+
+For a second message to the same target session, send another chat command
+with the same target `AgentSession` UID:
+
+```bash
+mainsequence agent session a2a send \
+  <target_agent_session_uid> \
+  --message "Now identify the highest priority follow-up."
+```
+
+## Response Handling
+
+- Parse the CLI output as the standard A2A JSON response.
+- Consume only `message.parts` from the A2A response.
+- Do not depend on reasoning, tool traces, runtime paths, or transport metadata.
+
+## Deterministic Execution Path
+
+1. Build the discovery prompt.
+2. Run `mainsequence agent search "<discoveryPrompt>" --limit <n> --json`.
+3. Select the target agent.
+4. Get the target `AgentSession` UID.
+5. Run `mainsequence agent session a2a send <target_agent_session_uid> ...`.
+6. Parse `message.parts` from the CLI output.
+
+## Role-Specific Behavior
+
+### Orchestrator Agent
+
+- May discover candidates without confirmation.
+- Must get user confirmation before sending a real A2A request for user-originated requests.
+- Should offer A2A briefly when another agent may be better suited.
+
+### Runtime-Owned Child Or Executor Agent
+
+- May use bounded A2A within the active task scope without separate user confirmation.
+- Should keep the request tightly scoped to the current project or active task.
+
+## A2A Response Behavior
+
+- If the request is marked as A2A, respond agent-to-agent rather than user-to-agent.
+- If a response format or output schema is specified, follow it exactly.
+- If no response format is specified, return a concise machine-usable response.
+
+## Do Not
+
+- Do not let A2A broaden your scope.
+- Do not replace CLI discovery with ad hoc local prompt-file inspection.
+- Do not send another agent work when discovery alone was requested.
+- Do not call lower-level transports or extract runtime credentials.

{mainsequence-4.4.12 → mainsequence-4.4.16}/mainsequence/cli/api.py

@@ -38,6 +38,8 @@ CLI_BROWSER_CLIENT_ID = "mainsequence-cli"
 
 S = requests.Session()
 S.headers.update({"Content-Type": "application/json"})
+
+DEFAULT_AGENT_RUNTIME_READY_TIMEOUT_SECONDS = 900.0
 _UNSET = object()
 
 
@@ -421,10 +423,23 @@ def _format_env_value(value: Any) -> str:
 
 
 def _sdk_object_to_dict(obj: Any) -> dict[str, Any]:
+    def _strip_client_metadata(value: Any) -> Any:
+        if isinstance(value, dict):
+            return {
+                key: _strip_client_metadata(item)
+                for key, item in value.items()
+                if key != "orm_class"
+            }
+        if isinstance(value, list):
+            return [_strip_client_metadata(item) for item in value]
+        if isinstance(value, tuple):
+            return [_strip_client_metadata(item) for item in value]
+        return value
+
     if isinstance(obj, dict):
-        return dict(obj)
+        return _strip_client_metadata(dict(obj))
     if hasattr(obj, "model_dump"):
-        return obj.model_dump(mode="json")
+        return _strip_client_metadata(obj.model_dump(mode="json"))
     if hasattr(obj, "uid"):
         return {"uid": getattr(obj, "uid", None)}
     return {"id": getattr(obj, "id", None)}
@@ -598,11 +613,7 @@ def get_logged_user_details() -> dict[str, Any]:
     try:
         who = authed("GET", AUTH_PATHS["ping"])
         data = who.json() if who.ok else {}
-        user_uid = (
-            data.get("uid")
-            or (data.get("user") or {}).get("uid")
-            or data.get("user_uid")
-        )
+        user_uid = data.get("uid") or (data.get("user") or {}).get("uid") or data.get("user_uid")
         if user_uid in (None, ""):
             raise ApiError("Could not determine the authenticated user uid.")
 
@@ -1270,7 +1281,9 @@ def list_agent_sessions(
                 raise ApiError(f"Agent not found for agent_unique_id={agent_unique_id!r}") from e
             if isinstance(e, (ApiError, NotLoggedIn)):
                 raise
-            raise ApiError(f"Agent lookup failed for agent_unique_id={agent_unique_id!r}: {e}") from e
+            raise ApiError(
+                f"Agent lookup failed for agent_unique_id={agent_unique_id!r}: {e}"
+            ) from e
 
         resolved_agent = _sdk_object_to_dict(agent)
         resolved_agent_uid = str(resolved_agent.get("uid") or "").strip()
@@ -1322,6 +1335,7 @@ def get_agent_session(
 def resolve_agent_session_runtime_access(
     agent_session_uid: str,
     *,
+    wait_for_runtime: bool = False,
     timeout: int | None = None,
 ) -> dict[str, Any]:
     """
@@ -1332,7 +1346,9 @@ def resolve_agent_session_runtime_access(
             module_name="mainsequence.client.agent_runtime_models",
             class_name="AgentSession",
             operation=lambda ClientAgentSession: ClientAgentSession.resolve_runtime_access(
-                str(agent_session_uid), timeout=timeout
+                str(agent_session_uid),
+                wait_for_runtime=wait_for_runtime,
+                timeout=timeout,
             ),
         )
         return _sdk_object_to_dict(runtime_access)
@@ -1345,6 +1361,224 @@ def resolve_agent_session_runtime_access(
         raise ApiError(f"Agent session runtime access resolve failed: {e}") from e
 
 
+def wait_agent_session_runtime_ready(
+    agent_session_uid: str,
+    *,
+    timeout_seconds: float = DEFAULT_AGENT_RUNTIME_READY_TIMEOUT_SECONDS,
+    timeout: int | None = None,
+) -> dict[str, Any]:
+    """
+    Wait for one agent session runtime through SDK client model.
+    """
+    try:
+        ready = _run_sdk_model_operation(
+            module_name="mainsequence.client.agent_runtime_models",
+            class_name="AgentSession",
+            operation=lambda ClientAgentSession: ClientAgentSession.wait_until_runtime_ready(
+                str(agent_session_uid),
+                timeout_seconds=timeout_seconds,
+                timeout=timeout,
+            ),
+        )
+        return _sdk_object_to_dict(ready)
+    except Exception as e:
+        err_name = type(e).__name__
+        if err_name == "NotFoundError":
+            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"Agent session runtime readiness failed: {e}") from e
+
+
+def send_agent_session_a2a_chat(
+    agent_session_uid: str,
+    *,
+    message: str | None = None,
+    a2a_payload: dict[str, Any] | None = None,
+    wait_for_runtime: bool = True,
+    runtime_ready_timeout_seconds: float = DEFAULT_AGENT_RUNTIME_READY_TIMEOUT_SECONDS,
+    poll_task_until_stable: bool | None = None,
+    runtime_turn_timeout_seconds: float | None = None,
+    omit_reasoning: bool | None = None,
+    response_format: dict[str, Any] | None = None,
+    json_repair: dict[str, Any] | None = None,
+    timeout: int | None = None,
+) -> dict[str, Any]:
+    """
+    Send an A2A request through the legacy backend compatibility endpoint.
+    """
+    try:
+        chat = _run_sdk_model_operation(
+            module_name="mainsequence.client.agent_runtime_models",
+            class_name="AgentSession",
+            operation=lambda ClientAgentSession: ClientAgentSession.send_a2a_chat(
+                str(agent_session_uid),
+                message=message,
+                a2a_payload=a2a_payload,
+                wait_for_runtime=wait_for_runtime,
+                runtime_ready_timeout_seconds=runtime_ready_timeout_seconds,
+                poll_task_until_stable=poll_task_until_stable,
+                runtime_turn_timeout_seconds=runtime_turn_timeout_seconds,
+                omit_reasoning=omit_reasoning,
+                response_format=response_format,
+                json_repair=json_repair,
+                timeout=timeout,
+            ),
+        )
+        return _sdk_object_to_dict(chat)
+    except Exception as e:
+        err_name = type(e).__name__
+        if err_name == "NotFoundError":
+            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"Agent session A2A chat failed: {e}") from e
+
+
+def send_agent_session_a2a_message(
+    agent_session_uid: str,
+    *,
+    message: str,
+    strict_dictionary: bool = False,
+    json_repair_attempts: int = 3,
+    history_length: int = 0,
+    return_immediately: bool = False,
+    wait_for_runtime: bool = True,
+    timeout: int | None = None,
+) -> dict[str, Any]:
+    """
+    Send one standard A2A message through the target session runtime.
+    """
+    try:
+        payload = _run_sdk_model_operation(
+            module_name="mainsequence.client.agent_runtime_models",
+            class_name="AgentSession",
+            operation=lambda ClientAgentSession: ClientAgentSession.send_a2a_message(
+                str(agent_session_uid),
+                message=message,
+                strict_dictionary=strict_dictionary,
+                json_repair_attempts=json_repair_attempts,
+                history_length=history_length,
+                return_immediately=return_immediately,
+                wait_for_runtime=wait_for_runtime,
+                timeout=timeout,
+            ),
+        )
+        return _sdk_object_to_dict(payload)
+    except Exception as e:
+        err_name = type(e).__name__
+        if err_name == "NotFoundError":
+            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"Agent session A2A message send failed: {e}") from e
+
+
+def chat_agent_session_runtime(
+    agent_session_uid: str,
+    *,
+    message: str,
+    runtime_access: dict[str, Any] | None = None,
+    wait_for_runtime: bool = True,
+    runtime_turn_timeout_seconds: float | None = None,
+    omit_reasoning: bool | None = True,
+    response_format: dict[str, Any] | None = None,
+    json_repair: dict[str, Any] | None = None,
+    timeout: int | None = None,
+) -> dict[str, Any]:
+    """
+    Send one message through the resolved A2A runtime chat stream.
+    """
+    operation_kwargs: dict[str, Any] = {
+        "message": message,
+        "wait_for_runtime": wait_for_runtime,
+        "runtime_turn_timeout_seconds": runtime_turn_timeout_seconds,
+        "omit_reasoning": omit_reasoning,
+        "response_format": response_format,
+        "json_repair": json_repair,
+        "timeout": timeout,
+    }
+    if runtime_access is not None:
+        operation_kwargs["runtime_access"] = runtime_access
+    try:
+        payload = _run_sdk_model_operation(
+            module_name="mainsequence.client.agent_runtime_models",
+            class_name="AgentSession",
+            operation=lambda ClientAgentSession: ClientAgentSession.a2a_chat(
+                str(agent_session_uid),
+                **operation_kwargs,
+            ),
+        )
+        return _sdk_object_to_dict(payload)
+    except Exception as e:
+        err_name = type(e).__name__
+        if err_name == "NotFoundError":
+            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"Agent session runtime chat failed: {e}") from e
+
+
+def cancel_agent_session_runtime(
+    agent_session_uid: str,
+    *,
+    reason: str = "client_requested",
+    message: str | None = None,
+    timeout: int | None = None,
+) -> dict[str, Any]:
+    """
+    Cancel the active turn on the resolved A2A runtime.
+    """
+    try:
+        payload = _run_sdk_model_operation(
+            module_name="mainsequence.client.agent_runtime_models",
+            class_name="AgentSession",
+            operation=lambda ClientAgentSession: ClientAgentSession.cancel_runtime(
+                str(agent_session_uid),
+                reason=reason,
+                message=message,
+                timeout=timeout,
+            ),
+        )
+        return _sdk_object_to_dict(payload)
+    except Exception as e:
+        err_name = type(e).__name__
+        if err_name == "NotFoundError":
+            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"Agent session runtime cancel failed: {e}") from e
+
+
+def detach_agent_session_runtime(
+    agent_session_uid: str,
+    *,
+    reason: str = "client_done",
+    timeout: int | None = None,
+) -> dict[str, Any]:
+    """
+    Detach the resolved A2A runtime for one agent session.
+    """
+    try:
+        payload = _run_sdk_model_operation(
+            module_name="mainsequence.client.agent_runtime_models",
+            class_name="AgentSession",
+            operation=lambda ClientAgentSession: ClientAgentSession.detach_runtime(
+                str(agent_session_uid),
+                reason=reason,
+                timeout=timeout,
+            ),
+        )
+        return _sdk_object_to_dict(payload)
+    except Exception as e:
+        err_name = type(e).__name__
+        if err_name == "NotFoundError":
+            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"Agent session runtime detach failed: {e}") from e
+
+
 def list_agent_users_can_view(
     agent_uid: str,
     *,
@@ -3280,11 +3514,11 @@ def _adapter_from_api_public_config_payload(
     dedupe_in_flight: bool | None = None,
 ) -> dict[str, Any]:
     public_config_model = _adapter_from_api_public_config_model()
-    normalized_api_base_url = api_base_url.strip() if isinstance(api_base_url, str) else api_base_url
+    normalized_api_base_url = (
+        api_base_url.strip() if isinstance(api_base_url, str) else api_base_url
+    )
     normalized_debug_api_base_url = (
-        debug_api_base_url.strip()
-        if isinstance(debug_api_base_url, str)
-        else debug_api_base_url
+        debug_api_base_url.strip() if isinstance(debug_api_base_url, str) else debug_api_base_url
     )
     normalized_api_base_url = normalized_api_base_url or None
     normalized_debug_api_base_url = normalized_debug_api_base_url or None
@@ -3328,7 +3562,9 @@ def _adapter_from_api_public_config_payload(
     try:
         if public_config is not None:
             payload = dict(public_config)
-            payload.update({key: value for key, value in alias_updates.items() if value is not None})
+            payload.update(
+                {key: value for key, value in alias_updates.items() if value is not None}
+            )
             config = public_config_model.model_validate(payload)
         elif normalized_debug_api_base_url is not None:
             config = public_config_model.direct(
@@ -3347,7 +3583,9 @@ def _adapter_from_api_public_config_payload(
                     "Adapter from API public config is required. Provide api_base_url, "
                     "debug_api_base_url, or public_config."
                 )
-            payload.update({key: value for key, value in alias_updates.items() if value is not None})
+            payload.update(
+                {key: value for key, value in alias_updates.items() if value is not None}
+            )
             config = public_config_model.model_validate(payload)
     except ApiError:
         raise