docs(teams): split meetings setup from operator runbook (salvage of #21412)#22042
Merged
Conversation
Fifth and final slice polish on top of @dlkakbs's docs + skill. Three things ship here: 1. Subscription renewal cron recipe (the #1 operational footgun). Microsoft Graph webhook subscriptions expire at 72 hours max and don't auto-renew. The shipped operator runbook mentioned `maintain-subscriptions --dry-run` as a "daily or periodic check" but never told operators how to actually automate it. Without a scheduled job, any production deployment silently stops ingesting meetings three days after go-live. Adds an "Automating subscription renewal (REQUIRED for production)" section to website/docs/guides/operate-teams-meeting-pipeline.md with three concrete options and copy-pasteable configs: - Option 1: Hermes cron (`hermes cron add --schedule "0 */12 * * *" --script-only --command "hermes teams-pipeline maintain-subscriptions"`) - Option 2: systemd service + timer (12h cadence, Persistent=true so missed runs catch up after reboots) - Option 3: plain crontab with a wrapper that sources .env for credentials Go-Live Checklist gains a bolded mandatory item for the schedule being in place, with a cross-link to the section. website/docs/user-guide/messaging/teams-meetings.md adds a `:::warning:::` admonition right after the manual `subscribe` examples so anyone who creates a subscription manually is told the same day that it will silently expire in 72 hours. 2. Sidebar wiring. Shela's new docs pages (teams-meetings.md and operate-teams-meeting-pipeline.md) weren't in website/sidebars.ts, so they were orphaned URLs — reachable only if someone knew the path. Wired teams-meetings into Messaging Platforms next to the existing teams entry, and operate-teams-meeting-pipeline into Guides & Tutorials next to microsoft-graph-app-registration from PR #21922. Adjacent placement keeps the related pages discoverable from each other. 3. SKILL.md rewrite (v1.0.0 → v1.1.0). The original skill had five Turkish-only trigger phrases, which works in a Turkish-speaking session but doesn't match English triggers. Rewrote the skill to: - Describe triggers by intent instead of exact phrases, with explicit "works in any language" framing and example phrases in both English and Turkish. - Add a Decision Tree section covering the three most common user asks (missing summary, setup verification, re-run request) and the specific CLI command sequence for each. - Add a dedicated "Critical pitfall: Graph subscriptions expire in 72 hours" section that tells the agent exactly what to do when a user reports "worked yesterday, nothing today" — the most common operational failure mode. - Expand the command reference into three labeled groups (Status and inspection / Re-running and debugging / Subscription management) so the agent can reach for the right command without scanning. - Add cross-links to all four related docs pages (Azure app registration, webhook listener setup, full pipeline setup, operator runbook). Validation: - npm run build: all new pages route, anchor to #automating-subscription-renewal-required-for-production resolves from both the runbook TOC and the teams-meetings.md admonition. - scripts/run_tests.sh on the relevant test suites (607 tests): all pass.
Contributor
🔎 Lint report:
|
| Rule | Count |
|---|---|
invalid-argument-type |
3 |
First entries
run_agent.py:12805: [invalid-argument-type] invalid-argument-type: Argument to function `_is_oauth_token` is incorrect: Expected `str`, found `str | dict[Unknown | str, Unknown | str | dict[str, str]] | Any | ... omitted 3 union elements`
run_agent.py:6811: [invalid-argument-type] invalid-argument-type: Argument to function `build_anthropic_client` is incorrect: Expected `str`, found `str | dict[Unknown | str, Unknown | str | dict[str, str]] | Any | ... omitted 3 union elements`
run_agent.py:12808: [invalid-argument-type] invalid-argument-type: Argument to function `len` is incorrect: Expected `Sized`, found `(str & ~AlwaysFalsy) | (dict[Unknown | str, Unknown | str | dict[str, str]] & ~AlwaysFalsy) | (Any & ~AlwaysFalsy) | ... omitted 3 union elements`
✅ Fixed issues (3):
| Rule | Count |
|---|---|
invalid-argument-type |
3 |
First entries
run_agent.py:12805: [invalid-argument-type] invalid-argument-type: Argument to function `_is_oauth_token` is incorrect: Expected `str`, found `str | dict[Unknown, Unknown] | Any | ... omitted 3 union elements`
run_agent.py:6811: [invalid-argument-type] invalid-argument-type: Argument to function `build_anthropic_client` is incorrect: Expected `str`, found `str | dict[Unknown, Unknown] | Any | ... omitted 3 union elements`
run_agent.py:12808: [invalid-argument-type] invalid-argument-type: Argument to function `len` is incorrect: Expected `Sized`, found `(str & ~AlwaysFalsy) | (dict[Unknown, Unknown] & ~AlwaysFalsy) | (Any & ~AlwaysFalsy) | ... omitted 3 union elements`
Unchanged: 4092 pre-existing issues carried over.
Diagnostics are surfaced as warnings — this check never fails the build.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Salvage of #21412 onto current
main, with the subscription-renewal cron recipe, sidebar wiring, and a rewritten SKILL.md on top.Fifth and final slice of the MS Teams meeting pipeline stack. @dlkakbs's split (setup page + operator runbook + skill asset) lands cleanly; we add the three things needed to make the docs actually work in practice.
Credit to @dlkakbs — her two commits are preserved via rebase-merge.
Changes
From @dlkakbs (unchanged):
website/docs/user-guide/messaging/teams-meetings.md(new, 227 lines) — full setup page: prerequisites, Graph credentials, webhook listener, delivery config, subscription creation, validation, troubleshooting.website/docs/guides/operate-teams-meeting-pipeline.md(new, 193 lines) — operator runbook: core commands, routine runbook, failure triage, go-live checklist, delivery-mode decision guide, operator worksheet, change review worksheet.website/docs/user-guide/messaging/teams.md— cross-link to the meetings page.website/docs/user-guide/messaging/index.md— meetings entry in the platform index.skills/productivity/teams-meeting-pipeline/SKILL.md(new) — initial agent-facing skill.tests/gateway/test_teams.py—@pytest.mark.asyncio→@pytest.mark.anyioconsistency fix across the file.Follow-ups added on top during salvage:
Subscription renewal cron recipe (the Terminal tool #1 operational footgun).
Microsoft Graph caps webhook subscriptions at 72 hours and does NOT auto-renew. Without a scheduled
maintain-subscriptionsjob, any production deployment silently stops ingesting meetings three days after go-live. Added an "Automating subscription renewal (REQUIRED for production)" section to the operator runbook with three concrete options (Hermes cron, systemd timer, plain crontab), copy-pasteable configs, and a verification block. Go-Live Checklist gains a bolded mandatory item.teams-meetings.mdgets a:::warning:::admonition next to the manualsubscribeexamples so any operator creating a subscription manually is told the same day that it will expire.Sidebar wiring. Shela's two new docs pages weren't in
website/sidebars.ts, so they were orphaned URLs — reachable only by knowing the path. Wiredteams-meetingsinto Messaging Platforms next to the existingteamsentry, andoperate-teams-meeting-pipelineinto Guides & Tutorials next tomicrosoft-graph-app-registration. Adjacent placement keeps related pages cross-discoverable.SKILL.md rewrite (v1.0.0 → v1.1.0). The original skill had five Turkish-only trigger phrases. Rewrote the skill to:
What this PR enables end-to-end
Merging this closes the entire #21408-#21412 stack. The pipeline is now:
hermes teams-pipelineis a real CLI, the skill teaches the agent to use it, the webhook listener ingests Graph notifications.Validation
scripts/run_tests.shon the relevant suites (tests/gateway/test_teams.py,tests/plugins/,tests/gateway/test_msgraph_webhook.py,tests/hermes_cli/test_teams_pipeline_plugin_cli.py) — 607/607 passed.npm run buildinwebsite/— new pages route at/docs/user-guide/messaging/teams-meetingsand/docs/guides/operate-teams-meeting-pipeline, anchor#automating-subscription-renewal-required-for-productionresolves from both the TOC and the cross-link fromteams-meetings.md, no new warnings or errors.Closes #21412. Closes the entire stack.