feat(server): implement Resource Scoping for tasks and push notifications

.github/actions/spelling/allow.txt

@@ -92,6 +92,7 @@ openapiv2
 opensource
 otherurl
 pb2
+poolclass
 postgres
 POSTGRES
 postgresql

pyproject.toml

@@ -106,6 +106,7 @@ style = "pep440"
 
 [dependency-groups]
 dev = [
+  "alembic>=1.14.0",
   "mypy>=1.15.0",
   "PyJWT>=2.0.0",
   "pytest>=8.3.5",
@@ -347,3 +348,17 @@ docstring-code-format = true
 docstring-code-line-length = "dynamic"
 quote-style = "single"
 indent-style = "space"
+
+
+[tool.alembic]
+
+# path to migration scripts.
+script_location = "src/a2a/migrations"
+
+# additional paths to be prepended to sys.path. defaults to the current working directory.
+prepend_sys_path = [
+    "src"
+]
+
+[project.scripts]
+a2a-db = "a2a.cli:run_migrations"

src/a2a/alembic.ini

@@ -0,0 +1,35 @@
+# A generic, single database configuration.
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

src/a2a/cli.py

@@ -0,0 +1,148 @@
+import argparse
+import os
+
+from importlib.resources import files
+
+from alembic import command
+from alembic.config import Config
+
+
+def run_migrations() -> None:
+    """CLI tool to manage database migrations."""
+    parser = argparse.ArgumentParser(description='A2A Database Migration Tool')
+
+    # Global options
+    parser.add_argument(
+        '-o',
+        '--owner',
+        help="Value for the 'owner' column (used in specific migrations). If not set defaults to 'unknown'",
+    )
+    parser.add_argument(
+        '-u',
+        '--database-url',
+        help='Database URL to use for the migrations. If not set, the DATABASE_URL environment variable will be used.',
+    )
+    parser.add_argument(
+        '-t',
+        '--table',
+        help="Specific table to update. If not set, both 'tasks' and 'push_notification_configs' are updated.",
+        action='append',
+    )
+    parser.add_argument(
+        '-v',
+        '--verbose',
+        help='Enable verbose output (sets sqlalchemy.engine logging to INFO)',
+        action='store_true',
+    )
+
+    subparsers = parser.add_subparsers(dest='cmd', help='Migration command')
+
+    # Upgrade command
+    up_parser = subparsers.add_parser(
+        'upgrade', help='Upgrade to a later version'
+    )
+    up_parser.add_argument(
+        'revision',
+        nargs='?',
+        default='head',
+        help='Revision target (default: head)',
+    )
+    up_parser.add_argument(
+        '-o', '--owner', dest='sub_owner', help='Alias for top-level --owner'
+    )
+    up_parser.add_argument(
+        '-u',
+        '--database-url',
+        dest='sub_database_url',
+        help='Alias for top-level --database-url',
+    )
+    up_parser.add_argument(
+        '-t',
+        '--table',
+        dest='sub_table',
+        help='Alias for top-level --table',
+        action='append',
+    )
+    up_parser.add_argument(
+        '-v',
+        '--verbose',
+        dest='sub_verbose',
+        help='Enable verbose output (sets sqlalchemy.engine logging to INFO)',
+        action='store_true',
+    )
+
+    # Downgrade command
+    down_parser = subparsers.add_parser(
+        'downgrade', help='Revert to a previous version'
+    )
+    down_parser.add_argument(
+        'revision',
+        nargs='?',
+        default='base',
+        help='Revision target (e.g., -1, base or a specific ID)',
+    )
+    down_parser.add_argument(
+        '-u',
+        '--database-url',
+        dest='sub_database_url',
+        help='Alias for top-level --database-url',
+    )
+    down_parser.add_argument(
+        '-t',
+        '--table',
+        dest='sub_table',
+        help='Alias for top-level --table',
+        action='append',
+    )
+    down_parser.add_argument(
+        '-v',
+        '--verbose',
+        dest='sub_verbose',
+        help='Enable verbose output (sets sqlalchemy.engine logging to INFO)',
+        action='store_true',
+    )
+
+    args = parser.parse_args()
+
+    # Default to upgrade head if no command is provided
+    if not args.cmd:
+        args.cmd = 'upgrade'
+        args.revision = 'head'
+
+    # Locate the bundled alembic.ini
+    ini_path = files('a2a').joinpath('alembic.ini')
+    cfg = Config(str(ini_path))
+
+    # Dynamically set the script location
+    migrations_path = files('a2a').joinpath('migrations')
+    cfg.set_main_option('script_location', str(migrations_path))
+
+    # Consolidate owner, db_url, tables and verbose values
+    owner = args.owner or getattr(args, 'sub_owner', None)
+    db_url = args.database_url or getattr(args, 'sub_database_url', None)
+    tables = args.table or getattr(args, 'sub_table', None)
+    verbose = args.verbose or getattr(args, 'sub_verbose', False)
+
+    # Pass custom arguments to the migration context
+    if owner:
+        if args.cmd == 'downgrade':
+            parser.error(
+                "The --owner option is not supported for the 'downgrade' command."
+            )
+        cfg.set_main_option('owner', owner)
+    if db_url:
+        os.environ['DATABASE_URL'] = db_url
+    if tables:
+        cfg.set_main_option('tables', ','.join(tables))
+    if verbose:
+        cfg.set_main_option('verbose', 'true')
+
+    # Execute the requested command
+    if args.cmd == 'upgrade':
+        print(f'Upgrading database to {args.revision}...')
+        command.upgrade(cfg, args.revision)
+    elif args.cmd == 'downgrade':
+        print(f'Downgrading database to {args.revision}...')
+        command.downgrade(cfg, args.revision)
+
+    print('Done.')

src/a2a/migrations/README.md

@@ -0,0 +1,88 @@
+# A2A SDK Database Migrations
+
+This directory handles the database schema updates for the A2A SDK. It uses a bundled CLI tool to simplify the migration process for both users and developers of the SDK.
+
+## User Guide (For Integrators)
+
+When you install the `a2a-sdk`, you get a built-in command `a2a-db` which updates tables 'tasks' and 'push_notification_configs' in your database to make it compatible with the latest version of the SDK.
+
+### 1. Recommended: Backup your database
+
+Before running migrations, it is recommended to backup your database.
+
+### 2. Set your Database URL
+Migrations require the `DATABASE_URL` environment variable to be set with an **async-compatible** driver or you can use the `-u` flag to specify the database URL for a single command.
+
+```bash
+# SQLite example
+export DATABASE_URL="sqlite+aiosqlite://user:pass@host:port/your_database_name"
+
+# PostgreSQL example
+export DATABASE_URL="postgresql+asyncpg://user:pass@localhost/your_database_name"
+
+# MySQL example
+export DATABASE_URL="mysql+aiomysql://user:pass@localhost/your_database_name"
+```
+
+### 3. Apply Migrations
+Always run this command after installing or upgrading the SDK to ensure your database matches the required schema.
+
+```bash
+# Bring the database to the latest version
+a2a-db
+```
+
+### 4. Customizing Defaults
+Add owner to tasks migration allows you to pass custom values for the new `owner` column. For example, to set a specific default owner for existing tasks:
+
+```bash
+a2a-db -o "admin_user"
+```
+
+### 5. Rolling Back
+If you need to revert a change:
+
+```bash
+# Step back one version
+a2a-db downgrade -1
+```
+
+```bash
+# Downgrade to a specific revision ID
+a2a-db downgrade <revision_id>
+```
+
+```bash
+# Revert all migrations
+a2a-db downgrade base
+```
+
+---
+
+## Developer Guide (For SDK Contributors)
+
+If you are modifying the SDK models and need to generate new migration files, use the following workflow.
+
+### Creating a New Migration
+Developers should use the raw `alembic` command locally to generate migrations. Ensure you are in the project root.
+
+```bash
+# Detect changes in models.py and generate a script
+uv run alembic revision --autogenerate -m "describe your changes"
+```
+
+### Internal Layout
+- `env.py`: Configures the migration engine and applies the mandatory `DATABASE_URL` check.
+- `versions/`: Contains the migration history.
+- `script.py.mako`: The template for all new migration files.
+
+## Troubleshooting
+
+### "Duplicate column name"
+If your database already has the required tables (e.g., created via `Base.metadata.create_all()` in a legacy script), you may need to "stamp" the database to tell the SDK that it is already up to date:
+
+```bash
+# Stamp the database without running SQL commands
+# (Requires raw alembic command for developer use)
+uv run alembic stamp head
+```

src/a2a/migrations/__init__.py

@@ -0,0 +1 @@
+"Alembic database migration package."