Merge origin/main into feat/acp-agent-tcp-transport

Resolve conflicts between TCP transport feature and upstream changes
(ACPAgent refactoring from #2133, ask_agent from #2145).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: simonrosenberg

.agents/skills/custom-codereview-guide.md

@@ -29,6 +29,14 @@ Examples of straightforward and low-risk PRs you should approve (non-exhaustive)
 - **Test-only changes**: Adding or updating tests without changing production code
 - **Dependency updates**: Version bumps with passing CI
 
+### When NOT to APPROVE - Blocking Issues
+
+**DO NOT APPROVE** PRs that have any of the following issues:
+
+- **Package version bumps in non-release PRs**: If any `pyproject.toml` file has changes to the `version` field (e.g., `version = "1.12.0"` → `version = "1.13.0"`), and the PR is NOT explicitly a release PR (title/description doesn't indicate it's a release), **DO NOT APPROVE**. Version numbers should only be changed in dedicated release PRs managed by maintainers.
+  - Check: Look for changes to `version = "..."` in any `*/pyproject.toml` files
+  - Exception: PRs with titles like "release: v1.x.x" or "chore: bump version to 1.x.x" from maintainers
+
 Examples:
 - A PR adding a new model to `resolve_model_config.py` or `verified_models.py` with corresponding test updates
 - A PR adding documentation notes to docstrings clarifying method behavior (e.g., security considerations, bypass behaviors)

.github/run-eval/resolve_model_config.py

@@ -86,6 +86,11 @@
         "display_name": "Gemini 3 Flash",
         "llm_config": {"model": "litellm_proxy/gemini-3-flash-preview"},
     },
+    "gemini-3.1-pro": {
+        "id": "gemini-3.1-pro",
+        "display_name": "Gemini 3.1 Pro",
+        "llm_config": {"model": "litellm_proxy/gemini-3.1-pro-preview"},
+    },
     "gpt-5.2": {
         "id": "gpt-5.2",
         "display_name": "GPT-5.2",

.github/scripts/check_sdk_api_breakage.py

@@ -30,6 +30,7 @@
 import ast
 import json
 import os
+import re
 import sys
 import tomllib
 import urllib.request
@@ -147,6 +148,38 @@ def ensure_griffe() -> None:
         raise SystemExit(1)
 
 
+def _is_field_metadata_only_change(old_val: object, new_val: object) -> bool:
+    """Check if the change is only in Field metadata (description, title, etc.).
+
+    Field metadata parameters like ``description``, ``title``, and ``examples``
+    don't affect runtime behavior - they're documentation-only. Changes to these
+    should not be considered breaking API changes.
+
+    Returns:
+        True if both values are Field() calls and only metadata parameters differ.
+    """
+    old_str = str(old_val)
+    new_str = str(new_val)
+
+    if not (old_str.startswith("Field(") and new_str.startswith("Field(")):
+        return False
+
+    # Metadata parameters that don't affect runtime behavior
+    # See https://docs.pydantic.dev/latest/api/fields/#pydantic.fields.Field
+    metadata_params = ["description", "title", "examples", "json_schema_extra"]
+
+    old_normalized = old_str
+    new_normalized = new_str
+
+    for param in metadata_params:
+        # Pattern to match param='...' or param="..." with simple string values
+        pattern = rf'{param}\s*=\s*([\'"])([^\'"]*?)\1'
+        old_normalized = re.sub(pattern, f"{param}=PLACEHOLDER", old_normalized)
+        new_normalized = re.sub(pattern, f"{param}=PLACEHOLDER", new_normalized)
+
+    return old_normalized == new_normalized
+
+
 def _collect_breakages_pairs(
     objs: Iterable[tuple[object, object]],
     *,
@@ -160,40 +193,81 @@ def _collect_breakages_pairs(
     Returns:
         (breakages, undeprecated_removals)
     """
+
     import griffe
-    from griffe import BreakageKind, ExplanationStyle, Kind
+    from griffe import Alias, AliasResolutionError, BreakageKind, ExplanationStyle, Kind
 
-    breakages = []
+    breakages: list[object] = []
     undeprecated_removals = 0
 
     for old, new in objs:
-        for br in griffe.find_breaking_changes(old, new):
-            obj = getattr(br, "obj", None)
-            if not getattr(obj, "is_public", True):
-                continue
-
-            print(br.explain(style=ExplanationStyle.GITHUB))
-            breakages.append(br)
-
-            if br.kind != BreakageKind.OBJECT_REMOVED:
-                continue
-
-            parent = getattr(obj, "parent", None)
-            if getattr(parent, "kind", None) != Kind.CLASS:
-                continue
-
-            feature = f"{parent.name}.{obj.name}"
-            if (
-                feature not in deprecated.qualified
-                and parent.name not in deprecated.top_level
-            ):
+        try:
+            for br in griffe.find_breaking_changes(old, new):
+                obj = getattr(br, "obj", None)
+                if not getattr(obj, "is_public", True):
+                    continue
+
+                # Skip ATTRIBUTE_CHANGED_VALUE when it's just Field metadata changes
+                # (description, title, examples, etc.) - these don't affect runtime
+                if br.kind == BreakageKind.ATTRIBUTE_CHANGED_VALUE:
+                    old_value = getattr(br, "old_value", None)
+                    new_value = getattr(br, "new_value", None)
+                    if _is_field_metadata_only_change(old_value, new_value):
+                        print(
+                            f"::notice title={title}::Ignoring Field metadata-only "
+                            f"change (non-breaking): {obj.name if obj else 'unknown'}"
+                        )
+                        continue
+
+                print(br.explain(style=ExplanationStyle.GITHUB))
+                breakages.append(br)
+
+                if br.kind != BreakageKind.OBJECT_REMOVED:
+                    continue
+
+                parent = getattr(obj, "parent", None)
+                if getattr(parent, "kind", None) != Kind.CLASS:
+                    continue
+
+                feature = f"{parent.name}.{obj.name}"
+                if (
+                    feature not in deprecated.qualified
+                    and parent.name not in deprecated.top_level
+                ):
+                    print(
+                        f"::error title={title}::Removed '{feature}' without prior "
+                        "deprecation. Mark it with @deprecated(...) or "
+                        f"warn_deprecated('{feature}', ...) for at least one release "
+                        "before removing."
+                    )
+                    undeprecated_removals += 1
+        except AliasResolutionError as e:
+            if isinstance(old, Alias) or isinstance(new, Alias):
+                old_target = old.target_path if isinstance(old, Alias) else None
+                new_target = new.target_path if isinstance(new, Alias) else None
+                if old_target != new_target:
+                    name = getattr(old, "name", None) or getattr(
+                        new, "name", "<unknown>"
+                    )
+                    print(
+                        f"::warning title={title}::Alias target changed for '{name}': "
+                        f"{old_target!r} -> {new_target!r}"
+                    )
+                    breakages.append(
+                        {
+                            "kind": "ALIAS_TARGET_CHANGED",
+                            "name": name,
+                            "old": old_target,
+                            "new": new_target,
+                        }
+                    )
+            else:
                 print(
-                    f"::error title={title}::Removed '{feature}' without prior "
-                    "deprecation. Mark it with @deprecated(...) or "
-                    f"warn_deprecated('{feature}', ...) for at least one release "
-                    "before removing."
+                    f"::notice title={title}::Skipping symbol comparison due to "
+                    f"unresolved alias: {e}"
                 )
-                undeprecated_removals += 1
+        except Exception as e:
+            print(f"::warning title={title}::Failed to compute breakages: {e}")
 
     return breakages, undeprecated_removals
 
@@ -247,7 +321,7 @@ def _check_version_bump(prev: str, new_version: str, total_breaks: int) -> int:
         0 if policy satisfied, 1 if not
     """
     if total_breaks == 0:
-        print("No SDK breaking changes detected")
+        print("No breaking changes detected")
         return 0
 
     parsed_prev = _parse_version(prev)
@@ -260,14 +334,14 @@ def _check_version_bump(prev: str, new_version: str, total_breaks: int) -> int:
 
     if not ok:
         print(
-            f"::error title=SDK SemVer::Breaking changes detected ({total_breaks}); "
+            f"::error title=SemVer::Breaking changes detected ({total_breaks}); "
             f"require at least minor version bump from "
             f"{parsed_prev.major}.{parsed_prev.minor}.x, but new is {new_version}"
         )
         return 1
 
     print(
-        f"SDK breaking changes detected ({total_breaks}) and version bump policy "
+        f"Breaking changes detected ({total_breaks}) and version bump policy "
         f"satisfied ({prev} -> {new_version})"
     )
     return 0
@@ -452,9 +526,7 @@ def _get_source_root(griffe_root: object) -> Path | None:
     return None
 
 
-def _compute_breakages(
-    old_root, new_root, cfg: PackageConfig, include: list[str]
-) -> tuple[int, int]:
+def _compute_breakages(old_root, new_root, cfg: PackageConfig) -> tuple[int, int]:
     """Detect breaking changes between old and new package versions.
 
     Returns:
@@ -468,79 +540,66 @@ def _compute_breakages(
     total_breaks = 0
     undeprecated_removals = 0
 
-    deprecated = DeprecatedSymbols()
+    source_root = _get_source_root(old_root)
+    deprecated = (
+        _find_deprecated_symbols(source_root) if source_root else DeprecatedSymbols()
+    )
 
     try:
         old_mod = _resolve_griffe_object(old_root, pkg, root_package=pkg)
         new_mod = _resolve_griffe_object(new_root, pkg, root_package=pkg)
-        old_exports = _extract_exported_names(old_mod)
-        new_exports = _extract_exported_names(new_mod)
-
-        removed = sorted(old_exports - new_exports)
+    except Exception as e:
+        raise RuntimeError(f"Failed to resolve root module '{pkg}'") from e
 
-        source_root = _get_source_root(old_root)
-        deprecated = (
-            _find_deprecated_symbols(source_root)
-            if source_root
-            else DeprecatedSymbols()
+    new_exports = _extract_exported_names(new_mod)
+    try:
+        old_exports = _extract_exported_names(old_mod)
+    except ValueError as e:
+        # The API breakage check relies on a curated public surface defined via
+        # __all__. If the previous release didn't define (or couldn't statically
+        # evaluate) __all__, we can't compute meaningful breakages.
+        #
+        # In this situation, skip rather than failing the entire workflow.
+        print(
+            f"::notice title={title}::Skipping breakage check; previous release "
+            f"has no statically-evaluable {pkg}.__all__: {e}"
         )
+        return 0, 0
 
-        # Check deprecation-before-removal policy (exports)
-        if removed:
-            for name in removed:
-                total_breaks += 1  # every removal is a structural break
-                if name not in deprecated.top_level:
-                    print(
-                        f"::error title={title}::Removed '{name}' from "
-                        f"{pkg}.__all__ without prior deprecation. "
-                        "Mark it with @deprecated or warn_deprecated() "
-                        "for at least one release before removing."
-                    )
-                    undeprecated_removals += 1
-                else:
-                    print(
-                        f"::notice title={title}::Removed previously-"
-                        f"deprecated symbol '{name}' from "
-                        f"{pkg}.__all__"
-                    )
+    removed = sorted(old_exports - new_exports)
 
-        common = sorted(old_exports & new_exports)
-        pairs: list[tuple[object, object]] = []
-        for name in common:
-            try:
-                pairs.append((old_mod[name], new_mod[name]))
-            except Exception as e:
-                print(f"::warning title={title}::Unable to resolve symbol {name}: {e}")
-
-        breakages, undeprecated_members = _collect_breakages_pairs(
-            pairs,
-            deprecated=deprecated,
-            title=title,
-        )
-        total_breaks += len(breakages)
-        undeprecated_removals += undeprecated_members
-    except Exception as e:
-        print(f"::warning title={title}::Failed to process top-level exports: {e}")
+    # Check deprecation-before-removal policy (exports)
+    for name in removed:
+        total_breaks += 1  # every removal is a structural break
+        if name not in deprecated.top_level:
+            print(
+                f"::error title={title}::Removed '{name}' from "
+                f"{pkg}.__all__ without prior deprecation. "
+                "Mark it with @deprecated or warn_deprecated() "
+                "for at least one release before removing."
+            )
+            undeprecated_removals += 1
+        else:
+            print(
+                f"::notice title={title}::Removed previously-deprecated symbol "
+                f"'{name}' from {pkg}.__all__"
+            )
 
-    extra_pairs: list[tuple[object, object]] = []
-    for path in include:
-        if path == pkg:
-            continue
+    common = sorted(old_exports & new_exports)
+    pairs: list[tuple[object, object]] = []
+    for name in common:
         try:
-            old_obj = _resolve_griffe_object(old_root, path, root_package=pkg)
-            new_obj = _resolve_griffe_object(new_root, path, root_package=pkg)
-            extra_pairs.append((old_obj, new_obj))
+            pairs.append((old_mod[name], new_mod[name]))
         except Exception as e:
-            print(f"::warning title={title}::Path {path} not found: {e}")
+            print(f"::warning title={title}::Unable to resolve symbol {name}: {e}")
 
-    if extra_pairs:
-        breakages, undeprecated_members = _collect_breakages_pairs(
-            extra_pairs,
-            deprecated=deprecated,
-            title=title,
-        )
-        total_breaks += len(breakages)
-        undeprecated_removals += undeprecated_members
+    breakages, undeprecated_members = _collect_breakages_pairs(
+        pairs,
+        deprecated=deprecated,
+        title=title,
+    )
+    total_breaks += len(breakages)
+    undeprecated_removals += undeprecated_members
 
     return total_breaks, undeprecated_removals
 
@@ -550,10 +609,6 @@ def _check_package(griffe_module, repo_root: str, cfg: PackageConfig) -> int:
     pyproj = os.path.join(repo_root, cfg.source_dir, "pyproject.toml")
     new_version = read_version_from_pyproject(pyproj)
 
-    include_env = f"{cfg.package.upper().replace('.', '_')}_INCLUDE_PATHS"
-    include = os.environ.get(include_env, cfg.package).split(",")
-    include = [p.strip() for p in include if p.strip()]
-
     title = f"{cfg.distribution} API"
     prev = get_prev_pypi_version(cfg.distribution, new_version)
     if not prev:
@@ -573,7 +628,11 @@ def _check_package(griffe_module, repo_root: str, cfg: PackageConfig) -> int:
     if not old_root:
         return 1
 
-    total_breaks, undeprecated = _compute_breakages(old_root, new_root, cfg, include)
+    try:
+        total_breaks, undeprecated = _compute_breakages(old_root, new_root, cfg)
+    except Exception as e:
+        print(f"::error title={title}::Failed to compute breakages: {e}")
+        return 1
 
     if undeprecated:
         print(