a2a-handler 0.1.21__tar.gz → 0.1.23__tar.gz

{a2a_handler-0.1.21 → a2a_handler-0.1.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a2a-handler
-Version: 0.1.21
+Version: 0.1.23
 Summary: An A2A Protocol client TUI and CLI.
 Keywords: a2a,a2a-protocol,agent,agent-to-agent,ai,cli,tui
 Author: Al Duncanson
@@ -20,7 +20,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: a2a-sdk>=0.3.24,<1.0.0
 Requires-Dist: click>=8.0.0
-Requires-Dist: google-adk>=1.26.0
+Requires-Dist: google-adk>=2.0.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: litellm>=1.0.0
 Requires-Dist: python-dotenv>=1.0.0
@@ -28,7 +28,7 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: textual>=0.47.0
 Requires-Dist: uvicorn>=0.30.0
 Requires-Dist: textual-serve>=1.1.0
-Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: mcp[cli]>=1.27.1
 Requires-Dist: truststore>=0.9.0
 Requires-Dist: platformdirs>=4.0.0
 Requires-Python: >=3.11
@@ -45,73 +45,78 @@ Description-Content-Type: text/markdown
 [![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v0.3.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/)
-[![PyPI monthly downloads](https://img.shields.io/pypi/dm/a2a-handler)](https://pypi.org/project/a2a-handler/)
 [![Pepy total downloads](https://img.shields.io/pepy/dt/a2a-handler?label=total%20downloads)](https://pepy.tech/projects/a2a-handler)
 [![GitHub stars](https://img.shields.io/github/stars/alDuncanson/handler)](https://github.com/alDuncanson/handler/stargazers)
 
-![Handler TUI](https://github.com/alDuncanson/Handler/blob/main/assets/handler-tui.png?raw=true)
+Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A)
+client for software engineers building, testing, and operating agentic systems.
+It provides an interactive TUI, a scriptable CLI with structured output, and an
+MCP server that lets other agents integrate with A2A services directly. Handler
+also supports global and repo-scoped A2A server configuration with bearer,
+API key, mTLS, and OAuth2 client credentials auth.
 
-Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A) client for your terminal.
-
-Use the TUI or CLI to send messages, manage tasks, and inspect agent cards.
-An included MCP server lets your AI assistant talk to A2A agents too.
+![Handler TUI connected to the built-in Handler Agent, showing the agent card and a completed assistant response](https://raw.githubusercontent.com/alDuncanson/Handler/73915875903b60dad6e4e404aa7ed91b6d94559f/assets/tui.png)
 
 ## Install
 
+Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool:
+
 ```bash
 uv tool install a2a-handler
 ```
 
-Or with [pipx](https://pipx.pypa.io/) / pip:
+Or with [pipx](https://pipx.pypa.io/):
 
 ```bash
-pipx install a2a-handler   # or: pip install a2a-handler
+pipx install a2a-handler
 ```
 
-## Quick Start
+Or with pip:
 
 ```bash
-handler tui                              # launch the interactive TUI
-handler message send URL "hello"         # send a message from the CLI
-handler card get URL                     # fetch an agent card
-handler mcp                              # start the MCP server
-handler server run agent                 # run the bundled reference agent
+pip install a2a-handler
 ```
 
-## Run Without Installing
+## Quick Start
+
+Open the interactive terminal UI:
 
 ```bash
-uvx --from a2a-handler handler           # or: pipx run a2a-handler
+handler tui
 ```
 
-## Servers
+Inspect an A2A server's agent card:
+
+```bash
+handler card get --url http://localhost:8000
+```
 
-Handler supports named servers in `$XDG_CONFIG_HOME/handler/servers.toml`
-(global) and `.handler/servers.toml` (repo-local).
+Send a message from the CLI:
 
-```toml
-version = 1
+```bash
+handler message send --url URL --text "hello"
+```
 
-[servers.local]
-url = "http://localhost:8000"
+Open the full documentation:
 
-[servers.local.auth]
-type = "bearer"
-env = "HANDLER_LOCAL_TOKEN"
+```bash
+handler docs
 ```
 
-See [docs/](docs) for the full auth reference covering bearer, API key, mTLS,
-and OAuth2.
+## Run Without Installing
+
+Run Handler with `uvx`:
 
-## Development
+```bash
+uvx --from a2a-handler handler
+```
 
-A [hermetic](https://zero-to-nix.com/concepts/hermeticity/) dev environment
-is available via [Nix](https://zero-to-nix.com/concepts/nix/):
+Run Handler with `pipx`:
 
 ```bash
-nix develop
+pipx run a2a-handler
 ```
 
-The Mintlify docs source lives in `docs/`.
+## Documentation
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Read the documentation at <https://handler.alduncanson.com>.

a2a_handler-0.1.23/README.md

@@ -0,0 +1,81 @@
+# Handler
+
+[![CI](https://github.com/alDuncanson/handler/actions/workflows/ci.yml/badge.svg)](https://github.com/alDuncanson/handler/actions/workflows/ci.yml)
+[![A2A Protocol](https://img.shields.io/badge/A2A_Protocol-v0.3.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/)
+[![Pepy total downloads](https://img.shields.io/pepy/dt/a2a-handler?label=total%20downloads)](https://pepy.tech/projects/a2a-handler)
+[![GitHub stars](https://img.shields.io/github/stars/alDuncanson/handler)](https://github.com/alDuncanson/handler/stargazers)
+
+Handler is an open-source [A2A protocol](https://github.com/a2aproject/A2A)
+client for software engineers building, testing, and operating agentic systems.
+It provides an interactive TUI, a scriptable CLI with structured output, and an
+MCP server that lets other agents integrate with A2A services directly. Handler
+also supports global and repo-scoped A2A server configuration with bearer,
+API key, mTLS, and OAuth2 client credentials auth.
+
+![Handler TUI connected to the built-in Handler Agent, showing the agent card and a completed assistant response](https://raw.githubusercontent.com/alDuncanson/Handler/73915875903b60dad6e4e404aa7ed91b6d94559f/assets/tui.png)
+
+## Install
+
+Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool:
+
+```bash
+uv tool install a2a-handler
+```
+
+Or with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install a2a-handler
+```
+
+Or with pip:
+
+```bash
+pip install a2a-handler
+```
+
+## Quick Start
+
+Open the interactive terminal UI:
+
+```bash
+handler tui
+```
+
+Inspect an A2A server's agent card:
+
+```bash
+handler card get --url http://localhost:8000
+```
+
+Send a message from the CLI:
+
+```bash
+handler message send --url URL --text "hello"
+```
+
+Open the full documentation:
+
+```bash
+handler docs
+```
+
+## Run Without Installing
+
+Run Handler with `uvx`:
+
+```bash
+uvx --from a2a-handler handler
+```
+
+Run Handler with `pipx`:
+
+```bash
+pipx run a2a-handler
+```
+
+## Documentation
+
+Read the documentation at <https://handler.alduncanson.com>.

{a2a_handler-0.1.21 → a2a_handler-0.1.23}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "a2a-handler"
-version = "0.1.21"
+version = "0.1.23"
 description = "An A2A Protocol client TUI and CLI."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -34,7 +34,7 @@ classifiers = [
 dependencies = [
     "a2a-sdk>=0.3.24,<1.0.0",
     "click>=8.0.0",
-    "google-adk>=1.26.0",
+    "google-adk>=2.0.0",
     "httpx>=0.27.0",
     "litellm>=1.0.0",
     "python-dotenv>=1.0.0",
@@ -42,7 +42,7 @@ dependencies = [
     "textual>=0.47.0",
     "uvicorn>=0.30.0",
     "textual-serve>=1.1.0",
-    "mcp[cli]>=1.2.0",
+    "mcp[cli]>=1.27.1",
     "truststore>=0.9.0",
     "platformdirs>=4.0.0",
 ]

{a2a_handler-0.1.21 → a2a_handler-0.1.23}/src/a2a_handler/auth.py

@@ -250,6 +250,10 @@ def create_mtls_auth(
     ca_cert_path: str | None = None,
 ) -> AuthCredentials:
     """Create mTLS (mutual TLS) client certificate authentication."""
+    cert_path = str(Path(cert_path).expanduser())
+    key_path = str(Path(key_path).expanduser())
+    ca_cert_path = str(Path(ca_cert_path).expanduser()) if ca_cert_path else None
+
     if not Path(cert_path).is_file():
         raise FileNotFoundError(f"Client certificate not found: {cert_path}")
     if not Path(key_path).is_file():

{a2a_handler-0.1.21 → a2a_handler-0.1.23}/src/a2a_handler/cli/__init__.py

@@ -19,6 +19,11 @@ truststore.inject_into_ssl()
 
 import logging
 import os
+import shutil
+import subprocess
+import webbrowser
+from collections.abc import Sequence
+from typing import Any
 
 logging.getLogger().setLevel(logging.WARNING)
 
@@ -30,6 +35,7 @@ from a2a_handler.common.dotenv import load_runtime_dotenv
 from a2a_handler.common.output import OutputFormat
 from a2a_handler.tui import HandlerTUI
 
+from ._helpers import configure_http_timeouts
 from .card import card
 from .mcp import mcp
 from .message import message
@@ -40,24 +46,81 @@ from .task import task
 
 log = get_logger(__name__)
 
+DOCS_URL = "https://handler.alduncanson.com/"
+PACKAGE_NAME = "a2a-handler"
 
-@click.group()
+
+class RuntimeDotenvGroup(click.Group):
+    """Click group that loads workspace .env before option envvars resolve."""
+
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = True,
+        windows_expand_args: bool = True,
+        **extra: Any,
+    ) -> Any:
+        """Load runtime dotenv before Click parses envvar-backed options."""
+        load_runtime_dotenv()
+        return super().main(
+            args=args,
+            prog_name=prog_name,
+            complete_var=complete_var,
+            standalone_mode=standalone_mode,
+            windows_expand_args=windows_expand_args,
+            **extra,
+        )
+
+
+@click.group(cls=RuntimeDotenvGroup)
 @click.version_option(version=__version__, prog_name="handler")
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging")
 @click.option("--debug", "-d", is_flag=True, help="Enable debug logging")
 @click.option(
     "--output",
     "output_format",
-    type=click.Choice(["json", "ndjson"]),
-    default="json",
+    type=click.Choice(["text", "json", "ndjson"]),
+    default="text",
     show_default=True,
-    help="Output format",
+    help="Output format (use json/ndjson for structured output)",
 )
 @click.option(
     "--quiet",
     is_flag=True,
     help="Suppress non-error output",
 )
+@click.option(
+    "--connect-timeout",
+    envvar="HANDLER_CONNECT_TIMEOUT",
+    metavar="SECONDS|none",
+    help="HTTP connect timeout in seconds (env: HANDLER_CONNECT_TIMEOUT)",
+)
+@click.option(
+    "--read-timeout",
+    envvar="HANDLER_READ_TIMEOUT",
+    metavar="SECONDS|none",
+    help="HTTP read timeout for non-streaming calls (env: HANDLER_READ_TIMEOUT)",
+)
+@click.option(
+    "--write-timeout",
+    envvar="HANDLER_WRITE_TIMEOUT",
+    metavar="SECONDS|none",
+    help="HTTP write timeout in seconds (env: HANDLER_WRITE_TIMEOUT)",
+)
+@click.option(
+    "--pool-timeout",
+    envvar="HANDLER_POOL_TIMEOUT",
+    metavar="SECONDS|none",
+    help="HTTP connection pool timeout in seconds (env: HANDLER_POOL_TIMEOUT)",
+)
+@click.option(
+    "--stream-read-timeout",
+    envvar="HANDLER_STREAM_READ_TIMEOUT",
+    metavar="SECONDS|none",
+    help="HTTP read timeout for streaming calls; default is none (env: HANDLER_STREAM_READ_TIMEOUT)",
+)
 @click.pass_context
 def cli(
     ctx: click.Context,
@@ -65,13 +128,24 @@ def cli(
     debug: bool,
     output_format: OutputFormat,
     quiet: bool,
+    connect_timeout: str | None,
+    read_timeout: str | None,
+    write_timeout: str | None,
+    pool_timeout: str | None,
+    stream_read_timeout: str | None,
 ) -> None:
     """Handler - A2A protocol client CLI."""
-    load_runtime_dotenv()
     ctx.ensure_object(dict)
     ctx.obj["output_format"] = output_format
     ctx.obj["quiet"] = quiet
     configure_output(output_format=output_format, quiet=quiet)
+    configure_http_timeouts(
+        connect_timeout=connect_timeout,
+        read_timeout=read_timeout,
+        write_timeout=write_timeout,
+        pool_timeout=pool_timeout,
+        stream_read_timeout=stream_read_timeout,
+    )
 
     if debug:
         setup_logging(level="DEBUG")
@@ -103,6 +177,66 @@ def version() -> None:
     output.json({"version": __version__})
 
 
+@cli.command()
+def docs() -> None:
+    """Open the Handler documentation in your browser.
+
+    \b
+    Examples:
+      $ handler docs
+    """
+    opened = webbrowser.open(DOCS_URL)
+    output = Output()
+    output.json({"url": DOCS_URL, "opened": opened})
+
+
+def _upgrade_command() -> list[str] | None:
+    """Return the preferred package manager command for upgrading Handler."""
+    if shutil.which("uv"):
+        return ["uv", "tool", "upgrade", PACKAGE_NAME]
+    if shutil.which("pipx"):
+        return ["pipx", "upgrade", PACKAGE_NAME]
+    return None
+
+
+@cli.command()
+def update() -> None:
+    """Update Handler to the latest published version.
+
+    \b
+    Examples:
+      $ handler update
+      $ handler upgrade
+    """
+    output = Output()
+    command = _upgrade_command()
+    if command is None:
+        output.error(
+            code="installer_not_found",
+            message="Could not find uv or pipx to update Handler.",
+            suggestion=(
+                "Install uv or pipx, then run `uv tool upgrade a2a-handler` "
+                "or `pipx upgrade a2a-handler`."
+            ),
+        )
+        raise SystemExit(1)
+
+    result = subprocess.run(command, check=False)
+    if result.returncode != 0:
+        output.error(
+            code="update_failed",
+            message="Handler update command failed.",
+            details={
+                "command": command,
+                "returncode": result.returncode,
+            },
+        )
+        raise SystemExit(result.returncode)
+
+
+cli.add_command(update, name="upgrade")
+
+
 @cli.command()
 @click.option(
     "--bearer-env", "-b", help="Env var containing bearer token for agent auth"

{a2a_handler-0.1.21 → a2a_handler-0.1.23}/src/a2a_handler/cli/_helpers.py

@@ -27,6 +27,13 @@ from a2a_handler.servers import (
 )
 
 TIMEOUT = 120
+_TIMEOUT_NONE_VALUES = {"none", "null", "off", "disabled"}
+
+_connect_timeout: float | None = float(TIMEOUT)
+_read_timeout: float | None = float(TIMEOUT)
+_write_timeout: float | None = float(TIMEOUT)
+_pool_timeout: float | None = float(TIMEOUT)
+_stream_read_timeout: float | None = None
 log = get_logger(__name__)
 
 
@@ -39,17 +46,109 @@ class AgentSelection:
 
 
 def build_http_client(
-    timeout: int = TIMEOUT,
+    timeout: int | float | httpx.Timeout | None = None,
     credentials: AuthCredentials | None = None,
 ) -> httpx.AsyncClient:
     """Build an HTTP client with the specified timeout."""
+    effective_timeout = timeout if timeout is not None else _standard_timeout()
     if credentials and credentials.auth_type == AuthType.MTLS:
         return httpx.AsyncClient(
-            timeout=timeout,
+            timeout=effective_timeout,
             verify=credentials.build_ssl_context(),
             trust_env=False,
         )
-    return httpx.AsyncClient(timeout=timeout, trust_env=False)
+    return httpx.AsyncClient(timeout=effective_timeout, trust_env=False)
+
+
+def build_streaming_http_client(
+    credentials: AuthCredentials | None = None,
+) -> httpx.AsyncClient:
+    """Build an HTTP client for long-lived streaming responses.
+
+    Streaming keeps the usual finite connect/write/pool timeouts but disables
+    the read timeout so an active long-running A2A task is not aborted just
+    because the server has no SSE event ready for a while.
+    """
+    return build_http_client(
+        timeout=httpx.Timeout(
+            connect=_connect_timeout,
+            read=_stream_read_timeout,
+            write=_write_timeout,
+            pool=_pool_timeout,
+        ),
+        credentials=credentials,
+    )
+
+
+def configure_http_timeouts(
+    *,
+    connect_timeout: str | int | float | None = None,
+    read_timeout: str | int | float | None = None,
+    write_timeout: str | int | float | None = None,
+    pool_timeout: str | int | float | None = None,
+    stream_read_timeout: str | int | float | None = None,
+) -> None:
+    """Configure default CLI HTTP timeouts.
+
+    Passing no values resets the defaults. String values may be seconds or
+    ``none`` to disable that timeout.
+    """
+    global _connect_timeout, _read_timeout, _write_timeout, _pool_timeout
+    global _stream_read_timeout
+
+    _connect_timeout = _parse_timeout_option(
+        connect_timeout, "connect-timeout", float(TIMEOUT)
+    )
+    _read_timeout = _parse_timeout_option(read_timeout, "read-timeout", float(TIMEOUT))
+    _write_timeout = _parse_timeout_option(
+        write_timeout, "write-timeout", float(TIMEOUT)
+    )
+    _pool_timeout = _parse_timeout_option(pool_timeout, "pool-timeout", float(TIMEOUT))
+    _stream_read_timeout = _parse_timeout_option(
+        stream_read_timeout, "stream-read-timeout", None
+    )
+
+
+def _standard_timeout() -> httpx.Timeout:
+    """Return the configured timeout for regular request/response calls."""
+    return httpx.Timeout(
+        connect=_connect_timeout,
+        read=_read_timeout,
+        write=_write_timeout,
+        pool=_pool_timeout,
+    )
+
+
+def _parse_timeout_option(
+    value: str | int | float | None,
+    field_name: str,
+    default: float | None,
+) -> float | None:
+    """Parse a CLI/env timeout value."""
+    if value is None:
+        return default
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if not normalized:
+            return default
+        if normalized in _TIMEOUT_NONE_VALUES:
+            return None
+        try:
+            parsed = float(normalized)
+        except ValueError as exc:
+            raise click.BadParameter(
+                "must be a number of seconds or 'none'",
+                param_hint=f"--{field_name}",
+            ) from exc
+    else:
+        parsed = float(value)
+
+    if parsed < 0:
+        raise click.BadParameter(
+            "must be greater than or equal to 0",
+            param_hint=f"--{field_name}",
+        )
+    return parsed
 
 
 def handle_client_error(e: Exception, agent_url: str, output: Output | None) -> None:

{a2a_handler-0.1.21 → a2a_handler-0.1.23}/src/a2a_handler/cli/card.py

@@ -11,8 +11,8 @@ from a2a_handler.common.input_validation import InputValidationError, validate_a
 from a2a_handler.service import A2AService
 from a2a_handler.validation import (
     ValidationResult,
+    ValidationSource,
     validate_agent_card_from_file,
-    validate_agent_card_from_url,
 )
 
 from ._helpers import (
@@ -155,7 +155,14 @@ def card_validate(
 
     async def do_validate() -> None:
         async with build_http_client(credentials=credentials) as http_client:
-            result = await validate_agent_card_from_url(resolved_url, http_client)
+            service = A2AService(http_client, resolved_url, credentials=credentials)
+            agent_card = await service.get_card()
+            result = ValidationResult(
+                valid=True,
+                source=resolved_url,
+                source_type=ValidationSource.URL,
+                agent_card=agent_card,
+            )
 
         _format_validation_result(result, output)