[#572] Implement Teams API Drift Detector workflow

[ceciliaavila]

Fixes # 572

Description

This pull request introduces a new GitHub Actions workflow, teams-api-drift-prs.yml, to automatically detect and report API drift for the Microsoft Teams API dependency in pull requests that modify the relevant setup.py. The workflow determines if the dependency version has changed, runs compatibility and contract tests, generates detailed reports (including an AI-generated advisory), and publishes a summary comment on the PR with actionable findings and downloadable artifacts.

The most important changes are:

New workflow for Teams API drift detection:

• Added .github/workflows/teams-api-drift-prs.yml to automate detection of API drift in microsoft-teams-api dependency changes within libraries/microsoft-agents-hosting-msteams/setup.py on PRs and workflow dispatch events.

Automated compatibility and contract testing:

• The workflow checks out the code, resolves old and new dependency versions, installs required tools, and runs both static and runtime compatibility tests (using mypy and pytest) to verify extension compatibility with the new API version.

Automated report generation and publishing:

• Generates a deterministic report summarizing API changes, test results, and compatibility findings, and uploads all evidence as workflow artifacts for transparency and traceability.
• Publishes a summary comment on the pull request with key actionable findings and a link to download the full report and

Testing

These images show the workflows working and the issues/PR comment generated.

[Copilot]

🟡 Changes recommended

The PR workflow can fail when findings.json is not produced (e.g., classification skipped) because the PR-comment step reads it unconditionally, and there is also a small maintainability fix needed in the report context bounds.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds deterministic Teams API drift detection tooling and CI workflows to assess the impact of changing the microsoft-teams-api dependency used by microsoft-agents-hosting-msteams, producing artifacts/reports (and optionally an AI advisory) for maintainers.

Changes:

• Added a new PR workflow and a scheduled workflow to detect Teams API drift, run compatibility checks, upload artifacts, and publish summaries (PR comment / scheduled issue).
• Introduced a new scripts/teams-api-drift toolchain (resolve/compare/classify/report/context validation) plus focused tests that validate determinism, redaction, and report contracts.
• Added/updated package metadata and configuration (Teams API exact pin in hosting-msteams, usage manifest + capabilities map, dev deps/docs/gitignore).

File summaries

File	Description
.github/workflows/teams-api-drift-prs.yml	PR workflow to resolve versions, compare APIs, run tests, upload artifacts, and comment on PRs.
.github/workflows/teams-api-drift-scheduled.yml	Scheduled workflow to compare pinned vs latest stable, upload artifacts, and upsert an advisory issue.
.gitignore	Ignores local Teams API drift artifacts directory.
dev_dependencies.txt	Adds dev dependencies needed by drift tooling (packaging/PyYAML).
libraries/microsoft-agents-hosting-msteams/config/teams-capabilities.yaml	Capability ownership + adoption policy mapping for Teams API areas.
libraries/microsoft-agents-hosting-msteams/pyproject.toml	Adjusts setuptools package discovery configuration.
libraries/microsoft-agents-hosting-msteams/setup.py	Pins microsoft-teams-api to an exact version required by the drift tooling.
libraries/microsoft-agents-hosting-msteams/teams-api-usage-manifest.json	Curated usage manifest used to classify upstream API changes by real SDK usage.
scripts/README.md	Links to the Teams API drift detection documentation.
scripts/teams-api-drift/README.md	Documents local usage, evidence artifacts, and workflow behavior/policies.
scripts/teams-api-drift/mypy.ini	Mypy config for strict contract checking against upstream types.
scripts/teams-api-drift/requirements.txt	Tooling-only pinned requirements for drift analysis and report generation.
scripts/teams-api-drift/teams-api-agent-report-prompt.md	Prompt contract for AI advisory report generation and validation.
scripts/teams-api-drift/teams-api-drift.py	CLI entrypoint wrapper for the drift tooling.
scripts/teams-api-drift/teams_api_drift/__init__.py	Defines drift tooling package version metadata.
scripts/teams-api-drift/teams_api_drift/candidate.py	Builds and installs local SDK wheels into the candidate environment for validation.
scripts/teams-api-drift/teams_api_drift/classify.py	Classifies upstream API diffs using curated usage + capability policy.
scripts/teams-api-drift/teams_api_drift/cli.py	Implements drift CLI subcommands (resolve/compare/detect/render/prepare/validate/etc.).
scripts/teams-api-drift/teams_api_drift/common.py	Shared utilities (artifact IO/validation, safe setup.py parsing, subprocess runner).
scripts/teams-api-drift/teams_api_drift/compare.py	Installs exact upstream versions, extracts API models, produces deterministic diffs.
scripts/teams-api-drift/teams_api_drift/extract.py	Extracts a normalized API model from installed upstream packages (deterministic formatting).
scripts/teams-api-drift/teams_api_drift/report.py	Renders deterministic report, bounds/redacts context for AI report generation/validation.
scripts/teams-api-drift/teams_api_drift/resolve.py	Resolves exact pinned baseline/candidate versions from setup.py sources.
tests/hosting_msteams/test_api_boundaries.py	Adds runtime boundary tests to validate behavior against real upstream models/clients.
tests/teams_api_drift/conftest.py	Ensures drift tooling is importable in test runs without shipping it in SDK distributions.
tests/teams_api_drift/test_analysis.py	Unit tests for parsing, version resolution, comparison/classification behavior.
tests/teams_api_drift/test_contracts.py	Mypy-only contract tests verifying consumed upstream types remain compatible.
tests/teams_api_drift/test_extraction.py	Tests for deterministic type extraction/model representation.
tests/teams_api_drift/test_reports.py	Tests report determinism, validation rules, context bounding/redaction.

Review details

• Files reviewed: 28/29 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.