@open-everywhere/provider-teams 0.0.0-stage → 0.1.0

package/agent/channels/teams-engagement.ts

@@ -0,0 +1,391 @@
+// THE TEAMS AMBIENT ENGAGEMENT SEAM (chat-surface contract §2.5) — the Teams wiring over core's
+// pure engagement policy (`packages/core/agent/channels/engagement.ts`). It gives Teams the middle
+// posture Slack and Discord already have: an @mention marks the conversation ENGAGED, a later PLAIN
+// message in that conversation wakes the agent, and `stand_down` stores the stop.
+//
+// THE ANCHOR is `conversation.id`, and it names a different container per scope — which is exactly
+// what the seam wants:
+//   • a TEAM CHANNEL activity carries `<channelId>;messageid=<root>`, so the anchor is the REPLY
+//     CHAIN, not the channel. Engagement is per reply chain, matching Slack's per-thread grain.
+//   • a GROUP CHAT activity carries the CHAT id, so the anchor is the chat.
+//   • a 1:1 (personal) chat carries NO anchor at all. That omission is the honest half, and it is
+//     Discord's DM precedent (discord-identity.ts): a 1:1 is answered unconditionally, so no gate
+//     anywhere reads a mark on it and writing one would suppress nothing. `stand_down` refuses on a
+//     1:1 for the same reason, in its own words.
+//
+// 🔴 THE PLATFORM CONSTRAINT, AND WHY IT IS NOT A DEFECT. Microsoft delivers a NON-MENTION message
+// to a bot only where the tenant has consented to the matching resource-specific-consent (RSC)
+// grant: `ChannelMessage.Read.Group` for a team channel, `ChatMessage.Read.Chat` for a chat (both
+// are in `teams-app/manifest.json`). Without it, only @mention activities ever arrive, so the seam
+// is armed but nothing can exercise it — the surface answers once per mention, exactly as before.
+// There is NO API that reports whether a tenant granted an RSC permission, so this module states
+// the dependency out loud instead of guessing, and logs the named reason ONCE per scope while no
+// proof has arrived. Never a silent gap (contract §3), and never a refusal either — a declaration.
+//
+// 🔴 BE EXACT ABOUT WHAT THE PROOF COVERS, because the sentence here used to overstate it
+// (OPE-1527). The probe sits on the seam's own read, which the front reaches for a HUMAN-authored
+// activity with a RESOLVABLE partition and nothing else: a machine-authored activity skips the seam,
+// and an activity whose identity will not resolve returns `unanchored` above the probe. So the proof
+// is one-directional. A scope that HAS printed the proof is granted — Microsoft delivered a
+// non-mention message, and nothing else could have. A scope that has NOT printed it says only that
+// no such message has been SEEN in this process; the grant may be present and the traffic may simply
+// have been mentions, bot posts, or activities this deployment could not anchor. A serverless
+// invocation is a fresh process, so a granted tenant keeps printing "delivery UNPROVEN" per cold
+// start. That is the honest reading of a signal no API can give us, not a defect to design around.
+
+import type { TeamsConversationScope, TeamsMessageActivity } from "eve/channels/teams";
+import { buildTeamsAuth, teamsMembershipType, teamsMode } from "./teams-identity.js";
+import {
+  getOperationalStore,
+  getThreadEngagement,
+  markThreadEngaged,
+  resolvePartition,
+  roomEngagementAddress,
+  shouldDeliverReply,
+  type EngagementRow,
+  type Partition,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The RSC permission Microsoft requires before it delivers NON-MENTION messages in this scope, or
+ *  `undefined` for a scope the seam does not anchor (a 1:1 chat, which needs no grant — a personal
+ *  message is delivered to its own bot unconditionally). */
+export function teamsSeamGrant(scope: TeamsConversationScope): string | undefined {
+  if (scope === "personal") return undefined;
+  return scope === "groupChat" ? "ChatMessage.Read.Chat" : "ChannelMessage.Read.Group";
+}
+
+/** The named platform reason the seam is UNSUPPORTED without the tenant's RSC grant. One sentence,
+ *  naming the grant, so a log line or a doc row can carry it verbatim. */
+export function teamsSeamUnsupportedReason(scope: TeamsConversationScope): string {
+  const grant = teamsSeamGrant(scope) ?? "no RSC grant";
+  const room = scope === "groupChat" ? "group-chat" : "channel";
+  return (
+    `Microsoft delivers non-mention ${room} messages only with the ${grant} RSC grant consented in this tenant; ` +
+    `without it a plain follow-up never reaches this deployment, so the engaged seam can wake nothing here`
+  );
+}
+
+/**
+ * Is this activity MACHINE-AUTHORED — the agent itself, a Bot-Framework bot role, or any `28:`
+ * application id?
+ *
+ * 🔴 ONE PREDICATE, TWO CALLERS, AND THAT IS THE POINT. `teams-front.ts` computes this to decide
+ * whether an activity may wake anything, and the native gate below needs the SAME answer: a
+ * machine-authored CHANNEL activity is still FORWARDED to the native path (only the DM branch and
+ * the single-window branch drop one), so an engaged conversation would otherwise admit a bot's own
+ * post and self-trigger. A weaker second copy here — `from.role === "bot"` alone, say — would miss
+ * exactly the id-shaped cases the front catches.
+ */
+export function teamsMachineAuthored(a: TeamsMessageActivity): boolean {
+  // DEFENSIVE ON `recipient`, unlike the front's own copy. The front only ever sees an activity
+  // `parseTeamsActivity` produced, which always carries one; this is also called from the native
+  // handler, which a test or an ops script can drive with a hand-built activity. An absent recipient
+  // must not throw here — the author question still has two other answers.
+  const self = a.recipient?.id;
+  return (self !== undefined && a.from.id === self) || a.from.role === "bot" || a.from.id.startsWith("28:");
+}
+
+/**
+ * The engagement-registry anchor for one conversation, or `undefined` for a 1:1 chat.
+ *
+ * 🔴 IT IS THE ONE PREDICATE THE MAPPER AND THE FRONT SHARE. `bindTeams` publishes exactly this as
+ * `engagementKey`, so `stand_down`'s mark and this seam's read address the same row. Two spellings
+ * of "which conversations are anchored" is how a stop comes to mark a row no gate reads.
+ */
+export function teamsEngagementAnchor(scope: TeamsConversationScope, conversationId: string | undefined): string | undefined {
+  if (!conversationId || conversationId.length === 0) return undefined;
+  return teamsMode(scope) === "dm" ? undefined : conversationId;
+}
+
+// --- the RSC support declaration (per-process, once per scope) ---------------------------------
+//
+// Module-scoped once-flags, the same shape `teams-front.ts`'s `warnedDedupeStore` uses: a serverless
+// invocation is a fresh process, so "once" means once per cold start per scope rather than once
+// forever. That is the right grain — the declaration is for the operator reading logs, and a
+// deployment whose grant is missing keeps saying so on each cold start rather than saying it once
+// and never again.
+
+const seamDeliveryProven = new Set<string>();
+const seamUnsupportedLogged = new Set<string>();
+
+/** Record that a NON-MENTION message arrived in this scope — positive proof the RSC grant is
+ *  consented, because Microsoft would not have delivered it otherwise. ONE-DIRECTIONAL: silence
+ *  here is not evidence of an absent grant (see the module header). */
+export function noteTeamsSeamDelivery(scope: TeamsConversationScope): void {
+  if (teamsSeamGrant(scope) !== undefined) seamDeliveryProven.add(scope);
+}
+
+/** Has a non-mention message ever arrived in this scope in this process? */
+export function teamsSeamDeliveryProven(scope: TeamsConversationScope): boolean {
+  return seamDeliveryProven.has(scope);
+}
+
+/**
+ * Declare the seam UNSUPPORTED-so-far for this scope, ONCE. Called when an @mention arms the seam
+ * and no non-mention message has yet proved the grant present. It logs and returns whether it
+ * logged, so a test can drive the once-ness; it never throws and never suppresses a wake.
+ */
+export function noteTeamsSeamArmed(scope: TeamsConversationScope): boolean {
+  if (teamsSeamGrant(scope) === undefined) return false; // a 1:1 needs no grant
+  if (seamDeliveryProven.has(scope) || seamUnsupportedLogged.has(scope)) return false;
+  seamUnsupportedLogged.add(scope);
+  // WORDED AS A DEPENDENCY, NOT A VERDICT. On a cold start whose first activity is a mention, nothing
+  // has been observed either way — and a serverless invocation is a fresh process, so that is the
+  // COMMON case even on a fully granted tenant. Saying "unsupported" there would be a confident wrong
+  // answer in an operator's log. The line says what the seam needs and what would prove it instead.
+  console.warn(`[open-everywhere:teams-engagement] engaged seam armed, delivery UNPROVEN in this process — ${teamsSeamUnsupportedReason(scope)}. One non-mention message from a person, in a conversation this deployment can anchor, would prove the grant present; nothing else this process sees can.`);
+  return true;
+}
+
+/** Test seam: clear both per-process flags. */
+export function resetTeamsSeamSupport(): void {
+  seamDeliveryProven.clear();
+  seamUnsupportedLogged.clear();
+}
+
+// --- the verdict -------------------------------------------------------------------------------
+
+/**
+ * What the seam says about one inbound activity. Four outcomes, and each names what the CALLER owes:
+ *
+ *  • `unanchored` — a 1:1 chat (or an activity with no conversation id). The seam has nothing to say
+ *    and the caller keeps today's path exactly.
+ *  • `engage` — an @mention. The caller marks the conversation engaged ({@link markTeamsEngaged});
+ *    the mention itself is answered by the caller's normal path, never by the seam. It carries the
+ *    row's `org` so the caller can DEDUPE the mark: a mark re-invites, which clears a `stopped`
+ *    flag, and a redelivered mention must never clear a stand-down nobody asked to lift.
+ *  • `deliver` — a plain message in an engaged conversation. The caller wakes a turn.
+ *  • `hold` — a plain message the seam does not admit. `stopped` says WHY, and it is the one field a
+ *    caller must branch on: `stopped: true` means the agent was asked to stand down here, so the
+ *    message must be SUPPRESSED outright — including on an ambient leg that never reads this
+ *    registry. `stopped: false` means the conversation simply is not engaged, which is not a
+ *    suppression: the caller keeps today's path.
+ */
+export type TeamsEngagementVerdict =
+  | { readonly kind: "unanchored"; readonly reason: string }
+  | { readonly kind: "engage"; readonly anchor: string; readonly org: string }
+  | { readonly kind: "deliver"; readonly anchor: string; readonly reason: string }
+  | { readonly kind: "hold"; readonly anchor: string; readonly reason: string; readonly stopped: boolean };
+
+/** Injectable seams so the whole verdict is unit-tested without a store. */
+export interface TeamsEngagementDeps {
+  readonly getEngagement?: (p: Partition, anchor: string) => Promise<EngagementRow | null>;
+  readonly markEngaged?: (p: Partition, anchor: string, atIso: string) => Promise<void>;
+  readonly now?: () => string;
+}
+
+/**
+ * The partition one activity's engagement row lives in — the CONVERSATION grain
+ * (`teams/<tenant>/<conversationId>`), never `domainKeyOf`'s channel grain.
+ *
+ * 🔴 THE GRAIN IS THE CONTRACT WITH `stand_down`. The verb resolves its own partition through
+ * `bindFrom` → `resolvePartition`, which keys on the binding's `surface` (the conversation). A seam
+ * that read the widened channel key would look at a different row from the one the stop marked, and
+ * the stop would suppress nothing. Null on an unresolvable identity — the caller then keeps today's
+ * path, the fail-open posture every carriage leg in this file family takes.
+ */
+function teamsSeamPartition(a: TeamsMessageActivity): Partition | null {
+  try {
+    const auth = buildTeamsAuth({
+      userId: a.from.id,
+      tenantId: a.tenantId ?? a.conversation.tenantId,
+      conversationId: a.conversation.id,
+      channelId: a.teamsChannelId,
+      teamId: a.teamId,
+      scope: a.scope,
+      membershipType: teamsMembershipType(a.channelData),
+    });
+    return resolvePartition({ channel: { kind: "teams" }, session: { auth: { current: auth } } });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the seam for one verified message activity — READ-ONLY. The mark is a separate call
+ * ({@link markTeamsEngaged}) so that exactly one caller writes the row: two writers is how a mention
+ * comes to engage a conversation twice per activity, once on each path.
+ *
+ * ORDERING. A mention is settled before any read: it is always answered by the caller's own path, so
+ * its verdict costs no store round-trip. Only a plain message pays for a read, and it pays for
+ * exactly one — the ROW, not a boolean, because the row carries both facts the decision needs (is
+ * this engaged, and was the agent asked to stand down here) and two reads could disagree.
+ *
+ * The DECISION ITSELF IS CORE'S. `shouldDeliverReply` owns the disqualifier order and the reasons;
+ * this function only translates Teams facts into its input. Nothing here re-states the policy.
+ *
+ * FAIL-CLOSED on a store error: `getThreadEngagement` reads a failure as `null`, so an unreadable
+ * registry holds rather than delivers — the agent does not barge into a conversation it cannot prove
+ * it was invited to.
+ */
+export async function resolveTeamsEngagement(
+  a: TeamsMessageActivity,
+  machineAuthored: boolean,
+  deps: TeamsEngagementDeps = {},
+): Promise<TeamsEngagementVerdict> {
+  const anchor = teamsEngagementAnchor(a.scope, a.conversation.id);
+  if (!anchor) return { kind: "unanchored", reason: "a 1:1 chat carries no engagement anchor — it is answered unconditionally" };
+  const partition = teamsSeamPartition(a);
+  if (!partition) return { kind: "unanchored", reason: "the activity has no resolvable partition — no row to address" };
+
+  if (a.isBotMentioned) return { kind: "engage", anchor, org: partition.org };
+
+  // A non-mention message ARRIVED, which is positive proof Microsoft is delivering this scope's
+  // ambient traffic — the RSC grant is consented. Recorded before the decision, so a stood-down
+  // conversation still counts as proof.
+  noteTeamsSeamDelivery(a.scope);
+
+  const read = deps.getEngagement ?? ((p, key) => getThreadEngagement(p, key));
+  const row = await read(partition, anchor);
+  const decision = shouldDeliverReply({
+    isEngaged: row !== null,
+    stopped: row?.stopped ?? false,
+    authorIsBot: machineAuthored,
+    isAppMention: false, // settled above — a mention never reaches this branch
+    inThread: true, // an anchored Teams conversation IS the container engagement is kept per
+  });
+  if (decision.deliver) return { kind: "deliver", anchor, reason: decision.reason };
+  return { kind: "hold", anchor, reason: decision.reason, stopped: row?.stopped === true };
+}
+
+/**
+ * Mark one conversation ENGAGED on an @mention, and declare the RSC dependency once.
+ *
+ * `participating: true` is the re-invitation: it promotes the row and CLEARS a previous stand-down,
+ * which is what "an @mention brings the agent back" means on every surface that wires this seam.
+ * Best-effort throughout — `markThreadEngaged` swallows a store failure, because engagement
+ * bookkeeping must never fail a turn.
+ *
+ * 🔴 THE PROMOTION CARRIES THE ACTIVITY ID, SO REPLAYING ONE THE ROW STILL HOLDS LIFTS NOTHING
+ * (OPE-1527). The
+ * Bot Framework redelivers an activity whenever it does not get a prompt 200, and a redelivered
+ * @mention is a REPLAYED invitation: it used to clear a `stopped` flag nobody asked to lift. The
+ * front's dedupe caught the ordinary case and could not catch this one, because it expires — its
+ * store TTL is ten minutes and a stand-down has no expiry at all, so a redelivery on a fresh process
+ * an hour later re-marked a stood-down conversation as engaged. `engagedBy` closes that durably: the
+ * store records the promoting id and refuses to clear `stopped` when a promotion repeats it. A
+ * SECOND, GENUINE @mention carries a different activity id and still brings the agent back, which is
+ * the behaviour this must not break.
+ *
+ * BE EXACT ABOUT THE REACH. The store keeps a BOUNDED LIST of recent promoters (OPE-1562), so what
+ * cannot be replayed is every promotion the list still holds — see `EngagementRow.recentPromoters`.
+ * Mention A, mention B, a stand-down, then a redelivery of A leaves the stop SET: a superseded
+ * mention is guarded like the latest one. What remains open is the BOUND — a replay of a mention
+ * that `PROMOTER_LIST_MAX` distinct later promotions have pushed off the list clears again.
+ */
+export async function markTeamsEngaged(a: TeamsMessageActivity, deps: TeamsEngagementDeps = {}): Promise<string | null> {
+  const anchor = teamsEngagementAnchor(a.scope, a.conversation.id);
+  if (!anchor) return null;
+  const partition = teamsSeamPartition(a);
+  if (!partition) return null;
+  const now = deps.now ?? (() => new Date().toISOString());
+  const mark =
+    deps.markEngaged ?? ((p, key, atIso) => markThreadEngaged(p, key, atIso, { participating: true, engagedBy: a.id }));
+  await mark(partition, anchor, now());
+  // The seam is armed here. Whether Microsoft will DELIVER the follow-ups is the tenant's RSC grant,
+  // which nothing can probe — so say it once rather than leave the gap silent.
+  noteTeamsSeamArmed(a.scope);
+  return anchor;
+}
+
+// --- THE ROOM-GRAIN WATCH ROW (OPE-1511) -------------------------------------------------------
+//
+// 🔴 A SECOND GRAIN, FOR A SECOND WAKE. Everything above is keyed per CONVERSATION, because an
+// @mention engages a reply chain. Leg A of the single-window front (teams-front.ts) is a different
+// wake with a different grain: on a vouched channel it wakes on ANY message in the ROOM, including a
+// reply chain nobody ever @mentioned the agent in. That wake read no registry of its own, so
+// `stand_down` found no row, refused, and the only off switch left was an operator un-vouching the
+// surface — a person in the room could not stop it and the agent could not stop it for them.
+//
+// THE RULE IS THAT A STORED STOP EXISTS EXACTLY WHERE A STORED WAKE EXISTS. So Leg A stores a
+// room-grain row on each ambient wake, its own gate reads that row's `stopped` flag, and
+// `tools/stand_down.ts` marks it when the conversation grain holds nothing. The address is core's
+// (`roomEngagementAddress`), derived from the partition by BOTH sides, so the wake and the stop
+// cannot drift onto two spellings of one room.
+//
+// WHAT THE ROOM ROW IS AND IS NOT. Leg E never reads it: the seam above keys on the CONVERSATION and
+// is untouched by any of this. The only two fields that matter here are `stopped` and — through the
+// promotion that clears it — `recentPromoters`.
+//
+// 🔴 `participating` ON A ROOM ROW MEANS NOTHING, AND THAT IS A HAZARD WORTH NAMING. An ambient
+// WATCH writes `participating: false`, but the @mention clear below writes `true`, and the flag is
+// monotonic in both store backends — so after the first @mention in the room it stays `true`
+// forever. Nothing reads it today: no production caller reads `listEngagements`, and Teams never
+// calls `bumpSilentStreak`, which is what the flag exists to gate. It is set as a side effect of
+// being the only way to clear `stopped`, not as a claim that anybody invited the agent into the
+// room. A future warm-shed rule must not read this row and conclude the agent was invited here.
+
+/**
+ * Has a stand-down landed on this partition's ROOM row?
+ *
+ * 🔴 FAIL-CLOSED, and the direction is the opposite of core's `isThreadStopped` on purpose. That
+ * predicate fails OPEN because it decides whether to SILENCE an answer the model has already
+ * written, where "unknown" must mean deliver. This one is a WAKE GATE: it decides whether to barge
+ * into a room nobody invited the agent into, where "unknown" must mean stay out. It is the same
+ * posture the group-chat branch of `teams-front.ts` takes two screens above, in its own words — an
+ * unreadable registry cannot prove the agent is still welcome.
+ *
+ * The cost is real and worth stating: while the operational store is unreadable, EVERY room on this
+ * surface holds its ambient wakes, including rooms nobody ever stood down. An @mention is
+ * unaffected — the addressed arm never reads this — so a person can still reach the agent through
+ * the affordance the stop copy itself points them at. That is the right trade for a gate whose
+ * failure mode in the other direction is an agent that keeps talking in a room that asked it to
+ * stop, and cannot be re-silenced because the same outage fails the write.
+ *
+ * It reads the store DIRECTLY rather than through `getThreadEngagement`, because that wrapper
+ * swallows an error to `null` and a null is indistinguishable from "no row" — which is exactly the
+ * distinction this answer turns on.
+ */
+export async function teamsRoomWatchStopped(partition: Partition): Promise<boolean> {
+  const room = roomEngagementAddress(partition);
+  try {
+    return (await getOperationalStore().getEngagement(room.partition.org, room.partition.surfaceKey, room.anchor))?.stopped === true;
+  } catch (err) {
+    console.warn(`[open-everywhere:teams-engagement] room stop unreadable for ${room.partition.surfaceKey} — HOLDING the ambient wake (fail-closed): ${String(err)}`);
+    return true;
+  }
+}
+
+/** Store the ROOM-grain wake row for an ambient (undirected) Leg A wake — the row a later stop
+ *  marks. Best-effort: `markThreadEngaged` swallows a store failure, and a lost watch row costs a
+ *  stop that could not land, never a turn. */
+export async function markTeamsRoomWatched(partition: Partition, atIso: string): Promise<void> {
+  const room = roomEngagementAddress(partition);
+  // `participating: false` — a WATCH, not an invitation. It also means this write never clears a
+  // `stopped` flag, which is what keeps an ambient wake from lifting the stand-down that should be
+  // suppressing it.
+  await markThreadEngaged(room.partition, room.anchor, atIso, { participating: false });
+}
+
+/**
+ * Lift a ROOM-grain stand-down on an @mention — the way back in, and the reason the room stop is not
+ * a trap. Without it a room stop would outlive every invitation: Leg E's mention mark promotes the
+ * CONVERSATION row, which says nothing about the room, so the room would stay silent with no verb
+ * able to reach it.
+ *
+ * `engagedBy` carries the mention's activity id for the same reason the conversation mark does — a
+ * redelivered mention must not lift a stand-down twice over.
+ */
+export async function clearTeamsRoomStop(partition: Partition, atIso: string, engagedBy: string): Promise<void> {
+  const room = roomEngagementAddress(partition);
+  await markThreadEngaged(room.partition, room.anchor, atIso, { participating: true, engagedBy });
+}
+
+/**
+ * The NATIVE path's one-line admission (channels/teams.ts's mention gate): may this plain,
+ * non-mention message run a turn?
+ *
+ * It exists because the native channel is where a Teams turn is actually minted — the front holds no
+ * continuation-token primitive it could wake an existing native session with, so admitting the
+ * activity through the mention gate IS the wake. The front owns the SUPPRESSION half above it (a
+ * stood-down conversation is never forwarded at all) and the MARK, so this call only ever answers
+ * the delivery question, and it never writes.
+ */
+export async function teamsEngagedAdmits(a: TeamsMessageActivity, deps: TeamsEngagementDeps = {}): Promise<boolean> {
+  if (a.isBotMentioned) return true; // the caller's own mention gate already admitted it
+  // 🔴 THE AUTHOR GATE RUNS HERE TOO, over the SAME predicate the front uses. A machine-authored
+  // CHANNEL activity IS forwarded to the native path, so this is the line that stops an engaged
+  // conversation from admitting the agent's own post and looping on itself.
+  const verdict = await resolveTeamsEngagement(a, teamsMachineAuthored(a), deps);
+  return verdict.kind === "deliver";
+}

package/agent/channels/teams-fire-eligibility.ts

@@ -0,0 +1,152 @@
+// teams-fire-eligibility — Microsoft Graph `accountEnabled` + channel-membership probes for the
+// routine fire-eligibility leg (OPE-522), mirroring core's Slack-only predicate
+// (@open-everywhere/core routines/fire-eligibility.ts, OPE-506) for Teams. Registered into core's
+// teams-bridge.ts (channels/teams-bridge.ts) by registerTeamsProvider() — core stays free of
+// Graph-specific parsing, the same split teams-read.ts already draws for channel reads.
+//
+// IDENTITY: both probes are keyed on the creator's Azure AD OBJECT id, never the Bot Framework
+// `from.id` that `Routine.createdBy` carries for Teams — a DIFFERENT identifier (see
+// teams-identity.ts's separate `aadObjectId` capture, and core's fire-eligibility.ts header). The
+// caller (core's dispatch.ts) reads it back off the routine's stored target via
+// register.ts's resolveTeamsTarget, which stamps it onto the fresh DispatchTarget's `attributes`.
+//
+// TOKEN + TRANSPORT: reuses teams-read.ts's `liveTeamsGraphRequest` (app-only client-credentials
+// Graph token, warm-cached, single-flight) — these are ordinary Graph GETs, no different in shape
+// from a channel-history read. `liveTeamsGraphRequest` fails LOUD (throws) on a missing token or a
+// non-ok response; every probe below catches around it, because this module's contract is fail-OPEN
+// on uncertainty, not fail-loud like the read adapter's.
+//
+// FAIL-OPEN ON UNCERTAINTY, same posture as every other probe in this module family
+// (routines/fire-eligibility.ts, fire-creator.ts): only a well-formed Graph response carrying a
+// POSITIVE "no" (`accountEnabled === false`, or a FULLY-ENUMERATED member list that does not include
+// the creator) skips a fire. A network error, an auth failure, a malformed response shape, or an id
+// Graph can't resolve is UNRESOLVABLE — never a fabricated "no". This is DELIBERATELY STRICTER than
+// routines/fire-eligibility.ts's own Slack room-membership probe on one point: that probe's
+// pagination bound (ROOM_MEMBER_MAX_PAGES) falls through to a cached `false` when a channel has more
+// members than the bound can scan, which reads as a confirmed "not a member" even though the roster
+// was never fully seen. This module tracks whether the LAST page fetched still had a `nextLink`
+// (more roster left unseen) and reports `roster_incomplete` in that case — "hit the page bound with
+// more to see" is kept distinct from "scanned every member and did not find them".
+//
+// 🔴 THE MEMBERSHIP READ TAKES THE GRAPH TEAM ID, AND THE ACTIVITY DOES NOT CARRY ONE (OPE-1810).
+// A Teams activity carries the Bot Connector's team id, a `19:…@thread.tacv2` string; every Graph
+// URL under `/teams/{team-id}/…` takes the team's Microsoft 365 GROUP id instead. Handing the
+// Connector spelling to Graph addresses nothing and answers 404 — so before OPE-1810 this probe
+// threw on EVERY call, read as unresolvable, and the creator check never once enforced. It now
+// resolves the one into the other through channels/teams-graph-team-id.ts, the same call the read
+// verbs and the catch-up window already make.
+//
+// 🔴 AND THE ANSWER NOW BINDS (Tommy, 2026-09-13). A creator confirmed OUT of the channel stops
+// getting their routine, the same outcome and the same `creator_removed_from_room` audit row the
+// Slack path has produced since OPE-506. Fail-open survives only for an answer the probe could not
+// GET, and every such arm names its own cause ({@link TeamsMembershipUnresolved}) so the dispatcher
+// can audit it — a fail-open that writes nothing is indistinguishable from a pass, which is the
+// state this module was in for its whole life before this ticket.
+
+import type {
+  TeamsAccountActiveCheck,
+  TeamsMembershipUnresolved,
+  TeamsRoomMembership,
+  TeamsRoomMembershipCheck,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { teamsGraphTeamId } from "./teams-graph-team-id.js";
+import { liveTeamsGraphRequest, type TeamsGraphRequester } from "./teams-read.js";
+
+const GRAPH_BASE = "https://graph.microsoft.com/v1.0";
+
+/** Bounds a busy channel roster's pagination (mirrors teams-read.ts's TEAMS_GRAPH_MAX_PAGES, a
+ *  larger bound here since a roster page is denser than a message page). */
+const TEAMS_MEMBER_MAX_PAGES = 10;
+
+interface GraphConversationMember {
+  /** The Azure AD object id for an `aadUserConversationMember` (every human Teams member). */
+  readonly userId?: string;
+}
+
+interface GraphMemberPage {
+  readonly value?: readonly GraphConversationMember[];
+  readonly ["@odata.nextLink"]?: string;
+}
+
+/** The one spelling of an unresolved answer, so no arm below can forget to name its cause. */
+function unresolved(cause: TeamsMembershipUnresolved): TeamsRoomMembership {
+  return { member: undefined, unresolved: cause };
+}
+
+/**
+ * Is `aadObjectId` a member of Teams channel `channelId` (inside team `botTeamId`) RIGHT NOW?
+ * Resolves `botTeamId` — the activity's own Bot Connector team id — into the Microsoft 365 group id
+ * Graph takes, then paginates `GET /teams/{team}/channels/{channel}/members`, bounded at
+ * {@link TEAMS_MEMBER_MAX_PAGES}.
+ *
+ * Pure but for the injected `req` — exported (not the `req`-defaulted live wrapper below) so the
+ * resolution, the pagination and every fail-open arm are unit-testable with a canned requester, no
+ * token mint and no network call. The team-id resolution is driven in a test through
+ * teams-graph-team-id.ts's own `_seedTeamsGraphTeamIdForTest` seam rather than a second injected
+ * dependency here: one team id maps to one group id for the life of the process, so the cache IS
+ * the seam.
+ */
+export async function teamsRoomMembershipViaGraph(
+  botTeamId: string,
+  channelId: string,
+  aadObjectId: string,
+  serviceUrl: string | undefined,
+  req: TeamsGraphRequester,
+): Promise<TeamsRoomMembership> {
+  if (botTeamId.length === 0 || channelId.length === 0 || aadObjectId.length === 0) return unresolved("missing_ids");
+  // 🔴 RESOLVE FIRST, AND NEVER FALL BACK TO `botTeamId`. A fallback would put the Connector
+  // spelling back in the Graph URL, which is the exact defect OPE-1810 removes — and because the
+  // read would then 404 into `read_error`, the fallback would be INVISIBLE in the audit trail.
+  const graphTeamId = await teamsGraphTeamId(botTeamId, serviceUrl);
+  if (graphTeamId === undefined) return unresolved("team_id_unresolved");
+  try {
+    let url: string | undefined = `${GRAPH_BASE}/teams/${encodeURIComponent(graphTeamId)}/channels/${encodeURIComponent(channelId)}/members`;
+    for (let page = 0; page < TEAMS_MEMBER_MAX_PAGES && url; page++) {
+      const json = (await req(url)) as GraphMemberPage;
+      // A genuine Graph success always carries `value` as an array, even an empty one — an
+      // unrecognised shape is read as UNRESOLVABLE, never as "confirmed nobody's in this channel"
+      // (the same posture routines/fire-eligibility.ts's liveRoomMembership takes on a malformed
+      // `members` field).
+      if (!Array.isArray(json.value)) return unresolved("malformed_response");
+      if (json.value.some((m) => m.userId === aadObjectId)) return { member: true };
+      url = typeof json["@odata.nextLink"] === "string" ? json["@odata.nextLink"] : undefined;
+    }
+    // `url` still set here means the page bound was hit with roster left unseen — that is NOT the
+    // same fact as "scanned every member and they weren't in it", so it stays unresolved rather than
+    // becoming a confirmed (and possibly wrong) "removed". Only a loop that ended because pagination
+    // itself ran out (`url` fell to `undefined`) has actually seen the WHOLE roster — and THAT is
+    // the answer that now skips a fire.
+    return url ? unresolved("roster_incomplete") : { member: false };
+  } catch {
+    return unresolved("read_error"); // token mint failure / network error / a non-ok Graph response
+  }
+}
+
+/** Live default: {@link teamsRoomMembershipViaGraph} through the real Graph token + transport. */
+export const liveTeamsRoomMembership: TeamsRoomMembershipCheck = (teamId, channelId, aadObjectId, serviceUrl) =>
+  teamsRoomMembershipViaGraph(teamId, channelId, aadObjectId, serviceUrl, liveTeamsGraphRequest);
+
+interface GraphUser {
+  readonly accountEnabled?: boolean;
+}
+
+/**
+ * Is `aadObjectId`'s Entra account CURRENTLY enabled? `GET /users/{id}?$select=accountEnabled`.
+ * Pure but for the injected `req` — same DI shape as {@link teamsRoomMembershipViaGraph}.
+ */
+export async function teamsAccountActiveViaGraph(aadObjectId: string, req: TeamsGraphRequester): Promise<boolean | undefined> {
+  if (aadObjectId.length === 0) return undefined;
+  try {
+    const json = (await req(`${GRAPH_BASE}/users/${encodeURIComponent(aadObjectId)}?$select=accountEnabled`)) as GraphUser;
+    // Only a POSITIVELY-TYPED boolean field counts — a response Graph returned for a different
+    // shape (or a 404/error already caught below) never reads as a fabricated "active" OR
+    // "inactive". Never a fabricated "no": the field must be `=== false`, not merely falsy/absent.
+    if (typeof json?.accountEnabled !== "boolean") return undefined;
+    return json.accountEnabled;
+  } catch {
+    return undefined; // 404 (unresolvable id) / auth error / transport failure ⇒ unresolvable
+  }
+}
+
+/** Live default: {@link teamsAccountActiveViaGraph} through the real Graph token + transport. */
+export const liveTeamsAccountActive: TeamsAccountActiveCheck = (aadObjectId) => teamsAccountActiveViaGraph(aadObjectId, liveTeamsGraphRequest);