mainsequence 4.4.22__tar.gz → 4.4.24__tar.gz

{mainsequence-4.4.22/mainsequence.egg-info → mainsequence-4.4.24}/PKG-INFO

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

{mainsequence-4.4.22 → mainsequence-4.4.24}/agent_scaffold/skills/a2a_communication/SKILL.md

@@ -105,6 +105,155 @@ mainsequence agent session a2a send \
   --message "Now identify the highest priority follow-up."
 ```
 
+## Handle Shortcut Helper
+
+For repeated communication with the same target agent, use a stable handle. On
+first use, include the target agent UID so the CLI can create or resolve the
+target session and cache the returned session UID:
+
+```bash
+mainsequence agent session a2a send \
+  <stable_handle_unique_id> \
+  --target-agent-uid <target_agent_uid> \
+  --message "Return a JSON object with keys: summary, risk_level, next_action." \
+  --strict-dictionary
+```
+
+`--name` is optional and only affects the session if the backend creates it:
+
+```bash
+mainsequence agent session a2a send \
+  portfolios \
+  --target-agent-uid <target_agent_uid> \
+  --name "Portfolio analysis" \
+  --message "Return a JSON object with keys: summary, risk_level, next_action." \
+  --strict-dictionary
+```
+
+After the handle is cached, reuse it without the target agent UID:
+
+```bash
+mainsequence agent session a2a send \
+  portfolios \
+  --message "Now identify the highest priority follow-up." \
+  --strict-dictionary
+```
+
+## Send Files
+
+A2A can send inline files as raw parts. For PDFs, use `--file`; the CLI reads
+the file bytes, enforces the 15 MiB inline limit, base64 encodes the bytes, and
+sends the part with `filename` and `mediaType`.
+
+```bash
+mainsequence agent session a2a send \
+  <target_agent_session_uid> \
+  --message "Please summarize this PDF." \
+  --file report.pdf \
+  --media-type application/pdf
+```
+
+The same handle shortcut works with files:
+
+```bash
+mainsequence agent session a2a send \
+  portfolios \
+  --message "Please summarize this PDF." \
+  --file report.pdf \
+  --media-type application/pdf
+```
+
+For retries of the exact same message and file attachment, reuse the same
+`--message-id`.
+
+## Python Usage
+
+In Python, use the backend handle to get or create the target session, then
+reuse the returned session UID for every message in the same conversation. The
+binding is:
+
+```text
+handle_unique_id -> AgentSession.uid -> A2A message.contextId
+```
+
+Direct SDK flow:
+
+```python
+from mainsequence.client.agent_runtime_models import Agent, AgentSession
+
+
+agent = Agent.get_by_uid(target_agent_uid)
+session = agent.get_or_create_session(
+    handle_unique_id="portfolios",
+    name="Portfolio analysis",
+)
+
+response = AgentSession.send_a2a_message(
+    session.uid,
+    message="Return a JSON object with keys: summary, risk_level, next_action.",
+    strict_dictionary=True,
+)
+```
+
+For another message in the same conversation, reuse the same `session.uid`:
+
+```python
+response = AgentSession.send_a2a_message(
+    session.uid,
+    message="Now identify the highest priority follow-up.",
+    strict_dictionary=True,
+)
+```
+
+To send a PDF, pass a file attachment. The SDK reads the raw bytes, enforces the
+15 MiB inline limit, base64 encodes them, and sends `filename` plus `mediaType`:
+
+```python
+response = AgentSession.send_a2a_message(
+    session.uid,
+    message="Please summarize this PDF.",
+    files=[
+        {
+            "path": "report.pdf",
+            "media_type": "application/pdf",
+            "filename": "report.pdf",
+        }
+    ],
+)
+```
+
+Reusable helper:
+
+```python
+from mainsequence.client.agent_runtime_models import Agent, AgentSession
+
+
+def send_to_agent_handle(
+    target_agent_uid: str,
+    handle_unique_id: str,
+    message: str,
+    *,
+    name: str | None = None,
+    files: list[dict[str, str]] | None = None,
+    strict_dictionary: bool = False,
+):
+    agent = Agent.get_by_uid(target_agent_uid)
+    session = agent.get_or_create_session(
+        handle_unique_id=handle_unique_id,
+        name=name,
+    )
+
+    return AgentSession.send_a2a_message(
+        session.uid,  # The SDK sends this as A2A message.contextId.
+        message=message,
+        files=files,
+        strict_dictionary=strict_dictionary,
+    )
+```
+
+Use the same `handle_unique_id` for the same target conversation. Use a new
+handle for a different task or conversation.
+
 ## Response Handling
 
 - Parse the CLI output as the standard A2A JSON response.

{mainsequence-4.4.22 → mainsequence-4.4.24}/mainsequence/cli/api.py

@@ -1244,6 +1244,7 @@ def send_agent_session_a2a_message(
     agent_session_uid: str,
     *,
     message: str,
+    files: list[dict[str, Any]] | None = None,
     message_id: str | None = None,
     strict_dictionary: bool = False,
     json_repair_attempts: int = 3,
@@ -1262,6 +1263,7 @@ def send_agent_session_a2a_message(
                 ClientAgentSession,
                 agent_session_uid=str(agent_session_uid),
                 message=message,
+                files=files,
                 message_id=message_id,
                 cached_runtime_access=cached_runtime_access,
                 strict_dictionary=strict_dictionary,
@@ -1287,6 +1289,7 @@ def _send_agent_session_a2a_message_with_cache(
     *,
     agent_session_uid: str,
     message: str,
+    files: list[dict[str, Any]] | None,
     message_id: str | None,
     cached_runtime_access: dict[str, Any] | None,
     strict_dictionary: bool,
@@ -1300,6 +1303,7 @@ def _send_agent_session_a2a_message_with_cache(
     payload = ClientAgentSession.send_a2a_message(
         agent_session_uid,
         message=message,
+        files=files,
         message_id=message_id,
         strict_dictionary=strict_dictionary,
         json_repair_attempts=json_repair_attempts,

{mainsequence-4.4.22 → mainsequence-4.4.24}/mainsequence/cli/cli.py

@@ -3829,11 +3829,77 @@ def _extract_standard_a2a_message_text(payload: dict[str, object]) -> str:
     return "".join(chunks)
 
 
+def _looks_like_uuid(value: str) -> bool:
+    try:
+        uuid.UUID(str(value))
+        return True
+    except (TypeError, ValueError):
+        return False
+
+
+def _resolve_agent_session_uid_or_handle(
+    target: str,
+    *,
+    target_agent_uid: str | None,
+    name: str | None,
+    parent_session_uid: str | None,
+    timeout: int | None,
+) -> str:
+    resolved_target = str(target or "").strip()
+    if not resolved_target:
+        error("agent session UID or handle is required.")
+        raise typer.Exit(1)
+    if _looks_like_uuid(resolved_target):
+        return resolved_target
+
+    resolved_agent_uid = str(target_agent_uid or "").strip()
+    if not resolved_agent_uid:
+        cached = cfg.get_a2a_handle_cache(resolved_target)
+        cached_session_uid = str((cached or {}).get("agent_session_uid") or "").strip()
+        if cached_session_uid:
+            return cached_session_uid
+        error(
+            f"No cached A2A session for handle '{resolved_target}'. "
+            "Pass --target-agent-uid once to create or resolve it."
+        )
+        raise typer.Exit(1)
+
+    try:
+        agent_session_payload = get_or_create_agent_session(
+            resolved_agent_uid,
+            handle_unique_id=resolved_target,
+            name=name,
+            parent_session_uid=parent_session_uid,
+            timeout=timeout,
+        )
+    except ApiError as e:
+        error(f"Agent session handle resolution failed: {e}")
+        raise typer.Exit(1) from e
+
+    agent_session_uid = str(agent_session_payload.get("uid") or "").strip()
+    if not agent_session_uid:
+        error("Agent session handle resolution did not return a session UID.")
+        raise typer.Exit(1)
+
+    cfg.save_a2a_handle_cache(
+        resolved_target,
+        agent_uid=resolved_agent_uid,
+        agent_session_uid=agent_session_uid,
+        name=name,
+    )
+    return agent_session_uid
+
+
 def _agent_session_a2a_send_impl(
     *,
-    agent_session_uid: str,
+    agent_session_uid_or_handle: str,
+    target_agent_uid: str | None,
+    name: str | None,
+    parent_session_uid: str | None,
     message: str | None,
     message_file: pathlib.Path | None,
+    files: list[pathlib.Path] | None,
+    media_types: list[str] | None,
     strict_dictionary: bool,
     json_repair_attempts: int,
     message_id: str | None,
@@ -3855,16 +3921,38 @@ def _agent_session_a2a_send_impl(
     if json_repair_attempts < 1:
         error("--json-repair-attempts must be greater than 0.")
         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):
+        error("--media-type must be provided once per --file when used.")
+        raise typer.Exit(1)
+    attachments = [
+        {
+            "path": str(path),
+            "media_type": attachment_media_types[index]
+            if attachment_media_types
+            else "application/pdf",
+        }
+        for index, path in enumerate(attachment_paths)
+    ]
     effective_message_id = str(message_id).strip() if message_id is not None else ""
     if not effective_message_id:
         effective_message_id = f"msg-{uuid.uuid4()}"
 
     _require_login()
+    agent_session_uid = _resolve_agent_session_uid_or_handle(
+        agent_session_uid_or_handle,
+        target_agent_uid=target_agent_uid,
+        name=name,
+        parent_session_uid=parent_session_uid,
+        timeout=timeout,
+    )
 
     try:
         response_payload = send_agent_session_a2a_message(
             agent_session_uid,
             message=resolved_message,
+            files=attachments,
             message_id=effective_message_id,
             strict_dictionary=strict_dictionary,
             json_repair_attempts=json_repair_attempts,
@@ -6677,8 +6765,26 @@ def agent_session_get_or_create_cmd(
 
 @agent_session_a2a_group.command("send")
 def agent_session_a2a_send_cmd(
-    agent_session_uid: str = pydantic_argument(
-        AGENT_SESSION_MODEL_REF, "uid", ..., help="Agent session UID."
+    agent_session_uid_or_handle: str = pydantic_argument(
+        AGENT_SESSION_MODEL_REF,
+        "uid",
+        ...,
+        help="Agent session UID, or cached A2A handle.",
+    ),
+    target_agent_uid: str | None = typer.Option(
+        None,
+        "--target-agent-uid",
+        help="Target agent UID used to create or resolve a handle on first use.",
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        help="Optional session name used only when resolving a handle with --target-agent-uid.",
+    ),
+    parent_session_uid: str | None = typer.Option(
+        None,
+        "--parent-session-uid",
+        help="Optional parent session UID used only when resolving a handle with --target-agent-uid.",
     ),
     message: str | None = typer.Option(
         None,
@@ -6690,6 +6796,16 @@ def agent_session_a2a_send_cmd(
         "--message-file",
         help="Path to a UTF-8 text file containing the A2A message.",
     ),
+    files: list[pathlib.Path] | None = typer.Option(
+        None,
+        "--file",
+        help="Inline file attachment to send as an A2A raw part.",
+    ),
+    media_types: list[str] | None = typer.Option(
+        None,
+        "--media-type",
+        help="Media type for each --file. Defaults to application/pdf.",
+    ),
     strict_dictionary: bool = typer.Option(
         False,
         "--strict-dictionary",
@@ -6713,12 +6829,17 @@ def agent_session_a2a_send_cmd(
     timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
 ):
     """
-    Send one standard A2A message to an existing agent session.
+    Send one standard A2A message to an existing session UID or cached handle.
     """
     _agent_session_a2a_send_impl(
-        agent_session_uid=agent_session_uid,
+        agent_session_uid_or_handle=agent_session_uid_or_handle,
+        target_agent_uid=target_agent_uid,
+        name=name,
+        parent_session_uid=parent_session_uid,
         message=message,
         message_file=message_file,
+        files=files,
+        media_types=media_types,
         strict_dictionary=strict_dictionary,
         json_repair_attempts=json_repair_attempts,
         message_id=message_id,

{mainsequence-4.4.22 → mainsequence-4.4.24}/mainsequence/cli/config.py

@@ -55,6 +55,7 @@ SESSION_OVERRIDES_DIR = CFG_DIR / "session_overrides"
 TOKENS_JSON = CFG_DIR / "token.json"
 AUTH_JSON = CFG_DIR / "auth.json"
 RUNTIME_ACCESS_CACHE_JSON = CFG_DIR / "runtime_access_cache.json"
+A2A_HANDLE_CACHE_JSON = CFG_DIR / "a2a_handle_cache.json"
 
 # Session-scoped auth environment variables (no token file persistence).
 ENV_USERNAME = "MAINSEQUENCE_USERNAME"
@@ -469,6 +470,78 @@ def clear_runtime_access_cache(
         return False
 
 
+def _a2a_handle_cache_key(handle_unique_id: str, backend: str | None = None) -> str:
+    backend_key = _auth_backend_key(backend)
+    raw = f"{backend_key}|{_runtime_access_user_key()}|{str(handle_unique_id).strip()}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _read_a2a_handle_cache() -> dict:
+    data = read_json(A2A_HANDLE_CACHE_JSON, {})
+    if not isinstance(data, dict):
+        return {"version": 1, "entries": {}}
+    entries = data.get("entries")
+    if not isinstance(entries, dict):
+        entries = {}
+    return {"version": 1, "entries": entries}
+
+
+def _write_a2a_handle_cache(data: dict) -> None:
+    write_json(A2A_HANDLE_CACHE_JSON, data)
+    if os.name == "posix":
+        try:
+            os.chmod(A2A_HANDLE_CACHE_JSON, 0o600)
+        except Exception:
+            pass
+
+
+def get_a2a_handle_cache(
+    handle_unique_id: str,
+    *,
+    backend: str | None = None,
+) -> dict | None:
+    """
+    Return a cached A2A handle mapping scoped by backend and current user.
+    """
+    handle = str(handle_unique_id or "").strip()
+    if not handle:
+        return None
+    cache = _read_a2a_handle_cache()
+    entry = cache["entries"].get(_a2a_handle_cache_key(handle, backend))
+    return dict(entry) if isinstance(entry, dict) else None
+
+
+def save_a2a_handle_cache(
+    handle_unique_id: str,
+    *,
+    agent_uid: str,
+    agent_session_uid: str,
+    name: str | None = None,
+    backend: str | None = None,
+) -> dict:
+    """
+    Cache an A2A handle to the backend AgentSession UID it resolves to.
+    """
+    handle = str(handle_unique_id or "").strip()
+    if not handle:
+        raise ValueError("handle_unique_id is required")
+
+    now = time.time()
+    entry = {
+        "backend_url": _auth_backend_key(backend),
+        "handle_unique_id": handle,
+        "agent_uid": str(agent_uid),
+        "agent_session_uid": str(agent_session_uid),
+        "name": str(name) if name is not None else None,
+        "cached_at_epoch": now,
+        "cached_at": _iso_utc_from_epoch(now),
+    }
+    cache = _read_a2a_handle_cache()
+    cache["entries"][_a2a_handle_cache_key(handle, backend)] = entry
+    _write_a2a_handle_cache(cache)
+    return dict(entry)
+
+
 def _keychain_account_for_backend(backend: str | None = None) -> str:
     """
     Return the backend-scoped keychain account name.

{mainsequence-4.4.22 → mainsequence-4.4.24}/mainsequence/client/agent_runtime_models.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import base64
 import datetime
 import json
+import pathlib
 import time
 import uuid
 from enum import Enum
@@ -22,6 +24,7 @@ STANDARD_A2A_CONTENT_TYPE = "application/a2a+json"
 STANDARD_A2A_OUTPUT_CONTRACT_METADATA_KEY = (
     "https://mainsequence.ai/a2a/extensions/output-contract/v1"
 )
+MAX_INLINE_A2A_FILE_BYTES = 15 * 1024 * 1024
 
 
 class AgentSessionStatus(str, Enum):
@@ -712,6 +715,7 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
         *,
         agent_session_uid: str,
         message: str,
+        files: list[Any] | None = None,
         message_id: str | None = None,
         strict_dictionary: bool = False,
         json_repair_attempts: int = 3,
@@ -727,12 +731,16 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
             normalized_message_id = f"msg-{uuid.uuid4()}"
 
         accepted_output_modes = ["application/json"] if strict_dictionary else ["text/plain"]
+        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))
+
         body: dict[str, Any] = {
             "message": {
                 "messageId": normalized_message_id,
                 "role": "ROLE_USER",
                 "contextId": agent_session_uid,
-                "parts": [{"text": normalized_message}],
+                "parts": parts,
             },
             "configuration": {
                 "acceptedOutputModes": accepted_output_modes,
@@ -751,6 +759,46 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
             }
         return body
 
+    @staticmethod
+    def _build_standard_a2a_raw_file_part(file_spec: Any) -> dict[str, Any]:
+        if isinstance(file_spec, (str, pathlib.Path)):
+            path = pathlib.Path(file_spec).expanduser()
+            media_type = "application/pdf" if path.suffix.lower() == ".pdf" else ""
+            filename = path.name
+        elif isinstance(file_spec, dict):
+            raw_path = file_spec.get("path")
+            if raw_path is None:
+                raise ValueError("A2A file attachment requires a path")
+            path = pathlib.Path(str(raw_path)).expanduser()
+            media_type = str(
+                file_spec.get("media_type") or file_spec.get("mediaType") or ""
+            ).strip()
+            if not media_type and path.suffix.lower() == ".pdf":
+                media_type = "application/pdf"
+            filename = str(file_spec.get("filename") or path.name).strip()
+        else:
+            raise TypeError("A2A file attachment must be a path or dict")
+
+        if not media_type:
+            raise ValueError(f"A2A file attachment '{path}' requires media_type")
+        if not filename:
+            raise ValueError(f"A2A file attachment '{path}' requires filename")
+
+        file_bytes = path.read_bytes()
+        if len(file_bytes) > MAX_INLINE_A2A_FILE_BYTES:
+            size_mib = len(file_bytes) / (1024 * 1024)
+            limit_mib = MAX_INLINE_A2A_FILE_BYTES / (1024 * 1024)
+            raise ValueError(
+                f"A2A attachment '{filename}' is {size_mib:.1f} MiB; "
+                f"inline attachments are limited to {limit_mib:.0f} MiB."
+            )
+
+        return {
+            "raw": base64.b64encode(file_bytes).decode("ascii"),
+            "filename": filename,
+            "mediaType": media_type,
+        }
+
     @classmethod
     def _post_standard_a2a_message(
         cls,
@@ -793,6 +841,7 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
         agent_session: str | AgentSession,
         *,
         message: str,
+        files: list[Any] | None = None,
         message_id: str | None = None,
         strict_dictionary: bool = False,
         json_repair_attempts: int = 3,
@@ -806,6 +855,7 @@ class AgentSession(BaseObjectOrm, BasePydanticModel):
         body = cls._build_standard_a2a_message_send_body(
             agent_session_uid=session_uid,
             message=message,
+            files=files,
             message_id=message_id,
             strict_dictionary=strict_dictionary,
             json_repair_attempts=json_repair_attempts,

{mainsequence-4.4.22 → mainsequence-4.4.24/mainsequence.egg-info}/PKG-INFO

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

{mainsequence-4.4.22 → mainsequence-4.4.24}/pyproject.toml

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