a2a-handler 0.1.20__tar.gz → 0.1.22__tar.gz

{a2a_handler-0.1.20 → a2a_handler-0.1.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a2a-handler
-Version: 0.1.20
+Version: 0.1.22
 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
@@ -75,7 +75,9 @@ 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
+handler server run agent                 # run the bundled embedded agent
+handler docs                             # open the hosted documentation
+handler update                           # upgrade Handler to the latest release
 ```
 
 ## Run Without Installing

{a2a_handler-0.1.20 → a2a_handler-0.1.22}/README.md

@@ -34,7 +34,9 @@ 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
+handler server run agent                 # run the bundled embedded agent
+handler docs                             # open the hosted documentation
+handler update                           # upgrade Handler to the latest release
 ```
 
 ## Run Without Installing

{a2a_handler-0.1.20 → a2a_handler-0.1.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "a2a-handler"
-version = "0.1.20"
+version = "0.1.22"
 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.20 → a2a_handler-0.1.22}/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.20 → a2a_handler-0.1.22}/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.20 → a2a_handler-0.1.22}/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)