asap-protocol 0.5.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

asap/transport/server.py

@@ -40,14 +40,20 @@ Example:
     >>> # Run with: uvicorn asap.transport.server:app --host 0.0.0.0 --port 8000
 """
 
+import importlib
 import json
 import os
+import sys
+import threading
 import time
+import traceback
 from dataclasses import dataclass
-from typing import Any, Callable, TypeVar
+from pathlib import Path
+from typing import Any, Callable, TypeVar, cast
 
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.responses import JSONResponse, PlainTextResponse
+from opentelemetry import context
 from pydantic import ValidationError
 from slowapi.errors import RateLimitExceeded
 
@@ -55,7 +61,18 @@ from asap.errors import InvalidNonceError, InvalidTimestampError, ThreadPoolExha
 from asap.models.constants import MAX_REQUEST_SIZE
 from asap.models.entities import Capability, Endpoint, Manifest, Skill
 from asap.models.envelope import Envelope
-from asap.observability import get_logger, get_metrics
+from asap.observability import (
+    get_logger,
+    get_metrics,
+    is_debug_log_mode,
+    is_debug_mode,
+    sanitize_for_logging,
+)
+from asap.observability.tracing import (
+    configure_tracing,
+    extract_and_activate_envelope_trace_context,
+    inject_envelope_trace_context,
+)
 from asap.utils.sanitization import sanitize_nonce
 from asap.transport.middleware import (
     AuthenticationMiddleware,
@@ -84,6 +101,10 @@ from asap.transport.jsonrpc import (
     JsonRpcRequest,
     JsonRpcResponse,
 )
+from asap.transport.compression import (
+    decompress_payload,
+    get_supported_encodings,
+)
 from asap.transport.validators import (
     InMemoryNonceStore,
     NonceStore,
@@ -98,6 +119,72 @@ logger = get_logger(__name__)
 T = TypeVar("T")
 HandlerResult = tuple[T | None, JSONResponse | None]
 
+# Environment variable to enable handler hot reload (development)
+ENV_HOT_RELOAD = "ASAP_HOT_RELOAD"
+
+
+class RegistryHolder:
+    """Mutable holder for HandlerRegistry to support hot reload.
+
+    When hot reload is enabled, a background thread watches handlers.py and
+    replaces the registry on file change so new handler code is used without
+    restarting the server.
+    """
+
+    def __init__(self, registry: HandlerRegistry) -> None:
+        self.registry = registry
+        self._executor: BoundedExecutor | None = None
+
+    def replace_registry(self, new_registry: HandlerRegistry) -> None:
+        """Replace the held registry (e.g. after reloading handlers module)."""
+        if self._executor is not None:
+            new_registry._executor = self._executor
+        self.registry = new_registry
+
+
+def _run_handler_watcher(holder: RegistryHolder, handlers_path: str) -> None:
+    """Background thread: watch handlers_path and reload registry on change.
+
+    Graceful degradation: if watchfiles is not installed, hot reload is skipped
+    and the server runs normally without file watching.
+    """
+    try:
+        from watchfiles import watch
+    except ImportError:
+        logger.warning(
+            "asap.server.handler_watcher_skip",
+            path=handlers_path,
+            message="watchfiles not installed; hot reload disabled. Install with: pip install watchfiles",
+        )
+        return
+    try:
+        for changes in watch(handlers_path):
+            if not changes:
+                continue
+            try:
+                import asap.transport.handlers as handlers_module
+
+                importlib.reload(handlers_module)
+                new_registry = handlers_module.create_default_registry()
+                holder.replace_registry(new_registry)
+                logger.info(
+                    "asap.server.handlers_reloaded",
+                    path=handlers_path,
+                    handlers=new_registry.list_handlers(),
+                )
+            except Exception as e:
+                logger.warning(
+                    "asap.server.handlers_reload_failed",
+                    path=handlers_path,
+                    error=str(e),
+                )
+    except Exception as e:
+        logger.warning(
+            "asap.server.handler_watcher_stopped",
+            path=handlers_path,
+            error=str(e),
+        )
+
 
 @dataclass
 class RequestContext:
@@ -139,13 +226,13 @@ class ASAPRequestHandler:
         auth_middleware: Optional authentication middleware
 
     Example:
-        >>> handler = ASAPRequestHandler(registry, manifest, auth_middleware)
+        >>> handler = ASAPRequestHandler(RegistryHolder(registry), manifest, auth_middleware)
         >>> response = await handler.handle_message(request)
     """
 
     def __init__(
         self,
-        registry: HandlerRegistry,
+        registry_holder: RegistryHolder,
         manifest: Manifest,
         auth_middleware: AuthenticationMiddleware | None = None,
         max_request_size: int = MAX_REQUEST_SIZE,
@@ -154,13 +241,13 @@ class ASAPRequestHandler:
         """Initialize the request handler.
 
         Args:
-            registry: Handler registry for dispatching payloads
+            registry_holder: Holder for handler registry (supports hot reload).
             manifest: Agent manifest describing capabilities
             auth_middleware: Optional authentication middleware for request validation
             max_request_size: Maximum allowed request size in bytes
             nonce_store: Optional nonce store for replay attack prevention
         """
-        self.registry = registry
+        self.registry_holder = registry_holder
         self.manifest = manifest
         self.auth_middleware = auth_middleware
         self.max_request_size = max_request_size
@@ -179,7 +266,7 @@ class ASAPRequestHandler:
         Returns:
             The payload type if registered, or "other" if unknown
         """
-        if self.registry.has_handler(payload_type):
+        if self.registry_holder.registry.has_handler(payload_type):
             return payload_type
         return "other"
 
@@ -235,6 +322,23 @@ class ASAPRequestHandler:
             duration_seconds,
             {"payload_type": normalized_payload_type, "status": "error"},
         )
+        # Specific error counters for observability
+        if error_type == "parse_error":
+            metrics.increment_counter("asap_parse_errors_total")
+        elif error_type == "auth_failed":
+            metrics.increment_counter("asap_auth_failures_total")
+        elif error_type == "invalid_timestamp":
+            metrics.increment_counter("asap_invalid_timestamp_total")
+        elif error_type == "invalid_nonce":
+            metrics.increment_counter("asap_invalid_nonce_total")
+        elif error_type == "sender_mismatch":
+            metrics.increment_counter("asap_sender_mismatch_total")
+        elif error_type in (
+            "invalid_envelope",
+            "missing_envelope",
+            "invalid_params",
+        ):
+            metrics.increment_counter("asap_validation_errors_total", {"reason": error_type})
 
     def _validate_envelope(
         self,
@@ -252,7 +356,6 @@ class ASAPRequestHandler:
             Tuple of (Envelope, payload_type) if valid, or (None, error_response) if invalid
         """
         rpc_request = ctx.rpc_request
-        # Validate params is a dict before accessing
         if not isinstance(rpc_request.params, dict):
             logger.warning(
                 "asap.request.invalid_params_type",
@@ -291,17 +394,18 @@ class ASAPRequestHandler:
             )
             return None, error_response
 
-        # Validate envelope structure
         try:
             envelope = Envelope(**envelope_data)
             payload_type = envelope.payload_type
             return envelope, payload_type
         except ValidationError as e:
-            logger.warning(
-                "asap.request.invalid_envelope",
-                error="Invalid envelope structure",
-                validation_errors=str(e.errors()),
-            )
+            log_data: dict[str, Any] = {
+                "error": "Invalid envelope structure",
+                "validation_errors": e.errors(),
+            }
+            if not is_debug_mode():
+                log_data = sanitize_for_logging(log_data)
+            logger.warning("asap.request.invalid_envelope", **log_data)
             duration_seconds = time.perf_counter() - ctx.start_time
             self.record_error_metrics(ctx.metrics, "unknown", "invalid_envelope", duration_seconds)
             error_response = self.build_error_response(
@@ -334,7 +438,9 @@ class ASAPRequestHandler:
         """
         payload_type = envelope.payload_type
         try:
-            response_envelope = await self.registry.dispatch_async(envelope, self.manifest)
+            response_envelope = await self.registry_holder.registry.dispatch_async(
+                envelope, self.manifest
+            )
             return response_envelope, payload_type
         except ThreadPoolExhaustedError as e:
             # Thread pool exhausted - service temporarily unavailable
@@ -490,6 +596,7 @@ class ASAPRequestHandler:
         Returns:
             JSON-RPC success response
         """
+        response_envelope = inject_envelope_trace_context(response_envelope)
         duration_seconds = time.perf_counter() - ctx.start_time
         duration_ms = duration_seconds * 1000
 
@@ -556,7 +663,7 @@ class ASAPRequestHandler:
         # Record error metrics (normalized to prevent cardinality explosion)
         self.record_error_metrics(ctx.metrics, payload_type, "internal_error", duration_seconds)
 
-        # Log error
+        # Always log full error server-side for diagnostics
         logger.exception(
             "asap.request.error",
             error=str(error),
@@ -564,12 +671,18 @@ class ASAPRequestHandler:
             duration_ms=round(duration_ms, 2),
         )
 
-        # Internal server error
+        # Production: generic error to client; debug: full error and stack trace
+        if is_debug_mode():
+            error_data: dict[str, Any] = {
+                "error": str(error),
+                "type": type(error).__name__,
+                "traceback": traceback.format_exc(),
+            }
+        else:
+            error_data = {"error": "Internal server error"}
+
         internal_error = JsonRpcErrorResponse(
-            error=JsonRpcError.from_code(
-                INTERNAL_ERROR,
-                data={"error": str(error), "type": type(error).__name__},
-            ),
+            error=JsonRpcError.from_code(INTERNAL_ERROR, data=error_data),
             id=ctx.request_id,
         )
         return JSONResponse(
@@ -577,6 +690,35 @@ class ASAPRequestHandler:
             content=internal_error.model_dump(),
         )
 
+    def _log_request_debug(self, rpc_request: JsonRpcRequest) -> None:
+        """Log full JSON-RPC request when ASAP_DEBUG_LOG is enabled (structured JSON)."""
+        if not is_debug_log_mode():
+            return
+        request_dict: dict[str, Any] = rpc_request.model_dump()
+        if not is_debug_mode():
+            request_dict = sanitize_for_logging(request_dict)
+        logger.info("asap.request.debug_request", request_json=request_dict)
+
+    def _log_response_debug(self, response: JSONResponse) -> None:
+        """Log full response when ASAP_DEBUG_LOG is enabled (structured JSON)."""
+        if not is_debug_log_mode():
+            return
+        try:
+            body_bytes = response.body
+            # Handle both bytes and memoryview
+            if isinstance(body_bytes, memoryview):
+                body_bytes = body_bytes.tobytes()
+            response_dict: dict[str, Any] = json.loads(body_bytes.decode("utf-8"))
+        except (ValueError, AttributeError):
+            response_dict = {"_raw": "(unable to decode response body)"}
+        if not is_debug_mode():
+            response_dict = sanitize_for_logging(response_dict)
+        logger.info(
+            "asap.request.debug_response",
+            status_code=response.status_code,
+            response_json=response_dict,
+        )
+
     async def _parse_and_validate_request(
         self,
         request: Request,
@@ -614,7 +756,6 @@ class ASAPRequestHandler:
             self.record_error_metrics(temp_metrics, "unknown", "parse_error", 0.0)
             return None, error_response
 
-        # Validate body is a dict (JSON-RPC requires object at root)
         if not isinstance(body, dict):
             error_response = self.build_error_response(
                 INVALID_REQUEST,
@@ -628,17 +769,13 @@ class ASAPRequestHandler:
             self.record_error_metrics(temp_metrics, "unknown", "invalid_request", 0.0)
             return None, error_response
 
-        # Validate JSON-RPC request structure and method
         rpc_request, validation_error = self.validate_jsonrpc_request(body)
         if validation_error is not None:
             temp_metrics = get_metrics()
             self.record_error_metrics(temp_metrics, "unknown", "invalid_request", 0.0)
             return None, validation_error
 
-        # Type narrowing: rpc_request is not None here
         if rpc_request is None:
-            # This should not happen if validate_jsonrpc_request is correct
-            # but guard against it for robustness
             error_response = self.build_error_response(
                 INTERNAL_ERROR,
                 data={"error": "Internal validation error"},
@@ -665,7 +802,6 @@ class ASAPRequestHandler:
         Raises:
             HTTPException: If request size exceeds maximum (413 Payload Too Large)
         """
-        # Check Content-Length header first
         content_length = request.headers.get("content-length")
         if content_length:
             try:
@@ -681,14 +817,14 @@ class ASAPRequestHandler:
                         detail=f"Request size ({size} bytes) exceeds maximum ({max_size} bytes)",
                     )
             except ValueError:
-                # Invalid Content-Length header, will check body size instead
                 pass
 
     async def parse_json_body(self, request: Request) -> dict[str, Any]:
-        """Parse JSON body from request with size validation.
+        """Parse JSON body from request with size validation and decompression.
 
         Validates request size before parsing to prevent DoS attacks.
         Checks both Content-Length header and actual body size.
+        Automatically decompresses gzip/brotli encoded requests.
 
         Args:
             request: FastAPI request object
@@ -698,16 +834,26 @@ class ASAPRequestHandler:
 
         Raises:
             HTTPException: If request size exceeds maximum (413)
+            HTTPException: If Content-Encoding is unsupported (415)
             ValueError: If JSON is invalid
         """
-        # Read body in chunks and validate size incrementally to prevent OOM attacks
-        # Note: Content-Length header validation is handled by SizeLimitMiddleware
-        # This validates actual body size during streaming to prevent OOM attacks
+        content_encoding = request.headers.get("content-encoding", "").lower().strip()
+        supported_encodings = get_supported_encodings() + ["identity", ""]
+        if content_encoding and content_encoding not in supported_encodings:
+            logger.warning(
+                "asap.request.unsupported_encoding",
+                content_encoding=content_encoding,
+                supported=supported_encodings,
+            )
+            raise HTTPException(
+                status_code=415,
+                detail=f"Unsupported Content-Encoding: {content_encoding}. Supported: {', '.join(get_supported_encodings())}",
+            )
+
         try:
             body_bytes = bytearray()
             async for chunk in request.stream():
                 body_bytes.extend(chunk)
-                # Validate size after each chunk to abort early if limit exceeded
                 if len(body_bytes) > self.max_request_size:
                     logger.warning(
                         "asap.request.size_exceeded",
@@ -719,6 +865,58 @@ class ASAPRequestHandler:
                         detail=f"Request size ({len(body_bytes)} bytes) exceeds maximum ({self.max_request_size} bytes)",
                     )
 
+            # Decompress if Content-Encoding is specified
+            if content_encoding and content_encoding not in ("identity", ""):
+                try:
+                    compressed_size = len(body_bytes)
+                    body_bytes = bytearray(decompress_payload(bytes(body_bytes), content_encoding))
+                    decompressed_size = len(body_bytes)
+
+                    logger.debug(
+                        "asap.request.decompressed",
+                        content_encoding=content_encoding,
+                        compressed_size=compressed_size,
+                        decompressed_size=decompressed_size,
+                    )
+
+                    if decompressed_size > self.max_request_size:
+                        compression_ratio = (
+                            decompressed_size / compressed_size if compressed_size > 0 else 0
+                        )
+                        logger.warning(
+                            "asap.request.decompressed_size_exceeded",
+                            decompressed_size=decompressed_size,
+                            original_compressed_size=compressed_size,
+                            compression_ratio=round(compression_ratio, 2),
+                            max_size=self.max_request_size,
+                        )
+                        raise HTTPException(
+                            status_code=413,
+                            detail=f"Decompressed request size ({decompressed_size} bytes) exceeds maximum ({self.max_request_size} bytes)",
+                        )
+                except ValueError as e:
+                    # Decompression failed (invalid compressed data or unsupported encoding)
+                    logger.warning(
+                        "asap.request.decompression_failed",
+                        content_encoding=content_encoding,
+                        error=str(e),
+                    )
+                    raise HTTPException(
+                        status_code=400,
+                        detail=f"Failed to decompress request: {e}",
+                    ) from e
+                except (OSError, EOFError) as e:
+                    # Invalid gzip/brotli data (OSError) or truncated data (EOFError)
+                    logger.warning(
+                        "asap.request.invalid_compressed_data",
+                        content_encoding=content_encoding,
+                        error=str(e),
+                    )
+                    raise HTTPException(
+                        status_code=400,
+                        detail=f"Invalid compressed data: {e}",
+                    ) from e
+
             # Parse JSON from bytes
             body: dict[str, Any] = json.loads(body_bytes.decode("utf-8"))
             return body
@@ -740,11 +938,9 @@ class ASAPRequestHandler:
         Returns:
             Tuple of (JsonRpcRequest, None) if valid, or (None, error_response) if invalid
         """
-        # Validate JSON-RPC structure
         try:
             rpc_request = JsonRpcRequest(**body)
         except (ValidationError, TypeError) as e:
-            # Check if error is specifically about params type
             error_code = INVALID_REQUEST
             error_message = "Invalid JSON-RPC structure"
             if isinstance(e, ValidationError):
@@ -756,12 +952,18 @@ class ASAPRequestHandler:
                         error_message = "JSON-RPC 'params' must be an object"
                         break
 
-            logger.warning(
-                "asap.request.invalid_structure",
-                error=error_message,
-                error_type=type(e).__name__,
-                validation_errors=str(e.errors()) if isinstance(e, ValidationError) else str(e),
-            )
+            log_struct: dict[str, Any] = {
+                "error": error_message,
+                "error_type": type(e).__name__,
+                "validation_errors": (
+                    e.errors()
+                    if isinstance(e, ValidationError)
+                    else [{"type": "type_error", "loc": (), "msg": str(e), "input": None}]
+                ),
+            }
+            if not is_debug_mode():
+                log_struct = sanitize_for_logging(log_struct)
+            logger.warning("asap.request.invalid_structure", **log_struct)
             error_response = self.build_error_response(
                 error_code,
                 data={
@@ -776,7 +978,6 @@ class ASAPRequestHandler:
             )
             return None, error_response
 
-        # Check method
         if rpc_request.method != ASAP_METHOD:
             logger.warning("asap.request.unknown_method", method=rpc_request.method)
             error_response = self.build_error_response(
@@ -812,17 +1013,16 @@ class ASAPRequestHandler:
         payload_type = "unknown"
 
         try:
-            # Parse and validate JSON-RPC request
             parse_result = await self._parse_and_validate_request(request)
             rpc_request, parse_error = parse_result
             if parse_error is not None:
+                self._log_response_debug(parse_error)
                 return parse_error
-            # Type narrowing: rpc_request is not None here
-            # Use explicit check instead of assert to avoid removal in optimized builds
             if rpc_request is None:
                 raise RuntimeError("Internal error: rpc_request is None after validation")
 
-            # Create request context
+            self._log_request_debug(rpc_request)
+
             ctx = RequestContext(
                 request_id=rpc_request.id,
                 start_time=start_time,
@@ -830,107 +1030,115 @@ class ASAPRequestHandler:
                 rpc_request=rpc_request,
             )
 
-            # Authenticate request if enabled
             auth_result = await self._authenticate_request(request, ctx)
             authenticated_agent_id, auth_error = auth_result
             if auth_error is not None:
+                self._log_response_debug(auth_error)
                 return auth_error
 
-            # Validate and extract envelope
             envelope_result = self._validate_envelope(ctx)
             envelope_or_none, result = envelope_result
             if envelope_or_none is None:
-                # result is JSONResponse when envelope is None
-                return result  # type: ignore[return-value]
+                error_resp = cast(JSONResponse, result)
+                self._log_response_debug(error_resp)
+                return error_resp
             envelope = envelope_or_none
-            # result is payload_type (str) when envelope is not None
-            payload_type = result  # type: ignore[assignment]
-
-            # Verify sender matches authenticated identity
-            sender_error = self._verify_sender_matches_auth(
-                authenticated_agent_id,
-                envelope,
-                ctx,
-                payload_type,
-            )
-            if sender_error is not None:
-                return sender_error
+            payload_type = cast(str, result)
 
-            # Validate envelope timestamp to prevent replay attacks
+            trace_token = extract_and_activate_envelope_trace_context(envelope)
             try:
-                validate_envelope_timestamp(envelope)
-            except InvalidTimestampError as e:
-                logger.warning(
-                    "asap.request.invalid_timestamp",
-                    envelope_id=envelope.id,
-                    error=e.message,
-                    details=e.details,
+                sender_error = self._verify_sender_matches_auth(
+                    authenticated_agent_id,
+                    envelope,
+                    ctx,
+                    payload_type,
                 )
-                duration_seconds = time.perf_counter() - ctx.start_time
-                self.record_error_metrics(
-                    ctx.metrics, payload_type, "invalid_timestamp", duration_seconds
-                )
-                return self.build_error_response(
-                    INVALID_PARAMS,
-                    data={
-                        "error": "Invalid envelope timestamp",
-                        "code": e.code,
-                        "message": e.message,
+                if sender_error is not None:
+                    self._log_response_debug(sender_error)
+                    return sender_error
+
+                try:
+                    validate_envelope_timestamp(envelope)
+                except InvalidTimestampError as e:
+                    log_ts: dict[str, Any] = {
+                        "envelope_id": envelope.id,
+                        "error": e.message,
                         "details": e.details,
-                    },
-                    request_id=ctx.request_id,
-                )
+                    }
+                    if not is_debug_mode() and isinstance(e.details, dict):
+                        log_ts["details"] = sanitize_for_logging(e.details)
+                    logger.warning("asap.request.invalid_timestamp", **log_ts)
+                    duration_seconds = time.perf_counter() - ctx.start_time
+                    self.record_error_metrics(
+                        ctx.metrics, payload_type, "invalid_timestamp", duration_seconds
+                    )
+                    err_resp = self.build_error_response(
+                        INVALID_PARAMS,
+                        data={
+                            "error": "Invalid envelope timestamp",
+                            "code": e.code,
+                            "message": e.message,
+                            "details": e.details,
+                        },
+                        request_id=ctx.request_id,
+                    )
+                    self._log_response_debug(err_resp)
+                    return err_resp
+
+                try:
+                    validate_envelope_nonce(envelope, self.nonce_store)
+                except InvalidNonceError as e:
+                    # Sanitize nonce in logs to prevent full value exposure
+                    nonce_sanitized = sanitize_nonce(e.nonce)
+                    error_msg = e.message if is_debug_mode() else "Duplicate nonce detected"
+                    logger.warning(
+                        "asap.request.invalid_nonce",
+                        envelope_id=envelope.id,
+                        nonce=nonce_sanitized,
+                        error=error_msg,
+                    )
+                    duration_seconds = time.perf_counter() - ctx.start_time
+                    self.record_error_metrics(
+                        ctx.metrics, payload_type, "invalid_nonce", duration_seconds
+                    )
+                    err_resp = self.build_error_response(
+                        INVALID_PARAMS,
+                        data={
+                            "error": "Invalid envelope nonce",
+                            "code": e.code,
+                            "message": e.message,
+                            "details": e.details,
+                        },
+                        request_id=ctx.request_id,
+                    )
+                    self._log_response_debug(err_resp)
+                    return err_resp
 
-            # Validate envelope nonce if nonce store is available
-            try:
-                validate_envelope_nonce(envelope, self.nonce_store)
-            except InvalidNonceError as e:
-                # Sanitize nonce in logs to prevent full value exposure
-                nonce_sanitized = sanitize_nonce(e.nonce)
-                logger.warning(
-                    "asap.request.invalid_nonce",
+                logger.info(
+                    "asap.request.received",
                     envelope_id=envelope.id,
-                    nonce=nonce_sanitized,
-                    error=e.message,
-                )
-                duration_seconds = time.perf_counter() - ctx.start_time
-                self.record_error_metrics(
-                    ctx.metrics, payload_type, "invalid_nonce", duration_seconds
-                )
-                return self.build_error_response(
-                    INVALID_PARAMS,
-                    data={
-                        "error": "Invalid envelope nonce",
-                        "code": e.code,
-                        "message": e.message,
-                        "details": e.details,
-                    },
-                    request_id=ctx.request_id,
+                    trace_id=envelope.trace_id,
+                    payload_type=envelope.payload_type,
+                    sender=envelope.sender,
+                    recipient=envelope.recipient,
+                    authenticated=authenticated_agent_id is not None,
                 )
 
-            # Log request received
-            logger.info(
-                "asap.request.received",
-                envelope_id=envelope.id,
-                trace_id=envelope.trace_id,
-                payload_type=envelope.payload_type,
-                sender=envelope.sender,
-                recipient=envelope.recipient,
-                authenticated=authenticated_agent_id is not None,
-            )
-
-            # Dispatch to handler
-            dispatch_result = await self._dispatch_to_handler(envelope, ctx)
-            response_or_none, result = dispatch_result
-            if response_or_none is None:
-                # result is JSONResponse when response is None
-                return result  # type: ignore[return-value]
-            response_envelope = response_or_none
-            # result is payload_type (str) when response is not None
-            payload_type = result  # type: ignore[assignment]
-
-            # Build and return success response
-            return self._build_success_response(response_envelope, ctx, payload_type)
+                dispatch_result = await self._dispatch_to_handler(envelope, ctx)
+                response_or_none, result = dispatch_result
+                if response_or_none is None:
+                    error_resp = cast(JSONResponse, result)
+                    self._log_response_debug(error_resp)
+                    return error_resp
+                response_envelope = response_or_none
+                payload_type = cast(str, result)
+
+                success_resp = self._build_success_response(response_envelope, ctx, payload_type)
+                self._log_response_debug(success_resp)
+                return success_resp
+            finally:
+                if trace_token is not None:
+                    context.detach(trace_token)
 
         except Exception as e:
             # Create minimal context for error handling if we don't have rpc_request yet
@@ -947,7 +1155,9 @@ class ASAPRequestHandler:
                     metrics=temp_metrics,
                     rpc_request=temp_rpc_request,
                 )
-            return self._handle_internal_error(e, ctx, payload_type)
+            err_resp = self._handle_internal_error(e, ctx, payload_type)
+            self._log_response_debug(err_resp)
+            return err_resp
 
 
 def create_app(
@@ -958,6 +1168,7 @@ def create_app(
     max_request_size: int | None = None,
     max_threads: int | None = None,
     require_nonce: bool = False,
+    hot_reload: bool | None = None,
 ) -> FastAPI:
     """Create and configure a FastAPI application for ASAP protocol.
 
@@ -977,9 +1188,14 @@ def create_app(
         token_validator: Optional function to validate Bearer tokens.
             Required if manifest.auth is configured. Should return agent ID
             if token is valid, None otherwise.
-        rate_limit: Optional rate limit string (e.g., "100/minute").
+        rate_limit: Optional rate limit string (e.g., "10/second;100/minute").
             Rate limiting is IP-based (per client IP address) to prevent DoS attacks.
-            Defaults to ASAP_RATE_LIMIT environment variable or "100/minute".
+            Uses token bucket pattern: burst limit + sustained limit.
+            Defaults to ASAP_RATE_LIMIT environment variable or "10/second;100/minute".
+            **Warning:** The default storage is ``memory://`` (per-process). In
+            multi-worker deployments (e.g., Gunicorn with 4 workers), each worker
+            has isolated limits, so effective rate = limit × workers (e.g.,
+            10/s → 40/s). For production, use Redis-backed storage via slowapi.
         max_request_size: Optional maximum request size in bytes.
             Defaults to ASAP_MAX_REQUEST_SIZE environment variable or 10MB.
         max_threads: Optional maximum number of threads for sync handlers.
@@ -988,6 +1204,8 @@ def create_app(
         require_nonce: If True, enables nonce validation for replay attack prevention.
             When enabled, creates an InMemoryNonceStore and validates nonces in envelopes.
             Defaults to False (nonce validation is optional).
+        hot_reload: If True, watch handlers.py and reload handler registry on file change
+            (development only). Defaults to ASAP_HOT_RELOAD env or False.
 
     Returns:
         Configured FastAPI application ready to run
@@ -1044,6 +1262,7 @@ def create_app(
         )
 
     # Use default registry if none provided
+    use_default_registry = registry is None
     if registry is None:
         registry = create_default_registry()
 
@@ -1051,6 +1270,15 @@ def create_app(
     if executor is not None:
         registry._executor = executor
 
+    # Wrap registry in holder for hot reload support
+    registry_holder = RegistryHolder(registry)
+    if executor is not None:
+        registry_holder._executor = executor
+
+    # Resolve hot_reload from env if not specified
+    if hot_reload is None:
+        hot_reload = os.getenv(ENV_HOT_RELOAD, "").strip().lower() in ("true", "1", "yes")
+
     # Create authentication middleware if auth is configured
     auth_middleware: AuthenticationMiddleware | None = None
     if manifest.auth is not None:
@@ -1081,12 +1309,45 @@ def create_app(
         )
 
     # Create request handler
-    handler = ASAPRequestHandler(registry, manifest, auth_middleware, max_request_size, nonce_store)
+    handler = ASAPRequestHandler(
+        registry_holder, manifest, auth_middleware, max_request_size, nonce_store
+    )
+
+    # Start handler file watcher when hot reload is enabled (only with default registry)
+    if hot_reload and use_default_registry:
+        _handlers_module = sys.modules.get("asap.transport.handlers")
+        _handlers_file = getattr(_handlers_module, "__file__", "") if _handlers_module else ""
+        if _handlers_file and Path(_handlers_file).exists():
+            watcher = threading.Thread(
+                target=_run_handler_watcher,
+                args=(registry_holder, _handlers_file),
+                name="asap-handler-watcher",
+                daemon=True,
+            )
+            watcher.start()
+            logger.info(
+                "asap.server.hot_reload_enabled",
+                manifest_id=manifest.id,
+                path=_handlers_file,
+            )
+        else:
+            logger.warning(
+                "asap.server.hot_reload_skipped",
+                reason="handlers module path not found",
+            )
+
+    # Enable Swagger UI (/docs) and ReDoc (/redoc) only when ASAP_DEBUG=true
+    _docs_url = "/docs" if is_debug_mode() else None
+    _redoc_url = "/redoc" if is_debug_mode() else None
+    _openapi_url = "/openapi.json" if is_debug_mode() else None
 
     app = FastAPI(
         title="ASAP Protocol Server",
         description=f"ASAP server for {manifest.name}",
         version=manifest.version,
+        docs_url=_docs_url,
+        redoc_url=_redoc_url,
+        openapi_url=_openapi_url,
     )
 
     # Add size limit middleware (runs before routing)
@@ -1094,7 +1355,8 @@ def create_app(
 
     # Configure rate limiting
     if rate_limit is None:
-        rate_limit_str = os.getenv("ASAP_RATE_LIMIT", "100/minute")
+        # Default matches DD-012: Burst allowance for better UX with bursty agent traffic
+        rate_limit_str = os.getenv("ASAP_RATE_LIMIT", "10/second;100/minute")
     else:
         rate_limit_str = rate_limit
 
@@ -1115,10 +1377,35 @@ def create_app(
         max_request_size=max_request_size,
     )
 
-    # Note: Request size limits should be configured at the ASGI server level (e.g., uvicorn).
-    # For production, consider setting --limit-max-requests or using a reverse proxy
+    # Note: Request size limits should be configured at the ASGI server level
+    # (e.g., uvicorn --limit-max-body).
+    # For production, consider using a reverse proxy
     # (nginx, traefik) to enforce request size limits (e.g., 10MB max).
 
+    @app.get("/health")
+    async def health() -> JSONResponse:
+        """Liveness probe: always OK if the process is running.
+
+        Used by Kubernetes livenessProbe and Docker HEALTHCHECK.
+        Returns 200 with {"status": "ok"}.
+
+        Returns:
+            JSONResponse with status ok
+        """
+        return JSONResponse(status_code=200, content={"status": "ok"})
+
+    @app.get("/ready")
+    async def ready() -> JSONResponse:
+        """Readiness probe: OK when the server is ready to accept traffic.
+
+        Used by Kubernetes readinessProbe. Returns 200 when the app
+        is initialized and can serve requests.
+
+        Returns:
+            JSONResponse with status ok
+        """
+        return JSONResponse(status_code=200, content={"status": "ok"})
+
     @app.get("/.well-known/asap/manifest.json")
     async def get_manifest() -> dict[str, Any]:
         """Return the agent's manifest for discovery.
@@ -1152,9 +1439,12 @@ def create_app(
         metrics = get_metrics()
         return PlainTextResponse(
             content=metrics.export_prometheus(),
-            media_type="text/plain; version=0.0.4; charset=utf-8",
+            media_type="application/openmetrics-text; version=1.0.0; charset=utf-8",
         )
 
+    # OpenTelemetry tracing (zero-config via OTEL_* env vars)
+    configure_tracing(service_name=manifest.id, app=app)
+
     @app.post("/asap")
     @limiter.limit(rate_limit_str)  # slowapi uses app.state.limiter at runtime
     async def handle_asap_message(request: Request) -> JSONResponse:
@@ -1194,7 +1484,7 @@ def _create_default_manifest() -> Manifest:
     return Manifest(
         id="urn:asap:agent:default-server",
         name="ASAP Default Server",
-        version="0.3.0",
+        version="1.0.0-dev",
         description="Default ASAP protocol server with echo capabilities",
         capabilities=Capability(
             asap_version="0.1",