Merge branch 'google:main' into add-agent-registry-support

Author: agrawalradhika-cell

.agents/skills/adk-issue/SKILL.md

@@ -7,9 +7,14 @@ description: Analyze and triage GitHub issues for the adk-python repository. Use
 
 This skill provides a structured workflow for analyzing, verifying, and triaging GitHub issues from the `google/adk-python` repository. When a user provides a GitHub issue number or link, use this skill to perform deep investigation and report your findings.
 
-## Issue Triage Workflow
+> [!IMPORTANT]
+> ## CRITICAL EXECUTION RULE: STOP AFTER STEP 2
+> * **Phase 1 (Triage & Report) is strictly read-only**: Do NOT modify any code, create new branches, or write any implementation in your first response.
+> * **STOP and ask**: You must present the analysis report first and explicitly ask the user:
+>   > "Would you like me to create and implement a fix for this issue in the workspace? (Note: The changes and tests will be created in a new branch but NOT committed, so you can review and iterate on them.)"
+> * **Wait for Approval**: Only proceed with Phase 2 (Step 3: Implementation) in a subsequent turn *after* the user explicitly approves the recommendation.
 
-Follow this 3-step process to analyze the issue:
+## Phase 1: Triage and Analysis (Read-Only)
 
 ### Step 1: Retrieve and Parse the Issue
 1. **Extract the issue number**: Parse the number from the link or prompt (e.g., `https://github.com/google/adk-python/issues/5882` -> `5882`).
@@ -63,13 +68,15 @@ Search for any existing pull requests that attempt to resolve the issue:
   gh pr view <pr_number> --repo google/adk-python --json number,title,state,url,body,author
   ```
 - **Analyze progress**: Check if the PR is open, merged, or closed, and if it successfully fixes the issue according to the repository's testing patterns.
+- **Present the structured report**: Format and present your findings structured as a premium report following the **Report Template** below.
 - **Offer to create a fix**: If no existing PR is found, you MUST explicitly ask the user: "Would you like me to create and implement a fix for this issue in the workspace? (Note: The changes and tests will be created in a new branch but NOT committed, so you can review and iterate on them.)"
 
 ---
 
-### Step 3: Report & Propose Fix
-1. **Present the structured report**: Follow the **Report Template** below to format your findings.
-2. **Propose a fix**: If there is no existing PR addressing the issue, explicitly ask the user if they would like you to implement the fix in the workspace. When implementing the fix:
+## Phase 2: Implementation (After User Approval)
+
+### Step 3: Propose and Implement Fix
+Once the user has approved the implementation of the fix in the workspace, follow these rules:
    - **Do NOT commit the changes**: Leave them uncommitted in the workspace so the user can review and iterate on them.
    - **Base the branch on remote HEAD**: When creating the new branch, ensure it is based on the remote tracking branch HEAD (`origin/main`), not the current local branch. For example:
      ```bash

.agents/skills/adk-pr-triage/SKILL.md

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helper script for ADK PR Triage verification and remote update."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+
+
+def run_command(args: list[str]) -> tuple[int, str, str]:
+  """Runs a shell command and returns its exit code, stdout, and stderr."""
+  try:
+    res = subprocess.run(args, capture_output=True, text=True, check=False)
+    return res.returncode, res.stdout.strip(), res.stderr.strip()
+  except Exception as e:
+    return -1, "", str(e)
+
+
+def verify_cla(pr_number: str) -> bool:
+  """Verifies if the Google CLA is signed for the given PR number."""
+  print(f"[*] Fetching status checks for PR #{pr_number}...")
+  cmd = [
+      "gh",
+      "pr",
+      "view",
+      pr_number,
+      "--repo",
+      "google/adk-python",
+      "--json",
+      "statusCheckRollup",
+  ]
+  code, stdout, stderr = run_command(cmd)
+  if code != 0:
+    print(
+        f"Error: Failed to fetch PR details from GitHub: {stderr}",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+  try:
+    data = json.loads(stdout)
+  except json.JSONDecodeError:
+    print("Error: Failed to parse GitHub API JSON response.", file=sys.stderr)
+    sys.exit(1)
+
+  status_checks = data.get("statusCheckRollup", [])
+  cla_check = None
+  for check in status_checks:
+    if check.get("name") == "cla/google":
+      cla_check = check
+      break
+
+  if not cla_check:
+    print("\n" + "=" * 80)
+    print("🚨  CRITICAL COMPLIANCE REFUSAL: GOOGLE CLA NOT SIGNED/VERIFIED  🚨")
+    print("=" * 80)
+    print(
+        "Error: The mandatory 'cla/google' status check is completely missing"
+        " on GitHub."
+    )
+    print(
+        "The contributor HAS NOT signed the Google Contributor License"
+        " Agreement."
+    )
+    print(
+        "Legal policy strictly prohibits triaging, downloading, or reviewing"
+        " this PR."
+    )
+    print("=" * 80 + "\n")
+    return False
+
+  conclusion = cla_check.get("conclusion")
+  if conclusion != "SUCCESS":
+    print("\n" + "=" * 80)
+    print("🚨  CRITICAL COMPLIANCE REFUSAL: GOOGLE CLA NOT SIGNED/VERIFIED  🚨")
+    print("=" * 80)
+    print(
+        "Error: The 'cla/google' status check has the status:"
+        f" '{conclusion or 'UNKNOWN'}'."
+    )
+    print(
+        "The contributor HAS NOT successfully signed or verified the Google"
+        " CLA."
+    )
+    print(
+        "Legal policy strictly prohibits triaging, downloading, or reviewing"
+        " this PR."
+    )
+    print("=" * 80 + "\n")
+    return False
+
+  print("✅ Google CLA is verified and signed (status SUCCESS).")
+  return True
+
+
+def update_pr_branch(pr_number: str) -> None:
+  """Updates the remote PR branch with the latest changes from the base branch."""
+  print(
+      f"\n[*] Attempting to update PR #{pr_number} branch via remote REBASE..."
+  )
+  rebase_cmd = [
+      "gh",
+      "pr",
+      "update-branch",
+      pr_number,
+      "--rebase",
+      "--repo",
+      "google/adk-python",
+  ]
+  code, stdout, stderr = run_command(rebase_cmd)
+  if code == 0:
+    print(
+        "✅ Successfully updated PR branch on GitHub by rebasing onto base"
+        " branch!"
+    )
+    if stdout:
+      print(stdout)
+    return
+
+  print(f"Warning: Remote rebase-update failed: {stderr}")
+  print("[*] Falling back to standard remote MERGE commit update...")
+
+  merge_cmd = [
+      "gh",
+      "pr",
+      "update-branch",
+      pr_number,
+      "--repo",
+      "google/adk-python",
+  ]
+  code, stdout, stderr = run_command(merge_cmd)
+  if code == 0:
+    print(
+        "✅ Successfully updated PR branch on GitHub via standard merge commit!"
+    )
+    if stdout:
+      print(stdout)
+    return
+
+  print(
+      "\n[!] Warning: Remote branch update failed completely on GitHub server:"
+      f" {stderr}"
+  )
+  print("    This is typical if edits are disabled on the contributor's fork.")
+  print(
+      "    No worries! We will automatically rebase locally after checking out."
+  )
+
+
+def main() -> None:
+  parser = argparse.ArgumentParser(
+      description="Triage PR verification and sync helper."
+  )
+  parser.add_argument(
+      "pr_number", help="The GitHub Pull Request number (e.g. 5875)."
+  )
+  parser.add_argument(
+      "--skip-update",
+      action="store_true",
+      help="Skip updating the remote PR branch on GitHub.",
+  )
+  args = parser.parse_args()
+
+  # Step 1: Verify CLA
+  if not verify_cla(args.pr_number):
+    sys.exit(2)  # Exit code 2 indicates compliance refusal
+
+  # Step 2: Update branch
+  if not args.skip_update:
+    update_pr_branch(args.pr_number)
+
+  print("\n[*] Verification complete. Safe to proceed with checkout.")
+  sys.exit(0)
+
+
+if __name__ == "__main__":
+  main()

.agents/skills/adk-pr-triage/scripts/triage_pr.py

@@ -0,0 +1,76 @@
+---
+name: adk-review
+description: Reviews all local changes in the repository for errors, styling compliance, unintended outcomes, and necessary documentation/test/sample updates. Generates a report and assists in fixing identified issues on-demand. Triggers on "adk-review", "review changes", "pr review", "check code style", "verify changes".
+---
+
+# ADK Change Reviewer (adk-review)
+
+This skill guides AI assistants in performing a comprehensive, rigorous review of local repository changes before they are committed or submitted. It evaluates code correctness, style guidelines, architectural impact, and checks if associated tests, samples, and documentation need updates. It generates a detailed report and, upon explicit user request, assists in automatically fixing the identified issues.
+
+> [!NOTE]
+> Always read this skill and follow its steps when asked to review local changes or before finalizing a PR/commit.
+
+---
+
+## Review Checklist Dimensions
+
+### 1. Code Correctness & Errors
+- **Syntax & Types**: Ensure the code is free of syntax errors and conforms to strong typing guidelines. Avoid using `Any`, and prefer specific/abstract types. Use `X | None` instead of `Optional[X]`.
+- **Imports**: Verify there are no circular imports. Ensure absolute imports are used where appropriate.
+- **Exception Handling**: Avoid bare `except:`. Always catch specific exceptions and log them properly with context.
+- **Visibility**: Ensure internal modules and package-private attributes use proper naming (e.g., prefixed with `_`) per ADK rules.
+- **Edge Cases & Defensive Programming**:
+  - **Type & Attribute Discrimination**: Explicitly verify an object's type (e.g., using `isinstance`) before checking type-specific or custom attributes (e.g., checking if a node is an `LlmAgent` before inspecting its `mode`), avoiding errors on unexpected types.
+  - **Boundary and Null Conditions**: Ensure robust handling for boundary conditions and null values (e.g., `None`, empty collections, zero, or empty strings) using validation or fallback defaults.
+  - **Preconditions & Invariants**: Validate that preconditions and state invariants are checked before performing core logic.
+
+### 2. Style and Convention Compliance
+- **ADK Style Guide**: Cross-reference all code changes with the guidelines in the `adk-style` skill (including Pydantic v2 patterns, lazy logging evaluation, and file structure).
+- **Pre-commit Hooks**: Ensure changed files are formatted and linted. Remind the user to run `pre-commit run --files <files>` if hooks like `isort`, `pyink`, `addlicense`, or `mdformat` are not configured automatically.
+
+### 3. Architectural Integrity & Unintended Outcomes
+- **Public API Stability**: Verify whether changes modify, remove, or restrict public-facing interfaces, classes, methods, argument lists, or CLI structures (e.g., in the public package namespaces under `src/google/adk/`). Breaking changes are unacceptable without a formal deprecation cycle under Semantic Versioning.
+- **Execution & Resumption**: If changing workflows, nodes, or state management, ensure compatibility with the ADK 2.0 event execution lifecycle and session resumption (HITL/checkpoints).
+- **Concurrency & Safety**: Check for race conditions or resource leaks. Ensure long-running or shared resources (like plugins, exporters, and connections) are closed/disposed of safely.
+
+### 4. Documentation Impact (`docs/design` and `docs/guides`)
+- **Design & Architecture**: Determine if the change updates a core design contract. If so, check if design docs under `docs/design/` require updates or new documents need to be written.
+- **Guides**: If the changes introduce a new feature or change a public API/workflow pattern, check if the guides under `docs/guides/` need updates.
+
+### 5. Sample Compatibility & Updates
+- **Sample Integrity**: Verify if existing samples under `contributing/samples/` are affected by the change.
+- **New Samples**: If the changes introduce a key new capability, assess whether a new sample should be added to demonstrate the feature (following `adk-sample-creator` conventions).
+
+### 6. Test Coverage & Quality
+- **Coverage**: Ensure that all modified or new code paths have corresponding unit or integration tests under `tests/`.
+- **ADK Test Rules**: Ensure test implementations adhere to the 9 rules in the `adk-style` testing reference (e.g., using deterministic IDs, event normalization, and clean up utilities).
+
+---
+
+## Execution Workflow
+
+When the `adk-review` skill is triggered, you MUST execute the following steps:
+
+### Step 1: Retrieve Local Changes
+Run `git status` and `git diff` to identify exactly which files have been modified, added, or deleted.
+
+### Step 2: Perform the Multi-Dimensional Review
+Analyze the retrieved diffs file-by-file against the six dimensions in the Checklist. Identify any errors, deviations, or missing files (such as docs, tests, or samples).
+
+### Step 3: Generate and Present a Review Report
+Generate a clear, beautifully formatted Markdown report categorized by priority:
+- 🔴 **Critical Errors / Bugs**: Syntax, type safety violations, race conditions, or resource leaks.
+- 🟡 **Style & Conventions**: Lints, formatting issues, non-lazy logging, or typing mismatches.
+- 🔵 **Documentation, Tests, & Samples**: Missing or stale test coverage, design docs, or user guides.
+
+Include the specific filename and line number/context for each finding.
+
+### Step 4: Present Findings and Stop
+Stop execution here. Do **NOT** call any code editing tools or modify the codebase automatically. Present the generated review report clearly to the user, highlighting key takeaways, and stop.
+
+Do **NOT** ask the user if they want you to fix the issues, and do **NOT** offer interactive fixing options by default. Simply stop and wait for the user to explicitly command or ask you to fix the changes.
+
+### Step 5 (Optional): Implement Authorized Fixes & Verify
+If, and only if, the user explicitly instructs or requests you to apply a fix for some or all of the identified findings:
+1. Perform the necessary edits using precise code editing tools. Ensure all fixes strictly comply with the established `adk-style` and `adk-architecture` rules.
+2. Verify correctness by running associated unit and integration tests (e.g., via `pytest` or pre-commit hooks) before concluding.

.agents/skills/adk-review/SKILL.md

@@ -57,11 +57,12 @@ jobs:
                 console.log(`\n--- Processing commit ${sha.substring(0, 7)} ---`);
                 console.log(`Committer: ${committer}`);
 
-                // Check if this is a Copybara commit
+                // Check if this is a Copybara commit or has a pull request reference
                 const isCopybara = committer === 'Copybara-Service' ||
                                    commit.author?.email === 'genai-sdk-bot@google.com' ||
                                    message.includes('GitOrigin-RevId:') ||
-                                   message.includes('PiperOrigin-RevId:');
+                                   message.includes('PiperOrigin-RevId:') ||
+                                   /Merge:?\s+https:\/\/github\.com\/google\/adk-python\/pull\/(\d+)/.test(message);
 
                 if (!isCopybara) {
                   console.log('Not a Copybara commit, skipping');
@@ -118,6 +119,14 @@ jobs:
                   body: `Thank you @${author} for your contribution! 🎉\n\nYour changes have been successfully imported and merged via Copybara in commit ${commitSha}.\n\nClosing this PR as the changes are now in the main branch.`
                 });
 
+                // Add 'merged' label to the PR
+                await github.rest.issues.addLabels({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: prNumber,
+                  labels: ['merged']
+                });
+
                 // Close the PR
                 await github.rest.pulls.update({
                   owner: context.repo.owner,

.github/workflows/copybara-pr-handler.yml

@@ -14,6 +14,13 @@ For all matters regarding ADK development, please use the appropriate skill:
   - Read `.agents/skills/adk-git/SKILL.md` for full instructions.
 - **`adk-sample-creator`**: Use this skill when creating new samples demonstrating features or agent patterns, or when adding examples to subdirectories under `contributing/`.
   - Read `.agents/skills/adk-sample-creator/SKILL.md` for full instructions.
+- **`adk-review`**: Use this skill to review local changes for errors, style compliance, unintended outcomes, and to check if associated design docs, guides, samples, or tests need updates.
+  - Read `.agents/skills/adk-review/SKILL.md` for full instructions.
+- **`adk-issue`**: Use this skill when analyzing and triaging GitHub issues for the adk-python repository to verify legitimacy, recommend fixes, and check for existing PRs.
+  - Read `.agents/skills/adk-issue/SKILL.md` for full instructions.
+- **`adk-pr-triage`**: Use this skill when triaging and analyzing GitHub pull requests (PRs) to evaluate their objectives, legitimacy, value, and alignment with ADK's architectural, styling, and testing principles.
+  - Read `.agents/skills/adk-pr-triage/SKILL.md` for full instructions.
+
 
 ## Project Overview
 

AGENTS.md

@@ -12,8 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Agent definition for testing the Interactions API integration.
-"""
+"""Agent definition for testing the Interactions API integration."""
 
 from google.adk.agents.llm_agent import Agent
 from google.adk.models.google_llm import Gemini