agent-client-protocol 0.12.0__tar.gz → 1.0.0__tar.gz

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agent-client-protocol
-Version: 0.12.0
+Version: 1.0.0
 Summary: A Python implement of Agent Client Protocol (ACP, by Zed Industries)
 Keywords: python
 Author-Email: Chojan Shang <psiace@apache.org>, Frost Ming <me@frostming.com>
@@ -12,18 +12,21 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Project-URL: Homepage, https://agentclientprotocol.github.io/python-sdk/
 Project-URL: Repository, https://github.com/agentclientprotocol/python-sdk
 Project-URL: Documentation, https://agentclientprotocol.github.io/python-sdk/
-Requires-Python: <3.15,>=3.10
+Requires-Python: <3.16,>=3.10
 Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-core>=2.18.1
 Provides-Extra: logfire
 Requires-Dist: logfire>=0.14; extra == "logfire"
 Requires-Dist: opentelemetry-sdk>=1.28.0; extra == "logfire"
 Provides-Extra: http
-Requires-Dist: httpx[http2]>=0.27; extra == "http"
+Requires-Dist: httpx2[http2]>=2.12; extra == "http"
 Requires-Dist: websockets>=12.0; extra == "http"
+Requires-Dist: starlette>=0.49.3; extra == "http"
 Description-Content-Type: text/markdown
 
 <a href="https://agentclientprotocol.com/">
@@ -32,7 +35,7 @@ Description-Content-Type: text/markdown
 
 # Agent Client Protocol (Python)
 
-Build ACP-compliant agents and clients in Python with generated schema models, asyncio transports, helper builders, and runnable demos.
+Build ACP-compliant agents and clients in Python with generated schema models, asyncio transports, and runnable demos.
 
 > Releases track the upstream ACP schema; contributions that tighten coverage or tooling are always welcome.
 
@@ -47,14 +50,14 @@ uv add agent-client-protocol
 ## At a glance
 
 - **Spec parity:** Generated Pydantic models in `acp.schema` track every ACP release so payloads stay valid.
+- **Direct construction:** Generated discriminator fields have defaults, so models can be instantiated directly.
 - **Runtime ergonomics:** Async base classes, stdio JSON-RPC plumbing, and lifecycle helpers keep custom agents tiny.
 - **Examples ready:** Streaming, permissions, Gemini bridge, and duet demos live under `examples/`.
-- **Helper builders:** `acp.helpers` mirrors the Go/TS SDK APIs for content blocks, tool calls, and session updates.
 - **Contrib utilities:** Session accumulators, tool call trackers, and permission brokers share patterns from real deployments.
 
 ## Who benefits
 
-- Agent authors who need typed models, helper builders, and event-stream ergonomics for ACP-compatible assistants.
+- Agent authors who need typed models and event-stream ergonomics for ACP-compatible assistants.
 - Client integrators embedding ACP parties inside Python applications or wrapping existing CLIs via stdio.
 - Tooling teams experimenting with permission flows, streaming UX, or Gemini bridges without re-implementing transports.
 See real adopters like kimi-cli in the [Use Cases list](https://agentclientprotocol.github.io/python-sdk/use-cases/).
@@ -80,7 +83,7 @@ See real adopters like kimi-cli in the [Use Cases list](https://agentclientproto
 
 ## Project layout
 
-- `src/acp/`: runtime package (agents, clients, transports, helpers, schema bindings, contrib utilities)
+- `src/acp/`: runtime package (agents, clients, transports, schema bindings, contrib utilities)
 - `schema/`: upstream JSON schema sources (regenerate via `make gen-all`)
 - `docs/`: MkDocs content backing the published documentation
 - `examples/`: runnable scripts covering stdio orchestration patterns

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/README.md

@@ -4,7 +4,7 @@
 
 # Agent Client Protocol (Python)
 
-Build ACP-compliant agents and clients in Python with generated schema models, asyncio transports, helper builders, and runnable demos.
+Build ACP-compliant agents and clients in Python with generated schema models, asyncio transports, and runnable demos.
 
 > Releases track the upstream ACP schema; contributions that tighten coverage or tooling are always welcome.
 
@@ -19,14 +19,14 @@ uv add agent-client-protocol
 ## At a glance
 
 - **Spec parity:** Generated Pydantic models in `acp.schema` track every ACP release so payloads stay valid.
+- **Direct construction:** Generated discriminator fields have defaults, so models can be instantiated directly.
 - **Runtime ergonomics:** Async base classes, stdio JSON-RPC plumbing, and lifecycle helpers keep custom agents tiny.
 - **Examples ready:** Streaming, permissions, Gemini bridge, and duet demos live under `examples/`.
-- **Helper builders:** `acp.helpers` mirrors the Go/TS SDK APIs for content blocks, tool calls, and session updates.
 - **Contrib utilities:** Session accumulators, tool call trackers, and permission brokers share patterns from real deployments.
 
 ## Who benefits
 
-- Agent authors who need typed models, helper builders, and event-stream ergonomics for ACP-compatible assistants.
+- Agent authors who need typed models and event-stream ergonomics for ACP-compatible assistants.
 - Client integrators embedding ACP parties inside Python applications or wrapping existing CLIs via stdio.
 - Tooling teams experimenting with permission flows, streaming UX, or Gemini bridges without re-implementing transports.
 See real adopters like kimi-cli in the [Use Cases list](https://agentclientprotocol.github.io/python-sdk/use-cases/).
@@ -52,7 +52,7 @@ See real adopters like kimi-cli in the [Use Cases list](https://agentclientproto
 
 ## Project layout
 
-- `src/acp/`: runtime package (agents, clients, transports, helpers, schema bindings, contrib utilities)
+- `src/acp/`: runtime package (agents, clients, transports, schema bindings, contrib utilities)
 - `schema/`: upstream JSON schema sources (regenerate via `make gen-all`)
 - `docs/`: MkDocs content backing the published documentation
 - `examples/`: runnable scripts covering stdio orchestration patterns

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/examples/agent.py

@@ -12,8 +12,6 @@ from acp import (
     PromptResponse,
     SetSessionModeResponse,
     run_agent,
-    text_block,
-    update_agent_message,
 )
 from acp.interfaces import Client
 from acp.schema import (
@@ -43,7 +41,7 @@ class ExampleAgent(Agent):
         self._conn = conn
 
     async def _send_agent_message(self, session_id: str, content: Any) -> None:
-        update = content if isinstance(content, AgentMessageChunk) else update_agent_message(content)
+        update = content if isinstance(content, AgentMessageChunk) else AgentMessageChunk(content=content)
         await self._conn.session_update(session_id, update)
 
     async def initialize(
@@ -109,7 +107,7 @@ class ExampleAgent(Agent):
         if session_id not in self._sessions:
             self._sessions.add(session_id)
 
-        await self._send_agent_message(session_id, text_block("Client sent:"))
+        await self._send_agent_message(session_id, TextContentBlock(text="Client sent:"))
         for block in prompt:
             await self._send_agent_message(session_id, block)
         return PromptResponse(stop_reason="end_turn")

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/examples/client.py

@@ -12,7 +12,6 @@ from acp import (
     Client,
     RequestError,
     connect_to_agent,
-    text_block,
 )
 from acp.core import ClientSideConnection
 from acp.schema import (
@@ -170,7 +169,7 @@ async def interactive_loop(conn: ClientSideConnection, session_id: str) -> None:
         try:
             await conn.prompt(
                 session_id=session_id,
-                prompt=[text_block(line)],
+                prompt=[TextContentBlock(text=line)],
             )
         except Exception as exc:
             logging.error("Prompt failed: %s", exc)  # noqa: TRY400

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/examples/echo_agent.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10,<3.15"
+# requires-python = ">=3.10,<3.16"
 # dependencies = [
 #     "agent-client-protocol",
 # ]
@@ -14,11 +14,10 @@ from acp import (
     NewSessionResponse,
     PromptResponse,
     run_agent,
-    text_block,
-    update_agent_message,
 )
 from acp.interfaces import Client
 from acp.schema import (
+    AgentMessageChunk,
     AudioContentBlock,
     ClientCapabilities,
     EmbeddedResourceContentBlock,
@@ -70,7 +69,7 @@ class EchoAgent(Agent):
     ) -> PromptResponse:
         for block in prompt:
             text = block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "")
-            chunk = update_agent_message(text_block(text))
+            chunk = AgentMessageChunk(content=TextContentBlock(text=text))
             chunk.field_meta = {"echo": True}
             chunk.content.field_meta = {"echo": True}
 

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/examples/gemini.py

@@ -17,7 +17,6 @@ from acp import (
     Client,
     RequestError,
     connect_to_agent,
-    text_block,
 )
 from acp.core import ClientSideConnection
 from acp.schema import (
@@ -254,7 +253,7 @@ def _print_text_content(content: object) -> None:
 async def _send_prompt(conn: ClientSideConnection, session_id: str, prompt: str, timeout: float | None) -> None:
     request = conn.prompt(
         session_id=session_id,
-        prompt=[text_block(prompt)],
+        prompt=[TextContentBlock(text=prompt)],
     )
     if timeout is None:
         await request

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/examples/http_client.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10,<3.15"
+# requires-python = ">=3.10,<3.16"
 # dependencies = [
 #     "agent-client-protocol[http]",
 # ]
@@ -12,9 +12,10 @@ Start the server first (``uv run examples/http_server.py``), then run this.
 import asyncio
 from typing import Any
 
-from acp import connect_to_agent, text_block
+from acp import connect_to_agent
 from acp.http import create_http_stream
 from acp.interfaces import Client
+from acp.schema import TextContentBlock
 
 
 class ExampleClient(Client):
@@ -43,7 +44,7 @@ async def main() -> None:
         print(f"initialized (protocol v{init.protocol_version})")
         session = await conn.new_session(cwd=".", mcp_servers=[])
         print(f"session: {session.session_id}")
-        result = await conn.prompt(session_id=session.session_id, prompt=[text_block("hello over http")])
+        result = await conn.prompt(session_id=session.session_id, prompt=[TextContentBlock(text="hello over http")])
         print(f"stop reason: {result.stop_reason}")
     finally:
         await conn.close()

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/examples/http_server.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10,<3.15"
+# requires-python = ">=3.10,<3.16"
 # dependencies = [
 #     "agent-client-protocol[http]",
 #     "hypercorn>=0.17",
@@ -25,12 +25,10 @@ from acp import (
     InitializeResponse,
     NewSessionResponse,
     PromptResponse,
-    text_block,
-    update_agent_message,
 )
 from acp.http.asgi import create_asgi_app
 from acp.interfaces import Client
-from acp.schema import ClientCapabilities, Implementation
+from acp.schema import AgentMessageChunk, ClientCapabilities, Implementation, TextContentBlock
 
 
 class EchoAgent(Agent):
@@ -56,12 +54,12 @@ class EchoAgent(Agent):
             text = block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "")
             await self._conn.session_update(
                 session_id=session_id,
-                update=update_agent_message(text_block(f"echo: {text}")),
+                update=AgentMessageChunk(content=TextContentBlock(text=f"echo: {text}")),
             )
         return PromptResponse(stop_reason="end_turn")
 
 
-# One agent instance per connection.
+# A Starlette application with one agent instance per connection.
 app = create_asgi_app(lambda conn: EchoAgent())
 
 

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/examples/ws_client.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.10,<3.15"
+# requires-python = ">=3.10,<3.16"
 # dependencies = [
 #     "agent-client-protocol[http]",
 # ]
@@ -12,8 +12,9 @@ Start the server first (``uv run examples/http_server.py``), then run this.
 import asyncio
 from typing import Any
 
-from acp import connect_to_agent, text_block
+from acp import connect_to_agent
 from acp.interfaces import Client
+from acp.schema import TextContentBlock
 from acp.ws import create_websocket_stream
 
 
@@ -42,7 +43,9 @@ async def main() -> None:
         print(f"initialized (protocol v{init.protocol_version})")
         session = await conn.new_session(cwd=".", mcp_servers=[])
         print(f"session: {session.session_id}")
-        result = await conn.prompt(session_id=session.session_id, prompt=[text_block("hello over websocket")])
+        result = await conn.prompt(
+            session_id=session.session_id, prompt=[TextContentBlock(text="hello over websocket")]
+        )
         print(f"stop reason: {result.stop_reason}")
     finally:
         await conn.close()

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-client-protocol"
-version = "0.12.0"
+version = "1.0.0"
 description = "A Python implement of Agent Client Protocol (ACP, by Zed Industries)"
 authors = [
     { name = "Chojan Shang", email = "psiace@apache.org" },
@@ -10,7 +10,7 @@ readme = "README.md"
 keywords = [
     "python",
 ]
-requires-python = ">=3.10,<3.15"
+requires-python = ">=3.10,<3.16"
 classifiers = [
     "Intended Audience :: Developers",
     "Programming Language :: Python",
@@ -20,10 +20,12 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
     "pydantic>=2.7",
+    "pydantic-core>=2.18.1",
 ]
 
 [project.urls]
@@ -37,13 +39,14 @@ logfire = [
     "opentelemetry-sdk>=1.28.0",
 ]
 http = [
-    "httpx[http2]>=0.27",
+    "httpx2[http2]>=2.12",
     "websockets>=12.0",
+    "starlette>=0.49.3",
 ]
 
 [dependency-groups]
 dev = [
-    "datamodel-code-generator>=0.25",
+    "datamodel-code-generator==0.81.0",
     "pytest>=7.2.0",
     "pytest-asyncio>=0.21.0",
     "tox-uv>=1.11.3",
@@ -55,9 +58,10 @@ dev = [
     "mkdocstrings[python]>=0.26.1",
     "python-dotenv>=1.1.1",
     "prek>=0.2.17",
-    "httpx[http2]>=0.27",
+    "httpx2[http2]>=2.12",
     "websockets>=12.0",
     "uvicorn>=0.30",
+    "starlette>=0.49.3",
 ]
 
 [build-system]
@@ -122,6 +126,12 @@ ignore = [
 "src/acp/schema.py" = [
     "ALL",
 ]
+"src/acp/experimental/v2/meta.py" = [
+    "ALL",
+]
+"src/acp/experimental/v2/schema.py" = [
+    "ALL",
+]
 
 [tool.ruff.format]
 preview = true

agent_client_protocol-1.0.0/scripts/_schema_semantics.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib import import_module
+from pathlib import Path
+from typing import Protocol, cast
+
+ROOT = Path(__file__).resolve().parents[1]
+
+DEFAULT_PROTOCOL_VERSION = 1
+SEMANTIC_MODULES = {
+    1: "scripts.gen_schema_v1",
+    2: "scripts.gen_schema_v2",
+}
+SUPPORTED_PROTOCOL_VERSIONS = tuple(SEMANTIC_MODULES)
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaSemantics:
+    schema_json: Path
+    version_file: Path
+    schema_out: Path
+    base_class: str
+    model_name_map: dict[str, str]
+    compatibility_aliases: str = ""
+    field_type_overrides: dict[str, str] = field(default_factory=dict)
+
+
+class _SemanticsModule(Protocol):
+    SEMANTICS: SchemaSemantics
+
+
+def get_schema_semantics(protocol_version: int) -> SchemaSemantics:
+    try:
+        module_name = SEMANTIC_MODULES[protocol_version]
+    except KeyError:
+        raise ValueError(f"Unsupported protocol version: {protocol_version}") from None
+    module = cast(_SemanticsModule, import_module(module_name))
+    return module.SEMANTICS
+
+
+def inline_model_ref(definition: str, *steps: tuple[str, int | None]) -> str:
+    ref = f"#/$defs/{definition}"
+    for keyword, index in steps:
+        ref += f"#-datamodel-code-generator-#-{keyword}-#-special-#"
+        if index is not None:
+            ref += f"/{index}"
+    return ref
+
+
+def variant_model_map(
+    definition: str,
+    keyword: str,
+    branch: str,
+    names: tuple[str, ...],
+) -> dict[str, str]:
+    return {inline_model_ref(definition, (keyword, index), (branch, None)): name for index, name in enumerate(names)}

{agent_client_protocol-0.12.0 → agent_client_protocol-1.0.0}/scripts/gen_all.py

@@ -18,13 +18,11 @@ if str(ROOT) not in sys.path:
 from scripts import gen_meta, gen_schema, gen_signature  # noqa: E402  pylint: disable=wrong-import-position
 
 SCHEMA_DIR = ROOT / "schema"
-SCHEMA_JSON = SCHEMA_DIR / "schema.json"
-META_JSON = SCHEMA_DIR / "meta.json"
-VERSION_FILE = SCHEMA_DIR / "VERSION"
 
 DEFAULT_REPO = "agentclientprotocol/agent-client-protocol"
 LEGACY_SCHEMA_PATHS = ("schema/schema.unstable.json", "schema/meta.unstable.json")
 V1_SCHEMA_PATHS = ("schema/v1/schema.unstable.json", "schema/v1/meta.unstable.json")
+V2_SCHEMA_PATHS = ("schema/v2/schema.unstable.json", "schema/v2/meta.unstable.json")
 
 
 def parse_args() -> argparse.Namespace:
@@ -42,6 +40,13 @@ def parse_args() -> argparse.Namespace:
         default=os.environ.get("ACP_SCHEMA_REPO", DEFAULT_REPO),
         help="Source repository providing schema.json/meta.json (default: %(default)s)",
     )
+    parser.add_argument(
+        "--protocol-version",
+        type=int,
+        choices=(1, 2),
+        default=int(os.environ.get("ACP_SCHEMA_PROTOCOL", "1")),
+        help="Protocol bindings to generate (default: %(default)s)",
+    )
     parser.add_argument(
         "--no-download",
         action="store_true",
@@ -67,23 +72,32 @@ def main() -> None:
 
     version = args.version or os.environ.get("ACP_SCHEMA_VERSION")
     repo = args.repo
-    should_download = _should_download(args, version)
+    protocol_version = args.protocol_version
+    schema_dir = _schema_dir(protocol_version)
+    schema_json = schema_dir / "schema.json"
+    meta_json = schema_dir / "meta.json"
+    should_download = _should_download(args, version, protocol_version)
 
     if should_download:
         ref = resolve_ref(version)
-        download_schema(repo, ref)
+        download_schema(repo, ref, protocol_version)
     else:
-        ref = resolve_ref(version) if version else _cached_ref()
+        ref = resolve_ref(version) if version else _cached_ref(protocol_version)
 
-    if not (SCHEMA_JSON.exists() and META_JSON.exists()):
-        print("schema/schema.json or schema/meta.json missing; run with --version to fetch them.", file=sys.stderr)
+    if not (schema_json.exists() and meta_json.exists()):
+        print(
+            f"{schema_dir.relative_to(ROOT)} is missing schema.json or meta.json; run with --version.", file=sys.stderr
+        )
         sys.exit(1)
 
-    gen_schema.generate_schema()
-    gen_meta.generate_meta()
-    gen_signature.gen_signature(ROOT / "src" / "acp")
+    gen_schema.generate_schema(protocol_version=protocol_version)
+    gen_meta.generate_meta(protocol_version=protocol_version)
+    if protocol_version == 1:
+        gen_signature.gen_signature(ROOT / "src" / "acp")
+    else:
+        gen_signature.gen_signature(ROOT / "src" / "acp" / "experimental" / "v2", protocol_version=2)
     if args.format_output:
-        format_generated_files()
+        format_generated_files(protocol_version)
 
     if ref:
         print(f"Generated schema using ref: {ref}")
@@ -91,32 +105,44 @@ def main() -> None:
         print("Generated schema using local schema files")
 
 
-def format_generated_files() -> None:
-    files = [
-        ROOT / "src" / "acp" / "schema.py",
-        ROOT / "src" / "acp" / "meta.py",
-        ROOT / "src" / "acp" / "interfaces.py",
-        ROOT / "src" / "acp" / "agent" / "connection.py",
-        ROOT / "src" / "acp" / "client" / "connection.py",
-    ]
+def format_generated_files(protocol_version: int) -> None:
+    if protocol_version == 1:
+        files = [
+            ROOT / "src" / "acp" / "schema.py",
+            ROOT / "src" / "acp" / "meta.py",
+            ROOT / "src" / "acp" / "interfaces.py",
+            ROOT / "src" / "acp" / "agent" / "connection.py",
+            ROOT / "src" / "acp" / "client" / "connection.py",
+        ]
+    else:
+        files = [
+            ROOT / "src" / "acp" / "experimental" / "v2" / "schema.py",
+            ROOT / "src" / "acp" / "experimental" / "v2" / "meta.py",
+            ROOT / "src" / "acp" / "experimental" / "v2" / "interfaces.py",
+            ROOT / "src" / "acp" / "experimental" / "v2" / "agent.py",
+            ROOT / "src" / "acp" / "experimental" / "v2" / "client.py",
+        ]
     subprocess.check_call([sys.executable, "-m", "ruff", "check", "--fix", *(str(path) for path in files)])  # noqa: S603
     subprocess.check_call([sys.executable, "-m", "ruff", "format", *(str(path) for path in files)])  # noqa: S603
 
 
-def _should_download(args: argparse.Namespace, version: str | None) -> bool:
+def _should_download(args: argparse.Namespace, version: str | None, protocol_version: int) -> bool:
+    schema_dir = _schema_dir(protocol_version)
+    schema_json = schema_dir / "schema.json"
+    meta_json = schema_dir / "meta.json"
     env_override = os.environ.get("ACP_SCHEMA_DOWNLOAD")
     if env_override is not None:
         return env_override.lower() in {"1", "true", "yes"}
     if args.no_download:
         return False
     if version:
-        if not SCHEMA_JSON.exists() or not META_JSON.exists():
+        if not schema_json.exists() or not meta_json.exists():
             return True
-        cached = _cached_ref()
+        cached = _cached_ref(protocol_version)
         if args.force:
             return True
         return cached != resolve_ref(version)
-    return not (SCHEMA_JSON.exists() and META_JSON.exists())
+    return not (schema_json.exists() and meta_json.exists())
 
 
 def resolve_ref(version: str | None) -> str:
@@ -124,31 +150,35 @@ def resolve_ref(version: str | None) -> str:
         return "refs/heads/main"
     if version.startswith("refs/"):
         return version
-    if re.fullmatch(r"schema-v\d+\.\d+\.\d+", version):
+    if re.fullmatch(r"schema-v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", version):
         return f"refs/tags/{version}"
-    if re.fullmatch(r"v?\d+\.\d+\.\d+", version):
+    if re.fullmatch(r"v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", version):
         value = version if version.startswith("v") else f"v{version}"
         return f"refs/tags/{value}"
     return f"refs/heads/{version}"
 
 
-def download_schema(repo: str, ref: str) -> None:
-    SCHEMA_DIR.mkdir(parents=True, exist_ok=True)
+def download_schema(repo: str, ref: str, protocol_version: int = 1) -> None:
+    schema_dir = _schema_dir(protocol_version)
+    schema_json = schema_dir / "schema.json"
+    meta_json = schema_dir / "meta.json"
+    version_file = schema_dir / "VERSION"
+    schema_dir.mkdir(parents=True, exist_ok=True)
     try:
-        schema_data, meta_data = fetch_schema_pair(repo, ref)
+        schema_data, meta_data = fetch_schema_pair(repo, ref, protocol_version)
     except RuntimeError as exc:  # pragma: no cover - network error path
         print(exc, file=sys.stderr)
         sys.exit(1)
 
-    SCHEMA_JSON.write_text(json.dumps(schema_data, indent=2) + "\n", encoding="utf-8")
-    META_JSON.write_text(json.dumps(meta_data, indent=2) + "\n", encoding="utf-8")
-    VERSION_FILE.write_text(ref + "\n", encoding="utf-8")
+    schema_json.write_text(json.dumps(schema_data, indent=2) + "\n", encoding="utf-8")
+    meta_json.write_text(json.dumps(meta_data, indent=2) + "\n", encoding="utf-8")
+    version_file.write_text(ref + "\n", encoding="utf-8")
     print(f"Fetched schema and meta from {repo}@{ref}")
 
 
-def fetch_schema_pair(repo: str, ref: str) -> tuple[dict, dict]:
+def fetch_schema_pair(repo: str, ref: str, protocol_version: int = 1) -> tuple[dict, dict]:
     errors = []
-    for schema_path, meta_path in schema_source_paths(ref):
+    for schema_path, meta_path in schema_source_paths(ref, protocol_version):
         schema_url = f"https://raw.githubusercontent.com/{repo}/{ref}/{schema_path}"
         meta_url = f"https://raw.githubusercontent.com/{repo}/{ref}/{meta_path}"
         try:
@@ -160,8 +190,10 @@ def fetch_schema_pair(repo: str, ref: str) -> tuple[dict, dict]:
     raise RuntimeError(f"Failed to fetch schema and meta from {repo}@{ref}. Attempts:\n{attempted}")
 
 
-def schema_source_paths(ref: str) -> tuple[tuple[str, str], ...]:
-    if re.fullmatch(r"refs/tags/schema-v\d+\.\d+\.\d+", ref):
+def schema_source_paths(ref: str, protocol_version: int = 1) -> tuple[tuple[str, str], ...]:
+    if protocol_version == 2:
+        return (V2_SCHEMA_PATHS,)
+    if re.fullmatch(r"refs/tags/schema-v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", ref):
         return (V1_SCHEMA_PATHS, LEGACY_SCHEMA_PATHS)
     return (LEGACY_SCHEMA_PATHS, V1_SCHEMA_PATHS)
 
@@ -174,9 +206,18 @@ def fetch_json(url: str) -> dict:
         raise RuntimeError(f"Failed to fetch {url}: {exc}") from exc
 
 
-def _cached_ref() -> str | None:
-    if VERSION_FILE.exists():
-        return VERSION_FILE.read_text(encoding="utf-8").strip() or None
+def _schema_dir(protocol_version: int) -> Path:
+    if protocol_version == 1:
+        return SCHEMA_DIR
+    if protocol_version == 2:
+        return SCHEMA_DIR / "v2"
+    raise ValueError(f"Unsupported protocol version: {protocol_version}")
+
+
+def _cached_ref(protocol_version: int) -> str | None:
+    version_file = _schema_dir(protocol_version) / "VERSION"
+    if version_file.exists():
+        return version_file.read_text(encoding="utf-8").strip() or None
     return None