mainsequence 3.19.8__tar.gz → 3.19.9__tar.gz

{mainsequence-3.19.8 → mainsequence-3.19.9}/PKG-INFO

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

{mainsequence-3.19.8 → mainsequence-3.19.9}/agent_scaffold/skills/a2a_communication/SKILL.md

@@ -59,7 +59,7 @@ mainsequence agent search "<discoveryPrompt>" --limit 10 --json
 5. Start a backend session for the selected agent:
 
 ```bash
-mainsequence agent start_new_session <agent_id>
+mainsequence agent allocate_agent_a2a_target_session <agent_id>
 ```
 
 6. Resolve runtime access for that agent session:

{mainsequence-3.19.8 → mainsequence-3.19.9}/mainsequence/cli/api.py

@@ -988,32 +988,38 @@ def delete_agent(
         raise ApiError(f"Agent deletion failed: {e}") from e
 
 
-def start_agent_new_session(
+def allocate_agent_a2a_target_session(
     agent_id: int | str,
     *,
+    caller_agent_session_id: int | str,
+    a2a_correlation_id: str,
     timeout: int | None = None,
 ) -> dict[str, Any]:
     """
-    Start a new session for one agent via SDK client model.
+    Allocate or reuse the delegated A2A target session for one agent via SDK client model.
     """
     try:
-        def _start(ClientAgent):
+        def _allocate(ClientAgent):
             agent = ClientAgent.get(pk=int(agent_id), timeout=timeout)
-            return agent.start_new_session(timeout=timeout)
+            return agent.allocate_a2a_target_session(
+                caller_agent_session_id=int(caller_agent_session_id),
+                a2a_correlation_id=a2a_correlation_id,
+                timeout=timeout,
+            )
 
-        session = _run_sdk_model_operation(
+        payload = _run_sdk_model_operation(
             module_name="mainsequence.client.agent_runtime_models",
             class_name="Agent",
-            operation=_start,
+            operation=_allocate,
         )
-        return _sdk_object_to_dict(session)
+        return _sdk_object_to_dict(payload)
     except Exception as e:
         err_name = type(e).__name__
         if err_name == "NotFoundError":
             raise ApiError(f"Agent not found: {agent_id}") from e
         if isinstance(e, (ApiError, NotLoggedIn)):
             raise
-        raise ApiError(f"Agent session start failed: {e}") from e
+        raise ApiError(f"Agent A2A target session allocation failed: {e}") from e
 
 
 def get_agent_latest_session(

{mainsequence-3.19.8 → mainsequence-3.19.9}/mainsequence/cli/cli.py

@@ -77,6 +77,7 @@ from .api import (
     add_team_user_to_edit,
     add_team_user_to_view,
     add_workspace_labels,
+    allocate_agent_a2a_target_session,
     create_agent,
     create_constant,
     create_organization_team,
@@ -191,7 +192,6 @@ from .api import (
     schedule_batch_project_jobs,
     search_projects,
     semantic_search_agents,
-    start_agent_new_session,
     sync_project_after_commit,
     update_organization_team,
     update_workspace,
@@ -3458,6 +3458,15 @@ def _format_agent_session_details(agent_session_payload: dict[str, object]) -> l
     ]
 
 
+def _format_agent_a2a_allocation_preview(allocation_payload: dict[str, object]) -> list[tuple[str, str]]:
+    session_payload = allocation_payload.get("session")
+    return [
+        ("Agent Session ID", str(allocation_payload.get("agent_session_id") or "-")),
+        ("Allocation State", str(allocation_payload.get("allocation_state") or "-")),
+        ("Session", _format_agent_session_ref_label(session_payload)),
+    ]
+
+
 def _agent_list_impl(
     timeout: int | None,
     filter_entries: list[str] | None,
@@ -3751,25 +3760,35 @@ def _agent_delete_impl(
     print_kv("Deleted Agent", _format_agent_preview(deleted))
 
 
-def _agent_start_new_session_impl(
+def _agent_allocate_a2a_target_session_impl(
     *,
     agent_id: int,
+    caller_agent_session_id: int,
+    a2a_correlation_id: str,
     timeout: int | None,
 ) -> None:
     _require_login()
 
     try:
-        agent_session_payload = start_agent_new_session(agent_id, timeout=timeout)
+        allocation_payload = allocate_agent_a2a_target_session(
+            agent_id,
+            caller_agent_session_id=caller_agent_session_id,
+            a2a_correlation_id=a2a_correlation_id,
+            timeout=timeout,
+        )
     except ApiError as e:
-        error(f"Agent session start failed: {e}")
+        error(f"Agent A2A target session allocation failed: {e}")
         raise typer.Exit(1) from e
 
-    if _emit_json(agent_session_payload):
+    if _emit_json(allocation_payload):
         return
 
-    success(f"Agent session started: agent_id={agent_id}")
-    print_kv("Agent Session", _format_agent_session_preview(agent_session_payload))
-    print_kv("Agent Session Details", _format_agent_session_details(agent_session_payload))
+    success(f"Agent A2A target session allocated: agent_id={agent_id}")
+    print_kv("A2A Target Session Allocation", _format_agent_a2a_allocation_preview(allocation_payload))
+    session_payload = allocation_payload.get("session")
+    if isinstance(session_payload, dict):
+        print_kv("Agent Session", _format_agent_session_preview(session_payload))
+        print_kv("Agent Session Details", _format_agent_session_details(session_payload))
 
 
 def _agent_get_latest_session_impl(
@@ -5876,24 +5895,36 @@ def agent_delete_cmd(
     _agent_delete_impl(agent_id=agent_id, timeout=timeout)
 
 
-@agent.command("start_new_session")
-def agent_start_new_session_cmd(
+@agent.command("allocate_a2a_target_session")
+def agent_allocate_a2a_target_session_cmd(
     agent_id: int = pydantic_argument(AGENT_MODEL_REF, "id", ..., help="Agent ID."),
+    caller_agent_session_id: int = pydantic_argument(
+        AGENT_SESSION_MODEL_REF,
+        "id",
+        ...,
+        help="Caller agent session ID.",
+    ),
+    a2a_correlation_id: str = typer.Argument(..., help="Stable correlation id for the delegated A2A task."),
     timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
 ):
     """
-    Start a new session for one agent and return the created agent session.
+    Allocate or reuse the delegated A2A target session for one agent.
 
-    Uses SDK client `Agent.start_new_session()` as the single source of truth.
+    Uses SDK client `Agent.allocate_a2a_target_session()` as the single source of truth.
 
     Examples
     --------
     ```bash
-    mainsequence agent start_new_session 12
-    mainsequence agent start_new_session 12 --timeout 60
+    mainsequence agent allocate_a2a_target_session 12 801 delegation-step-1
+    mainsequence agent allocate_a2a_target_session 12 801 delegation-step-1 --timeout 60
     ```
     """
-    _agent_start_new_session_impl(agent_id=agent_id, timeout=timeout)
+    _agent_allocate_a2a_target_session_impl(
+        agent_id=agent_id,
+        caller_agent_session_id=caller_agent_session_id,
+        a2a_correlation_id=a2a_correlation_id,
+        timeout=timeout,
+    )
 
 
 @agent.command("get_latest_session")

{mainsequence-3.19.8 → mainsequence-3.19.9}/mainsequence/client/agent_runtime_models.py

@@ -176,30 +176,71 @@ class Agent(ShareableObjectMixin, BaseObjectOrm, BasePydanticModel):
 
         return [AgentSemanticSearchResult(**item) for item in data]
 
-    def start_new_session(self, timeout=None, **kwargs):
+
+
+    def allocate_a2a_target_session(
+        self,
+        *,
+        caller_agent_session_id: int | AgentSession,
+        a2a_correlation_id: str,
+        timeout=None,
+    ) -> dict[str, Any]:
         """
-        Start a new session for this agent and return the created `AgentSession`.
+        Allocate or reuse the delegated target session for one logical A2A task.
 
-        Keyword arguments are sent as session-creation overrides on top of the
-        agent defaults, so callers can pass values such as `thread_id`,
-        `runtime_session_id`, `external_session_id`,
-        `runtime_config_snapshot`, or explicit runtime fields.
+        Hits:
+            POST <detail_url>allocate-a2a-target-session/
+
+        Why prefer this over `start_new_session()` for A2A communication:
+        - `start_new_session()` always creates a brand-new `AgentSession`.
+        - `allocate_a2a_target_session()` is idempotent for delegated work and is keyed
+          by `(caller_agent_session_id, self.id, a2a_correlation_id)`.
+        - Retrying the same delegated task reuses the same target session instead of
+          silently creating a sibling conversation.
+        - This keeps reconnects, transport retries, and stream timeouts attached to the
+          same delegated session.
+        - If the caller wants a fresh delegated conversation, it should mint a new
+          `a2a_correlation_id` and call this method again.
+
+        Returns the canonical backend allocation payload:
+        - `agent_session_id`
+        - `allocation_state`
+        - `session`
         """
-        url = f"{self.get_detail_url()}start_new_session/"
-        payload: dict[str, Any] = {}
-        if kwargs:
-            payload["json"] = serialize_to_json(kwargs)
+        if isinstance(caller_agent_session_id, AgentSession):
+            resolved_caller_session_id = getattr(caller_agent_session_id, 'id', None)
+        else:
+            resolved_caller_session_id = caller_agent_session_id
+
+        if resolved_caller_session_id is None:
+            raise ValueError(
+                'caller_agent_session_id must be an AgentSession or a session id'
+            )
+
+        a2a_correlation_id = str(a2a_correlation_id or '').strip()
+        if not a2a_correlation_id:
+            raise ValueError('a2a_correlation_id is required')
+
+        url = f"{self.get_detail_url()}allocate-a2a-target-session/"
+        payload = {
+            'json': serialize_to_json(
+                {
+                    'caller_agent_session_id': int(resolved_caller_session_id),
+                    'a2a_correlation_id': a2a_correlation_id,
+                }
+            )
+        }
         response = make_request(
             s=self.build_session(),
             loaders=self.LOADERS,
-            r_type="POST",
+            r_type='POST',
             url=url,
             payload=payload,
             time_out=timeout,
         )
-        if response.status_code != 201:
+        if response.status_code not in (200, 201):
             raise_for_response(response, payload=payload)
-        return AgentSession(**response.json())
+        return response.json()
 
     def get_latest_session(self, timeout=None):
         """

{mainsequence-3.19.8 → mainsequence-3.19.9}/mainsequence/client/models_user.py

@@ -863,7 +863,12 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
         description="Unique identifier of the user.",
         examples=[42],
     )
-    profile_picture:Any | None = Field()
+    profile_picture: str | None = Field(
+        None,
+        title="Profile Picture URL",
+        description="Absolute or relative URL of the user's profile picture when one is set.",
+        examples=["https://api.example.com/media/user_profile_pictures/avatar.png"],
+    )
     is_verified: bool | None = Field(
         None,
         title="Is Verified",

{mainsequence-3.19.8 → mainsequence-3.19.9}/mainsequence.egg-info/PKG-INFO

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

{mainsequence-3.19.8 → mainsequence-3.19.9}/pyproject.toml

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

{mainsequence-3.19.8 → mainsequence-3.19.9}/tests/test_cli.py

@@ -1468,7 +1468,7 @@ def test_get_or_create_agent_uses_client_model(cli_mod, monkeypatch):
     assert out["id"] == 12
 
 
-def test_start_agent_new_session_uses_client_model(cli_mod, monkeypatch):
+def test_allocate_agent_a2a_target_session_uses_client_model(cli_mod, monkeypatch):
     api_mod = importlib.import_module("mainsequence.cli.api")
     captured = {}
 
@@ -1495,9 +1495,21 @@ def test_start_agent_new_session_uses_client_model(cli_mod, monkeypatch):
                 captured["timeout"] = timeout
 
                 class _Agent:
-                    def start_new_session(self, timeout=None):
-                        captured["start_new_session_timeout"] = timeout
-                        return FakeAgentSession()
+                    def allocate_a2a_target_session(
+                        self,
+                        *,
+                        caller_agent_session_id,
+                        a2a_correlation_id,
+                        timeout=None,
+                    ):
+                        captured["caller_agent_session_id"] = caller_agent_session_id
+                        captured["a2a_correlation_id"] = a2a_correlation_id
+                        captured["allocate_timeout"] = timeout
+                        return {
+                            "agent_session_id": 801,
+                            "allocation_state": "created",
+                            "session": FakeAgentSession().model_dump(),
+                        }
 
                 return _Agent()
 
@@ -1505,15 +1517,23 @@ def test_start_agent_new_session_uses_client_model(cli_mod, monkeypatch):
 
     monkeypatch.setattr(api_mod, "_run_sdk_model_operation", _run_sdk_model_operation)
 
-    out = api_mod.start_agent_new_session(12, timeout=16)
+    out = api_mod.allocate_agent_a2a_target_session(
+        12,
+        caller_agent_session_id=700,
+        a2a_correlation_id="delegation-step-1",
+        timeout=16,
+    )
     assert captured == {
         "module_name": "mainsequence.client.agent_runtime_models",
         "class_name": "Agent",
         "pk": 12,
         "timeout": 16,
-        "start_new_session_timeout": 16,
+        "caller_agent_session_id": 700,
+        "a2a_correlation_id": "delegation-step-1",
+        "allocate_timeout": 16,
     }
-    assert out["id"] == 801
+    assert out["agent_session_id"] == 801
+    assert out["allocation_state"] == "created"
 
 
 def test_get_agent_latest_session_uses_client_model(cli_mod, monkeypatch):
@@ -6614,28 +6634,41 @@ def test_agent_get_or_create_parses_json_fields(cli_mod, runner, monkeypatch):
     assert "Agent resolved via get_or_create: Research Copilot" in result.output
 
 
-def test_agent_start_new_session(cli_mod, runner, monkeypatch):
+def test_agent_allocate_a2a_target_session(cli_mod, runner, monkeypatch):
     monkeypatch.setattr(cli_mod, "_require_login", lambda: {"username": "u"})
     monkeypatch.setattr(
         cli_mod,
-        "start_agent_new_session",
-        lambda agent_id, timeout=None: {
-            "id": 801,
-            "agent": {"id": agent_id, "name": "Research Copilot"},
-            "status": "pending",
-            "started_at": "2026-04-11T09:15:00Z",
-            "llm_provider": "openai",
-            "llm_model": "gpt-5.4",
-            "engine_name": "codex",
-            "thread_id": "thread-123",
-            "runtime_config_snapshot": {"temperature": 0},
-            "session_metadata": {"origin": "cli"},
+        "allocate_agent_a2a_target_session",
+        lambda agent_id, caller_agent_session_id, a2a_correlation_id, timeout=None: {
+            "agent_session_id": 801,
+            "allocation_state": "created",
+            "session": {
+                "id": 801,
+                "agent": {"id": agent_id, "name": "Research Copilot"},
+                "status": "pending",
+                "started_at": "2026-04-11T09:15:00Z",
+                "llm_provider": "openai",
+                "llm_model": "gpt-5.4",
+                "engine_name": "codex",
+                "thread_id": "thread-123",
+                "runtime_config_snapshot": {"temperature": 0},
+                "session_metadata": {
+                    "origin": "cli",
+                    "caller_agent_session_id": caller_agent_session_id,
+                    "a2a_correlation_id": a2a_correlation_id,
+                },
+            },
         },
     )
 
-    result = runner.invoke(cli_mod.app, ["agent", "start_new_session", "12"])
+    result = runner.invoke(
+        cli_mod.app,
+        ["agent", "allocate_a2a_target_session", "12", "700", "delegation-step-1"],
+    )
     assert result.exit_code == 0
-    assert "Agent session started: agent_id=12" in result.output
+    assert "Agent A2A target session allocated: agent_id=12" in result.output
+    assert "A2A Target Session Allocation" in result.output
+    assert "created" in result.output
     assert "Agent Session Details" in result.output
     assert "thread-123" in result.output
     assert "temperature" in result.output