@yemi33/minions 0.1.2448 → 0.1.2449

package/watch-plugins/teams-channel.js

@@ -0,0 +1,869 @@
+/**
+ * watch-plugins/teams-channel.js — Watch a Microsoft Teams channel for messages
+ *
+ * Use case: trigger a registered watch action for each new root message or
+ * reply in a configured Microsoft Teams channel.
+ *
+ * ── Target syntax ───────────────────────────────────────────────────────────
+ *   target: 'teamId:channelId'
+ *     → bare colon-delimited string. The first ':' splits team / channel.
+ *       Channel ids have additional colons (`19:foo@thread.skype`); the
+ *       parser uses indexOf — NOT lastIndexOf — so the channel side keeps its
+ *       internal `:`.
+ *
+ *   target: { teamId, channelId }
+ *     → explicit form. Same semantics.
+ *
+ * ── Conditions ──────────────────────────────────────────────────────────────
+ *   new-message — fires once per newly-observed message id. The candidate
+ *                 set includes BOTH root messages and thread replies, with
+ *                 system messages excluded. Each candidate carries
+ *                 `rootMessageId` (= the root for replies, = `id` for roots)
+ *                 and an `isReply` boolean.
+ *
+ * Burst handling: when N new messages land between ticks, the plugin
+ * advances its seen-set by exactly ONE per evaluation. The watch fires once
+ * per tick until the backlog drains — zero messages are lost even if a
+ * human posts five in the same minute. Costs ~30s × N to drain (one tick
+ * per message at the interval cadence).
+ *
+ * First tick after watch creation MUST NOT fire — the engine seeds
+ * `_lastState` by calling captureState() before evaluate() on the first
+ * check, so the entire baseline message set lands in prevState before
+ * evaluate runs. New messages only start firing from tick 2 onward.
+ *
+ * ── Templating vars exposed to actions ──────────────────────────────────────
+ *   {{messageId}}, {{messageBody}} (HTML stripped, truncated to 2KB),
+ *   {{authorDisplayName}}, {{authorEmail}}, {{createdDateTime}},
+ *   {{messageWebUrl}}, {{teamId}}, {{channelId}},
+ *   {{rootMessageId}}  — for a root: same as {{messageId}}; for a reply: the
+ *                        parent root's id. Use this to thread follow-ups.
+ *   {{isReply}}        — boolean string ('true' / 'false'). Lets the action
+ *                        prompt distinguish reply context from a new bug
+ *                        report on the root.
+ * Plus standard watch vars (target, condition, watchId, message, …).
+ *
+ * ── Idempotency contract for downstream actions ─────────────────────────────
+ * Any work item created by an action wired to this watch SHOULD stamp the
+ * following provenance shape on `meta.teams_source` so consumers can
+ * deduplicate WIs that map back to the same Teams message:
+ *
+ *   meta.teams_source = {
+ *     teamId,              // GUID
+ *     channelId,           // 19:…@thread.skype
+ *     messageId,           // the candidate id (root OR reply)
+ *     rootMessageId,       // the parent root id (== messageId for roots)
+ *     messageWebUrl,       // deep link back to the chat message
+ *     authorEmail,         // may be '' — Graph doesn't always expose it
+ *     authorDisplayName,   // may be '' — same caveat
+ *     reportedAt,          // ISO-8601 — the message's createdDateTime
+ *   }
+ *
+ * This is a CONTRACT for action authors (e.g. the cc-triage prompt), not
+ * code in the plugin itself: this plugin does no WI mutation. The shape
+ * is intentionally flat — no nested objects — so it round-trips cleanly
+ * through JSON storage and is easy to query with `meta.teams_source.messageId`
+ * lookups. See the dispatched cc-triage prompt template stored on the watch
+ * action params for the canonical "always stamp before dispatching" rule.
+ *
+ * ── Fetch model ─────────────────────────────────────────────────────────────
+ * The engine's checkWatches loop is synchronous and runs inside a
+ * mutateJsonFileLocked callback, so this plugin maintains its own
+ * background-fetch cache. `fetchEntity` is sync: it returns the cached
+ * entity and, when the cached value is older than 60s (or absent), kicks
+ * off a background Graph refresh. First tick after a watch is created
+ * therefore returns null (no entity yet); the second tick captures the
+ * baseline; subsequent ticks detect new messages.
+ *
+ * Tests short-circuit this entirely by passing a pre-populated map at
+ * `state.teamsChannelMessages[targetKey]` (see `_targetKey`) — the plugin
+ * uses that shape directly, no shell-out required. Tests can also
+ * override the underlying Graph fetcher via `setLister(fn)` to drive the
+ * cache path.
+ *
+ * ── Auth ────────────────────────────────────────────────────────────────────
+ * Microsoft Graph bearer token, acquired via (default chain):
+ *
+ *   1. `az account get-access-token --resource https://graph.microsoft.com
+ *       --query accessToken -o tsv`  (primary)
+ *   2. `azureauth aad --resource https://graph.microsoft.com
+ *       --timeout 1 --output token`  (fallback when `az` is missing)
+ *
+ * The default chain uses the Azure CLI's well-known client app registration
+ * (`04b07795-8ddb-461a-bbee-02f9e1bf7b46`), which IS NOT preauthorized for
+ * the `ChannelMessage.Read.All` Graph permission required to list channel
+ * messages. With the default chain a `403 Forbidden` is the expected outcome
+ * on `GET /teams/{id}/channels/{id}/messages` even when the user is a
+ * tenant member — the bearer carries delegated scopes like Group.ReadWrite.All
+ * (enough to POST messages, per the team's teams-graph posting recipe) but
+ * NOT ChannelMessage.Read.All. To make this watch actually fire, configure
+ * a custom app registration on the watch target:
+ *
+ *   target: {
+ *     teamId: "<guid>", channelId: "19:...@thread.skype",
+ *     auth: {
+ *       method: "azureauth",              // or "az"
+ *       client: "<app-reg-guid>",         // app reg with ChannelMessage.Read.All
+ *                                         //   admin-consented in the tenant
+ *       tenant: "<tenant-guid>",          // optional — defaults to home tenant
+ *       scope:  ".default"                // optional — defaults to <resource>/.default
+ *     }
+ *   }
+ *
+ * Tokens are cached in-process for 25 min (Entra access tokens normally last
+ * ~1 h). Cache is keyed by the serialized auth-config so two watches with
+ * different `target.auth` never share a token.
+ *
+ * Security: the token is ONLY passed to Graph via the request
+ * `Authorization: Bearer …` header. It never appears on argv, never in
+ * logs, never in persisted watch records. Plugin trust level matches playbooks
+ * (user-trusted). `target.auth.client` / `tenant` are only forwarded as
+ * argv values to `az` or `azureauth` (argv-array spawn — no shell
+ * interpolation) so values containing shell metacharacters cannot escape.
+ *
+ * ── Error surfacing ─────────────────────────────────────────────────────────
+ * Graph error responses are parsed (`error.code` + `error.message` +
+ * `error.innerError.request-id`) and surfaced verbatim on `_lastState.lastError`
+ * alongside a one-line remediation hint — "Missing Graph permission
+ * ChannelMessage.Read.All — set target.auth.client to an app registration
+ * that has admin-consented this scope" — so the dashboard / `notes/inbox`
+ * reader can act on the failure without grepping engine logs.
+ *
+ * ── Out of scope (left as TODOs) ────────────────────────────────────────────
+ *   - Attachments, reactions, edit/delete detection, multi-channel watch.
+ */
+
+const { spawn } = require('child_process');
+const https = require('https');
+
+function ts() { return new Date().toISOString(); }
+function _warn(msg) { try { console.warn(`[${ts()}] [warn] ${msg}`); } catch {} }
+
+const CACHE_FRESHNESS_MS = 60 * 1000;
+const TOKEN_TTL_MS = 25 * 60 * 1000;
+const SHELL_TIMEOUT_MS = 15 * 1000;
+const GRAPH_TIMEOUT_MS = 15 * 1000;
+const SEEN_IDS_CAP = 500; // bound state growth per watch
+const MESSAGE_BODY_MAX_BYTES = 2048;
+const GRAPH_RESOURCE = 'https://graph.microsoft.com';
+
+// Module-level caches. Survive across ticks; reset on engine restart.
+const _entityCache = new Map();         // key -> { messages, fetchedAt, error? }
+const _inFlight = new Set();
+// Token cache is keyed by serialized auth config so different watches with
+// different `target.auth` settings never clobber each other's tokens. Default
+// (no auth specified) lives under the 'default' key. Tokens never appear in
+// the key itself — only the auth-config shape that produced them.
+const _cachedTokens = new Map();        // authKey -> { token, expiresAt }
+
+// Override-able listers — defaults use real Graph fetch. Tests inject mocks.
+//
+// THREE injection points (use whichever fits the test surface):
+//   setLister(fn)        → override the ENTIRE composed pipeline. The fn
+//                          receives `cfg` and must return the full
+//                          { messages: [...], fetchedAt, error? } envelope.
+//                          Bypasses both rootsLister and replyLister.
+//   setRootsLister(fn)   → override just the roots fetch. Composer still
+//                          fans out per-root replies via _replyLister.
+//   setReplyLister(fn)   → override the per-root replies fetcher used by
+//                          the default composer. Throwing simulates per-root
+//                          Graph failure — must NOT break the tick.
+//
+// The composer is the production wiring; test it end-to-end by stubbing
+// rootsLister + replyLister together.
+let _lister = _defaultComposedList;
+let _rootsLister = _defaultGraphListRoots;
+let _replyLister = _defaultGraphListReplies;
+function setLister(fn) { _lister = typeof fn === 'function' ? fn : _defaultComposedList; }
+function setRootsLister(fn) { _rootsLister = typeof fn === 'function' ? fn : _defaultGraphListRoots; }
+function setReplyLister(fn) { _replyLister = typeof fn === 'function' ? fn : _defaultGraphListReplies; }
+function _resetCache() { _entityCache.clear(); _inFlight.clear(); _cachedTokens.clear(); }
+
+/**
+ * Validate + normalize `target.auth`. Returns null when `auth` is absent or
+ * malformed (caller falls back to the default az → azureauth chain). The
+ * returned shape is { method, client?, tenant?, scope? } with strings only —
+ * forwarded as argv values to `az` / `azureauth` so all fields MUST be
+ * strings (no shell interpolation, but we still reject non-string inputs
+ * defensively so an accidental `{ client: { foo: 'bar' } }` doesn't crash
+ * the spawn call).
+ */
+function _normalizeAuthCfg(auth) {
+  if (!auth || typeof auth !== 'object') return null;
+  const method = typeof auth.method === 'string' ? auth.method.trim().toLowerCase() : '';
+  if (method !== 'az' && method !== 'azureauth') return null;
+  const out = { method };
+  for (const k of ['client', 'tenant', 'scope']) {
+    if (auth[k] != null) {
+      if (typeof auth[k] !== 'string') return null;
+      const v = auth[k].trim();
+      if (v) out[k] = v;
+    }
+  }
+  if (method === 'azureauth' && !out.client) {
+    // azureauth requires --client; without it the tool prompts interactively
+    // and we'd hang the tick. Reject up-front so the warn surfaces the cause.
+    return null;
+  }
+  return out;
+}
+
+function _authCacheKey(authCfg) {
+  if (!authCfg) return 'default';
+  // Stable serialization — keys are sorted, so { tenant, client } and
+  // { client, tenant } collapse to the same cache entry.
+  const keys = Object.keys(authCfg).sort();
+  return keys.map((k) => `${k}=${authCfg[k]}`).join('|');
+}
+
+function _resolveCfg(target) {
+  if (typeof target === 'string' && target.includes(':')) {
+    // First ':' splits team / channel — channel ids contain internal colons
+    // like `19:abc@thread.skype` so lastIndexOf would mangle them.
+    const idx = target.indexOf(':');
+    const teamId = target.slice(0, idx).trim();
+    const channelId = target.slice(idx + 1).trim();
+    if (!teamId || !channelId) return null;
+    return { teamId, channelId, auth: null };
+  }
+  if (target && typeof target === 'object'
+      && typeof target.teamId === 'string' && target.teamId
+      && typeof target.channelId === 'string' && target.channelId) {
+    return {
+      teamId: target.teamId.trim(),
+      channelId: target.channelId.trim(),
+      auth: _normalizeAuthCfg(target.auth),
+    };
+  }
+  return null;
+}
+
+function _validateTarget(target) {
+  const cfg = _resolveCfg(target);
+  if (!cfg || !cfg.teamId || !cfg.channelId) {
+    return 'target must be "teamId:channelId" or an object with teamId and channelId';
+  }
+  if (target && typeof target === 'object'
+      && target.auth !== undefined
+      && target.auth !== null
+      && !_normalizeAuthCfg(target.auth)) {
+    return 'target.auth must declare a valid az or azureauth configuration';
+  }
+  return null;
+}
+
+function _targetKey(target) {
+  const cfg = _resolveCfg(target);
+  if (!cfg) return typeof target === 'string' ? target : JSON.stringify(target);
+  // Include auth in the cache key so two watches against the same channel
+  // but with different `target.auth` cache entities independently — otherwise
+  // a 403 on one would leak to the other's _lastState.lastError.
+  const authKey = _authCacheKey(cfg.auth);
+  return authKey === 'default'
+    ? `${cfg.teamId}::${cfg.channelId}`
+    : `${cfg.teamId}::${cfg.channelId}::${authKey}`;
+}
+
+/**
+ * Run a shell command with captured stdout. Never throws on non-zero exit.
+ * Returns { code, stdout, stderr }.
+ */
+function _runCmd(cmd, args, timeoutMs) {
+  return new Promise((resolve) => {
+    // Windows: enable shell so .cmd shims like `az.cmd` resolve via PATHEXT.
+    // All args here are hardcoded constants — no injection surface.
+    const child = spawn(cmd, args, {
+      env: process.env,
+      windowsHide: true,
+      shell: process.platform === 'win32',
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try { child.kill('SIGTERM'); } catch {}
+      resolve({ code: -1, stdout, stderr: stderr + `\n[teams-channel] ${cmd} timeout after ${timeoutMs}ms` });
+    }, timeoutMs);
+    child.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
+    child.stderr.on('data', (b) => { stderr += b.toString('utf8'); });
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code: -1, stdout, stderr: stderr + `\n[teams-channel] ${cmd} spawn error: ${err.message}` });
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code: code == null ? -1 : code, stdout, stderr });
+    });
+  });
+}
+
+async function _resolveToken(authCfg) {
+  const cacheKey = _authCacheKey(authCfg);
+  const cached = _cachedTokens.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) return cached.token;
+
+  // Explicit per-watch auth config — single provider, no fallback chain
+  // (the user picked the method; chaining would mask the misconfiguration).
+  if (authCfg) {
+    const cmd = authCfg.method === 'azureauth' ? 'azureauth' : 'az';
+    const args = authCfg.method === 'azureauth'
+      ? _buildAzureauthArgs(authCfg)
+      : _buildAzArgs(authCfg);
+    const res = await _runCmd(cmd, args, SHELL_TIMEOUT_MS);
+    const token = res.code === 0 ? _extractTokenFromOutput(authCfg.method, res.stdout) : '';
+    if (token) {
+      _cachedTokens.set(cacheKey, { token, expiresAt: Date.now() + TOKEN_TTL_MS });
+      return token;
+    }
+    _warn(`teams-channel: token fetch failed via ${authCfg.method}. exit=${res.code} (${(res.stderr || '').trim().slice(0, 200)})`);
+    return null;
+  }
+
+  // Default chain: az then azureauth. NOTE: this chain uses the Azure CLI's
+  // well-known client app reg, which lacks ChannelMessage.Read.All. Expect
+  // 403 on channel-message reads unless the watch overrides via target.auth.
+  const azRes = await _runCmd(
+    'az',
+    ['account', 'get-access-token', '--resource', GRAPH_RESOURCE, '--query', 'accessToken', '-o', 'tsv'],
+    SHELL_TIMEOUT_MS,
+  );
+  if (azRes.code === 0 && azRes.stdout.trim()) {
+    const token = azRes.stdout.trim();
+    _cachedTokens.set(cacheKey, { token, expiresAt: Date.now() + TOKEN_TTL_MS });
+    return token;
+  }
+  // Fallback: azureauth (1ES helper). `azureauth aad --output token` prints
+  // ONLY the raw bearer token on stdout (no extra status text). The `--timeout 1`
+  // caps interactive prompts to 1 minute. Note the v0.9 CLI uses `aad`, not
+  // `aad token` (there is no `token` subcommand).
+  const aaRes = await _runCmd(
+    'azureauth',
+    ['aad', '--resource', GRAPH_RESOURCE, '--timeout', '1', '--output', 'token'],
+    SHELL_TIMEOUT_MS,
+  );
+  if (aaRes.code === 0 && aaRes.stdout.trim()) {
+    const token = aaRes.stdout.trim();
+    _cachedTokens.set(cacheKey, { token, expiresAt: Date.now() + TOKEN_TTL_MS });
+    return token;
+  }
+  _warn(`teams-channel: token fetch failed. az exit=${azRes.code} (${(azRes.stderr || '').trim().slice(0, 200)}); azureauth exit=${aaRes.code} (${(aaRes.stderr || '').trim().slice(0, 200)})`);
+  return null;
+}
+
+function _buildAzArgs(authCfg) {
+  // `az account get-access-token` produces TSV when --query is used. For
+  // user-supplied scope/tenant we forward as argv values (no shell).
+  const args = ['account', 'get-access-token'];
+  if (authCfg.scope) args.push('--scope', authCfg.scope);
+  else args.push('--resource', GRAPH_RESOURCE);
+  if (authCfg.tenant) args.push('--tenant', authCfg.tenant);
+  args.push('--query', 'accessToken', '-o', 'tsv');
+  return args;
+}
+
+function _buildAzureauthArgs(authCfg) {
+  // azureauth aad --client <id> --resource <url> [--tenant <id>] [--scope <s>]
+  //               --timeout 1 --output token
+  // --output token prints ONLY the raw bearer on stdout.
+  const args = ['aad', '--client', authCfg.client, '--resource', GRAPH_RESOURCE];
+  if (authCfg.tenant) args.push('--tenant', authCfg.tenant);
+  if (authCfg.scope) args.push('--scope', authCfg.scope);
+  args.push('--timeout', '1', '--output', 'token');
+  return args;
+}
+
+function _extractTokenFromOutput(method, stdout) {
+  const s = String(stdout || '').trim();
+  if (!s) return '';
+  // Both `az ... -o tsv` and `azureauth ... --output token` emit just the
+  // bearer on stdout. Strip whitespace + trailing newlines defensively.
+  return s.split(/\s+/)[0] || '';
+}
+
+/**
+ * Strip HTML to plain text, collapse whitespace, truncate to MESSAGE_BODY_MAX_BYTES.
+ * No regex-based sanitization is needed for security — the body is treated as
+ * untrusted input wrapped in <UNTRUSTED-INPUT> when handed to CC.
+ */
+function _stripHtml(html) {
+  if (typeof html !== 'string' || !html) return '';
+  // Remove <script> / <style> blocks outright.
+  let s = html
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, ' ')
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, ' ');
+  // Convert <br> and block-level closers to newlines so structure survives strip.
+  s = s.replace(/<\s*(br|\/p|\/div|\/li|\/h[1-6])\b[^>]*>/gi, '\n');
+  // Drop all remaining tags.
+  s = s.replace(/<[^>]+>/g, '');
+  // Decode the most common HTML entities (Teams only emits these handful).
+  s = s
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'");
+  // Collapse runs of whitespace, trim.
+  s = s.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').replace(/[ \t]{2,}/g, ' ').trim();
+  if (s.length > MESSAGE_BODY_MAX_BYTES) {
+    s = s.slice(0, MESSAGE_BODY_MAX_BYTES) + '…';
+  }
+  return s;
+}
+
+/**
+ * GET https://graph.microsoft.com/v1.0/teams/{teamId}/channels/{channelId}/messages
+ *   ?$top=20&$orderby=createdDateTime desc
+ * Token passed via Authorization header — never on argv, never logged.
+ */
+function _graphGet(pathPart, token) {
+  return new Promise((resolve) => {
+    const opts = {
+      method: 'GET',
+      hostname: 'graph.microsoft.com',
+      port: 443,
+      path: pathPart,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+        'User-Agent': 'minions-watch-teams-channel',
+      },
+      timeout: GRAPH_TIMEOUT_MS,
+    };
+    const req = https.request(opts, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        resolve({
+          status: res.statusCode || 0,
+          body: Buffer.concat(chunks).toString('utf8'),
+        });
+      });
+    });
+    req.on('error', (err) => resolve({ status: 0, body: '', error: err.message || String(err) }));
+    req.on('timeout', () => { req.destroy(new Error(`graph timeout after ${GRAPH_TIMEOUT_MS}ms`)); });
+    req.end();
+  });
+}
+
+/**
+ * Parse a Graph JSON error body into structured fields. Graph always returns
+ *   { "error": { "code": "...", "message": "...", "innerError": { "request-id": "..." } } }
+ * on 4xx/5xx, so this normalizes the shape. Returns null when the body isn't
+ * parseable JSON or doesn't carry an error envelope — caller falls back to
+ * the raw body snippet.
+ *
+ * Also detects the canonical "Missing scope permissions on the request. API
+ * requires one of 'X, Y'" message and lifts the required-scope list into a
+ * dedicated `missingScopes` array for the remediation hint.
+ */
+function _parseGraphError(body) {
+  if (typeof body !== 'string' || !body) return null;
+  let parsed;
+  try { parsed = JSON.parse(body); } catch { return null; }
+  const err = parsed && parsed.error;
+  if (!err || typeof err !== 'object') return null;
+  const code = typeof err.code === 'string' ? err.code : '';
+  const message = typeof err.message === 'string' ? err.message : '';
+  const inner = err.innerError && typeof err.innerError === 'object' ? err.innerError : {};
+  // Graph uses both `request-id` (kebab) and `requestId` (camel) in different
+  // surfaces — accept either so the request-id always makes it into the log.
+  const requestId = String(inner['request-id'] || inner.requestId || '');
+  // Lift "API requires one of 'X[, Y]'" — single-quoted comma list.
+  const scopeMatch = message.match(/API requires one of '([^']+)'/i);
+  const missingScopes = scopeMatch
+    ? scopeMatch[1].split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+  return { code, message, requestId, missingScopes };
+}
+
+/**
+ * One-line remediation hint for a Graph auth failure. Designed to be
+ * actionable in the dashboard tooltip without needing to read code or logs.
+ * Returns '' when no hint is available (caller appends nothing).
+ */
+function _remediationHint(status, parsed, authCfg) {
+  if (parsed && parsed.missingScopes && parsed.missingScopes.length > 0) {
+    const scopes = parsed.missingScopes.join(', ');
+    if (authCfg && authCfg.method === 'azureauth' && authCfg.client) {
+      return `Missing Graph permission ${scopes} on app reg ${authCfg.client} — admin-consent this scope in the tenant.`;
+    }
+    if (authCfg && authCfg.method === 'az') {
+      return `Missing Graph permission ${scopes} — the az CLI client app does not preauthorize this scope. Switch target.auth.method to 'azureauth' with a custom app reg that has ${scopes} admin-consented.`;
+    }
+    return `Missing Graph permission ${scopes} — default az/azureauth chain uses the Azure CLI client which does not preauthorize this scope. Set target.auth = { method: 'azureauth', client: '<app-reg-guid>' } pointing at an app registration that has ${scopes} admin-consented.`;
+  }
+  if (status === 401) {
+    return authCfg
+      ? `Graph token rejected (401) — re-acquire via '${authCfg.method} ...' (token may be expired or revoked).`
+      : `Graph token rejected (401) — refresh sign-in: 'az login' or 'azureauth aad --client <app-reg>'.`;
+  }
+  if (status === 403 && parsed && /Authorization_RequestDenied/i.test(parsed.code || '')) {
+    return `Graph rejected the request (Authorization_RequestDenied) — verify the signed-in identity is a member of team ${''} and that the app registration is admin-consented in the tenant.`;
+  }
+  return '';
+}
+
+/**
+ * Build the final error string surfaced on _lastState.lastError. Always
+ * prefixed with `graph auth failed: HTTP <status>` for 401/403 to preserve
+ * backward-compatible substring matching (existing tests assert /401/ or
+ * /403/). The parsed Graph code/message and the remediation hint are
+ * appended after a separator.
+ */
+function _buildGraphAuthError(status, body, authCfg) {
+  const parsed = _parseGraphError(body);
+  const baseline = `graph auth failed: HTTP ${status}`;
+  const parts = [baseline];
+  if (parsed && parsed.code) parts.push(parsed.code);
+  if (parsed && parsed.message) parts.push(parsed.message.slice(0, 240));
+  const hint = _remediationHint(status, parsed, authCfg);
+  if (hint) parts.push(`Hint: ${hint}`);
+  if (parsed && parsed.requestId) parts.push(`[request-id ${parsed.requestId}]`);
+  return parts.join(' — ');
+}
+
+/**
+ * Build the error for non-auth Graph failures (5xx, 4xx other than 401/403,
+ * network errors). Same structure but without the auth-specific hint.
+ */
+function _buildGraphHttpError(status, body) {
+  const parsed = _parseGraphError(body);
+  const baseline = `graph HTTP ${status}`;
+  if (!parsed) return `${baseline}: ${(body || '').slice(0, 300)}`;
+  const parts = [baseline];
+  if (parsed.code) parts.push(parsed.code);
+  if (parsed.message) parts.push(parsed.message.slice(0, 240));
+  if (parsed.requestId) parts.push(`[request-id ${parsed.requestId}]`);
+  return parts.join(' — ');
+}
+
+/**
+ * Normalize a raw Graph chatMessage payload to the plugin's compact shape.
+ * `rootIdOverride` is supplied when this is a reply — replies in Graph carry
+ * `replyToId` / no `webUrl` of their own (Graph uses the root's webUrl with a
+ * fragment), so the parent root id is threaded in by the caller.
+ */
+function _shapeMessage(m, rootIdOverride) {
+  const isReply = rootIdOverride != null && rootIdOverride !== m.id;
+  const rootMessageId = rootIdOverride != null ? String(rootIdOverride) : String(m.id);
+  return {
+    id: String(m.id),
+    rootMessageId,
+    isReply,
+    bodyHtml: m.body && typeof m.body.content === 'string' ? m.body.content : '',
+    contentType: m.body && m.body.contentType ? String(m.body.contentType) : 'text',
+    createdDateTime: String(m.createdDateTime || ''),
+    webUrl: String(m.webUrl || ''),
+    authorDisplayName: m.from && m.from.user && m.from.user.displayName
+      ? String(m.from.user.displayName) : '',
+    // Graph's chatMessage `from.user` exposes id (oid) but NOT email — that
+    // lives in `.from.user.userIdentityType`-dependent extension fields. The
+    // dashboard cc-triage prompt links the webUrl so a missing email is not
+    // load-bearing; surfacing whatever Graph returns is enough.
+    authorEmail: m.from && m.from.user && (m.from.user.email || m.from.user.userPrincipalName)
+      ? String(m.from.user.email || m.from.user.userPrincipalName) : '',
+  };
+}
+
+/**
+ * Fetch the top-20 root messages for a channel.
+ * Returns { messages, error?, fetchedAt }. Never throws.
+ */
+async function _defaultGraphListRoots(cfg) {
+  const token = await _resolveToken(cfg && cfg.auth);
+  if (!token) {
+    return { messages: [], error: 'no graph token available', fetchedAt: ts() };
+  }
+  // Use encodeURIComponent on ids — channel ids contain `:` and `@` which
+  // are reserved in URL paths. teamId is a plain GUID but encode for safety.
+  const team = encodeURIComponent(cfg.teamId);
+  const channel = encodeURIComponent(cfg.channelId);
+  const path = `/v1.0/teams/${team}/channels/${channel}/messages?$top=20&$orderby=createdDateTime%20desc`;
+  const res = await _graphGet(path, token);
+  if (res.error) {
+    return { messages: [], error: `graph request error: ${res.error}`, fetchedAt: ts() };
+  }
+  if (res.status === 401 || res.status === 403) {
+    // Force a token re-fetch on next tick — current token might be expired.
+    _cachedTokens.delete(_authCacheKey(cfg && cfg.auth));
+    return {
+      messages: [],
+      error: _buildGraphAuthError(res.status, res.body, cfg && cfg.auth),
+      fetchedAt: ts(),
+    };
+  }
+  if (res.status < 200 || res.status >= 300) {
+    return {
+      messages: [],
+      error: _buildGraphHttpError(res.status, res.body),
+      fetchedAt: ts(),
+    };
+  }
+  let parsed;
+  try { parsed = JSON.parse(res.body || '{}'); }
+  catch (e) {
+    return { messages: [], error: `graph JSON parse failed: ${e.message}`, fetchedAt: ts() };
+  }
+  const arr = Array.isArray(parsed && parsed.value) ? parsed.value : [];
+  const messages = arr
+    .filter((m) => m && m.id && m.messageType === 'message' && m.from)
+    .map((m) => _shapeMessage(m, m.id));
+  return { messages, fetchedAt: ts() };
+}
+
+/**
+ * Fetch replies for a single root message. Returns { messages: [...] } or
+ * throws — the caller is responsible for swallowing errors so one bad root
+ * doesn't break the whole tick.
+ */
+async function _defaultGraphListReplies(cfg, rootId) {
+  const token = await _resolveToken(cfg && cfg.auth);
+  if (!token) {
+    const err = new Error('no graph token available');
+    err.code = 'NO_TOKEN';
+    throw err;
+  }
+  const team = encodeURIComponent(cfg.teamId);
+  const channel = encodeURIComponent(cfg.channelId);
+  const root = encodeURIComponent(rootId);
+  const path = `/v1.0/teams/${team}/channels/${channel}/messages/${root}/replies?$top=20&$orderby=createdDateTime%20desc`;
+  const res = await _graphGet(path, token);
+  if (res.error) {
+    throw new Error(`graph request error: ${res.error}`);
+  }
+  if (res.status === 401 || res.status === 403) {
+    _cachedTokens.delete(_authCacheKey(cfg && cfg.auth));
+    throw new Error(_buildGraphAuthError(res.status, res.body, cfg && cfg.auth));
+  }
+  if (res.status < 200 || res.status >= 300) {
+    throw new Error(_buildGraphHttpError(res.status, res.body));
+  }
+  let parsed;
+  try { parsed = JSON.parse(res.body || '{}'); }
+  catch (e) {
+    throw new Error(`graph JSON parse failed: ${e.message}`);
+  }
+  const arr = Array.isArray(parsed && parsed.value) ? parsed.value : [];
+  const messages = arr
+    .filter((m) => m && m.id && m.messageType === 'message' && m.from)
+    .map((m) => _shapeMessage(m, rootId));
+  return { messages };
+}
+
+/**
+ * Default composed lister — fetch roots (via `_rootsLister`), then in
+ * parallel fetch replies for each root (via `_replyLister`). Per-root
+ * reply-fetch failures are logged and skipped so one bad root doesn't
+ * break the whole tick. Returns the merged candidate set with the
+ * root-level error (if any) preserved on the envelope.
+ */
+async function _defaultComposedList(cfg) {
+  const rootEnv = await _rootsLister(cfg);
+  const messages = (rootEnv && Array.isArray(rootEnv.messages))
+    ? rootEnv.messages.slice() : [];
+  // If the roots fetch errored, surface the error but skip reply fetches —
+  // there's nothing to fetch replies for.
+  if ((rootEnv && rootEnv.error) || messages.length === 0) {
+    return {
+      messages,
+      error: (rootEnv && rootEnv.error) || null,
+      fetchedAt: (rootEnv && rootEnv.fetchedAt) || ts(),
+    };
+  }
+  const settled = await Promise.allSettled(
+    messages.map((root) => _replyLister(cfg, root.id))
+  );
+  for (let i = 0; i < settled.length; i++) {
+    const s = settled[i];
+    const root = messages[i];
+    if (s.status === 'fulfilled' && s.value && Array.isArray(s.value.messages)) {
+      for (const r of s.value.messages) messages.push(r);
+    } else if (s.status === 'rejected') {
+      const reason = s.reason && s.reason.message ? s.reason.message : String(s.reason);
+      _warn(`teams-channel: replies fetch failed for root ${root.id}: ${reason}`);
+    }
+  }
+  return { messages, fetchedAt: rootEnv.fetchedAt || ts() };
+}
+
+function _scheduleRefresh(target, key) {
+  if (_inFlight.has(key)) return;
+  const cfg = _resolveCfg(target);
+  if (!cfg) return;
+  _inFlight.add(key);
+  Promise.resolve()
+    .then(() => _lister(cfg))
+    .then((entity) => { _entityCache.set(key, entity); })
+    .catch((e) => {
+      _entityCache.set(key, {
+        messages: [],
+        error: e && e.message ? e.message : String(e),
+        fetchedAt: ts(),
+      });
+    })
+    .then(() => { _inFlight.delete(key); });
+}
+
+function fetchEntity(target, state) {
+  const key = _targetKey(target);
+  // Test/external override path — state.teamsChannelMessages[key] short-circuits
+  // the background-fetch cache so unit tests can drive the plugin without
+  // ever invoking the Graph fetcher.
+  if (state && state.teamsChannelMessages
+      && Object.prototype.hasOwnProperty.call(state.teamsChannelMessages, key)) {
+    const inj = state.teamsChannelMessages[key];
+    return inj ? { ...inj, _target: target } : null;
+  }
+  const cached = _entityCache.get(key);
+  const cachedAge = cached && cached.fetchedAt
+    ? Date.now() - new Date(cached.fetchedAt).getTime()
+    : Infinity;
+  if (!cached || cachedAge > CACHE_FRESHNESS_MS) {
+    _scheduleRefresh(target, key);
+  }
+  return cached ? { ...cached, _target: target } : null;
+}
+
+/**
+ * State shape: { ids: string[], lastFetchedAt?: string, lastError?: string }
+ * `ids` is the all-time-seen set (insertion-ordered, capped at SEEN_IDS_CAP).
+ *
+ * First-observation semantics: when `prevState` has no `ids` key the entire
+ * current candidate set is absorbed as the baseline so an existing channel
+ * backlog never floods actions (per W-mq00x0hx0007acaa spec).
+ *
+ * Burst handling on subsequent calls: when N new ids appear between ticks,
+ * captureState advances by AT MOST ONE per call so bursts drain losslessly
+ * across consecutive checks (one fire per tick, in concert with evaluate).
+ */
+function captureState(entity, prevState) {
+  // The engine seeds _lastState with `{}` on watch creation, then later calls
+  // captureState with the prior `{ ids: [...] }`. Use the presence of the
+  // `ids` key — not its length — to distinguish "first observation" from
+  // "channel happens to be empty right now". This is what lets a brand-new
+  // watch on an empty channel still drain a later burst one-per-tick.
+  const isFirstObservation = !prevState || !Object.prototype.hasOwnProperty.call(prevState, 'ids');
+  const prevIds = Array.isArray(prevState && prevState.ids) ? prevState.ids : [];
+  if (!entity) return { ids: prevIds };
+  const seen = new Set(prevIds);
+  // Sort by createdDateTime ascending so the oldest unseen message drains
+  // first (FIFO across bursts).
+  const current = (entity.messages || [])
+    .slice()
+    .sort((a, b) => String(a.createdDateTime).localeCompare(String(b.createdDateTime)));
+  let nextIds;
+  if (isFirstObservation) {
+    nextIds = current.map((m) => m.id);
+  } else {
+    const newOnes = current.filter((m) => !seen.has(m.id));
+    if (newOnes.length === 0) {
+      nextIds = prevIds.slice();
+    } else {
+      nextIds = [...prevIds, newOnes[0].id];
+    }
+  }
+  if (nextIds.length > SEEN_IDS_CAP) {
+    nextIds = nextIds.slice(nextIds.length - SEEN_IDS_CAP);
+  }
+  return {
+    ids: nextIds,
+    lastFetchedAt: entity.fetchedAt || null,
+    lastError: entity.error || null,
+  };
+}
+
+function _firstUnseenMessage(entity, prevState) {
+  if (!entity) return null;
+  const prevIds = Array.isArray(prevState && prevState.ids) ? prevState.ids : [];
+  const seen = new Set(prevIds);
+  const candidates = (entity.messages || [])
+    .filter((m) => !seen.has(m.id))
+    .sort((a, b) => String(a.createdDateTime).localeCompare(String(b.createdDateTime)));
+  return candidates[0] || null;
+}
+
+function evaluate(condition, entity, prevState, target) {
+  if (condition !== 'new-message') {
+    return { triggered: false, message: '' };
+  }
+  if (!entity) return { triggered: false, message: '' };
+  if (entity.error) {
+    // Surface the fetch error so engine/watches/index.js writes it to
+    // _history[].reason — otherwise the watch silently sleeps forever
+    // with reason="" and no visible signal that Graph auth is broken
+    // (e.g. HTTP 403 missing ChannelMessage.Read.All scope).
+    return { triggered: false, message: `teams-channel fetch error: ${entity.error}` };
+  }
+  const next = _firstUnseenMessage(entity, prevState);
+  if (!next) return { triggered: false, message: '' };
+  const cfg = _resolveCfg(target);
+  const channelLabel = cfg ? cfg.channelId : '<unknown>';
+  const author = next.authorDisplayName || 'unknown';
+  const preview = _stripHtml(next.bodyHtml).slice(0, 80);
+  return {
+    triggered: true,
+    message: `New Teams message in ${channelLabel} from ${author}: ${preview}`,
+  };
+}
+
+function contextVars(entity, prevState, _newState) {
+  const next = _firstUnseenMessage(entity, prevState);
+  if (!next) return {};
+  const cfg = _resolveCfg(entity && entity._target);
+  return {
+    messageId: next.id,
+    messageBody: _stripHtml(next.bodyHtml),
+    authorDisplayName: next.authorDisplayName,
+    authorEmail: next.authorEmail,
+    createdDateTime: next.createdDateTime,
+    messageWebUrl: next.webUrl,
+    teamId: cfg ? cfg.teamId : '',
+    channelId: cfg ? cfg.channelId : '',
+    rootMessageId: next.rootMessageId || next.id,
+    // Templating substitutes via String(), so booleans surface as 'true'/'false'.
+    // Downstream prompt authors can branch on the literal string.
+    isReply: next.isReply === true,
+  };
+}
+
+module.exports = {
+  name: 'teams-channel',
+  spec: {
+    label: 'Microsoft Teams Channel',
+    description: 'Poll a Microsoft Teams channel for new messages. Tracks both root messages and thread replies; fires once per newly-observed message id (system messages excluded). First tick captures baseline without firing.',
+    conditions: ['new-message'],
+    absoluteConditions: [],
+    validateTarget: _validateTarget,
+    fetchEntity,
+    captureState,
+    evaluate,
+    contextVars,
+  },
+  // Exported for tests
+  _resolveCfg,
+  _targetKey,
+  _firstUnseenMessage,
+  _stripHtml,
+  _shapeMessage,
+  _defaultComposedList,
+  _normalizeAuthCfg,
+  _authCacheKey,
+  _parseGraphError,
+  _remediationHint,
+  _buildGraphAuthError,
+  _buildGraphHttpError,
+  _buildAzArgs,
+  _buildAzureauthArgs,
+  setLister,
+  setRootsLister,
+  setReplyLister,
+  _resetCache,
+};