feat: Add cursor-based pagination to artifacts and delivery tools

[bokelley]

Summary

Implement cursor-based pagination for get_media_buy_artifacts and offset-based pagination for get_creative_delivery. Currently these tools return all results without pagination support.

AdCP version: v3.0.0-beta.3 (adcp library 3.3.0)

Pagination Patterns in AdCP v3

Cursor-Based (get_media_buy_artifacts)

class Pagination(AdCPBaseModel):
    cursor: str | None      # Opaque cursor from previous response
    max_results: int = 1000 # 1-10,000

# Response includes:
class PaginationResponse(AdCPBaseModel):
    next_cursor: str | None  # None when no more results
    total_results: int | None

Cursor-based is better for large, changing datasets (artifacts accumulate over time).

Offset-Based (get_creative_delivery)

# Request
class Pagination(AdCPBaseModel):
    limit: int = 50   # 1-100
    offset: int = 0   # Skip count

# Response
class Pagination(AdCPBaseModel):
    has_more: bool
    limit: int
    offset: int
    total: int | None

Implementation Plan

1. Cursor-Based Pagination (Artifacts)

Generate opaque cursors that encode position:

• Timestamp + ID: Cursor = base64-encoded timestamp + artifact ID for stable pagination across changing data

import base64
import json

def encode_cursor(timestamp: str, artifact_id: str) -> str:
    return base64.urlsafe_b64encode(
        json.dumps({"ts": timestamp, "id": artifact_id}).encode()
    ).decode()

def decode_cursor(cursor: str) -> dict:
    return json.loads(base64.urlsafe_b64decode(cursor))

2. Offset-Based Pagination (Creative Delivery)

Apply LIMIT/OFFSET to the creative query and return has_more and total.

3. Update existing tools

get_media_buy_artifacts (#1001) should include pagination from the start. get_creative_delivery should include offset pagination.

Files to Modify

File	Change
src/core/tools/media_buy_artifacts.py	Add cursor pagination to artifacts tool
src/core/tools/creative_delivery.py	Add offset pagination to creative delivery
src/core/utils/pagination.py	New: shared cursor encode/decode utilities
tests/unit/test_pagination.py	Pagination utility tests

Testing

Test cases:

• First page returns next_cursor when more results exist
• Passing cursor returns next page
• Last page has next_cursor=None
• max_results limits page size
• Invalid cursor returns error
• Offset pagination: has_more=True when more results
• Offset pagination: total count accurate

[KonstantinMirin]

This feature requires the PaginationRequest and PaginationResponse types available in adcp 3.3.0. Prerequisite: #1043 (adcp 3.3.0 upgrade).