Performance improvements findAgentToRun method

.github/workflows/analyze-releases-for-adk-docs-updates.yml

@@ -0,0 +1,85 @@
+name: Analyze New Release for ADK Docs Updates
+
+on:
+  # Runs on every new release.
+  release:
+    types: [published]
+  # Manual trigger for testing and retrying.
+  workflow_dispatch:
+    inputs:
+      start_tag:
+        description: 'Older release tag (base), e.g. v0.1.0'
+        required: false
+        type: string
+      end_tag:
+        description: 'Newer release tag (head), e.g. v0.2.0'
+        required: false
+        type: string
+      dry_run:
+        description: 'Dry run: preview only. Set to false to actually create the issue and PRs.'
+        required: false
+        default: true
+        type: boolean
+
+jobs:
+  analyze-new-release-for-adk-docs-updates:
+    runs-on: ubuntu-latest
+    # Dry-run reads only (this repo + the public docs repo) and skips writes, so
+    # the built-in GITHUB_TOKEN suffices. For --no-dry-run, use a PAT with write
+    # access to the docs repo.
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - name: Cache Maven packages
+        uses: actions/cache@v5
+        with:
+          path: ~/.m2/repository
+          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+          restore-keys: |
+            ${{ runner.os }}-maven-
+
+      - name: Run the ADK Docs Release Analyzer
+        env:
+          # Built-in token is enough for dry-run (read-only). For --no-dry-run, use a
+          # PAT with docs-repo write access, e.g. ${{ secrets.ADK_TRIAGE_AGENT }}.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+          GOOGLE_GENAI_USE_VERTEXAI: '0'
+          DOC_OWNER: 'google'
+          CODE_OWNER: 'google'
+          DOC_REPO: 'adk-docs'
+          CODE_REPO: 'adk-java'
+          ANALYZER_START_TAG: ${{ github.event.inputs.start_tag }}
+          ANALYZER_END_TAG: ${{ github.event.inputs.end_tag }}
+          # Defaults to dry-run (preview only). Flip to false via manual dispatch
+          # to actually create the issue and PRs.
+          ANALYZER_DRY_RUN: ${{ github.event.inputs.dry_run || 'true' }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ "${ANALYZER_DRY_RUN}" == "false" ]]; then
+            args="--no-dry-run"
+          else
+            args="--dry-run"
+          fi
+          if [[ -n "${ANALYZER_START_TAG:-}" ]]; then
+            args="${args} --start-tag ${ANALYZER_START_TAG}"
+          fi
+          if [[ -n "${ANALYZER_END_TAG:-}" ]]; then
+            args="${args} --end-tag ${ANALYZER_END_TAG}"
+          fi
+          # Install ADK libs + sample, then run exec:java scoped to this module
+          # (exec:java with -am would also run on the parent, which has no mainClass).
+          ./mvnw -B -q -pl contrib/samples/github/adkreleasedocs -am install -DskipTests
+          ./mvnw -B -q -pl contrib/samples/github/adkreleasedocs exec:java \
+            -Dexec.args="${args}"

.github/workflows/pr-title-check.yml

@@ -0,0 +1,31 @@
+# Validates that the PR title is a Conventional Commit. Pull requests are
+# squash-merged into a single commit (see pr-commit-check.yml), so the PR title
+# becomes the commit message release-please parses for versioning and changelog
+# generation.
+name: PR Title Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  check-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate Conventional Commit title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-zA-Z0-9][a-zA-Z0-9/]*[a-zA-Z0-9]\))?!?:.*[^.[:space:]]$'
+          if [[ "$PR_TITLE" =~ $pattern ]]; then
+            echo "PR title is a valid Conventional Commit: $PR_TITLE"
+          else
+            echo "::error::Invalid PR title: \"$PR_TITLE\""
+            echo "Expected: <type>[(scope)][!]: <description>"
+            echo "Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test"
+            echo "The description must not be empty and must not end with a period."
+            exit 1
+          fi

.github/workflows/pr-triage-adk-java.yml

@@ -0,0 +1,94 @@
+# Triages newly-opened (and reopened/edited) adk-java pull requests with the ADK
+# PR Triaging Agent sample under contrib/samples/github/adkprtriaging. The agent
+# labels the PR and, when it falls short of the contribution guidelines, posts a
+# single comment asking the author for the missing context.
+#
+# Required repository secrets:
+#   - GOOGLE_API_KEY    : Gemini API key (or wire up Vertex AI credentials and
+#                         set GOOGLE_GENAI_USE_VERTEXAI=TRUE).
+# Labeling/commenting uses the built-in GITHUB_TOKEN (no secret to manage); the
+# `permissions:` block below grants it the `pull-requests: write` scope it needs.
+# Swap in a PAT only if you specifically want triage actions attributed to a
+# distinct bot identity.
+#
+# Security note: this workflow uses `pull_request_target`, so it runs with the
+# base repository's token/secrets. It deliberately relies on the DEFAULT checkout
+# (the base branch) and never checks out the PR head, so untrusted PR code is
+# never executed — the agent only reads the PR through the GitHub API. The agent
+# additionally treats the PR title/body/diff as untrusted data, binds its writes
+# to the triggering PR number and a fixed label allowlist, and pins writes to
+# this repository (see the sample's README for the full threat model).
+name: ADK PR Triaging Agent
+
+on:
+  pull_request_target:
+    types: [opened, reopened, edited]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: 'The pull request number to triage'
+        required: true
+        type: 'string'
+      dry_run:
+        description: 'Dry run: preview only. Set to false to actually create the issue and PRs.'
+        required: false
+        default: true
+        type: boolean
+
+# Serialize runs that touch the same PR so a re-trigger (e.g. an "edited" event)
+# can't race an in-flight run on the same PR (which, with label appends, could
+# duplicate labels or comments).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.inputs.pr_number }}
+  cancel-in-progress: false
+
+jobs:
+  agent-triage-pull-request:
+    runs-on: ubuntu-latest
+    # Only run on the upstream repo, for newly-opened/reopened/edited PRs or a
+    # manual dispatch.
+    if: >-
+      github.repository == 'google/adk-java' && (
+        github.event_name == 'workflow_dispatch' ||
+        github.event.action == 'opened' ||
+        github.event.action == 'reopened' ||
+        github.event.action == 'edited'
+      )
+    permissions:
+      pull-requests: write
+      contents: read
+
+    steps:
+      # Default checkout: the base branch (trusted code), NOT the PR head.
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+          cache: maven
+
+      - name: Run PR Triaging Agent
+        env:
+          # Built-in token scoped by the `permissions:` block above. Replace with a
+          # PAT (e.g. ${{ secrets.ADK_TRIAGE_AGENT }}) only if you need a distinct
+          # bot identity for the label/comment actions.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+          GOOGLE_GENAI_USE_VERTEXAI: '0'
+          OWNER: ${{ github.repository_owner }}
+          REPO: ${{ github.event.repository.name }}
+          INTERACTIVE: '0'
+          # Defaults to a dry run (logs intended labels/comments without writing).
+          # Verify the pipeline, then set DRY_RUN to '0' to go live.
+          DRY_RUN: ${{ github.event.inputs.dry_run || 'true' }}
+          EVENT_NAME: ${{ github.event_name }}
+          PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number || github.event.inputs.pr_number }}
+        run: |
+          # Install the ADK libs + this sample, then run exec:java scoped to this
+          # module (exec:java with -am would also run on the parent/core modules,
+          # which have no mainClass).
+          ./mvnw -B -q -pl contrib/samples/github/adkprtriaging -am install -DskipTests
+          ./mvnw -B -q -pl contrib/samples/github/adkprtriaging exec:java

.github/workflows/spam-detection-adk-java-issues.yml

@@ -0,0 +1,94 @@
+# Scans adk-java issues for spam/promotional content with the ADK Issue
+# Monitoring (Spam Detection) Agent sample under
+# contrib/samples/github/adkspam.
+#
+# Required repository secrets:
+#   - GOOGLE_API_KEY    : Gemini API key (or wire up Vertex AI credentials and
+#                         set GOOGLE_GENAI_USE_VERTEXAI=TRUE).
+# Labeling/commenting uses the built-in GITHUB_TOKEN (no secret to manage); the
+# `permissions:` block below grants it the `issues: write` scope it needs. Swap
+# in a PAT only if you specifically want the spam label/alert comment attributed
+# to a distinct bot identity.
+#
+# NOTE: the `spam` label (or whatever SPAM_LABEL_NAME is set to) must already
+# exist in the repository's labels; the agent applies it but does not create it.
+name: ADK Issue Monitoring (Spam Detection) Agent
+
+on:
+  issues:
+    types: [opened]
+  schedule:
+    # Run daily at 06:00 UTC, matching the Python issue-monitor workflow.
+    - cron: '0 6 * * *'
+  workflow_dispatch:
+    inputs:
+      full_scan:
+        description: 'Audit ALL open issues (not just those updated in the last 24h).'
+        required: false
+        default: false
+        type: boolean
+      dry_run:
+        description: 'Dry run: preview only. Set to false to actually create the issue and PRs.'
+        required: false
+        default: true
+        type: boolean
+
+# Serialize runs that touch the same issue so the scheduled sweep can't race a
+# per-issue run on that issue.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.issue.number || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  agent-scan-issues:
+    runs-on: ubuntu-latest
+    # Only run on the upstream repo, for newly-opened issues, the scheduled
+    # sweep, or a manual dispatch.
+    if: >-
+      github.repository == 'google/adk-java' && (
+        github.event_name == 'schedule' ||
+        github.event_name == 'workflow_dispatch' ||
+        github.event.action == 'opened'
+      )
+    permissions:
+      issues: write
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+          cache: maven
+
+      - name: Run Spam Detection Agent
+        env:
+          # Built-in token scoped by the `permissions:` block above. Replace with a
+          # PAT (e.g. ${{ secrets.ADK_TRIAGE_AGENT }}) only if you need a distinct
+          # bot identity for the label/comment actions.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+          GOOGLE_GENAI_USE_VERTEXAI: '0'
+          OWNER: ${{ github.repository_owner }}
+          REPO: ${{ github.event.repository.name }}
+          INTERACTIVE: '0'
+          # Defaults to a dry run (logs intended labels/comments without writing).
+          # Verify the pipeline, then set DRY_RUN to '0' to go live.
+          DRY_RUN: ${{ github.event.inputs.dry_run || 'true' }}
+          EVENT_NAME: ${{ github.event_name }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          ISSUE_BODY: ${{ github.event.issue.body }}
+          # Mapped to the manual-dispatch checkbox. On the daily schedule this is
+          # empty, so only issues updated in the last 24h are audited.
+          INITIAL_FULL_SCAN: ${{ github.event.inputs.full_scan }}
+        run: |
+          # Install the ADK libs + this sample, then run exec:java scoped to this
+          # module (exec:java with -am would also run on the parent/core modules,
+          # which have no mainClass).
+          ./mvnw -B -q -pl contrib/samples/github/adkspam -am install -DskipTests
+          ./mvnw -B -q -pl contrib/samples/github/adkspam exec:java

.github/workflows/stale-adk-java-issues.yml

@@ -0,0 +1,85 @@
+# Audits stale adk-java issues with the ADK Stale Issue Auditor sample under
+# contrib/samples/github/adkstale.
+#
+# Required repository secrets:
+#   - GOOGLE_API_KEY    : Gemini API key (or wire up Vertex AI credentials and
+#                         set GOOGLE_GENAI_USE_VERTEXAI=TRUE).
+# Commenting/labelling/closing uses the built-in GITHUB_TOKEN (no secret to
+# manage); the `permissions:` block below grants it the `issues: write` scope it
+# needs. Swap in a PAT only if you specifically want stale actions attributed to
+# a distinct bot identity.
+#
+# Prerequisite: the `stale` label (and, if used, `request clarification`) must
+# exist in the repository; GitHub will not auto-create labels when the agent
+# applies them.
+name: ADK Stale Issue Auditor
+
+on:
+  schedule:
+    # Run daily at 06:00 UTC.
+    - cron: '0 6 * * *'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Dry run: preview only. Set to false to actually create the issue and PRs.'
+        required: false
+        default: true
+        type: boolean
+
+# Serialize runs so an in-flight daily sweep can't overlap a manual dispatch and
+# act on the same issues twice.
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  agent-audit-stale-issues:
+    runs-on: ubuntu-latest
+    # Only run on the upstream repo, on the daily schedule or a manual dispatch.
+    if: >-
+      github.repository == 'google/adk-java' && (
+        github.event_name == 'schedule' ||
+        github.event_name == 'workflow_dispatch'
+      )
+    permissions:
+      issues: write
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+          cache: maven
+
+      - name: Run Stale Issue Auditor
+        env:
+          # Built-in token scoped by the `permissions:` block above. Replace with a
+          # PAT (e.g. ${{ secrets.ADK_STALE_AGENT }}) only if you need a distinct
+          # bot identity for the comment/label/close actions.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+          GOOGLE_GENAI_USE_VERTEXAI: '0'
+          OWNER: ${{ github.repository_owner }}
+          REPO: ${{ github.event.repository.name }}
+          INTERACTIVE: '0'
+          # Defaults to a dry run (logs intended comments/labels/closures without
+          # writing). Flip to false via manual dispatch to actually mark as stale.
+          DRY_RUN: ${{ github.event.inputs.dry_run || 'true' }}
+          EVENT_NAME: ${{ github.event_name }}
+          # Max number of stale-candidate issues to audit per run.
+          ISSUE_COUNT_TO_PROCESS: '20'
+          # Optional: comma-separated GitHub handles to treat as maintainers when
+          # the token cannot list push-access collaborators. Stored as a repo
+          # variable rather than committed to source.
+          MAINTAINERS: ${{ vars.ADK_MAINTAINERS }}
+        run: |
+          # Install the ADK libs + this sample, then run exec:java scoped to this
+          # module (exec:java with -am would also run on the parent/core modules,
+          # which have no mainClass).
+          ./mvnw -B -q -pl contrib/samples/github/adkstale -am install -DskipTests
+          ./mvnw -B -q -pl contrib/samples/github/adkstale exec:java