mainsequence 4.4.20__tar.gz → 4.4.21__tar.gz

{mainsequence-4.4.20/mainsequence.egg-info → mainsequence-4.4.21}/PKG-INFO

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

{mainsequence-4.4.20 → mainsequence-4.4.21}/agent_scaffold/skills/a2a_communication/SKILL.md

@@ -5,8 +5,8 @@ description: Canonical guidance for discovering agents and sending session-scope
 
 # A2A Communication
 
-Use this skill when you need to discover another agent or send a bounded A2A
-request to an existing target `AgentSession`.
+Use this skill when you need to discover another agent, create or resolve a
+target `AgentSession`, and send a bounded A2A request.
 
 ## Canonical CLI Path
 
@@ -17,7 +17,7 @@ internally and sends a standard A2A message.
 
 - 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.
+- Before sending a request to a target agent session.
 - When a request explicitly arrives through the A2A channel.
 
 ## Core Rules
@@ -42,13 +42,40 @@ 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.
+   Include agent name, agent UID, 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.
+After selecting the target agent, create or resolve a target session:
+
+```bash
+mainsequence agent session get_or_create \
+  <target_agent_uid> \
+  --handle-unique-id <stable_handle_unique_id> \
+  --name "<human_readable_session_name>" \
+  --json
+```
+
+Use the returned session `uid` as the target `AgentSession` UID.
+
+If this A2A request originates from an existing caller session, include the
+parent session UID:
+
+```bash
+mainsequence agent session get_or_create \
+  <target_agent_uid> \
+  --handle-unique-id <stable_handle_unique_id> \
+  --parent-session-uid <caller_agent_session_uid> \
+  --name "<human_readable_session_name>" \
+  --json
+```
+
+Handle rules:
+
+- Repetitive workflow: use a stable semantic handle, for example `portfolio-review-q2-2026`.
+- One-off delegation: use a fresh task-specific handle, for example `a2a-risk-summary-<uuid>`.
+- Retry of the same session creation step: reuse the same handle.
+- New user turn in the same target session: reuse the returned session UID, not a new handle.
 
 ## Send A2A Chat
 
@@ -93,9 +120,10 @@ mainsequence agent session a2a send \
 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.
+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.
 
 ## Role-Specific Behavior
 

{mainsequence-4.4.20 → mainsequence-4.4.21}/mainsequence/cli/api.py

@@ -1141,59 +1141,40 @@ def delete_agent(
         raise ApiError(f"Agent deletion failed: {e}") from e
 
 
-def allocate_agent_a2a_target_session(
+def get_or_create_agent_session(
     agent_uid: str,
     *,
-    caller_agent_session_uid: str,
+    session_uid: str | None = None,
     handle_unique_id: str | None = None,
+    name: str | None = None,
+    parent_session_uid: str | None = None,
+    llm_provider: str | None = None,
+    llm_model: str | None = None,
+    llm_thinking: str | None = None,
     timeout: int | None = None,
 ) -> dict[str, Any]:
     """
-    Allocate or reuse the delegated A2A target session for one agent via SDK client model.
+    Get an existing session by UID, or get/create one by handle via SDK client model.
     """
     try:
 
-        def _allocate(ClientAgent):
+        def _get_or_create(ClientAgent):
             agent = ClientAgent.get_by_uid(str(agent_uid), timeout=timeout)
-            return agent.allocate_a2a_target_session(
-                caller_agent_session_uid=str(caller_agent_session_uid),
+            return agent.get_or_create_session(
+                session_uid=session_uid,
                 handle_unique_id=handle_unique_id,
+                name=name,
+                parent_session_uid=parent_session_uid,
+                llm_provider=llm_provider,
+                llm_model=llm_model,
+                llm_thinking=llm_thinking,
                 timeout=timeout,
             )
 
-        payload = _run_sdk_model_operation(
-            module_name="mainsequence.client.agent_runtime_models",
-            class_name="Agent",
-            operation=_allocate,
-        )
-        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_uid}") from e
-        if isinstance(e, (ApiError, NotLoggedIn)):
-            raise
-        raise ApiError(f"Agent A2A target session allocation failed: {e}") from e
-
-
-def get_agent_latest_session(
-    agent_uid: str,
-    *,
-    timeout: int | None = None,
-) -> dict[str, Any]:
-    """
-    Retrieve the latest session for one agent via SDK client model.
-    """
-    try:
-
-        def _get_latest(ClientAgent):
-            agent = ClientAgent.get_by_uid(str(agent_uid), timeout=timeout)
-            return agent.get_latest_session(timeout=timeout)
-
         session = _run_sdk_model_operation(
             module_name="mainsequence.client.agent_runtime_models",
             class_name="Agent",
-            operation=_get_latest,
+            operation=_get_or_create,
         )
         return _sdk_object_to_dict(session)
     except Exception as e:
@@ -1202,7 +1183,7 @@ def get_agent_latest_session(
             raise ApiError(f"Agent not found: {agent_uid}") from e
         if isinstance(e, (ApiError, NotLoggedIn)):
             raise
-        raise ApiError(f"Agent latest session fetch failed: {e}") from e
+        raise ApiError(f"Agent session get-or-create failed: {e}") from e
 
 
 def list_agent_sessions(

{mainsequence-4.4.20 → mainsequence-4.4.21}/mainsequence/cli/cli.py

@@ -83,7 +83,6 @@ from .api import (
     add_team_user_to_edit,
     add_team_user_to_view,
     add_workspace_labels,
-    allocate_agent_a2a_target_session,
     create_adapter_from_api_connection,
     create_agent,
     create_constant,
@@ -108,7 +107,6 @@ from .api import (
     delete_secret,
     delete_workspace,
     get_agent,
-    get_agent_latest_session,
     get_agent_run,
     get_agent_session,
     get_connection_instance,
@@ -118,6 +116,7 @@ from .api import (
     get_data_node_storage,
     get_logged_user_details,
     get_meta_table,
+    get_or_create_agent_session,
     get_organization_team,
     get_project,
     get_project_data_node_updates,
@@ -3543,12 +3542,6 @@ def _format_agent_run_details(agent_run_payload: dict[str, object]) -> list[tupl
     ]
 
 
-def _format_agent_session_ref_label(session_ref: object) -> str:
-    if isinstance(session_ref, dict):
-        return str(session_ref.get("uid") or "-")
-    return str(session_ref or "-")
-
-
 def _format_agent_session_preview(
     agent_session_payload: dict[str, object],
 ) -> list[tuple[str, str]]:
@@ -3583,18 +3576,7 @@ def _format_agent_session_details(
         ),
         ("Usage Summary", _format_json_value(agent_session_payload.get("usage_summary"))),
         ("Session Metadata", _format_json_value(agent_session_payload.get("session_metadata"))),
-    ]
-
-
-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 UID", str(allocation_payload.get("agent_session_uid") or "-")),
-        ("Allocation State", str(allocation_payload.get("allocation_state") or "-")),
-        ("Session", _format_agent_session_ref_label(session_payload)),
+        ("Bound Handle", _format_json_value(agent_session_payload.get("bound_handle"))),
     ]
 
 
@@ -3833,59 +3815,6 @@ def _agent_delete_impl(
     print_kv("Deleted Agent", _format_agent_preview(deleted))
 
 
-def _agent_allocate_a2a_target_session_impl(
-    *,
-    agent_uid: str,
-    caller_agent_session_uid: str,
-    handle_unique_id: str | None,
-    timeout: int | None,
-) -> None:
-    _require_login()
-
-    try:
-        allocation_payload = allocate_agent_a2a_target_session(
-            agent_uid,
-            caller_agent_session_uid=caller_agent_session_uid,
-            handle_unique_id=handle_unique_id,
-            timeout=timeout,
-        )
-    except ApiError as e:
-        error(f"Agent A2A target session allocation failed: {e}")
-        raise typer.Exit(1) from e
-
-    if _emit_json(allocation_payload):
-        return
-
-    success(f"Agent A2A target session allocated: agent_uid={agent_uid}")
-    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(
-    *,
-    agent_uid: str,
-    timeout: int | None,
-) -> None:
-    _require_login()
-
-    try:
-        agent_session_payload = get_agent_latest_session(agent_uid, timeout=timeout)
-    except ApiError as e:
-        error(f"Agent latest session fetch failed: {e}")
-        raise typer.Exit(1) from e
-
-    if _emit_json(agent_session_payload):
-        return
-
-    print_kv("Agent Session", _format_agent_session_preview(agent_session_payload))
-    print_kv("Agent Session Details", _format_agent_session_details(agent_session_payload))
-
-
 def _extract_standard_a2a_message_text(payload: dict[str, object]) -> str:
     response_message = payload.get("message")
     if not isinstance(response_message, dict):
@@ -3950,6 +3879,64 @@ def _agent_session_a2a_send_impl(
     typer.echo(json.dumps(response_payload, indent=2))
 
 
+def _agent_session_get_or_create_impl(
+    *,
+    agent_uid: str,
+    session_uid: str | None,
+    handle_unique_id: str | None,
+    name: str | None,
+    parent_session_uid: str | None,
+    llm_provider: str | None,
+    llm_model: str | None,
+    llm_thinking: str | None,
+    timeout: int | None,
+) -> None:
+    resolved_session_uid = str(session_uid or "").strip() if session_uid is not None else ""
+    resolved_handle_unique_id = (
+        str(handle_unique_id or "").strip() if handle_unique_id is not None else ""
+    )
+    if bool(resolved_session_uid) == bool(resolved_handle_unique_id):
+        error("Provide exactly one of --session-uid or --handle-unique-id.")
+        raise typer.Exit(1)
+
+    creation_options = {
+        "--name": name,
+        "--parent-session-uid": parent_session_uid,
+        "--llm-provider": llm_provider,
+        "--llm-model": llm_model,
+        "--llm-thinking": llm_thinking,
+    }
+    if resolved_session_uid and any(value is not None for value in creation_options.values()):
+        provided = ", ".join(key for key, value in creation_options.items() if value is not None)
+        error(f"Creation options require --handle-unique-id, not --session-uid: {provided}.")
+        raise typer.Exit(1)
+
+    _require_login()
+
+    try:
+        agent_session_payload = get_or_create_agent_session(
+            agent_uid,
+            session_uid=resolved_session_uid or None,
+            handle_unique_id=resolved_handle_unique_id or None,
+            name=name,
+            parent_session_uid=parent_session_uid,
+            llm_provider=llm_provider,
+            llm_model=llm_model,
+            llm_thinking=llm_thinking,
+            timeout=timeout,
+        )
+    except ApiError as e:
+        error(f"Agent session get-or-create failed: {e}")
+        raise typer.Exit(1) from e
+
+    if _emit_json(agent_session_payload):
+        return
+
+    success(f"Agent session resolved: uid={agent_session_payload.get('uid') or '-'}")
+    print_kv("Agent Session", _format_agent_session_preview(agent_session_payload))
+    print_kv("Agent Session Details", _format_agent_session_details(agent_session_payload))
+
+
 def _agent_session_list_impl(
     *,
     agent_uid: str | None,
@@ -6580,105 +6567,111 @@ def agent_delete_cmd(
     _agent_delete_impl(agent_uid=agent_uid, timeout=timeout)
 
 
-@agent.command("allocate_a2a_target_session")
-def agent_allocate_a2a_target_session_cmd(
-    agent_uid: str = pydantic_argument(
-        AGENT_MODEL_REF,
-        "uid",
-        ...,
-        help="Agent UID.",
-    ),
-    caller_agent_session_uid: str = pydantic_argument(
+@agent_session_group.command("list")
+def agent_session_list_cmd(
+    agent_uid: str | None = pydantic_option(
         AGENT_SESSION_MODEL_REF,
-        "uid",
-        ...,
-        help="Caller agent session UID.",
-    ),
-    handle_unique_id: str | None = typer.Option(
+        "agent_uid",
         None,
-        "--handle-unique-id",
-        help="Optional delegated-session handle to reuse an existing target session on retries.",
+        "--agent-uid",
+        help="Agent UID to scope the session list.",
+    ),
+    filter_entries: list[str] | None = typer.Option(None, "--filter", help=LIST_FILTER_OPTION_HELP),
+    show_filters: bool = typer.Option(
+        False, "--show-filters", help="Show the filters supported by this list command and exit."
     ),
     timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
 ):
     """
-    Allocate or reuse the delegated A2A target session for one agent.
+    List agent sessions, optionally scoped to one agent.
 
-    Uses SDK client `Agent.allocate_a2a_target_session()` as the single source of truth.
+    Uses SDK client `AgentSession.filter()` as the single source of truth.
 
     Examples
     --------
     ```bash
-    mainsequence agent allocate_a2a_target_session e0e75693-4110-464c-93e0-82c7fd9c9a23 3f1cc452-43ec-49cb-b2ba-87dbac164d29
-    mainsequence agent allocate_a2a_target_session e0e75693-4110-464c-93e0-82c7fd9c9a23 3f1cc452-43ec-49cb-b2ba-87dbac164d29 --handle-unique-id delegated-handle-1 --timeout 60
+    mainsequence agent session list
+    mainsequence agent session list --agent-uid e0e75693-4110-464c-93e0-82c7fd9c9a23
+    mainsequence agent session list --agent-uid e0e75693-4110-464c-93e0-82c7fd9c9a23 --filter status=running
     ```
     """
-    _agent_allocate_a2a_target_session_impl(
+    _agent_session_list_impl(
         agent_uid=agent_uid,
-        caller_agent_session_uid=caller_agent_session_uid,
-        handle_unique_id=handle_unique_id,
         timeout=timeout,
+        filter_entries=filter_entries,
+        show_filters=show_filters,
     )
 
 
-@agent.command("get_latest_session")
-def agent_get_latest_session_cmd(
+@agent_session_group.command("get_or_create")
+def agent_session_get_or_create_cmd(
     agent_uid: str = pydantic_argument(
         AGENT_MODEL_REF,
         "uid",
         ...,
         help="Agent UID.",
     ),
-    timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
-):
-    """
-    Retrieve the latest session recorded for one agent.
-
-    Uses SDK client `Agent.get_latest_session()` as the single source of truth.
-
-    Examples
-    --------
-    ```bash
-    mainsequence agent get_latest_session e0e75693-4110-464c-93e0-82c7fd9c9a23
-    mainsequence agent get_latest_session e0e75693-4110-464c-93e0-82c7fd9c9a23 --timeout 60
-    ```
-    """
-    _agent_get_latest_session_impl(agent_uid=agent_uid, timeout=timeout)
-
-
-@agent_session_group.command("list")
-def agent_session_list_cmd(
-    agent_uid: str | None = pydantic_option(
+    session_uid: str | None = pydantic_option(
         AGENT_SESSION_MODEL_REF,
-        "agent_uid",
+        "uid",
         None,
-        "--agent-uid",
-        help="Agent UID to scope the session list.",
+        "--session-uid",
+        help="Existing agent session UID to resolve for this agent.",
     ),
-    filter_entries: list[str] | None = typer.Option(None, "--filter", help=LIST_FILTER_OPTION_HELP),
-    show_filters: bool = typer.Option(
-        False, "--show-filters", help="Show the filters supported by this list command and exit."
+    handle_unique_id: str | None = typer.Option(
+        None,
+        "--handle-unique-id",
+        help="Reusable session handle key to get or create a session.",
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        help="Human-readable session display name used when creating a handle-backed session.",
+    ),
+    parent_session_uid: str | None = typer.Option(
+        None,
+        "--parent-session-uid",
+        help="Parent or origin agent session UID used when creating a handle-backed session.",
+    ),
+    llm_provider: str | None = typer.Option(
+        None,
+        "--llm-provider",
+        help="Session LLM provider override used when creating a handle-backed session.",
+    ),
+    llm_model: str | None = typer.Option(
+        None,
+        "--llm-model",
+        help="Session LLM model override used when creating a handle-backed session.",
+    ),
+    llm_thinking: str | None = typer.Option(
+        None,
+        "--llm-thinking",
+        help="Session thinking/reasoning override used when creating a handle-backed session.",
     ),
     timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
 ):
     """
-    List agent sessions, optionally scoped to one agent.
+    Get an existing agent session by UID, or get/create one by handle.
 
-    Uses SDK client `AgentSession.filter()` as the single source of truth.
+    Sends exactly one lookup key to the backend: `session_uid` or `handle_unique_id`.
 
     Examples
     --------
     ```bash
-    mainsequence agent session list
-    mainsequence agent session list --agent-uid e0e75693-4110-464c-93e0-82c7fd9c9a23
-    mainsequence agent session list --agent-uid e0e75693-4110-464c-93e0-82c7fd9c9a23 --filter status=running
+    mainsequence agent session get_or_create e0e75693-4110-464c-93e0-82c7fd9c9a23 --session-uid 3f1cc452-43ec-49cb-b2ba-87dbac164d29
+    mainsequence agent session get_or_create e0e75693-4110-464c-93e0-82c7fd9c9a23 --handle-unique-id portfolio-review-q2-2026 --name "Quarterly portfolio review"
     ```
     """
-    _agent_session_list_impl(
+    _agent_session_get_or_create_impl(
         agent_uid=agent_uid,
+        session_uid=session_uid,
+        handle_unique_id=handle_unique_id,
+        name=name,
+        parent_session_uid=parent_session_uid,
+        llm_provider=llm_provider,
+        llm_model=llm_model,
+        llm_thinking=llm_thinking,
         timeout=timeout,
-        filter_entries=filter_entries,
-        show_filters=show_filters,
     )