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

asap/__init__.py

@@ -4,4 +4,4 @@ A streamlined, scalable, asynchronous protocol for agent-to-agent communication
 and task coordination.
 """
 
-__version__ = "0.3.0"
+__version__ = "1.0.0"

asap/cli.py

@@ -1,6 +1,7 @@
 """Command-line interface for ASAP Protocol utilities.
 
-This module provides CLI commands for schema export, inspection, and validation.
+This module provides CLI commands for schema export, inspection, validation,
+trace visualization, and an interactive REPL for testing payloads.
 
 Example:
     >>> # From terminal:
@@ -9,9 +10,14 @@ Example:
     >>> # asap list-schemas
     >>> # asap show-schema agent
     >>> # asap validate-schema message.json --schema-type envelope
+    >>> # asap trace <trace-id> [--log-file asap.log] [--format ascii|json]
+    >>> # asap repl  # Interactive REPL with ASAP models
 """
 
+import code
 import json
+import os
+import sys
 from pathlib import Path
 from typing import Annotated, Optional
 
@@ -19,6 +25,10 @@ import typer
 from pydantic import ValidationError
 
 from asap import __version__
+from asap.models import Envelope, TaskRequest, generate_id
+from asap.models.entities import Capability, Endpoint, Manifest, Skill
+
+from asap.observability.trace_parser import parse_trace_from_lines, trace_to_json_export
 from asap.schemas import SCHEMA_REGISTRY, export_all_schemas, get_schema_json, list_schema_entries
 
 app = typer.Typer(help="ASAP Protocol CLI.")
@@ -175,7 +185,6 @@ def validate_schema(
     message_send, state_query, state_restore, artifact_notify, mcp_tool_call,
     mcp_tool_result, mcp_resource_fetch, mcp_resource_data, envelope.
     """
-    # Check file exists
     if not file.exists():
         raise typer.BadParameter(f"File not found: {file}")
 
@@ -211,6 +220,132 @@ def validate_schema(
     typer.echo(f"Valid {effective_schema_type} schema: {file}")
 
 
+# Environment variable for default trace log file
+ENV_TRACE_LOG = "ASAP_TRACE_LOG"
+
+# REPL banner and namespace
+REPL_BANNER = (
+    "ASAP Protocol REPL - test payloads interactively.\n"
+    "  Envelope, TaskRequest, Manifest, generate_id, sample_envelope() available.\n"
+    "  Type exit() or Ctrl-D to quit."
+)
+
+
+def _repl_namespace() -> dict[str, object]:
+    """Build namespace for the ASAP REPL with models and a sample envelope helper."""
+
+    def sample_envelope() -> Envelope:
+        """Return a sample task.request envelope for quick testing."""
+        return Envelope(
+            asap_version="0.1",
+            sender="urn:asap:agent:repl-sender",
+            recipient="urn:asap:agent:repl-recipient",
+            payload_type="task.request",
+            payload=TaskRequest(
+                conversation_id=f"conv-{generate_id()}",
+                skill_id="echo",
+                input={"message": "hello from REPL"},
+            ).model_dump(),
+        )
+
+    return {
+        "Envelope": Envelope,
+        "TaskRequest": TaskRequest,
+        "Manifest": Manifest,
+        "Capability": Capability,
+        "Endpoint": Endpoint,
+        "Skill": Skill,
+        "generate_id": generate_id,
+        "sample_envelope": sample_envelope,
+    }
+
+
+@app.command("repl")
+def repl() -> None:
+    """Start an interactive REPL with ASAP models for testing payloads.
+
+    Provides Envelope, TaskRequest, Manifest, generate_id, and sample_envelope()
+    in the namespace. Use Python's code module for the interactive loop.
+    """
+    namespace = _repl_namespace()
+    code.interact(banner=REPL_BANNER, local=namespace)
+
+
+@app.command("trace")
+def trace(
+    trace_id: Annotated[
+        Optional[str],
+        typer.Argument(help="Trace ID to search for in logs (e.g. from envelope.trace_id)."),
+    ] = None,
+    log_file: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--log-file",
+            "-f",
+            help="Log file to search (JSON lines). Default: ASAP_TRACE_LOG env or stdin.",
+        ),
+    ] = None,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-o",
+            help="Output format: ascii (diagram) or json (for external tools).",
+        ),
+    ] = "ascii",
+) -> None:
+    """Show request flow and timing for a trace ID from ASAP JSON logs.
+
+    Searches log lines for asap.request.received and asap.request.processed
+    events with the given trace_id and prints an ASCII diagram of the flow
+    with latency per hop (e.g. agent_a -> agent_b (15ms) -> agent_c (23ms)).
+
+    Use --format json to output structured JSON for piping to jq, CI, or
+    observability platforms.
+
+    Logs must be JSON lines (ASAP_LOG_FORMAT=json). Use --log-file to pass
+    a file, or set ASAP_TRACE_LOG; otherwise reads from stdin.
+    """
+    effective_log_file = log_file
+    if effective_log_file is None and os.environ.get(ENV_TRACE_LOG):
+        effective_log_file = Path(os.environ[ENV_TRACE_LOG])
+
+    if trace_id is None or trace_id.strip() == "":
+        typer.echo(
+            "Error: trace_id is required. Usage: asap trace <trace-id> [--log-file PATH]", err=True
+        )
+        raise typer.Exit(1)
+
+    trace_id = trace_id.strip()
+    fmt = output_format.strip().lower() if output_format else "ascii"
+    if fmt not in ("ascii", "json"):
+        typer.echo("Error: --format must be 'ascii' or 'json'", err=True)
+        raise typer.Exit(1)
+
+    def _lines() -> list[str]:
+        if effective_log_file is None:
+            return sys.stdin.readlines()
+        if not effective_log_file.exists():
+            raise typer.BadParameter(f"Log file not found: {effective_log_file}")
+        return effective_log_file.read_text(encoding="utf-8").splitlines()
+
+    try:
+        lines = _lines()
+    except typer.BadParameter:
+        raise
+    except OSError as exc:
+        raise typer.BadParameter(f"Cannot read log file: {exc}") from exc
+
+    hops, diagram = parse_trace_from_lines(lines, trace_id)
+    if not hops:
+        typer.echo(f"No trace found for: {trace_id}")
+        raise typer.Exit(1)
+    if fmt == "json":
+        typer.echo(json.dumps(trace_to_json_export(trace_id, hops), indent=2))
+    else:
+        typer.echo(diagram)
+
+
 def main() -> None:
     """Run the ASAP Protocol CLI."""
     app()

asap/errors.py

@@ -190,3 +190,170 @@ class ThreadPoolExhaustedError(ASAPError):
         )
         self.max_threads = max_threads
         self.active_threads = active_threads
+
+
+class InvalidTimestampError(ASAPError):
+    """Raised when an envelope timestamp is invalid (too old or too far in the future).
+
+    This error occurs when validating envelope timestamps for replay attack prevention.
+    Envelopes with timestamps outside the acceptable window are rejected.
+
+    Attributes:
+        timestamp: The invalid timestamp value
+        age_seconds: Age of the envelope in seconds (if too old)
+        future_offset_seconds: Offset in seconds from current time (if too far in future)
+    """
+
+    def __init__(
+        self,
+        timestamp: str,
+        message: str,
+        age_seconds: float | None = None,
+        future_offset_seconds: float | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize invalid timestamp error.
+
+        Args:
+            timestamp: The invalid timestamp value
+            message: Human-readable error description
+            age_seconds: Age of the envelope in seconds (if too old)
+            future_offset_seconds: Offset in seconds from current time (if too far in future)
+            details: Optional additional context
+        """
+        # Build details dict with optional fields
+        details_dict: dict[str, Any] = {"timestamp": timestamp}
+        if age_seconds is not None:
+            details_dict["age_seconds"] = age_seconds
+        if future_offset_seconds is not None:
+            details_dict["future_offset_seconds"] = future_offset_seconds
+        if details:
+            details_dict.update(details)
+
+        super().__init__(
+            code="asap:protocol/invalid_timestamp",
+            message=message,
+            details=details_dict,
+        )
+        self.timestamp = timestamp
+        self.age_seconds = age_seconds
+        self.future_offset_seconds = future_offset_seconds
+
+
+class InvalidNonceError(ASAPError):
+    """Raised when an envelope nonce is invalid (duplicate or malformed).
+
+    This error occurs when validating envelope nonces for replay attack prevention.
+    Nonces that have been used before within the TTL window are rejected.
+
+    Attributes:
+        nonce: The invalid nonce value
+    """
+
+    def __init__(
+        self,
+        nonce: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize invalid nonce error.
+
+        Args:
+            nonce: The invalid nonce value
+            message: Human-readable error description
+            details: Optional additional context
+        """
+        super().__init__(
+            code="asap:protocol/invalid_nonce",
+            message=message,
+            details={
+                "nonce": nonce,
+                **(details or {}),
+            },
+        )
+        self.nonce = nonce
+
+
+class CircuitOpenError(ASAPError):
+    """Raised when circuit breaker is open and request is rejected.
+
+    This error occurs when the circuit breaker pattern has detected
+    too many consecutive failures and is preventing further requests
+    to protect the system from cascading failures.
+
+    Attributes:
+        base_url: The URL for which the circuit is open
+        consecutive_failures: Number of consecutive failures that opened the circuit
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        consecutive_failures: int,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize circuit open error.
+
+        Args:
+            base_url: The URL for which the circuit is open
+            consecutive_failures: Number of consecutive failures
+            details: Optional additional context
+        """
+        message = (
+            f"Circuit breaker is OPEN for {base_url}. "
+            f"Too many consecutive failures ({consecutive_failures}). "
+            "Service temporarily unavailable."
+        )
+        super().__init__(
+            code="asap:transport/circuit_open",
+            message=message,
+            details={
+                "base_url": base_url,
+                "consecutive_failures": consecutive_failures,
+                **(details or {}),
+            },
+        )
+        self.base_url = base_url
+        self.consecutive_failures = consecutive_failures
+
+
+class UnsupportedAuthSchemeError(ASAPError):
+    """Raised when an unsupported authentication scheme is specified.
+
+    This error occurs when a Manifest specifies an authentication scheme
+    that is not supported by the current implementation.
+
+    Attributes:
+        scheme: The unsupported scheme name
+        supported_schemes: List of supported schemes
+    """
+
+    def __init__(
+        self,
+        scheme: str,
+        supported_schemes: set[str] | frozenset[str],
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize unsupported auth scheme error.
+
+        Args:
+            scheme: The unsupported scheme name
+            supported_schemes: Set of supported schemes
+            details: Optional additional context
+        """
+        supported_list = sorted(supported_schemes)
+        message = (
+            f"Unsupported authentication scheme '{scheme}'. "
+            f"Supported schemes: {', '.join(supported_list)}"
+        )
+        super().__init__(
+            code="asap:auth/unsupported_scheme",
+            message=message,
+            details={
+                "scheme": scheme,
+                "supported_schemes": list(supported_list),
+                **(details or {}),
+            },
+        )
+        self.scheme = scheme
+        self.supported_schemes = supported_schemes

asap/examples/README.md

@@ -1,25 +1,96 @@
+# ASAP Protocol Examples
+
+This directory contains real-world examples for the ASAP protocol: minimal agents, demos, and patterns you can reuse.
+
 ## Overview
 
-The examples demonstrate a minimal end-to-end flow between two agents:
-an echo agent and a coordinator agent.
+Examples cover:
+
+- **Core flow**: Echo agent, coordinator, and a full demo (run_demo).
+- **Advanced patterns**: Multi-agent orchestration, long-running tasks with checkpoints, error recovery, MCP integration, state migration, auth, rate limiting.
+- **Concepts**: WebSocket (not implemented), streaming responses, multi-step workflows.
 
-## Running the demo
+Run any example from the repository root with:
 
-Run the demo runner module from the repository root:
+```bash
+uv run python -m asap.examples.<module_name> [options]
+```
 
-- `uv run python -m asap.examples.run_demo`
+## Running the full demo
 
-This starts the echo agent on port 8001 and the coordinator agent on port 8000.
-The coordinator sends a TaskRequest to the echo agent and logs the response.
+Starts the echo agent on port 8001 and the coordinator on port 8000; the coordinator sends a TaskRequest to the echo agent and logs the response.
 
-## Running agents individually
+```bash
+uv run python -m asap.examples.run_demo
+```
 
-You can run the agents separately if needed:
+Run agents individually:
 
 - `uv run python -m asap.examples.echo_agent --host 127.0.0.1 --port 8001`
-- `uv run python -m asap.examples.coordinator`
+- `uv run python -m asap.examples.coordinator --echo-url http://127.0.0.1:8001`
+
+---
+
+## Examples by topic
+
+### Core agents and demo
+
+| Module | Description | Usage |
+|--------|-------------|--------|
+| **run_demo** | Full demo: echo + coordinator, one TaskRequest round-trip | `uv run python -m asap.examples.run_demo` |
+| **echo_agent** | Minimal echo agent (FastAPI app, manifest, echo handler) | `uv run python -m asap.examples.echo_agent [--host H] [--port P]` |
+| **coordinator** | Coordinator that dispatches TaskRequest to echo agent | `uv run python -m asap.examples.coordinator [--echo-url URL] [--message MSG]` |
+| **secure_handler** | Reference handler: TaskRequest validation, FilePart URI checks, sanitize_for_logging | Use `create_secure_handler()` in your handler registry (see `docs/security.md`) |
+
+### Multi-agent and orchestration
+
+| Module | Description | Usage |
+|--------|-------------|--------|
+| **orchestration** | Main agent delegates to 2 sub-agents; task coordination and state tracking | `uv run python -m asap.examples.orchestration [--worker-a-url URL] [--worker-b-url URL]` (start two echo agents on 8001 and 8002 first) |
+
+### State and long-running tasks
+
+| Module | Description | Usage |
+|--------|-------------|--------|
+| **long_running** | Long-running task with checkpoints (StateSnapshot); save, “crash”, resume | `uv run python -m asap.examples.long_running [--num-steps N] [--crash-after N]` |
+| **state_migration** | Move task state between agents (StateQuery, StateRestore, SnapshotStore) | `uv run python -m asap.examples.state_migration` |
+
+### Error recovery and resilience
+
+| Module | Description | Usage |
+|--------|-------------|--------|
+| **error_recovery** | Retry with backoff, circuit breaker, fallback patterns | `uv run python -m asap.examples.error_recovery [--skip-retry] [--skip-circuit] [--skip-fallback]` |
+
+### MCP and integration
+
+| Module | Description | Usage |
+|--------|-------------|--------|
+| **mcp_integration** | Call MCP tools via ASAP envelopes (McpToolCall, McpToolResult) | `uv run python -m asap.examples.mcp_integration [--agent-url URL]` (local build only if no URL) |
+
+### Authentication and rate limiting
+
+| Module | Description | Usage |
+|--------|-------------|--------|
+| **auth_patterns** | Bearer auth, custom token validators, OAuth2 concept (manifest + create_app) | `uv run python -m asap.examples.auth_patterns` |
+| **rate_limiting** | Per-sender and per-endpoint rate limit patterns (create_limiter, ASAP_RATE_LIMIT) | `uv run python -m asap.examples.rate_limiting` |
+
+### Concepts (no full implementation)
+
+| Module | Description | Usage |
+|--------|-------------|--------|
+| **websocket_concept** | How WebSocket would work with ASAP (comments/pseudocode only) | `uv run python -m asap.examples.websocket_concept` |
+
+### Streaming and workflows
+
+| Module | Description | Usage |
+|--------|-------------|--------|
+| **streaming_response** | Stream TaskUpdate progress chunks (simulated streaming) | `uv run python -m asap.examples.streaming_response [--chunks N]` |
+| **multi_step_workflow** | Multi-step pipeline: fetch → transform → summarize (WorkflowState, run_workflow) | `uv run python -m asap.examples.multi_step_workflow` |
+
+---
 
 ## Notes
 
 - The echo agent exposes `/.well-known/asap/manifest.json` for readiness checks.
 - Update ports in `asap.examples.run_demo` if you change the defaults.
+- Examples use the basic ASAP API; for production, add authentication via `manifest.auth` and follow `docs/security.md`.

asap/examples/auth_patterns.py

@@ -0,0 +1,212 @@
+"""Authentication patterns example for ASAP protocol.
+
+This module shows how to configure Bearer token auth, custom token validators,
+and the OAuth2 concept (obtain Bearer tokens via OAuth2; ASAP validates Bearer).
+
+Patterns:
+    1. Bearer: AuthScheme(schemes=["bearer"]) and token_validator for create_app.
+    2. Custom validators: Static map, env-based, or callable(token) -> agent_id | None.
+    3. OAuth2 concept: oauth2 dict in AuthScheme for discovery; clients get Bearer via OAuth2.
+
+Run:
+    uv run python -m asap.examples.auth_patterns
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Callable, Sequence
+
+from asap.models.entities import AuthScheme, Capability, Endpoint, Manifest, Skill
+from asap.models.constants import SUPPORTED_AUTH_SCHEMES
+from asap.observability import get_logger
+from asap.transport.middleware import BearerTokenValidator
+from asap.transport.server import create_app
+
+logger = get_logger(__name__)
+
+DEFAULT_ASAP_ENDPOINT = "http://localhost:8000/asap"
+DEFAULT_AGENT_ID = "urn:asap:agent:secured"
+
+
+def build_manifest_bearer_only(asap_endpoint: str = DEFAULT_ASAP_ENDPOINT) -> Manifest:
+    """Build a manifest that requires Bearer token authentication.
+
+    Use with create_app(manifest, token_validator=your_validator).
+    Only schemes in SUPPORTED_AUTH_SCHEMES are allowed (e.g. bearer, basic).
+
+    Args:
+        asap_endpoint: URL where the agent receives ASAP messages.
+
+    Returns:
+        Manifest with auth=AuthScheme(schemes=["bearer"]).
+    """
+    return Manifest(
+        id=DEFAULT_AGENT_ID,
+        name="Secured Agent",
+        version="0.1.0",
+        description="Agent with Bearer token authentication",
+        capabilities=Capability(
+            asap_version="0.1",
+            skills=[Skill(id="execute", description="Execute tasks")],
+            state_persistence=False,
+        ),
+        endpoints=Endpoint(asap=asap_endpoint),
+        auth=AuthScheme(schemes=["bearer"]),
+    )
+
+
+def build_manifest_oauth2_concept(asap_endpoint: str = DEFAULT_ASAP_ENDPOINT) -> Manifest:
+    """Build a manifest with Bearer + OAuth2 discovery (concept).
+
+    ASAP currently validates Bearer tokens only. The oauth2 dict describes
+    where clients obtain tokens (authorization_url, token_url, scopes).
+    Clients perform OAuth2 flow externally and send the access_token as Bearer.
+
+    Args:
+        asap_endpoint: URL where the agent receives ASAP messages.
+
+    Returns:
+        Manifest with auth=AuthScheme(schemes=["bearer"], oauth2={...}).
+    """
+    return Manifest(
+        id=DEFAULT_AGENT_ID,
+        name="OAuth2-Aware Agent",
+        version="0.1.0",
+        description="Agent with Bearer auth; clients get tokens via OAuth2",
+        capabilities=Capability(
+            asap_version="0.1",
+            skills=[Skill(id="execute", description="Execute tasks")],
+            state_persistence=False,
+        ),
+        endpoints=Endpoint(asap=asap_endpoint),
+        auth=AuthScheme(
+            schemes=["bearer"],
+            oauth2={
+                "authorization_url": "https://auth.example.com/authorize",  # nosec B105
+                "token_url": "https://auth.example.com/token",  # nosec B105
+                "scopes": ["asap:execute", "asap:read"],
+            },
+        ),
+    )
+
+
+def static_map_validator(token_to_agent: dict[str, str]) -> Callable[[str], str | None]:
+    """Build a token validator that maps known tokens to agent IDs.
+
+    Use for demos or small fixed sets. For production, use a secure store or JWT.
+
+    Args:
+        token_to_agent: Map from token string to agent URN.
+
+    Returns:
+        Callable(token) -> agent_id or None.
+    """
+
+    def validate(token: str) -> str | None:
+        return token_to_agent.get(token)
+
+    return validate
+
+
+def env_based_validator(
+    env_var: str = "ASAP_DEMO_TOKEN",
+    expected_agent_id: str = "urn:asap:agent:demo-client",
+) -> Callable[[str], str | None]:
+    """Build a token validator that accepts a token from an environment variable.
+
+    Use for testing; avoid in production (env vars can be inspected).
+
+    Args:
+        env_var: Environment variable holding the valid token.
+        expected_agent_id: Agent ID to return when token matches.
+
+    Returns:
+        Callable(token) -> agent_id or None.
+    """
+    expected_token = os.environ.get(env_var, "")
+
+    def validate(token: str) -> str | None:
+        if token and token == expected_token:
+            return expected_agent_id
+        return None
+
+    return validate
+
+
+def run_demo() -> None:
+    """Demonstrate auth patterns: Bearer manifest, custom validators, OAuth2 concept."""
+    # Bearer-only manifest
+    manifest_bearer = build_manifest_bearer_only()
+    logger.info(
+        "asap.auth_patterns.bearer_manifest",
+        schemes=manifest_bearer.auth.schemes if manifest_bearer.auth else [],
+    )
+
+    # Custom validator: static map
+    token_map = {
+        "demo-token-123": "urn:asap:agent:client-a",
+        "other-token": "urn:asap:agent:client-b",
+    }
+    validator_static = static_map_validator(token_map)
+    bearer_validator = BearerTokenValidator(validator_static)
+    agent_id = bearer_validator("demo-token-123")
+    logger.info(
+        "asap.auth_patterns.static_validator",
+        token_preview="demo-token-***",  # nosec B106
+        agent_id=agent_id,
+    )
+    assert agent_id == "urn:asap:agent:client-a"  # nosec B101
+    assert bearer_validator("invalid") is None  # nosec B101
+
+    # Custom validator: env-based (no env set -> invalid)
+    validator_env = env_based_validator(env_var="ASAP_DEMO_TOKEN")
+    assert validator_env("any") is None  # nosec B101
+    logger.info(
+        "asap.auth_patterns.env_validator",
+        message="Use ASAP_DEMO_TOKEN to test env-based validator",
+    )
+
+    # OAuth2 concept manifest (Bearer + oauth2 discovery)
+    manifest_oauth2 = build_manifest_oauth2_concept()
+    logger.info(
+        "asap.auth_patterns.oauth2_concept",
+        schemes=manifest_oauth2.auth.schemes if manifest_oauth2.auth else [],
+        oauth2_urls=(
+            list(manifest_oauth2.auth.oauth2.keys())
+            if manifest_oauth2.auth and manifest_oauth2.auth.oauth2
+            else []
+        ),
+    )
+
+    # Wire app with Bearer auth (no server started; just create_app)
+    app = create_app(
+        manifest_bearer,
+        token_validator=validator_static,
+    )
+    logger.info(
+        "asap.auth_patterns.app_created",
+        message="create_app(manifest, token_validator=...) enables Bearer auth",
+        supported_schemes=list(SUPPORTED_AUTH_SCHEMES),
+    )
+    # Reference app so it's not garbage-collected if someone holds the result
+    assert app is not None  # nosec B101
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the auth patterns demo."""
+    parser = argparse.ArgumentParser(
+        description="Authentication patterns: Bearer, custom validators, OAuth2 concept."
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the auth patterns demo."""
+    parse_args(argv)
+    run_demo()
+
+
+if __name__ == "__main__":
+    main()