feat: better gen scripts and rename map for better dev

Signed-off-by: Chojan Shang <chojan.shang@vesoft.com>

Author: Chojan Shang

AGENTS.md

@@ -4,7 +4,7 @@
 The package code lives under `src/acp`, exposing the high-level Agent, transport helpers, and generated protocol schema. Generated artifacts such as `schema/` and `src/acp/schema.py` are refreshed via `scripts/gen_all.py` against the upstream ACP schema. Integration examples are in `examples/`, including `echo_agent.py` and the mini SWE bridge. Tests reside in `tests/` with async fixtures and doctests; documentation sources live in `docs/` and publish via MkDocs. Built distributions drop into `dist/` after builds.
 
 ## Build, Test, and Development Commands
-Run `make install` to create a `uv` managed virtualenv and install pre-commit hooks. `make check` executes lock verification, Ruff linting, `ty` static checks, and deptry analysis. `make test` calls `uv run python -m pytest --doctest-modules`. For release prep use `make build` or `make build-and-publish`. `make gen-all` regenerates protocol models; use this before committing schema updates. `make docs` serves MkDocs locally; `make docs-test` ensures clean builds.
+Run `make install` to create a `uv` managed virtualenv and install pre-commit hooks. `make check` executes lock verification, Ruff linting, `ty` static checks, and deptry analysis. `make test` calls `uv run python -m pytest --doctest-modules`. For release prep use `make build` or `make build-and-publish`. `make gen-all` regenerates protocol models; export `ACP_SCHEMA_VERSION=<ref>` beforehand to fetch a specific upstream schema (defaults to the cached copy). `make docs` serves MkDocs locally; `make docs-test` ensures clean builds.
 
 ## Coding Style & Naming Conventions
 Target Python 3.10+ with type hints and 120-character lines enforced by Ruff (`pyproject.toml`). Prefer dataclasses/pydantic models from the schema modules rather than bare dicts. Tests may ignore security lint (see per-file ignores) but still follow snake_case names. Keep public API modules under `acp/*` lean; place utilities in internal `_`-prefixed modules when needed.

README.md

@@ -19,6 +19,7 @@ uv add agent-client-protocol
 
 ```bash
 make install   # set up venv
+ACP_SCHEMA_VERSION=<ref> make gen-all   # generate meta.py & schema.py
 make check     # lint + typecheck
 make test      # run tests
 ```
@@ -42,7 +43,7 @@ from acp import (
     SessionNotification,
     stdio_streams,
 )
-from acp.schema import ContentBlock1, SessionUpdate2
+from acp.schema import TextContentBlock, AgentMessageChunk
 
 
 class EchoAgent(Agent):
@@ -61,9 +62,9 @@ class EchoAgent(Agent):
             await self._conn.sessionUpdate(
                 SessionNotification(
                     sessionId=params.sessionId,
-                    update=SessionUpdate2(
+                    update=AgentMessageChunk(
                         sessionUpdate="agent_message_chunk",
-                        content=ContentBlock1(type="text", text=text),
+                        content=TextContentBlock(type="text", text=text),
                     ),
                 )
             )

schema/VERSION

@@ -0,0 +1 @@
+refs/tags/v0.4.5

scripts/__init__.py

@@ -0,0 +1 @@
+"""Utility scripts for generating ACP bindings."""

scripts/gen_all.py

@@ -1,15 +1,152 @@
 #!/usr/bin/env python3
 from __future__ import annotations
 
-import runpy
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
 from pathlib import Path
 
-SCRIPTS = Path(__file__).resolve().parent
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.append(str(ROOT))
+
+from scripts import gen_meta, gen_schema  # 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 = "zed-industries/agent-client-protocol"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Regenerate schema.py and meta.py from the ACP schema.")
+    parser.add_argument(
+        "--version",
+        "-v",
+        help=(
+            "Git ref (tag/branch) of zed-industries/agent-client-protocol to fetch the schema from. "
+            "If omitted, uses the cached schema files or falls back to 'main' when missing."
+        ),
+    )
+    parser.add_argument(
+        "--repo",
+        default=os.environ.get("ACP_SCHEMA_REPO", DEFAULT_REPO),
+        help="Source repository providing schema.json/meta.json (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--no-download",
+        action="store_true",
+        help="Skip downloading schema files even when a version is provided.",
+    )
+    parser.add_argument(
+        "--format",
+        dest="format_output",
+        action="store_true",
+        help="Format generated files with 'uv run ruff format'.",
+    )
+    parser.add_argument(
+        "--no-format",
+        dest="format_output",
+        action="store_false",
+        help="Disable formatting with ruff.",
+    )
+    parser.set_defaults(format_output=True)
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force schema download even if the requested ref is already cached locally.",
+    )
+    return parser.parse_args()
 
 
 def main() -> None:
-    runpy.run_path(str(SCRIPTS / "gen_schema.py"), run_name="__main__")
-    runpy.run_path(str(SCRIPTS / "gen_meta.py"), run_name="__main__")
+    args = parse_args()
+
+    version = args.version or os.environ.get("ACP_SCHEMA_VERSION")
+    repo = args.repo
+    should_download = _should_download(args, version)
+
+    if should_download:
+        ref = resolve_ref(version)
+        download_schema(repo, ref)
+    else:
+        ref = resolve_ref(version) if version else _cached_ref()
+
+    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)
+        sys.exit(1)
+
+    gen_schema.generate_schema(format_output=args.format_output)
+    gen_meta.generate_meta()
+
+    if ref:
+        print(f"Generated schema using ref: {ref}")
+    else:
+        print("Generated schema using local schema files")
+
+
+def _should_download(args: argparse.Namespace, version: str | None) -> bool:
+    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():
+            return True
+        cached = _cached_ref()
+        if args.force:
+            return True
+        return cached != resolve_ref(version)
+    return not (SCHEMA_JSON.exists() and META_JSON.exists())
+
+
+def resolve_ref(version: str | None) -> str:
+    if not version:
+        return "refs/heads/main"
+    if version.startswith("refs/"):
+        return version
+    if re.fullmatch(r"v?\d+\.\d+\.\d+", 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)
+    schema_url = f"https://raw.githubusercontent.com/{repo}/{ref}/schema/schema.json"
+    meta_url = f"https://raw.githubusercontent.com/{repo}/{ref}/schema/meta.json"
+    try:
+        schema_data = fetch_json(schema_url)
+        meta_data = fetch_json(meta_url)
+    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), encoding="utf-8")
+    META_JSON.write_text(json.dumps(meta_data, indent=2), encoding="utf-8")
+    VERSION_FILE.write_text(ref + "\n", encoding="utf-8")
+    print(f"Fetched schema and meta from {repo}@{ref}")
+
+
+def fetch_json(url: str) -> dict:
+    try:
+        with urllib.request.urlopen(url) as response:  # noqa: S310 - trusted source configured by repo
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Failed to fetch {url}: {exc}") from exc  # noqa: TRY003
+
+
+def _cached_ref() -> str | None:
+    if VERSION_FILE.exists():
+        return VERSION_FILE.read_text(encoding="utf-8").strip() or None
+    return None
 
 
 if __name__ == "__main__":

scripts/gen_meta.py

@@ -4,21 +4,38 @@
 import json
 from pathlib import Path
 
-ROOT = Path.cwd()
+ROOT = Path(__file__).resolve().parents[1]
+SCHEMA_DIR = ROOT / "schema"
+VERSION_FILE = SCHEMA_DIR / "VERSION"
 
 
 def main() -> None:
-    meta_json = ROOT / "schema" / "meta.json"
+    generate_meta()
+
+
+def generate_meta() -> None:
+    meta_json = SCHEMA_DIR / "meta.json"
     out_py = ROOT / "src" / "acp" / "meta.py"
-    data = json.loads(meta_json.read_text())
+    if not meta_json.exists():
+        raise SystemExit("schema/meta.json not found. Run gen_schema.py first.")  # noqa: TRY003
+
+    data = json.loads(meta_json.read_text("utf-8"))
     agent_methods = data.get("agentMethods", {})
     client_methods = data.get("clientMethods", {})
     version = data.get("version", 1)
+    header_lines = ["# Generated from schema/meta.json. Do not edit by hand."]
+    if VERSION_FILE.exists():
+        ref = VERSION_FILE.read_text("utf-8").strip()
+        if ref:
+            header_lines.append(f"# Schema ref: {ref}")
+
     out_py.write_text(
-        "# This file is generated from schema/meta.json. Do not edit by hand.\n"
-        f"AGENT_METHODS = {agent_methods!r}\n"
-        f"CLIENT_METHODS = {client_methods!r}\n"
-        f"PROTOCOL_VERSION = {int(version)}\n"
+        "\n".join(header_lines)
+        + "\n"
+        + f"AGENT_METHODS = {agent_methods!r}\n"
+        + f"CLIENT_METHODS = {client_methods!r}\n"
+        + f"PROTOCOL_VERSION = {int(version)}\n",
+        encoding="utf-8",
     )