feat: Migrate server core to a2a-sdk components, expand public API exports, and update documentation for Python 3.11+ and apcore 0.9.0+.

Author: tercel

CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-03-10
+
+### Changed
+
+- Updated Python requirement from 3.10+ to 3.11+ to match pyproject.toml.
+- Updated apcore dependency requirement from 0.6.0+ to 0.9.0+.
+- Delegated TaskStore and InMemoryTaskStore to a2a-sdk (replaces custom protocol).
+- Replaced ExecutionRouter, TaskManager, and TransportManager with a2a-sdk components (ApCoreAgentExecutor, DefaultRequestHandler, A2AStarletteApplication).
+- CLI `--host` default changed from `0.0.0.0` to `127.0.0.1` for safer defaults.
+- Default agent name fallback changed from `"apcore-agent"` to `"Apcore Agent"`.
+- Auth 401 response body now returns `{"error": "Unauthorized", "detail": "Missing or invalid Bearer token"}`.
+- AgentCard `defaultOutputModes` now includes both `"text/plain"` and `"application/json"`.
+
+### Added
+
+- Expanded public API exports: auth classes, adapter classes, and server factory now re-exported from top-level `__init__.py`.
+- Documented that SkillMapper `_build_extensions()` cannot wire annotations into AgentSkill (a2a-sdk lacks `extensions` field); annotations available via Explorer UI instead.
+- ErrorMapper `_sanitize_message()` now strips traceback lines in addition to file paths.
+- Explorer `create_explorer_mount()` accepts optional `registry` parameter to enrich agent card with input schemas.
+- Path-based registry resolution: `serve()` and `async_serve()` accept `str`/`Path` for auto-discovery.
+
+### Fixed
+
+- Feature specs updated to match actual implementation (F-01 through F-11).
+- Documentation version references corrected (Python 3.11+, apcore 0.9.0+).
+
 ## [0.1.0] - 2026-03-07
 
 ### Added

README.md

@@ -5,7 +5,7 @@
 # apcore-a2a
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Node_18%2B-blue)](https://github.com/aipartnerup/apcore-a2a-typescript)
 
 **apcore-a2a** is an automatic [A2A (Agent-to-Agent)](https://google.github.io/A2A/) protocol adapter for the [apcore](https://github.com/aipartnerup/apcore-python) ecosystem. It allows you to expose any apcore Module Registry as a fully functional, standards-compliant A2A agent with zero manual effort.
@@ -33,7 +33,7 @@ By reading the existing apcore metadata—including `input_schema`, `output_sche
 ```bash
 pip install apcore-a2a
 ```
-Requires Python 3.10+ and apcore-python 0.6.0+.
+Requires Python 3.11+ and apcore 0.9.0+.
 
 **TypeScript**
 ```bash

docs/features/adapters.md

@@ -26,17 +26,30 @@ class AgentCardBuilder:
 
     def build(
         self,
-        registry: object,        # duck-typed: has list() + get_definition()
+        registry: Any,           # duck-typed: has list() + get_definition()
         *,
         name: str,
         description: str,
         version: str,
         url: str,
         capabilities: AgentCapabilities,
-        security_schemes: dict | None = None,
+        security_schemes: Any | None = None,
     ) -> AgentCard:
         """Returns a2a.types.AgentCard Pydantic model."""
 
+    def get_cached_or_build(
+        self,
+        registry: Any,
+        *,
+        name: str,
+        description: str,
+        version: str,
+        url: str,
+        capabilities: AgentCapabilities,
+        security_schemes: Any | None = None,
+    ) -> AgentCard:
+        """Return cached card if available, otherwise build a new one."""
+
     def build_extended(
         self,
         *,
@@ -64,7 +77,7 @@ class AgentCardBuilder:
      "skills": [...],
      "capabilities": {"streaming": bool, "pushNotifications": bool, "stateTransitionHistory": bool},
      "defaultInputModes": ["text/plain", "application/json"],
-     "defaultOutputModes": ["application/json"]
+     "defaultOutputModes": ["text/plain", "application/json"]
    }
    ```
 7. Cache in `self._cached_card`. Extended card in `self._cached_extended_card`.
@@ -101,7 +114,7 @@ class SkillMapper:
 | `examples[:10]` | `examples` | `title` → `name`, `inputs` → JSON string in TextPart |
 | computed | `inputModes` | See mode logic below |
 | computed | `outputModes` | See mode logic below |
-| `annotations` | `extensions.apcore.annotations` | All 5 boolean flags |
+| `annotations` | *(not mapped)* | `_build_extensions()` exists but `a2a.types.AgentSkill` has no `extensions` field; annotations are available via the Explorer UI's `_inputSchemas` enrichment instead |
 
 **Input/output mode logic:**
 
@@ -132,9 +145,9 @@ class SkillMapper:
 Converts apcore JSON Schemas for A2A DataPart usage. Reuses logic from apcore-mcp's SchemaConverter.
 
 ```python
-class SchemaConverter:
-    MAX_DEPTH = 32
+_MAX_REF_DEPTH = 32  # module-level constant
 
+class SchemaConverter:
     def convert_input_schema(self, descriptor: object) -> dict:
         """Convert input_schema: inline $refs, strip $defs, ensure root type=object."""
 
@@ -144,8 +157,15 @@ class SchemaConverter:
     def detect_root_type(self, schema: dict | None) -> str:
         """Return 'string', 'object', or 'unknown'."""
 
-    def _inline_refs(self, schema: dict, defs: dict, depth: int, visited: set) -> dict:
+    def _inline_refs(self, schema: Any, defs: dict[str, Any],
+                     _seen: set[str] | None = None, _depth: int = 0) -> Any:
         """Recursively resolve $ref. Raises ValueError on circular refs or depth > 32."""
+
+    def _resolve_ref(self, ref: str, defs: dict[str, Any]) -> dict:
+        """Resolve a single $ref string against $defs."""
+
+    def _ensure_object_type(self, schema: dict) -> dict:
+        """Ensure root schema has type: object."""
 ```
 
 **Conversion rules:**
@@ -165,33 +185,33 @@ Maps apcore exceptions to A2A JSON-RPC error dicts with security-aware sanitizat
 ```python
 class ErrorMapper:
     def to_jsonrpc_error(self, error: Exception) -> dict:
-        """Returns: {"code": int, "message": str, "data": dict | None}"""
+        """Returns: {"code": int, "message": str}"""
 
-    def _build_validation_data(self, error: Exception) -> dict:
-        """For SchemaValidationError: extract field-level detail."""
+    def _handle_apcore_error(self, error: Exception, error_code: str) -> dict:
+        """Handle apcore errors with a .code attribute (string matching)."""
 
     def _sanitize_message(self, message: str) -> str:
         """Strip paths, tracebacks. Truncate to 500 chars."""
 ```
 
+**Error dispatch:** Errors are matched by string `.code` attribute (e.g., `"MODULE_NOT_FOUND"`),
+not by exception class names.
+
 **Error map:**
 
-| apcore Exception | code | message | sanitized |
+| apcore `.code` | JSON-RPC code | message | sanitized |
 |---|---|---|---|
-| `ModuleNotFoundError` | -32601 | `"Skill not found: {module_id}"` | No |
-| `SchemaValidationError` | -32602 | `"Invalid params"` | No (field details in `data.errors`) |
-| `ACLDeniedError` | -32001 | `"Task not found"` | **Yes** (masks real type) |
-| `ModuleExecuteError` | -32603 | `"Internal error"` | Yes |
-| `ModuleTimeoutError` | -32603 | `"Execution timed out"` | Yes |
-| `InvalidInputError` | -32602 | `"Invalid input: {description}"` | No |
-| `CallDepthExceededError` | -32603 | `"Safety limit exceeded"` | Yes |
-| `CircularCallError` | -32603 | `"Safety limit exceeded"` | Yes |
-| `CallFrequencyExceededError` | -32603 | `"Safety limit exceeded"` | Yes |
-| `ApprovalPendingError` | N/A | Task transitions to `input_required` | N/A |
-| Any other `Exception` | -32603 | `"Internal error"` | Yes |
+| `MODULE_NOT_FOUND` | -32601 | sanitized original message | Yes |
+| `SCHEMA_VALIDATION_ERROR` | -32602 | sanitized original message | Yes |
+| `ACL_DENIED` | -32001 | `"Task not found"` | **Yes** (masks real type) |
+| `MODULE_TIMEOUT` / `EXECUTION_TIMEOUT` | -32603 | `"Execution timeout"` | No |
+| `INVALID_INPUT` | -32602 | `"Invalid input: {sanitized description}"` | Yes |
+| `CALL_DEPTH_EXCEEDED` / `CIRCULAR_CALL` / `CALL_FREQUENCY_EXCEEDED` | -32603 | `"Safety limit exceeded"` | No |
+| `asyncio.TimeoutError` | -32603 | `"Execution timeout"` | No |
+| Any other `Exception` | -32603 | `"Internal server error"` | No |
 
 **Sanitization rules:**
-1. Strip substrings matching file path pattern `r'/[^\s]+/[^\s]+'`.
+1. Strip substrings matching file path pattern `r'~?/[^\s]*'` (Unix paths and `~` paths).
 2. Strip traceback lines (`Traceback`, `File "`, `line \d+`).
 3. Truncate to 500 characters.
 4. Log full unsanitized exception at ERROR level with stack trace.
@@ -204,28 +224,31 @@ Bidirectional converter between A2A Parts and apcore module inputs/outputs.
 
 ```python
 class PartConverter:
-    def __init__(self, schema_converter: SchemaConverter) -> None: ...
+    def __init__(self, schema_converter: SchemaConverter | None = None) -> None:
+        """schema_converter defaults to SchemaConverter() if not provided."""
 
-    def parts_to_input(self, parts: list[dict], descriptor: object) -> dict | str:
+    def parts_to_input(self, parts: list[Part], descriptor: Any) -> dict | str:
         """Convert A2A message Parts to apcore module input.
 
         Rules:
         1. Empty parts → raise ValueError("Message must contain at least one Part")
-        2. First DataPart(mediaType="application/json") → return data dict
-        3. TextPart + input_schema root type 'string' → return text string
-        4. TextPart + input_schema root type 'object' → JSON.parse(text)
-           - parse failure → raise ValueError("Invalid JSON in TextPart")
-        5. FilePart → return {"uri": ..., "name": ..., "mimeType": ...}
+        2. Multiple parts → raise ValueError("Multiple parts are not supported; expected exactly one Part")
+        3. DataPart → return data dict
+        4. TextPart + input_schema root type 'string' → return text string
+        5. TextPart + input_schema root type 'object' → JSON.parse(text)
+           - parse failure → raise ValueError("TextPart text is not valid JSON: {error}")
+        6. FilePart → raise ValueError("FilePart is not supported")
         """
 
-    def output_to_parts(self, output: object) -> a2a.types.Artifact:
+    def output_to_parts(self, output: Any, task_id: str = "") -> Artifact:
         """Convert apcore module output to an a2a.types.Artifact Pydantic model.
 
         Rules:
-        1. None → []
-        2. dict → [DataPart(data=output, mediaType="application/json")]
-        3. str → [TextPart(text=output)]
-        4. bytes → [FilePart(bytes=base64(output), mimeType=detected)]
+        1. None → Artifact(artifact_id=..., parts=[])
+        2. dict → Artifact with [DataPart(data=output)]
+        3. str → Artifact with [TextPart(text=output)]
+        4. list → Artifact with [TextPart(text=json.dumps(output))]
+        5. Other → Artifact with [TextPart(text=str(output))]
         """
 ```
 

docs/features/auth.md

@@ -145,7 +145,7 @@ class AuthMiddleware:
         3. Extract headers dict (lowercase keys) from scope["headers"].
         4. identity = authenticator.authenticate(headers).
         5. If identity is None and require_auth:
-           → send 401 with body {"error": "Authentication required"}
+           → send 401 with body {"error": "Unauthorized", "detail": "Missing or invalid Bearer token"}
              and header WWW-Authenticate: Bearer.
         6. Set auth_identity_var.set(identity) (token for ContextVar).
         7. Await downstream app.

docs/features/cli.md

@@ -36,8 +36,8 @@ def main() -> None:
         help="Path to directory containing apcore module extensions",
     )
     serve_parser.add_argument(
-        "--host", default="0.0.0.0",
-        help="Bind host (default: 0.0.0.0)",
+        "--host", default="127.0.0.1",
+        help="Bind host (default: 127.0.0.1)",
     )
     serve_parser.add_argument(
         "--port", type=int, default=8000,
@@ -163,6 +163,15 @@ if args.auth_type == "bearer":
 url = args.url or f"http://{args.host}:{args.port}"
 ```
 
+**Step 4b — Security warning:**
+```python
+if args.host == "0.0.0.0" and auth is None:
+    logger.warning(
+        "--host 0.0.0.0 binds to all network interfaces without authentication; "
+        "consider using --host 127.0.0.1 or enabling --auth-type bearer"
+    )
+```
+
 **Step 5 — Call `serve()`:**
 ```python
 from apcore_a2a import serve

docs/features/explorer.md

@@ -18,11 +18,12 @@ Browser-based interactive UI for exploring and testing an A2A agent. Mounted as
 
 ```python
 def create_explorer_mount(
-    agent_card: dict,
+    agent_card: AgentCard | dict,
     router: object,  # duck-typed: DefaultRequestHandler or ExecutionRouter
     *,
     explorer_prefix: str = "/explorer",
     authenticator: object | None = None,
+    registry: object | None = None,    # optional: enriches agent card with input schemas
 ) -> Mount:
     """Create a Starlette Mount for the Explorer UI.
 
@@ -104,14 +105,23 @@ from starlette.routing import Mount, Route
 from starlette.responses import HTMLResponse
 from starlette.staticfiles import StaticFiles
 
-def create_explorer_mount(agent_card, router, *, explorer_prefix="/explorer", authenticator=None):
+def create_explorer_mount(agent_card, router, *, explorer_prefix="/explorer",
+                          authenticator=None, registry=None):
     html_path = Path(__file__).parent / "index.html"
 
     async def serve_index(request):
         return HTMLResponse(html_path.read_text())
 
     async def serve_agent_card(request):
-        return JSONResponse(agent_card)
+        # If agent_card is a Pydantic model, serialize to dict via model_dump()
+        card_data = agent_card.model_dump() if hasattr(agent_card, "model_dump") else agent_card
+        # If registry provided, enrich skills with _inputSchemas
+        if registry is not None:
+            for skill in card_data.get("skills", []):
+                defn = registry.get_definition(skill.get("id"))
+                if defn and getattr(defn, "input_schema", None):
+                    skill["_inputSchemas"] = defn.input_schema
+        return JSONResponse(card_data)
 
     return Mount(explorer_prefix, routes=[
         Route("/", endpoint=serve_index),

docs/features/ops.md

@@ -35,7 +35,7 @@ async def handle_health(self, request: Request) -> JSONResponse:
     return JSONResponse({
         "status": "healthy",
         "module_count": len(self._registry.list()),
-        "uptime_seconds": int(uptime),
+        "uptime_seconds": uptime,  # float (seconds since start)
         "version": self._version,
     })
 ```
@@ -45,7 +45,7 @@ HTTP 200:
 {
   "status": "healthy",
   "module_count": 5,
-  "uptime_seconds": 3600,
+  "uptime_seconds": 3600.5,
   "version": "1.0.0"
 }
 ```
@@ -106,28 +106,25 @@ HTTP 404 (when `metrics=False`, the default):
 
 ### Counter Implementation
 
-Task state counters are maintained in `TransportManager` via callback from `TaskManager`:
+Task state counters are maintained in a `_MetricsState` dataclass within `server/factory.py`, updated via `on_state_change` callback from `ApCoreAgentExecutor`:
 
 ```python
-class TransportManager:
-    def __init__(self, ...) -> None:
-        self._counters = {
-            "active": 0,
-            "completed": 0,
-            "failed": 0,
-            "canceled": 0,
-            "requests": 0,
-        }
-        self._started_at = time.monotonic()
+@dataclass
+class _MetricsState:
+    active: int = 0
+    completed: int = 0
+    failed: int = 0
+    canceled: int = 0
+    input_required: int = 0
+    started_at: float = field(default_factory=time.monotonic)
 ```
 
-`TaskManager` increments counters on `transition()` callbacks:
+State change callbacks update counters:
 - `→ working` : `active += 1`
 - `→ completed`: `active -= 1`, `completed += 1`
 - `→ failed`   : `active -= 1`, `failed += 1`
 - `→ canceled` : `active -= 1`, `canceled += 1`
-
-`TransportManager.handle_jsonrpc()` increments `requests` on each valid JSON-RPC call.
+- `→ input_required`: `input_required += 1`
 
 ### `serve()` kwarg
 
@@ -177,18 +174,12 @@ def invalidate_cache(self) -> None:
 
 After invalidation, the next `GET /.well-known/agent.json` call triggers a full rebuild from the registry.
 
-### Transport Hot-Swap
-
-The `TransportManager` holds a reference to the agent card dict:
-```python
-class TransportManager:
-    def update_agent_card(self, agent_card: dict) -> None:
-        """Replace agent card. Thread-safe for async event loop."""
-        self._agent_card = agent_card
-        self._extended_card = None  # Reset extended card too
-```
+### Agent Card Hot-Swap
 
-Since this is an async event loop context (single-threaded), the dict replacement is atomic.
+Agent Card updates are handled via `AgentCardBuilder.invalidate_cache()` combined with a
+`card_modifier` callback passed to `A2AStarletteApplication`. The a2a-sdk lazily rebuilds
+the card on the next request after cache invalidation. There is no `TransportManager` —
+transport is handled by a2a-sdk's `A2AStarletteApplication`.
 
 ---