a2a-handler 0.3.0__tar.gz → 0.4.0__tar.gz

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a2a-handler
-Version: 0.3.0
+Version: 0.4.0
 Summary: An A2A Protocol client TUI and CLI.
 Keywords: a2a,a2a-protocol,agent,agent-to-agent,ai,cli,tui
 Author: Al Duncanson
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: a2a-sdk[http-server]>=1.0.0,<2.0.0
@@ -42,6 +43,8 @@ Description-Content-Type: text/markdown
 # Handler
 
 [![CI](https://github.com/alDuncanson/handler/actions/workflows/ci.yml/badge.svg)](https://github.com/alDuncanson/handler/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FalDuncanson%2FHandler%2Fbadges%2Fcoverage.json)](https://github.com/alDuncanson/Handler/actions/workflows/ci.yml)
+[![SLSA 2](https://slsa.dev/images/gh-badge-level2.svg)](https://github.com/alDuncanson/Handler/attestations)
 [![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v1.0.0-blue)](https://a2a-protocol.org/latest/)
 [![PyPI version](https://img.shields.io/pypi/v/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![PyPI - Status](https://img.shields.io/pypi/status/a2a-handler)](https://pypi.org/project/a2a-handler/)

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/README.md

@@ -1,6 +1,8 @@
 # Handler
 
 [![CI](https://github.com/alDuncanson/handler/actions/workflows/ci.yml/badge.svg)](https://github.com/alDuncanson/handler/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FalDuncanson%2FHandler%2Fbadges%2Fcoverage.json)](https://github.com/alDuncanson/Handler/actions/workflows/ci.yml)
+[![SLSA 2](https://slsa.dev/images/gh-badge-level2.svg)](https://github.com/alDuncanson/Handler/attestations)
 [![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v1.0.0-blue)](https://a2a-protocol.org/latest/)
 [![PyPI version](https://img.shields.io/pypi/v/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![PyPI - Status](https://img.shields.io/pypi/status/a2a-handler)](https://pypi.org/project/a2a-handler/)

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "a2a-handler"
-version = "0.3.0"
+version = "0.4.0"
 description = "An A2A Protocol client TUI and CLI."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -24,6 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
 ]
@@ -71,7 +72,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.9.15,<0.13.0"]
+requires = ["uv_build>=0.9.15,<0.14.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -85,13 +86,49 @@ default = true
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "A",
+    "C4",
+    "SIM",
+    "PT",
+    "ASYNC",
+    "S",
+    "LOG",
+    "G",
+    "PERF",
+    "N",
+    "ERA",
+    "RUF",
+]
+ignore = [
+    "E501",
+    "S101",
+]
+
 [tool.ruff.lint.per-file-ignores]
 "src/a2a_handler/cli/__init__.py" = ["E402"]
+"src/a2a_handler/tui/**" = ["A002"]
+"tests/**" = [
+    "B009",
+    "B010",
+    "S104",
+    "S105",
+    "S106",
+    "S108",
+]
 
 [tool.coverage.run]
 source = ["a2a_handler"]
 
 [tool.coverage.report]
+fail_under = 88
 show_missing = true
 skip_empty = true
 exclude_lines = [

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "a2a-handler"
-version = "0.3.0"
+version = "0.4.0"
 description = "An A2A Protocol client TUI and CLI."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -27,6 +27,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
 ]
@@ -75,7 +76,7 @@ Changelog = "https://github.com/alDuncanson/handler/releases"
 handler = "a2a_handler.cli:main"
 
 [build-system]
-requires = ["uv_build>=0.9.15,<0.13.0"]
+requires = ["uv_build>=0.9.15,<0.14.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -93,13 +94,42 @@ default = true
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 
+[tool.ruff.lint]
+select = [
+    "E", "W",   # pycodestyle
+    "F",        # pyflakes
+    "I",        # isort
+    "UP",       # pyupgrade
+    "B",        # bugbear
+    "A",        # shadowed builtins
+    "C4",       # comprehensions
+    "SIM",      # simplify
+    "PT",       # pytest style
+    "ASYNC",    # async pitfalls
+    "S",        # bandit
+    "LOG", "G", # logging
+    "PERF",     # perflint
+    "N",        # pep8-naming
+    "ERA",      # commented-out code
+    "RUF",      # ruff-specific
+]
+ignore = [
+    "E501", # line length is ruff format's job
+    "S101", # asserts narrow types for ty; Handler never runs under -O
+]
+
 [tool.ruff.lint.per-file-ignores]
 "src/a2a_handler/cli/__init__.py" = ["E402"]
+# Textual widgets take `id`, like their base classes.
+"src/a2a_handler/tui/**" = ["A002"]
+# Tests monkeypatch with setattr and hold fixture secrets, paths, and bind addresses.
+"tests/**" = ["B009", "B010", "S104", "S105", "S106", "S108"]
 
 [tool.coverage.run]
 source = ["a2a_handler"]
 
 [tool.coverage.report]
+fail_under = 88
 show_missing = true
 skip_empty = true
 exclude_lines = [

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/src/a2a_handler/__init__.py

@@ -9,4 +9,4 @@ from a2a_handler.tui import HandlerTUI, main
 
 __version__ = version("a2a-handler")
 
-__all__ = ["__version__", "HandlerTUI", "main"]
+__all__ = ["HandlerTUI", "__version__", "main"]

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/src/a2a_handler/auth.py

@@ -14,6 +14,7 @@ from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
 
+import httpx
 
 from a2a_handler.common.input_validation import (
     check_key_file_permissions,
@@ -21,9 +22,6 @@ from a2a_handler.common.input_validation import (
     validate_token_url,
 )
 
-import httpx
-
-
 _TOKEN_EXPIRY_MARGIN = 30  # seconds before expiry to trigger refresh
 
 
@@ -82,7 +80,7 @@ class AuthCredentials:
             val = getattr(self, secret_field)
             redacted[secret_field] = "***" if val else None
         if self.custom_headers:
-            redacted["custom_headers"] = {k: "***" for k in self.custom_headers}
+            redacted["custom_headers"] = dict.fromkeys(self.custom_headers, "***")
         return f"AuthCredentials({redacted})"
 
     def to_headers(self) -> dict[str, str]:
@@ -94,9 +92,9 @@ class AuthCredentials:
         headers: dict[str, str] = {}
         if self.custom_headers:
             headers.update(self.custom_headers)
-        if self.auth_type == AuthType.BEARER and self.value:
-            headers["Authorization"] = f"Bearer {self.value}"
-        elif self.auth_type in TOKEN_FETCHING_AUTH_TYPES and self.value:
+        if (self.auth_type == AuthType.BEARER and self.value) or (
+            self.auth_type in TOKEN_FETCHING_AUTH_TYPES and self.value
+        ):
             headers["Authorization"] = f"Bearer {self.value}"
         elif self.auth_type == AuthType.BASIC and self.username is not None:
             userpass = f"{self.username}:{self.value}".encode()
@@ -241,7 +239,7 @@ class AuthCredentials:
         return data
 
     @classmethod
-    def from_dict(cls, data: dict) -> "AuthCredentials":
+    def from_dict(cls, data: dict) -> AuthCredentials:
         """Deserialize credentials from storage."""
         custom_headers_raw = data.get("custom_headers")
         custom_headers = (

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/src/a2a_handler/cli/__init__.py

@@ -223,7 +223,7 @@ def update() -> None:
         )
         raise SystemExit(1)
 
-    result = subprocess.run(command, check=False)
+    result = subprocess.run(command, check=False)  # noqa: S603
     if result.returncode != 0:
         output.error(
             code="update_failed",

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/src/a2a_handler/cli/_helpers.py

@@ -2,10 +2,11 @@
 
 import os
 import sys
+from collections.abc import Sequence
 from dataclasses import dataclass
 
-import httpx
 import click
+import httpx
 from a2a.client.errors import (
     A2AClientError,
     A2AClientTimeoutError,
@@ -29,9 +30,12 @@ from a2a_handler.common import Output, get_logger
 from a2a_handler.common.input_validation import InputValidationError
 from a2a_handler.servers import (
     ServerDefinition,
+    ServerLookupError,
+    find_named_server,
     load_server_catalog,
     resolve_server_credentials,
 )
+from a2a_handler.service import SavedPart
 
 TIMEOUT = 120
 _TIMEOUT_NONE_VALUES = {"none", "null", "off", "disabled"}
@@ -235,6 +239,23 @@ def _protocol_error_suggestion(error: A2AError) -> str | None:
     return None
 
 
+def report_saved_parts(saved: Sequence[SavedPart], output: Output) -> None:
+    """Tell the user what --save-artifacts wrote, without disturbing JSON output."""
+    if not saved:
+        output.text(
+            "No file or data parts to save."
+        ) if not output.is_structured else click.echo(
+            "No file or data parts to save.", err=True
+        )
+        return
+    for item in saved:
+        line = f"saved {item.path} ({item.kind}, {item.num_bytes} bytes)"
+        if output.is_structured:
+            click.echo(line, err=True)
+        else:
+            output.text(line)
+
+
 def _resolve_env_secret(env_var: str, label: str) -> str:
     """Read a secret from an environment variable."""
     value = os.environ.get(env_var)
@@ -247,22 +268,10 @@ def _resolve_env_secret(env_var: str, label: str) -> str:
 
 def _find_named_server(server: str) -> ServerDefinition:
     """Resolve a named server definition, failing closed on ambiguity."""
-    catalog = load_server_catalog()
-    matches = [
-        server_def
-        for server_def in (
-            *catalog.repository_servers,
-            *catalog.global_servers,
-        )
-        if server_def.name == server
-    ]
-    if len(matches) > 1:
-        raise click.UsageError(
-            f"Server '{server}' exists in multiple sources; use --url or rename one entry."
-        )
-    if matches:
-        return matches[0]
-    raise click.UsageError(f"Server '{server}' not found in servers.toml.")
+    try:
+        return find_named_server(server, load_server_catalog())
+    except ServerLookupError as error:
+        raise click.UsageError(str(error)) from error
 
 
 def resolve_agent_selection(

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/src/a2a_handler/cli/card.py

@@ -1,7 +1,7 @@
 """Card commands for agent card operations."""
 
 import asyncio
-from typing import Any, Optional
+from typing import Any
 
 import click
 from a2a.types import AgentCard
@@ -47,11 +47,11 @@ def card() -> None:
     "--api-key-env", "-k", help="Env var containing API key (overrides saved)"
 )
 def card_get(
-    agent_url: Optional[str],
-    server_name: Optional[str],
+    agent_url: str | None,
+    server_name: str | None,
     extended: bool,
-    bearer_env: Optional[str],
-    api_key_env: Optional[str],
+    bearer_env: str | None,
+    api_key_env: str | None,
 ) -> None:
     """Retrieve an agent's card.
 
@@ -91,7 +91,7 @@ def card_get(
 
         except Exception as e:
             handle_client_error(e, resolved_url, output)
-            raise click.Abort()
+            raise click.Abort() from e
 
     asyncio.run(do_get())
 
@@ -119,11 +119,11 @@ def _format_agent_card(card_data: object, output: Output) -> None:
     "--api-key-env", "-k", help="Env var containing API key (overrides saved)"
 )
 def card_validate(
-    agent_url: Optional[str],
-    file_path: Optional[str],
-    server_name: Optional[str],
-    bearer_env: Optional[str],
-    api_key_env: Optional[str],
+    agent_url: str | None,
+    file_path: str | None,
+    server_name: str | None,
+    bearer_env: str | None,
+    api_key_env: str | None,
 ) -> None:
     """Validate an agent card from URL or file.
 

{a2a_handler-0.3.0 → a2a_handler-0.4.0}/src/a2a_handler/cli/message.py

@@ -4,10 +4,11 @@ import asyncio
 import json
 from collections.abc import Sequence
 from dataclasses import replace
+from pathlib import Path
 from typing import Any
-from typing import Optional
 
 import click
+import httpx
 from a2a.types import Message, Part, Role
 
 from a2a_handler.auth import (
@@ -26,8 +27,8 @@ from a2a_handler.common.input_validation import (
     validate_webhook_url,
 )
 from a2a_handler.service import (
-    A2AService,
     A2AResponse,
+    A2AService,
     StreamEvent,
     attachment_part_from_spec,
     build_data_part,
@@ -39,6 +40,7 @@ from a2a_handler.service import (
     response_context_id,
     response_state,
     response_task_id,
+    save_response_parts,
     state_label,
     to_json_dict,
 )
@@ -49,6 +51,7 @@ from ._helpers import (
     build_streaming_http_client,
     handle_client_error,
     handle_validation_error,
+    report_saved_parts,
     resolve_agent_selection,
     resolve_selection_credentials,
 )
@@ -107,6 +110,12 @@ def message() -> None:
     help="Return as soon as the agent acknowledges with a task instead of "
     "waiting for completion",
 )
+@click.option(
+    "--save-artifacts",
+    "save_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Write the reply's file and data parts into this directory",
+)
 @click.option("--push-url", help="Webhook URL for push notifications")
 @click.option("--push-token", help="Authentication token for push notifications")
 @click.option(
@@ -130,24 +139,25 @@ def message() -> None:
     help="Custom header (repeatable, format: 'Name: Value')",
 )
 def message_send(
-    agent_url: Optional[str],
-    server_name: Optional[str],
-    text: Optional[str],
+    agent_url: str | None,
+    server_name: str | None,
+    text: str | None,
     files: tuple[str, ...],
     data_values: tuple[str, ...],
     stream: bool,
-    json_payload: Optional[str],
-    context_id: Optional[str],
-    task_id: Optional[str],
+    json_payload: str | None,
+    context_id: str | None,
+    task_id: str | None,
     use_session: bool,
     accepted_output_modes: tuple[str, ...],
-    history_length: Optional[int],
+    history_length: int | None,
     no_wait: bool,
-    push_url: Optional[str],
-    push_token: Optional[str],
+    push_url: str | None,
+    push_token: str | None,
+    save_dir: Path | None,
     extensions: tuple[str, ...],
-    bearer_env: Optional[str],
-    api_key_env: Optional[str],
+    bearer_env: str | None,
+    api_key_env: str | None,
     headers: tuple[str, ...] = (),
 ) -> None:
     """Send a message to an agent and receive a response.
@@ -341,6 +351,8 @@ def message_send(
                         attachments=attachments or None,
                         accepted_output_modes=accepted_output_modes or None,
                         history_length=history_length,
+                        save_dir=save_dir,
+                        http_client=http_client,
                     )
                 else:
                     response = await service.send(
@@ -358,10 +370,15 @@ def message_send(
                         response_task_id(response),
                     )
                     _format_response(response, output)
+                    if save_dir is not None:
+                        saved = await save_response_parts(
+                            response, save_dir, http_client=http_client
+                        )
+                        report_saved_parts(saved, output)
 
         except Exception as e:
             handle_client_error(e, resolved_url, output)
-            raise click.Abort()
+            raise click.Abort() from e
 
     asyncio.run(do_send())
 
@@ -375,9 +392,7 @@ def _build_attachments(
     Raises InputValidationError for an unreadable/oversized file or invalid
     JSON, so callers handle it alongside the other input checks.
     """
-    attachments: list[Part] = []
-    for file_spec in files:
-        attachments.append(attachment_part_from_spec(file_spec))
+    attachments: list[Part] = [attachment_part_from_spec(spec) for spec in files]
     for raw_value in data_values:
         try:
             value = json.loads(raw_value)
@@ -425,6 +440,12 @@ def _build_attachments(
     type=int,
     help="History messages the agent should include on the task",
 )
+@click.option(
+    "--save-artifacts",
+    "save_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Write the reply's file and data parts into this directory",
+)
 @click.option("--push-url", help="Webhook URL for push notifications")
 @click.option("--push-token", help="Authentication token for push notifications")
 @click.option(
@@ -450,21 +471,22 @@ def _build_attachments(
 @click.pass_context
 def message_stream(
     ctx: click.Context,
-    agent_url: Optional[str],
-    server_name: Optional[str],
-    text: Optional[str],
+    agent_url: str | None,
+    server_name: str | None,
+    text: str | None,
     files: tuple[str, ...],
     data_values: tuple[str, ...],
-    context_id: Optional[str],
-    task_id: Optional[str],
+    context_id: str | None,
+    task_id: str | None,
     use_session: bool,
     accepted_output_modes: tuple[str, ...],
-    history_length: Optional[int],
-    push_url: Optional[str],
-    push_token: Optional[str],
+    history_length: int | None,
+    push_url: str | None,
+    push_token: str | None,
+    save_dir: Path | None,
     extensions: tuple[str, ...],
-    bearer_env: Optional[str],
-    api_key_env: Optional[str],
+    bearer_env: str | None,
+    api_key_env: str | None,
     headers: tuple[str, ...] = (),
 ) -> None:
     """Send a message and stream the response in real-time.
@@ -492,6 +514,7 @@ def message_stream(
         no_wait=False,
         push_url=push_url,
         push_token=push_token,
+        save_dir=save_dir,
         extensions=extensions,
         bearer_env=bearer_env,
         api_key_env=api_key_env,
@@ -502,13 +525,15 @@ def message_stream(
 async def _stream_message(
     service: A2AService,
     text: str,
-    context_id: Optional[str],
-    task_id: Optional[str],
+    context_id: str | None,
+    task_id: str | None,
     agent_url: str,
     output: Output,
     attachments: Sequence[Part] | None = None,
     accepted_output_modes: tuple[str, ...] | None = None,
-    history_length: Optional[int] = None,
+    history_length: int | None = None,
+    save_dir: Path | None = None,
+    http_client: httpx.AsyncClient | None = None,
 ) -> None:
     """Stream a message and handle events."""
     last_context_id: str | None = None
@@ -578,6 +603,11 @@ async def _stream_message(
                     output.text()
             else:
                 output.text(_format_response_text(last_response))
+        if save_dir is not None:
+            saved = await save_response_parts(
+                last_response, save_dir, http_client=http_client
+            )
+            report_saved_parts(saved, output)
     else:
         output.error(code="no_response", message="No response received from stream")