mainsequence 3.19.8__tar.gz → 3.19.10__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 3.19.8
+Version: 3.19.10
 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.10}/agent_scaffold/skills/a2a_communication/SKILL.md

@@ -56,12 +56,24 @@ mainsequence agent search "<discoveryPrompt>" --limit 10 --json
    - optional agent hint
    - required response format or output schema if needed
 4. Discover and select the target agent through the discovery flow above.
-5. Start a backend session for the selected agent:
+5. Start or reuse the delegated backend session for the selected agent:
 
 ```bash
-mainsequence agent start_new_session <agent_id>
+mainsequence agent allocate_a2a_target_session <agent_id>
 ```
 
+5.1 Treat the allocation response as canonical. Persist both:
+- `handle_unique_id`
+- `agent_session_id`
+
+5.2 `handle_unique_id` is the stable delegated-conversation reuse key and must be kept.
+- If the delegated conversation is new, call `allocate_a2a_target_session` without a handle.
+- The backend will generate and return a new `handle_unique_id`; persist it immediately.
+- If you retry because of timeout, disconnect, health-check delay, stream restart, or runtime error recovery, call `allocate_a2a_target_session` again with that same `handle_unique_id`.
+- Reusing the same handle tells the backend to return the same delegated `AgentSession` instead of allocating a sibling session for the same work.
+- Do not drop, replace, or regenerate the handle while the delegated conversation is still the same.
+- Allocate a fresh handle only when you intentionally want a new delegated conversation.
+
 6. Resolve runtime access for that agent session:
 
 ```bash
@@ -110,10 +122,11 @@ the exact CLI and runtime requests below.
 3. Parse the JSON output.
 4. Normalize candidates.
 5. Select the preferred candidate.
-6. Create the backend session for the target agent.
-7. Resolve runtime access.
-8. Poll runtime health.
-9. Send `POST <rpc_url>/api/a2a/chat`.
+6. Allocate or reuse the delegated backend session for the target agent.
+7. Persist and reuse the returned `handle_unique_id` for the same delegated conversation.
+8. Resolve runtime access.
+9. Poll runtime health.
+10. Send `POST <rpc_url>/api/a2a/chat`.
 
 ## Role-specific behavior
 

{mainsequence-3.19.8 → mainsequence-3.19.10}/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,
+    handle_unique_id: str | None = None,
     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),
+                handle_unique_id=handle_unique_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.10}/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,16 @@ 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 [
+        ("Handle Unique ID", str(allocation_payload.get("handle_unique_id") or "-")),
+        ("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 +3761,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,
+    handle_unique_id: str | None,
     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,
+            handle_unique_id=handle_unique_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 +5896,40 @@ 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.",
+    ),
+    handle_unique_id: str | None = typer.Option(
+        None,
+        "--handle-unique-id",
+        help="Optional delegated-session handle to reuse an existing target session on retries.",
+    ),
     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
+    mainsequence agent allocate_a2a_target_session 12 801 --handle-unique-id delegated-handle-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,
+        handle_unique_id=handle_unique_id,
+        timeout=timeout,
+    )
 
 
 @agent.command("get_latest_session")

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

@@ -176,30 +176,86 @@ 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,
+        handle_unique_id: str | None = None,
+        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 this target `Agent`.
 
-        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/
+
+        Request contract:
+        - `caller_agent_session_id` is required and identifies the session that is
+          delegating work to this target agent.
+        - `handle_unique_id` is optional on the first call.
+        - when `handle_unique_id` is omitted, the backend creates a delegated
+          `AgentSessionHandle`, generates a new `handle_unique_id`, allocates the target
+          session, and returns that `handle_unique_id` in the response.
+        - when `handle_unique_id` is provided, the backend reuses the same delegated
+          handle and therefore the same target session for retries, reconnects, and
+          repeated calls for the same delegated conversation.
+
+        Why this is preferred over `start_new_session()` for A2A communication:
+        - `start_new_session()` always creates a brand-new `AgentSession`.
+        - A2A communication needs an idempotent control-plane allocation step so that
+          transport retries or stream reconnects do not silently create sibling target
+          sessions.
+        - `allocate_a2a_target_session()` makes the delegated conversation reusable by
+          returning a stable `handle_unique_id` that the caller can keep and send again.
+
+        Response contract:
+        - `handle_unique_id`: stable delegated-session reuse key.
+        - `agent_session_id`: allocated target session primary key.
+        - `allocation_state`: `created_new` or `reused_existing`.
+        - `session`: full canonical backend `AgentSession` payload for the target side.
+
+        Typical usage:
+        1. first call: send only `caller_agent_session_id`
+        2. persist the returned `handle_unique_id`
+        3. later retries for the same delegated task: resend that `handle_unique_id`
+        4. intentionally fresh delegated conversation: omit the old handle and let the
+           backend allocate a new one
         """
-        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'
+            )
+
+        resolved_handle_unique_id = str(handle_unique_id or '').strip()
+
+        body = {
+            'caller_agent_session_id': int(resolved_caller_session_id),
+        }
+        if resolved_handle_unique_id:
+            body['handle_unique_id'] = resolved_handle_unique_id
+
+        url = f"{self.get_detail_url()}allocate-a2a-target-session/"
+        payload = {
+            'json': serialize_to_json(body)
+        }
         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.10}/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.10}/mainsequence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 3.19.8
+Version: 3.19.10
 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.10}/pyproject.toml

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

{mainsequence-3.19.8 → mainsequence-3.19.10}/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,22 @@ 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,
+                        handle_unique_id=None,
+                        timeout=None,
+                    ):
+                        captured["caller_agent_session_id"] = caller_agent_session_id
+                        captured["handle_unique_id"] = handle_unique_id
+                        captured["allocate_timeout"] = timeout
+                        return {
+                            "handle_unique_id": "delegated-handle-1",
+                            "agent_session_id": 801,
+                            "allocation_state": "created_new",
+                            "session": FakeAgentSession().model_dump(),
+                        }
 
                 return _Agent()
 
@@ -1505,15 +1518,24 @@ 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,
+        handle_unique_id="delegated-handle-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,
+        "handle_unique_id": "delegated-handle-1",
+        "allocate_timeout": 16,
     }
-    assert out["id"] == 801
+    assert out["agent_session_id"] == 801
+    assert out["allocation_state"] == "created_new"
+    assert out["handle_unique_id"] == "delegated-handle-1"
 
 
 def test_get_agent_latest_session_uses_client_model(cli_mod, monkeypatch):
@@ -6614,28 +6636,43 @@ 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, handle_unique_id=None, timeout=None: {
+            "handle_unique_id": handle_unique_id or "delegated-handle-1",
+            "agent_session_id": 801,
+            "allocation_state": "created_new",
+            "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,
+                    "handle_unique_id": handle_unique_id or "delegated-handle-1",
+                },
+            },
         },
     )
 
-    result = runner.invoke(cli_mod.app, ["agent", "start_new_session", "12"])
+    result = runner.invoke(
+        cli_mod.app,
+        ["agent", "allocate_a2a_target_session", "12", "700"],
+    )
     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 "delegated-handle-1" in result.output
+    assert "created_new" in result.output
     assert "Agent Session Details" in result.output
     assert "thread-123" in result.output
     assert "temperature" in result.output