mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-09 03:11:58 +00:00
docs(teams-pipeline): cron renewal recipe, sidebar wiring, skill rewrite
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 `::⚠️::` 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.
This commit is contained in:
Teknium
parent
729a659a3c
commit
242da9db96
4 changed files with 179 additions and 21 deletions
|
|
@ -1,8 +1,8 @@
|
|||
---
|
||||
name: teams-meeting-pipeline
|
||||
description: "Operate the Teams meeting summary pipeline via Hermes CLI."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
description: "Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions."
|
||||
version: 1.1.0
|
||||
author: Hermes Agent + Teknium
|
||||
license: MIT
|
||||
prerequisites:
|
||||
env_vars: [MSGRAPH_TENANT_ID, MSGRAPH_CLIENT_ID, MSGRAPH_CLIENT_SECRET]
|
||||
|
|
@ -10,25 +10,36 @@ prerequisites:
|
|||
metadata:
|
||||
hermes:
|
||||
tags: [Teams, Microsoft Graph, Meetings, Productivity, Operations]
|
||||
related_docs:
|
||||
- /docs/guides/microsoft-graph-app-registration
|
||||
- /docs/user-guide/messaging/teams-meetings
|
||||
- /docs/guides/operate-teams-meeting-pipeline
|
||||
---
|
||||
|
||||
# Teams Meeting Pipeline
|
||||
|
||||
Use this skill when the user asks to summarize a Teams meeting, extract action items, inspect pipeline status, replay a stored job, or validate Microsoft Graph meeting-ingest setup.
|
||||
Use this skill whenever the user asks about Microsoft Teams meeting summaries, transcripts, recordings, action items, Graph subscriptions, or any operational question about the Teams meeting pipeline. Works in any language — the triggers below are examples, not an exhaustive list.
|
||||
|
||||
Prefer the Hermes CLI over ad hoc scripts. Route operator actions through the terminal tool with `hermes teams-pipeline ...`.
|
||||
Everything operator-facing is a `hermes teams-pipeline` subcommand run via the terminal tool. There are no new model tools for this pipeline — the CLI is the surface.
|
||||
|
||||
## When to use
|
||||
## When to use this skill
|
||||
|
||||
- "Teams meeting ozetle"
|
||||
- "action item cikar"
|
||||
- "toplanti notu"
|
||||
- "pipeline durumu"
|
||||
- "replay job"
|
||||
The user is asking to:
|
||||
- summarize a Teams meeting / extract action items / pull meeting notes
|
||||
- check pipeline status, inspect a stored meeting job, or see recent meetings
|
||||
- replay / re-run a stored job that failed or needs a fresh summary
|
||||
- validate Microsoft Graph setup after changing env or config
|
||||
- troubleshoot "meeting summary never arrived" or "no new meetings are ingesting"
|
||||
- manage Graph webhook subscriptions (create, renew, delete, inspect)
|
||||
- set up automated subscription renewal (see pitfall below)
|
||||
|
||||
## Required environment
|
||||
Multilingual trigger examples (not exhaustive):
|
||||
- English: "summarize the Teams meeting", "pipeline status", "replay job X"
|
||||
- Turkish: "Teams meeting özetle", "action item çıkar", "toplantı notu", "pipeline durumu", "replay job"
|
||||
|
||||
Set these in `~/.hermes/.env` before using the pipeline:
|
||||
## Prerequisites
|
||||
|
||||
Before using the pipeline, verify these are set in `~/.hermes/.env`:
|
||||
|
||||
```bash
|
||||
MSGRAPH_TENANT_ID=...
|
||||
|
|
@ -36,15 +47,70 @@ MSGRAPH_CLIENT_ID=...
|
|||
MSGRAPH_CLIENT_SECRET=...
|
||||
```
|
||||
|
||||
## Common commands
|
||||
If any are missing, direct the user to the Azure app registration guide at `/docs/guides/microsoft-graph-app-registration` — they need an Azure AD app registration with admin-consented Graph application permissions before the pipeline will work.
|
||||
|
||||
## Command reference
|
||||
|
||||
### Status and inspection (start here)
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline list
|
||||
hermes teams-pipeline show <job-id>
|
||||
hermes teams-pipeline replay <job-id>
|
||||
hermes teams-pipeline fetch --meeting-id <meeting-id>
|
||||
hermes teams-pipeline token-health
|
||||
hermes teams-pipeline maintain-subscriptions
|
||||
hermes teams-pipeline validate # config snapshot — run first after any change
|
||||
hermes teams-pipeline token-health # Graph token status
|
||||
hermes teams-pipeline token-health --force-refresh # force a fresh token acquisition
|
||||
hermes teams-pipeline list # recent meeting jobs
|
||||
hermes teams-pipeline list --status failed # only failed jobs
|
||||
hermes teams-pipeline show <job-id> # full detail of one job
|
||||
hermes teams-pipeline subscriptions # current Graph webhook subscriptions
|
||||
```
|
||||
|
||||
Start with `validate`, `list`, or `show` when the user asks for status. Use `replay` only when they explicitly want to rerun a stored job. Use `fetch` for dry-run artifact checks before changing pipeline config.
|
||||
### Re-running / debugging
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline run <job-id> # replay a stored job (re-summarize, re-deliver)
|
||||
hermes teams-pipeline fetch --meeting-id <id> # dry-run: resolve meeting + transcript without persisting
|
||||
hermes teams-pipeline fetch --join-web-url "<url>" # dry-run by join URL
|
||||
```
|
||||
|
||||
### Subscription management
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline subscribe \
|
||||
--resource communications/onlineMeetings/getAllTranscripts \
|
||||
--notification-url https://<your-public-host>/msgraph/webhook \
|
||||
--client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"
|
||||
|
||||
hermes teams-pipeline renew-subscription <sub-id> --expiration <iso-8601>
|
||||
hermes teams-pipeline delete-subscription <sub-id>
|
||||
hermes teams-pipeline maintain-subscriptions # renew near-expiry ones
|
||||
hermes teams-pipeline maintain-subscriptions --dry-run # show what would be renewed
|
||||
```
|
||||
|
||||
## Decision tree for common asks
|
||||
|
||||
- User asks "why didn't I get a summary for today's meeting?" → start with `list --status failed`, then `show <job-id>` on the relevant row. If the job doesn't exist at all, check `subscriptions` — the webhook may have expired (see pitfall below).
|
||||
- User asks "is setup working?" → `validate`, then `token-health`, then `subscriptions`. If all three pass, request a test meeting and check `list` for a fresh row.
|
||||
- User asks "re-run summary for meeting X" → `list` to find the job ID, `run <job-id>` to replay. If it fails again, `show <job-id>` to inspect the error and `fetch --meeting-id` to dry-run the artifact resolution.
|
||||
- User asks "add meeting X to the pipeline" → usually you don't — the pipeline is subscription-driven, not per-meeting. If they want a specific past meeting summarized, use `fetch` to pull transcript + `run` after a job is created.
|
||||
|
||||
## Critical pitfall: Graph subscriptions expire in 72 hours
|
||||
|
||||
Microsoft Graph caps webhook subscriptions at 72 hours and **will not auto-renew them**. If `maintain-subscriptions` is not scheduled, meeting notifications silently stop arriving 3 days after any manual subscription creation.
|
||||
|
||||
When the user reports "the pipeline worked yesterday but nothing is arriving today":
|
||||
1. Run `hermes teams-pipeline subscriptions` — if it's empty or all entries show `expirationDateTime` in the past, that's the cause.
|
||||
2. Recreate with `subscribe` as shown above.
|
||||
3. **Set up automated renewal immediately** via `hermes cron add`, a systemd timer, or plain crontab. The operator runbook at `/docs/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production` has all three options. 12-hour interval is safe (6x headroom against the 72h limit).
|
||||
|
||||
## Other pitfalls
|
||||
|
||||
- **Transcript not available yet.** Teams takes some time after a meeting ends to generate the transcript artifact. `fetch --meeting-id` on a just-ended meeting may return empty. Wait 2-5 minutes and retry, or let the Graph webhook drive ingestion naturally.
|
||||
- **Delivery mode mismatch.** If summaries are produced (`list` shows success) but nothing lands in Teams, check `platforms.teams.extra.delivery_mode` and the matching target config (`incoming_webhook_url` OR `chat_id` OR `team_id`+`channel_id`). The writer reads these from config.yaml or `TEAMS_*` env vars.
|
||||
- **Graph app permissions.** A token acquires cleanly (`token-health` passes) but Graph API calls return 401/403 when permissions were added but admin consent wasn't re-granted. Have the user revisit the app registration in the Azure portal and click "Grant admin consent" again.
|
||||
|
||||
## Related docs
|
||||
|
||||
Point the user to these when they need more depth than this skill covers:
|
||||
- Azure app registration walkthrough: `/docs/guides/microsoft-graph-app-registration`
|
||||
- Full pipeline setup: `/docs/user-guide/messaging/teams-meetings`
|
||||
- Operator runbook (renewal automation, troubleshooting, go-live checklist): `/docs/guides/operate-teams-meeting-pipeline`
|
||||
- Webhook listener setup: `/docs/user-guide/messaging/msgraph-webhook`
|
||||
|
|
|
|||
|
|
@ -46,6 +46,89 @@ hermes teams-pipeline maintain-subscriptions
|
|||
hermes teams-pipeline maintain-subscriptions --dry-run
|
||||
```
|
||||
|
||||
### Automating subscription renewal (REQUIRED for production)
|
||||
|
||||
**Microsoft Graph subscriptions expire in at most 72 hours.** If nothing renews them, meeting notifications silently stop after 3 days and the pipeline looks "broken." This is the #1 operational failure mode for any Graph-backed integration.
|
||||
|
||||
You MUST run `maintain-subscriptions` on a schedule. Pick one of these three options:
|
||||
|
||||
#### Option 1: Hermes cron (recommended if you already run the Hermes gateway)
|
||||
|
||||
Hermes ships a built-in cron scheduler. Add a script-only cron job that runs every 12 hours (gives 6x headroom against the 72h expiry window):
|
||||
|
||||
```bash
|
||||
hermes cron add \
|
||||
--name "teams-pipeline-maintain-subscriptions" \
|
||||
--schedule "0 */12 * * *" \
|
||||
--script-only \
|
||||
--command "hermes teams-pipeline maintain-subscriptions"
|
||||
```
|
||||
|
||||
Verify it was registered and inspect the next run time:
|
||||
|
||||
```bash
|
||||
hermes cron list
|
||||
hermes cron show teams-pipeline-maintain-subscriptions
|
||||
```
|
||||
|
||||
#### Option 2: systemd timer (recommended for Linux production deployments)
|
||||
|
||||
Create `/etc/systemd/system/hermes-teams-pipeline-maintain.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Hermes Teams pipeline subscription maintenance
|
||||
After=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
User=hermes
|
||||
EnvironmentFile=/etc/hermes/env
|
||||
ExecStart=/usr/local/bin/hermes teams-pipeline maintain-subscriptions
|
||||
```
|
||||
|
||||
And `/etc/systemd/system/hermes-teams-pipeline-maintain.timer`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Run Hermes Teams pipeline subscription maintenance every 12 hours
|
||||
|
||||
[Timer]
|
||||
OnBootSec=5min
|
||||
OnUnitActiveSec=12h
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
```
|
||||
|
||||
Enable:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now hermes-teams-pipeline-maintain.timer
|
||||
systemctl list-timers hermes-teams-pipeline-maintain.timer
|
||||
```
|
||||
|
||||
#### Option 3: Plain crontab
|
||||
|
||||
```cron
|
||||
0 */12 * * * /usr/local/bin/hermes teams-pipeline maintain-subscriptions >> /var/log/hermes/teams-pipeline-maintain.log 2>&1
|
||||
```
|
||||
|
||||
Make sure the cron environment has the `MSGRAPH_*` credentials. Simplest fix: source `~/.hermes/.env` at the top of a wrapper script that crontab calls.
|
||||
|
||||
#### Verifying renewal is working
|
||||
|
||||
After you've set up the schedule, check renewal activity after the first scheduled run:
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline subscriptions # should show expirationDateTime advanced
|
||||
hermes teams-pipeline maintain-subscriptions --dry-run # should show "0 expiring soon" most of the time
|
||||
```
|
||||
|
||||
If you ever see your Graph webhook mysteriously "stop working" after exactly ~72 hours, this is the first thing to check: did the renewal job actually run?
|
||||
|
||||
### Inspect recent jobs
|
||||
|
||||
```bash
|
||||
|
|
@ -145,6 +228,7 @@ Check:
|
|||
- [ ] Notion and Linear sinks are configured only if actually needed
|
||||
- [ ] `hermes teams-pipeline validate` returns an OK snapshot
|
||||
- [ ] `hermes teams-pipeline token-health --force-refresh` succeeds
|
||||
- [ ] **`maintain-subscriptions` is scheduled** (Hermes cron, systemd timer, or crontab — see [Automating subscription renewal](#automating-subscription-renewal-required-for-production)). Without this, Graph subscriptions silently expire within 72 hours.
|
||||
- [ ] a real end-to-end meeting event has produced a stored job
|
||||
- [ ] at least one summary has reached the intended delivery sink
|
||||
|
||||
|
|
|
|||
|
|
@ -194,6 +194,12 @@ hermes teams-pipeline subscribe \
|
|||
--client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"
|
||||
```
|
||||
|
||||
:::warning Graph subscriptions expire in 72 hours
|
||||
|
||||
Microsoft Graph caps webhook subscriptions at 72 hours and will not auto-renew them. You MUST schedule `hermes teams-pipeline maintain-subscriptions` before going live, or notifications will silently stop three days after any manual subscription creation. See [Automating subscription renewal](/docs/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production) in the operator runbook — three options (Hermes cron, systemd timer, plain crontab).
|
||||
|
||||
:::
|
||||
|
||||
For subscription maintenance and day-2 operator flows, continue with the guide: [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline).
|
||||
|
||||
## Validation
|
||||
|
|
|
|||
|
|
@ -138,6 +138,7 @@ const sidebars: SidebarsConfig = {
|
|||
'user-guide/messaging/qqbot',
|
||||
'user-guide/messaging/yuanbao',
|
||||
'user-guide/messaging/teams',
|
||||
'user-guide/messaging/teams-meetings',
|
||||
'user-guide/messaging/msgraph-webhook',
|
||||
'user-guide/messaging/open-webui',
|
||||
'user-guide/messaging/webhooks',
|
||||
|
|
@ -185,6 +186,7 @@ const sidebars: SidebarsConfig = {
|
|||
'guides/aws-bedrock',
|
||||
'guides/azure-foundry',
|
||||
'guides/microsoft-graph-app-registration',
|
||||
'guides/operate-teams-meeting-pipeline',
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue