From dc17c8501cdd44983c348921a3b361059ef5a539 Mon Sep 17 00:00:00 2001
From: sasha-gitg <44654632+sasha-gitg@users.noreply.github.com>
Date: Mon, 12 Jan 2026 16:42:46 -0500
Subject: [PATCH 1/7] chore: add breaking change detector

---
 .../workflows/breaking-change-detector.yml    | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 .github/workflows/breaking-change-detector.yml

diff --git a/.github/workflows/breaking-change-detector.yml b/.github/workflows/breaking-change-detector.yml
new file mode 100644
index 0000000000..e06fc75258
--- /dev/null
+++ b/.github/workflows/breaking-change-detector.yml
@@ -0,0 +1,56 @@
+name: Breaking Change Detector
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'src/**'
+
+jobs:
+  check-api:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Crucial for griffe.load_git to access the main branch history
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install Griffe
+        run: pip install griffe
+
+      - name: Run Breaking Change Detection
+        shell: python
+        run: |
+          import sys
+          import griffe
+          from griffe import find_breaking_changes, load, load_git
+
+          # 1. Load the current PR version from the local source
+          # The adk-python source is located in src/google/adk
+          try:
+              new_api = load("src/google/adk")
+              
+              # 2. Load the 'main' version for comparison
+              # Griffe will look at the main branch's version of the package
+              old_api = load_git("google.adk", ref="main")
+
+              # 3. Detect and explain breaking changes
+              breakages = list(find_breaking_changes(old_api, new_api))
+              
+              if breakages:
+                  print(f"::error::Found {len(breakages)} breaking changes!")
+                  for breakage in breakages:
+                      # .explain() provides a human-readable reason for the breakage
+                      print(breakage.explain())
+                  sys.exit(1)
+                  
+              print("No breaking changes detected.")
+          except Exception as e:
+              print(f"::warning::Breaking change detection failed: {e}")
+              # We don't exit 1 here to prevent CI failure if the tool itself crashes

From 20590deb810f02927a6003ab8831fb85acac680d Mon Sep 17 00:00:00 2001
From: sasha-gitg <44654632+sasha-gitg@users.noreply.github.com>
Date: Mon, 12 Jan 2026 16:49:48 -0500
Subject: [PATCH 2/7] trigger the workflow

---
 src/google/adk/runners.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/google/adk/runners.py b/src/google/adk/runners.py
index cbf2c59548..cccd6f27ba 100644
--- a/src/google/adk/runners.py
+++ b/src/google/adk/runners.py
@@ -353,7 +353,7 @@ def run(
       session_id: str,
       new_message: types.Content,
       run_config: Optional[RunConfig] = None,
-  ) -> Generator[Event, None, None]:
+  ) -> Generator[dict, None, None]:
     """Runs the agent.
 
     NOTE:

From e5e15a807e231f86808e19b486eb5a0e008e2c17 Mon Sep 17 00:00:00 2001
From: sasha-gitg <44654632+sasha-gitg@users.noreply.github.com>
Date: Mon, 12 Jan 2026 16:55:12 -0500
Subject: [PATCH 3/7] Update breaking-change-detector.yml

---
 .../workflows/breaking-change-detector.yml    | 38 ++++++++++++-------
 1 file changed, 24 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/breaking-change-detector.yml b/.github/workflows/breaking-change-detector.yml
index e06fc75258..c6bca1ef38 100644
--- a/.github/workflows/breaking-change-detector.yml
+++ b/.github/workflows/breaking-change-detector.yml
@@ -14,15 +14,22 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Crucial for griffe.load_git to access the main branch history
+          fetch-depth: 0  # Required for griffe.load_git to access main branch history
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: '3.10'
 
-      - name: Install Griffe
-        run: pip install griffe
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        # Syncing extras (like test) ensures 'google-auth' and other 'google.*' 
+        # namespaces are populated, preventing ModuleNotFound errors.
+        run: |
+          uv sync --extra test
+          uv pip install griffe
 
       - name: Run Breaking Change Detection
         shell: python
@@ -31,26 +38,29 @@ jobs:
           import griffe
           from griffe import find_breaking_changes, load, load_git
 
-          # 1. Load the current PR version from the local source
-          # The adk-python source is located in src/google/adk
+          # The package 'google.adk' is located inside the 'src' directory.
+          # Specifying search_paths=["src"] allows Griffe to find it.
           try:
-              new_api = load("src/google/adk")
+              print("Loading current API version...")
+              new_api = load("google.adk", search_paths=["src"])
               
-              # 2. Load the 'main' version for comparison
-              # Griffe will look at the main branch's version of the package
-              old_api = load_git("google.adk", ref="main")
+              print("Loading baseline API version from main branch...")
+              # load_git automatically handles the temporary checkout of the ref.
+              old_api = load_git("google.adk", ref="main", search_paths=["src"])
 
-              # 3. Detect and explain breaking changes
+              print("Comparing versions for breaking changes...")
               breakages = list(find_breaking_changes(old_api, new_api))
               
               if breakages:
+                  # Annotation for GitHub Actions UI
                   print(f"::error::Found {len(breakages)} breaking changes!")
                   for breakage in breakages:
-                      # .explain() provides a human-readable reason for the breakage
+                      # .explain() provides details on what was removed or changed
                       print(breakage.explain())
                   sys.exit(1)
                   
-              print("No breaking changes detected.")
+              print("Success: No breaking changes detected.")
           except Exception as e:
-              print(f"::warning::Breaking change detection failed: {e}")
-              # We don't exit 1 here to prevent CI failure if the tool itself crashes
+              # If Griffe fails (e.g., due to the 'google' module error), we fail the check.
+              print(f"::error::Breaking change detection failed: {e}")
+              sys.exit(1)

From 313b042b69249cc9b91df853d1f32aef3d20b207 Mon Sep 17 00:00:00 2001
From: sasha-gitg <44654632+sasha-gitg@users.noreply.github.com>
Date: Mon, 12 Jan 2026 16:57:30 -0500
Subject: [PATCH 4/7] Update breaking-change-detector.yml

---
 .../workflows/breaking-change-detector.yml    | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/breaking-change-detector.yml b/.github/workflows/breaking-change-detector.yml
index c6bca1ef38..856f6e1704 100644
--- a/.github/workflows/breaking-change-detector.yml
+++ b/.github/workflows/breaking-change-detector.yml
@@ -14,7 +14,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Required for griffe.load_git to access main branch history
+          fetch-depth: 0  # Required for griffe.load_git to access 'main' history
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -25,42 +25,42 @@ jobs:
         uses: astral-sh/setup-uv@v5
 
       - name: Install dependencies
-        # Syncing extras (like test) ensures 'google-auth' and other 'google.*' 
-        # namespaces are populated, preventing ModuleNotFound errors.
+        # 1. uv sync installs the SDK (google-auth, pydantic, etc.)
+        # 2. uv pip install griffe ensures the detector tool is in the venv
         run: |
           uv sync --extra test
           uv pip install griffe
 
       - name: Run Breaking Change Detection
-        shell: python
+        # Using 'uv run python' is the key: it automatically runs the script
+        # inside the .venv created in the previous step, so both 'griffe'
+        # and 'google' are found.
         run: |
+          uv run python - <<EOF
           import sys
           import griffe
           from griffe import find_breaking_changes, load, load_git
 
-          # The package 'google.adk' is located inside the 'src' directory.
-          # Specifying search_paths=["src"] allows Griffe to find it.
           try:
-              print("Loading current API version...")
+              print("Loading current API (from PR)...")
+              # We use 'google.adk' and tell Griffe to look in 'src'
               new_api = load("google.adk", search_paths=["src"])
               
-              print("Loading baseline API version from main branch...")
-              # load_git automatically handles the temporary checkout of the ref.
+              print("Loading baseline API (from main branch)...")
+              # search_paths=["src"] is also required here to find the package in the worktree
               old_api = load_git("google.adk", ref="main", search_paths=["src"])
 
-              print("Comparing versions for breaking changes...")
+              print("Comparing for breaking changes...")
               breakages = list(find_breaking_changes(old_api, new_api))
               
               if breakages:
-                  # Annotation for GitHub Actions UI
                   print(f"::error::Found {len(breakages)} breaking changes!")
                   for breakage in breakages:
-                      # .explain() provides details on what was removed or changed
                       print(breakage.explain())
                   sys.exit(1)
                   
               print("Success: No breaking changes detected.")
           except Exception as e:
-              # If Griffe fails (e.g., due to the 'google' module error), we fail the check.
               print(f"::error::Breaking change detection failed: {e}")
               sys.exit(1)
+          EOF

From 0bd06c09aa3d13f9c116004915696cf532a568e9 Mon Sep 17 00:00:00 2001
From: sasha-gitg <44654632+sasha-gitg@users.noreply.github.com>
Date: Mon, 12 Jan 2026 17:03:42 -0500
Subject: [PATCH 5/7] Update breaking-change-detector.yml

---
 .../workflows/breaking-change-detector.yml    | 31 ++++++++++---------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/breaking-change-detector.yml b/.github/workflows/breaking-change-detector.yml
index 856f6e1704..a1b535b591 100644
--- a/.github/workflows/breaking-change-detector.yml
+++ b/.github/workflows/breaking-change-detector.yml
@@ -14,27 +14,24 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Required for griffe.load_git to access 'main' history
+          fetch-depth: 0
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: '3.10'
 
-      - name: Install the latest version of uv
+      - name: Install dependencies
         uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
 
-      - name: Install dependencies
-        # 1. uv sync installs the SDK (google-auth, pydantic, etc.)
-        # 2. uv pip install griffe ensures the detector tool is in the venv
+      - name: Install project
         run: |
           uv sync --extra test
           uv pip install griffe
 
       - name: Run Breaking Change Detection
-        # Using 'uv run python' is the key: it automatically runs the script
-        # inside the .venv created in the previous step, so both 'griffe'
-        # and 'google' are found.
         run: |
           uv run python - <<EOF
           import sys
@@ -42,15 +39,18 @@ jobs:
           from griffe import find_breaking_changes, load, load_git
 
           try:
-              print("Loading current API (from PR)...")
-              # We use 'google.adk' and tell Griffe to look in 'src'
-              new_api = load("google.adk", search_paths=["src"])
+              # 1. Force static analysis (allow_inspection=False) to avoid sys.modules caching issues
+              print("Loading new API...")
+              new_api = load("google.adk", search_paths=["src"], allow_inspection=False)
               
-              print("Loading baseline API (from main branch)...")
-              # search_paths=["src"] is also required here to find the package in the worktree
-              old_api = load_git("google.adk", ref="main", search_paths=["src"])
+              print("Loading old API...")
+              old_api = load_git("google.adk", ref="main", search_paths=["src"], allow_inspection=False)
 
-              print("Comparing for breaking changes...")
+              # Debug: Verify we are comparing different files
+              print(f"DEBUG: New API path: {new_api.filepath}")
+              print(f"DEBUG: Old API path: {old_api.filepath}")
+
+              print("Comparing...")
               breakages = list(find_breaking_changes(old_api, new_api))
               
               if breakages:
@@ -60,6 +60,7 @@ jobs:
                   sys.exit(1)
                   
               print("Success: No breaking changes detected.")
+
           except Exception as e:
               print(f"::error::Breaking change detection failed: {e}")
               sys.exit(1)

From 97542097c9d327dbb22cdad12a551944ed2d6f3a Mon Sep 17 00:00:00 2001
From: sasha-gitg <44654632+sasha-gitg@users.noreply.github.com>
Date: Mon, 12 Jan 2026 17:15:20 -0500
Subject: [PATCH 6/7] Update breaking-change-detector.yml

---
 .../workflows/breaking-change-detector.yml    | 30 ++++++++++++++-----
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/breaking-change-detector.yml b/.github/workflows/breaking-change-detector.yml
index a1b535b591..affb81048c 100644
--- a/.github/workflows/breaking-change-detector.yml
+++ b/.github/workflows/breaking-change-detector.yml
@@ -38,18 +38,30 @@ jobs:
           import griffe
           from griffe import find_breaking_changes, load, load_git
 
+          def print_debug_info(api_obj, label):
+              try:
+                  # Navigate to Runner.run to check what Griffe sees
+                  runner = api_obj.members["Runner"]
+                  run_method = runner.members["run"]
+                  print(f"DEBUG [{label}]: Runner.run return annotation: '{run_method.returns}'")
+              except KeyError as e:
+                  print(f"DEBUG [{label}]: Could not find 'Runner.run' member. Missing: {e}")
+                  print(f"DEBUG [{label}]: Available members: {list(api_obj.members.keys())}")
+
           try:
-              # 1. Force static analysis (allow_inspection=False) to avoid sys.modules caching issues
-              print("Loading new API...")
+              # 1. Load NEW API (Force static analysis)
+              print("Loading new API from src/...")
               new_api = load("google.adk", search_paths=["src"], allow_inspection=False)
+              print(f"DEBUG: New API filepath: {new_api.filepath}")
+              print_debug_info(new_api, "NEW")
               
-              print("Loading old API...")
+              # 2. Load OLD API (Force static analysis from git)
+              print("Loading old API from main branch...")
               old_api = load_git("google.adk", ref="main", search_paths=["src"], allow_inspection=False)
+              print(f"DEBUG: Old API filepath: {old_api.filepath}")
+              print_debug_info(old_api, "OLD")
 
-              # Debug: Verify we are comparing different files
-              print(f"DEBUG: New API path: {new_api.filepath}")
-              print(f"DEBUG: Old API path: {old_api.filepath}")
-
+              # 3. Compare
               print("Comparing...")
               breakages = list(find_breaking_changes(old_api, new_api))
               
@@ -58,7 +70,9 @@ jobs:
                   for breakage in breakages:
                       print(breakage.explain())
                   sys.exit(1)
-                  
+              
+              # If we see different return types in DEBUG logs but 0 breakages here, 
+              # it means Griffe considers them compatible.
               print("Success: No breaking changes detected.")
 
           except Exception as e:

From b0610cac8e92fc13ac807498d46b4eb08ae1b6da Mon Sep 17 00:00:00 2001
From: sasha-gitg <44654632+sasha-gitg@users.noreply.github.com>
Date: Mon, 12 Jan 2026 17:19:10 -0500
Subject: [PATCH 7/7] Update breaking-change-detector.yml

---
 .../workflows/breaking-change-detector.yml    | 75 ++++++++++++-------
 1 file changed, 48 insertions(+), 27 deletions(-)

diff --git a/.github/workflows/breaking-change-detector.yml b/.github/workflows/breaking-change-detector.yml
index affb81048c..8dbabe7fbd 100644
--- a/.github/workflows/breaking-change-detector.yml
+++ b/.github/workflows/breaking-change-detector.yml
@@ -14,65 +14,86 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0
+          fetch-depth: 0  # Required for accessing the main branch history
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: '3.10'
 
-      - name: Install dependencies
+      - name: Install the latest version of uv
         uses: astral-sh/setup-uv@v5
-        with:
-          version: "latest"
 
-      - name: Install project
+      - name: Install dependencies
+        # Syncing installs the package and its dependencies (populating google.* namespace)
+        # Installing 'griffe' ensures the tool is available in the environment
         run: |
           uv sync --extra test
           uv pip install griffe
 
       - name: Run Breaking Change Detection
+        # Uses 'uv run python' to execute in the environment with all dependencies installed
         run: |
           uv run python - <<EOF
           import sys
           import griffe
           from griffe import find_breaking_changes, load, load_git
 
-          def print_debug_info(api_obj, label):
+          def check_return_types(old_obj, new_obj):
+              """Custom check to strictly compare return type annotations."""
+              errors = []
+              # Check Runner.run specifically, or extend to check all methods
               try:
-                  # Navigate to Runner.run to check what Griffe sees
-                  runner = api_obj.members["Runner"]
-                  run_method = runner.members["run"]
-                  print(f"DEBUG [{label}]: Runner.run return annotation: '{run_method.returns}'")
-              except KeyError as e:
-                  print(f"DEBUG [{label}]: Could not find 'Runner.run' member. Missing: {e}")
-                  print(f"DEBUG [{label}]: Available members: {list(api_obj.members.keys())}")
+                  old_run = old_obj.members["Runner"].members["run"]
+                  new_run = new_obj.members["Runner"].members["run"]
+                  
+                  # Convert to string and strip to compare the annotation text
+                  old_ret = str(old_run.returns).strip()
+                  new_ret = str(new_run.returns).strip()
+                  
+                  if old_ret != new_ret:
+                      errors.append(
+                          f"Breaking Change in {new_run.path}: Return type changed from '{old_ret}' to '{new_ret}'"
+                      )
+              except KeyError:
+                  pass # Member missing (will be caught by standard checks)
+              except AttributeError:
+                  pass # Member might not be a function
+              return errors
 
           try:
-              # 1. Load NEW API (Force static analysis)
-              print("Loading new API from src/...")
+              print("Loading new API (from local source)...")
+              # allow_inspection=False forces static analysis, preventing sys.modules caching issues
               new_api = load("google.adk", search_paths=["src"], allow_inspection=False)
-              print(f"DEBUG: New API filepath: {new_api.filepath}")
-              print_debug_info(new_api, "NEW")
               
-              # 2. Load OLD API (Force static analysis from git)
-              print("Loading old API from main branch...")
+              print("Loading baseline API (from main branch)...")
               old_api = load_git("google.adk", ref="main", search_paths=["src"], allow_inspection=False)
-              print(f"DEBUG: Old API filepath: {old_api.filepath}")
-              print_debug_info(old_api, "OLD")
 
-              # 3. Compare
-              print("Comparing...")
+              print("Running detection...")
+              
+              # 1. Standard Griffe Checks (Removals, Parameter changes)
               breakages = list(find_breaking_changes(old_api, new_api))
               
+              # 2. Custom Return Type Checks (Workaround for Griffe limitation)
+              custom_errors = check_return_types(old_api, new_api)
+
+              found_issues = False
+
               if breakages:
-                  print(f"::error::Found {len(breakages)} breaking changes!")
+                  found_issues = True
+                  print(f"::error::Found {len(breakages)} standard breaking changes!")
                   for breakage in breakages:
                       print(breakage.explain())
+
+              if custom_errors:
+                  found_issues = True
+                  print(f"::error::Found {len(custom_errors)} return type mismatches!")
+                  for error in custom_errors:
+                      print(f"- {error}")
+
+              if found_issues:
                   sys.exit(1)
-              
-              # If we see different return types in DEBUG logs but 0 breakages here, 
-              # it means Griffe considers them compatible.
+                  
               print("Success: No breaking changes detected.")
 
           except Exception as e: