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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: a2a-handler
-Version: 0.2.0
+Version: 0.3.0
 Summary: An A2A Protocol client TUI and CLI.
 Keywords: a2a,a2a-protocol,agent,agent-to-agent,ai,cli,tui
 Author: Al Duncanson
@@ -10,7 +10,6 @@ License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -30,12 +29,14 @@ Requires-Dist: textual-serve>=1.1.0
 Requires-Dist: mcp[cli]>=1.27.1,<2
 Requires-Dist: truststore>=0.9.0
 Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: a2a-sdk[grpc]>=1.0.0,<2.0.0 ; extra == 'grpc'
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/alDuncanson/handler
 Project-URL: Repository, https://github.com/alDuncanson/handler
 Project-URL: Documentation, https://github.com/alDuncanson/handler/tree/main/docs
 Project-URL: Issues, https://github.com/alDuncanson/handler/issues
 Project-URL: Changelog, https://github.com/alDuncanson/handler/releases
+Provides-Extra: grpc
 Description-Content-Type: text/markdown
 
 # Handler
@@ -52,10 +53,25 @@ 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.
+API key, HTTP Basic, mTLS, OAuth2 client credentials, and OpenID Connect auth.
 
 ![Handler TUI connected to an A2A agent, showing the agent card and a completed assistant response](https://raw.githubusercontent.com/alDuncanson/Handler/73915875903b60dad6e4e404aa7ed91b6d94559f/assets/tui.png)
 
+## Features
+
+- Streams replies as they arrive, in the TUI and the CLI, and can stop a
+  running task or answer an agent that pauses for input
+- Sends text, files (inline or by URL), and structured data, and shows the
+  file and data parts agents send back
+- Lists, inspects, cancels, and resubscribes to tasks, and manages push
+  notification configs with a bundled local webhook receiver
+- Speaks JSON-RPC and HTTP+JSON out of the box, gRPC with the `grpc` extra,
+  and lets the agent card pick the transport
+- Requests A2A extensions and fetches the extended card an agent offers to
+  authenticated clients
+- Keeps credentials on the origin you configured, never on a host an agent
+  card happens to name
+
 ## Install
 
 Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool:
@@ -96,6 +112,18 @@ Send a message from the CLI:
 handler message send --url URL --text "hello"
 ```
 
+Stream the reply, with a file attached:
+
+```bash
+handler message stream --url URL --text "Review this" --file ./report.pdf
+```
+
+List the agent's tasks:
+
+```bash
+handler task list --url URL
+```
+
 Open the full documentation:
 
 ```bash
@@ -119,3 +147,18 @@ pipx run a2a-handler
 ## Documentation
 
 Read the documentation at <https://handler.alduncanson.com>.
+
+### For coding agents
+
+The docs ship as an agent skill, regenerated on every deploy. Install it into
+Claude Code, Cursor, Windsurf, or any agent that reads the `SKILL.md` format:
+
+```bash
+npx skills add https://handler.alduncanson.com
+```
+
+Or fetch it by hand from <https://handler.alduncanson.com/skill.md>. For live
+lookups, agents can also use the hosted documentation MCP server at
+<https://handler.alduncanson.com/mcp> or the page index at
+<https://handler.alduncanson.com/llms.txt>. See the
+[agent skill guide](https://handler.alduncanson.com/guides/agent-skill).

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

@@ -12,10 +12,25 @@ 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.
+API key, HTTP Basic, mTLS, OAuth2 client credentials, and OpenID Connect auth.
 
 ![Handler TUI connected to an A2A agent, showing the agent card and a completed assistant response](https://raw.githubusercontent.com/alDuncanson/Handler/73915875903b60dad6e4e404aa7ed91b6d94559f/assets/tui.png)
 
+## Features
+
+- Streams replies as they arrive, in the TUI and the CLI, and can stop a
+  running task or answer an agent that pauses for input
+- Sends text, files (inline or by URL), and structured data, and shows the
+  file and data parts agents send back
+- Lists, inspects, cancels, and resubscribes to tasks, and manages push
+  notification configs with a bundled local webhook receiver
+- Speaks JSON-RPC and HTTP+JSON out of the box, gRPC with the `grpc` extra,
+  and lets the agent card pick the transport
+- Requests A2A extensions and fetches the extended card an agent offers to
+  authenticated clients
+- Keeps credentials on the origin you configured, never on a host an agent
+  card happens to name
+
 ## Install
 
 Install Handler from the [PyPI package](https://pypi.org/project/a2a-handler/) as a `uv` tool:
@@ -56,6 +71,18 @@ Send a message from the CLI:
 handler message send --url URL --text "hello"
 ```
 
+Stream the reply, with a file attached:
+
+```bash
+handler message stream --url URL --text "Review this" --file ./report.pdf
+```
+
+List the agent's tasks:
+
+```bash
+handler task list --url URL
+```
+
 Open the full documentation:
 
 ```bash
@@ -79,3 +106,18 @@ pipx run a2a-handler
 ## Documentation
 
 Read the documentation at <https://handler.alduncanson.com>.
+
+### For coding agents
+
+The docs ship as an agent skill, regenerated on every deploy. Install it into
+Claude Code, Cursor, Windsurf, or any agent that reads the `SKILL.md` format:
+
+```bash
+npx skills add https://handler.alduncanson.com
+```
+
+Or fetch it by hand from <https://handler.alduncanson.com/skill.md>. For live
+lookups, agents can also use the hosted documentation MCP server at
+<https://handler.alduncanson.com/mcp> or the page index at
+<https://handler.alduncanson.com/llms.txt>. See the
+[agent skill guide](https://handler.alduncanson.com/guides/agent-skill).

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

@@ -1,6 +1,6 @@
 [project]
 name = "a2a-handler"
-version = "0.2.0"
+version = "0.3.0"
 description = "An A2A Protocol client TUI and CLI."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -19,7 +19,6 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
@@ -47,6 +46,9 @@ dependencies = [
 name = "Al Duncanson"
 email = "alDuncanson@proton.me"
 
+[project.optional-dependencies]
+grpc = ["a2a-sdk[grpc]>=1.0.0,<2.0.0"]
+
 [project.urls]
 Homepage = "https://github.com/alDuncanson/handler"
 Repository = "https://github.com/alDuncanson/handler"
@@ -69,7 +71,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.9.15,<0.10.0"]
+requires = ["uv_build>=0.9.15,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

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

@@ -1,6 +1,6 @@
 [project]
 name = "a2a-handler"
-version = "0.2.0"
+version = "0.3.0"
 description = "An A2A Protocol client TUI and CLI."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,7 +22,6 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
@@ -48,6 +47,12 @@ dependencies = [
     "platformdirs>=4.0.0",
 ]
 
+[project.optional-dependencies]
+# Talking to gRPC-only agents needs the SDK's gRPC transport and its
+# grpcio dependencies, which are heavy enough to keep out of the default
+# install.
+grpc = ["a2a-sdk[grpc]>=1.0.0,<2.0.0"]
+
 [dependency-groups]
 dev = [
     "ruff>=0.8.0",
@@ -70,7 +75,7 @@ Changelog = "https://github.com/alDuncanson/handler/releases"
 handler = "a2a_handler.cli:main"
 
 [build-system]
-requires = ["uv_build>=0.9.15,<0.10.0"]
+requires = ["uv_build>=0.9.15,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

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

@@ -1,12 +1,13 @@
 """Authentication support for A2A protocol.
 
 Handles credential storage and HTTP authentication header generation.
-Supports API key, HTTP bearer, mTLS (mutual TLS), and OAuth2 client credentials
-authentication schemes.
+Supports API key, HTTP bearer, HTTP basic, mTLS (mutual TLS), OAuth2 client
+credentials, and OpenID Connect authentication schemes.
 """
 
 from __future__ import annotations
 
+import base64
 import ssl
 import time
 from dataclasses import dataclass, field
@@ -30,9 +31,18 @@ class AuthType(str, Enum):
     """Supported authentication types."""
 
     API_KEY = "api_key"
+    BASIC = "basic"
     BEARER = "bearer"
     MTLS = "mtls"
     OAUTH2 = "oauth2"
+    OIDC = "oidc"
+
+
+#: Auth types whose access token is fetched from a token endpoint and cached.
+TOKEN_FETCHING_AUTH_TYPES = {AuthType.OAUTH2, AuthType.OIDC}
+
+#: Path of the OpenID Connect discovery document below the issuer URL.
+OIDC_DISCOVERY_PATH = "/.well-known/openid-configuration"
 
 
 @dataclass
@@ -45,13 +55,15 @@ class AuthCredentials:
     auth_type: AuthType
     value: str = ""
     header_name: str | None = None  # For API key: custom header name
+    username: str | None = None  # For HTTP basic: username (value is password)
     cert_path: str | None = None  # For mTLS: client certificate path
     key_path: str | None = None  # For mTLS: client private key path
     ca_cert_path: str | None = None  # For mTLS: CA certificate path
-    token_url: str | None = None  # For OAuth2: token endpoint
-    client_id: str | None = None  # For OAuth2: client ID
-    client_secret: str | None = None  # For OAuth2: client secret
-    scopes: list[str] | None = None  # For OAuth2: optional scopes
+    token_url: str | None = None  # For OAuth2/OIDC: token endpoint
+    issuer_url: str | None = None  # For OIDC: issuer to discover endpoints from
+    client_id: str | None = None  # For OAuth2/OIDC: client ID
+    client_secret: str | None = None  # For OAuth2/OIDC: client secret
+    scopes: list[str] | None = None  # For OAuth2/OIDC: optional scopes
     custom_headers: dict[str, str] | None = None  # Additional headers for any auth type
     _token_expires_at: float | None = field(default=None, repr=False)
 
@@ -64,8 +76,9 @@ class AuthCredentials:
             "key_path": self.key_path,
             "ca_cert_path": self.ca_cert_path,
             "token_url": self.token_url,
+            "issuer_url": self.issuer_url,
         }
-        for secret_field in ("value", "client_id", "client_secret"):
+        for secret_field in ("value", "username", "client_id", "client_secret"):
             val = getattr(self, secret_field)
             redacted[secret_field] = "***" if val else None
         if self.custom_headers:
@@ -83,8 +96,12 @@ class AuthCredentials:
             headers.update(self.custom_headers)
         if self.auth_type == AuthType.BEARER and self.value:
             headers["Authorization"] = f"Bearer {self.value}"
-        elif self.auth_type == AuthType.OAUTH2 and self.value:
+        elif 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()
+            encoded = base64.b64encode(userpass).decode("ascii")
+            headers["Authorization"] = f"Basic {encoded}"
         elif self.auth_type == AuthType.API_KEY:
             header = self.header_name or "X-API-Key"
             headers[header] = self.value
@@ -122,8 +139,39 @@ class AuthCredentials:
         self.value = ""
         self._token_expires_at = None
 
+    async def discover_oidc_token_endpoint(self) -> str:
+        """Resolve the token endpoint from the OIDC discovery document.
+
+        Fetches ``<issuer>/.well-known/openid-configuration`` and caches the
+        advertised ``token_endpoint`` on ``token_url``.
+        """
+        if self.auth_type != AuthType.OIDC:
+            raise ValueError("OIDC discovery is only valid for OIDC credentials")
+        if self.token_url:
+            return self.token_url
+        if not self.issuer_url:
+            raise ValueError("issuer_url is required for OIDC discovery")
+        validate_token_url(self.issuer_url)
+
+        discovery_url = self.issuer_url.rstrip("/") + OIDC_DISCOVERY_PATH
+        async with httpx.AsyncClient(trust_env=False) as discovery_client:
+            response = await discovery_client.get(discovery_url)
+        response.raise_for_status()
+        document = response.json()
+        token_endpoint = document.get("token_endpoint")
+        if not isinstance(token_endpoint, str) or not token_endpoint:
+            raise ValueError(
+                f"OIDC discovery document at {discovery_url} has no token_endpoint"
+            )
+        validate_token_url(token_endpoint)
+        self.token_url = token_endpoint
+        return token_endpoint
+
     async def fetch_oauth2_token(self) -> str:
-        """Fetch an access token using OAuth2 client credentials grant.
+        """Fetch an access token using the client credentials grant.
+
+        Valid for OAuth2 and OIDC credentials; OIDC resolves its token
+        endpoint through the issuer's discovery document first.
 
         Uses a short-lived HTTP client so that agent auth headers and custom
         headers on the main client are never sent to the token endpoint.
@@ -131,8 +179,10 @@ class AuthCredentials:
         Updates self.value with the new token and returns it.
         Parses ``expires_in`` from the token response to track expiry.
         """
-        if self.auth_type != AuthType.OAUTH2:
-            raise ValueError("Token fetch is only valid for OAuth2 credentials")
+        if self.auth_type not in TOKEN_FETCHING_AUTH_TYPES:
+            raise ValueError("Token fetch is only valid for OAuth2 or OIDC credentials")
+        if self.auth_type == AuthType.OIDC:
+            await self.discover_oidc_token_endpoint()
         if not self.token_url or not self.client_id or not self.client_secret:
             raise ValueError("token_url, client_id, and client_secret are required")
         validate_token_url(self.token_url)
@@ -168,6 +218,10 @@ class AuthCredentials:
             "value": self.value,
             "header_name": self.header_name,
         }
+        if self.username is not None:
+            data["username"] = self.username
+        if self.issuer_url:
+            data["issuer_url"] = self.issuer_url
         if self.cert_path:
             data["cert_path"] = self.cert_path
         if self.key_path:
@@ -197,6 +251,8 @@ class AuthCredentials:
             auth_type=AuthType(data["auth_type"]),
             value=data.get("value") or "",
             header_name=data.get("header_name"),
+            username=data.get("username"),
+            issuer_url=data.get("issuer_url"),
             cert_path=data.get("cert_path"),
             key_path=data.get("key_path"),
             ca_cert_path=data.get("ca_cert_path"),
@@ -226,6 +282,15 @@ def create_bearer_auth(token: str) -> AuthCredentials:
     return AuthCredentials(auth_type=AuthType.BEARER, value=token)
 
 
+def create_basic_auth(username: str, password: str) -> AuthCredentials:
+    """Create HTTP basic authentication."""
+    return AuthCredentials(
+        auth_type=AuthType.BASIC,
+        username=username,
+        value=password,
+    )
+
+
 def create_api_key_auth(
     key: str,
     header_name: str = "X-API-Key",
@@ -286,3 +351,25 @@ def create_oauth2_auth(
         client_secret=client_secret,
         scopes=scopes,
     )
+
+
+def create_oidc_auth(
+    issuer_url: str,
+    client_id: str,
+    client_secret: str,
+    scopes: list[str] | None = None,
+    access_token: str = "",
+) -> AuthCredentials:
+    """Create OpenID Connect authentication.
+
+    The token endpoint is discovered from the issuer's
+    ``/.well-known/openid-configuration`` document on first token fetch.
+    """
+    return AuthCredentials(
+        auth_type=AuthType.OIDC,
+        value=access_token,
+        issuer_url=issuer_url,
+        client_id=client_id,
+        client_secret=client_secret,
+        scopes=scopes,
+    )

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

@@ -151,8 +151,10 @@ def cli(
         setup_logging(level="DEBUG")
     elif verbose:
         setup_logging(level="INFO")
-    else:
+    elif quiet:
         setup_logging(level="ERROR")
+    else:
+        setup_logging(level="WARNING")
 
 
 cli.add_command(message)

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

@@ -11,6 +11,13 @@ from a2a.client.errors import (
     A2AClientTimeoutError,
     AgentCardResolutionError,
 )
+from a2a.utils.errors import (
+    A2AError,
+    MethodNotFoundError,
+    TaskNotCancelableError,
+    TaskNotFoundError,
+    UnsupportedOperationError,
+)
 
 from a2a_handler.auth import (
     AuthCredentials,
@@ -172,6 +179,14 @@ def handle_client_error(e: Exception, agent_url: str, output: Output | None) ->
         log.error("A2A client error: %s", e)
         message = str(e)
         error_code = "a2a_client_error"
+    elif isinstance(e, A2AError):
+        # The agent answered with a protocol error. That is a normal outcome
+        # with a clear meaning, not a crash, so no traceback.
+        log.error("Agent returned an error: %s", e)
+        message = str(e)
+        error_code = "a2a_error"
+        details = {"error": type(e).__name__, "agent_url": agent_url}
+        suggestion = _protocol_error_suggestion(e)
     elif isinstance(e, httpx.ConnectError):
         log.error("Connection refused to %s", agent_url)
         message = f"Connection refused: Is the server running at {agent_url}?"
@@ -206,6 +221,20 @@ def handle_client_error(e: Exception, agent_url: str, output: Output | None) ->
         print(f"Error [{error_code}]: {message}", file=sys.stderr)
 
 
+def _protocol_error_suggestion(error: A2AError) -> str | None:
+    """A next step for the protocol errors a user can act on."""
+    if isinstance(error, TaskNotCancelableError):
+        return (
+            "The task has probably already finished; `handler task get` shows "
+            "its current state"
+        )
+    if isinstance(error, TaskNotFoundError):
+        return "Check the task ID; the agent may have discarded the task"
+    if isinstance(error, (UnsupportedOperationError, MethodNotFoundError)):
+        return "This agent does not implement that operation"
+    return None
+
+
 def _resolve_env_secret(env_var: str, label: str) -> str:
     """Read a secret from an environment variable."""
     value = os.environ.get(env_var)

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

@@ -35,6 +35,11 @@ def card() -> None:
 @card.command("get")
 @click.option("--url", "agent_url", help="Agent URL")
 @click.option("--server", "-s", "server_name", help="Named server from servers.toml")
+@click.option(
+    "--extended",
+    is_flag=True,
+    help="Fetch the extended card offered to authenticated clients",
+)
 @click.option(
     "--bearer-env", "-b", help="Env var containing bearer token (overrides saved)"
 )
@@ -44,6 +49,7 @@ def card() -> None:
 def card_get(
     agent_url: Optional[str],
     server_name: Optional[str],
+    extended: bool,
     bearer_env: Optional[str],
     api_key_env: Optional[str],
 ) -> None:
@@ -54,6 +60,7 @@ def card_get(
       $ handler card get --server my_agent
       $ handler card get --url http://localhost:8000
       $ handler card get --url http://localhost:8000 --bearer-env MY_TOKEN
+      $ handler card get --url http://localhost:8000 --extended --bearer-env MY_TOKEN
     """
     output = Output()
 
@@ -74,7 +81,10 @@ def card_get(
         try:
             async with build_http_client(credentials=credentials) as http_client:
                 service = A2AService(http_client, resolved_url, credentials=credentials)
-                card_data = await service.get_card()
+                if extended:
+                    card_data = await service.get_extended_card()
+                else:
+                    card_data = await service.get_card()
                 log.info("Retrieved card for agent: %s", card_data.name)
 
                 _format_agent_card(card_data, output)
@@ -162,6 +172,7 @@ def card_validate(
                 source=resolved_url,
                 source_type=ValidationSource.URL,
                 agent_card=agent_card,
+                raw_data=service.raw_card,
             )
 
         _format_validation_result(result, output)

{a2a_handler-0.2.0 → a2a_handler-0.3.0}/src/a2a_handler/cli/mcp.py

@@ -38,7 +38,7 @@ def mcp(transport: TransportType) -> None:
     \b
     Card Tools:
     - validate_agent_card: Validate an agent card from URL or file
-    - get_agent_card: Retrieve an agent's full card details
+    - get_agent_card: Retrieve an agent's public or extended card
 
     \b
     Message Tools:
@@ -47,9 +47,15 @@ def mcp(transport: TransportType) -> None:
     \b
     Task Tools:
     - get_task: Get task status and details
+    - list_tasks: List an agent's tasks, following pagination to the end
     - cancel_task: Cancel a running task
-    - set_task_notification: Configure push notification webhooks
-    - get_task_notification: Get push notification config
+
+    \b
+    Push Notification Tools:
+    - set_task_notification: Configure a push notification webhook
+    - get_task_notification: Get a task's push notification config
+    - list_task_notifications: List every push notification config for a task
+    - delete_task_notification: Delete a push notification config
 
     \b
     Session Tools:
@@ -57,10 +63,9 @@ def mcp(transport: TransportType) -> None:
     - get_session_info: Get session for a specific agent
     - clear_session_data: Clear saved session state
 
-    \b
-    Auth Tools:
-    - set_agent_credentials: Save bearer token or API key
-    - clear_agent_credentials: Remove saved credentials
+    Every tool that talks to an agent accepts bearer_token, api_key, mTLS
+    paths, and custom_headers; credentials are only sent to the origin of
+    the given agent URL.
 
     Example configuration for Claude Desktop (claude_desktop_config.json):