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

package/agent/channels/teams-stop.ts

@@ -0,0 +1,319 @@
+// THE TEAMS STOP ARM (OPE-898) — the reaction affordance, on the one glyph vocabulary Teams has.
+//
+// A person watching the agent do the wrong thing must be able to stop it, on every surface. Slack
+// and Discord reach that through a ✋ reaction (OPE-418). Teams delivers reactions too, so the arm is
+// event-driven here as well — but the VENDOR CONSTRAINTS are real and they shape the design, so read
+// them before changing anything in this file.
+//
+// 🔴 THIS FILE IS ALSO THE SURFACE'S ONE REACTION ENTRY POINT. The front acks every
+// `messageReaction` activity here and forwards none, so the FEEDBACK arm
+// (channels/teams-reaction-feedback.ts, OPE-1502) hangs off `routeTeamsStopReaction` rather than off
+// a second ingress. The fan-out comment on that function says how the two arms partition.
+//
+// ── WHAT MICROSOFT ACTUALLY DELIVERS (learn.microsoft.com, "Conversation events", read 2026-08-20)
+//
+//  1. The activity is `type: "messageReaction"`, with `reactionsAdded` / `reactionsRemoved`.
+//  2. 🔴 THE REACTION VOCABULARY IS SIX FIXED VALUES: `angry`, `heart`, `laugh`, `like`, `sad`,
+//     `surprised`. There is no ✋, no custom emoji and no shortcode. So the glyph Slack and Discord
+//     use cannot be the glyph here, and picking one of the six is not a style choice — it is the
+//     only choice the platform offers.
+//  3. 🔴 TEAMS SENDS THE EVENT ONLY FOR MESSAGES THE AGENT ITSELF SENT ("a user adds or removes
+//     reactions to a message, which was sent by your agent"). That is a FENCE, not a limitation: a
+//     reaction on somebody else's message can never reach this arm at all.
+//  4. `replyToId` names the agent's own message. It is NOT the turn's anchor message — the anchor is
+//     the human's triggering message — so this arm never resolves by `anchorKey`. It resolves by the
+//     CONVERSATION, which is the `/oe stop` grain: the newest running turn in this room.
+//  5. The event carries no message content, so nothing here reads or needs any.
+//
+// ── WHY `angry`
+//
+// Of the six, `angry` is the one people already use to mean "this is wrong". The false-stop window is
+// narrow by construction, and every side of it is a fence Teams or the registry already enforces: the
+// reaction must be on the AGENT's own message (3), in a room with a turn that is RUNNING RIGHT NOW
+// (the anchor registry's 45-minute TTL and its live-turn check), and from somebody who is not the
+// agent (the fail-closed guard below). A person who angry-reacts an agent message while the agent is
+// working is saying the thing the affordance is for.
+//
+// The value is a named constant so it can be changed in one place if the vendor widens the
+// vocabulary — which is the ONE upstream change that would let this surface use ✋ like the others.
+//
+// ⚠️ THE ARM SITS ABOVE THE EXTERNAL-PARTICIPANT GATE IN THE FRONT, AND THAT IS DELIBERATE. A cancel
+// only ever takes capability away — it can start nothing, spend nothing and read nothing — so a
+// person the policy would not let WAKE the agent may still stop it. That is the same posture the
+// Slack and Discord arms have carried since OPE-418, and treating stop as a privilege would put the
+// control furthest from the people most likely to need it.
+
+import {
+  cancelAnchoredTurn,
+  resolvePartition,
+  turnChannelKey,
+  type AttachSessionForCancel,
+  type CancelOutcome,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { buildTeamsAuth } from "./teams-identity.js";
+import { liveTeamsReactionFeedbackDeps, routeTeamsReactionFeedback, type TeamsReactionFeedbackDeps } from "./teams-reaction-feedback.js";
+
+/** The Bot Framework reaction type this surface treats as "stop". See the header for why it is not
+ *  ✋ and why it is this one of the six. */
+export const TEAMS_STOP_REACTION = "angry";
+
+/** One Teams `messageReaction` activity, narrowed to what the two reaction arms need. */
+export interface TeamsReactionActivity {
+  /** The reaction types ADDED by this activity. A removal never stops — see {@link routeTeamsStopReaction}. */
+  readonly added: readonly string[];
+  /** The reaction types REMOVED by this activity. The stop arm ignores them; the feedback arm
+   *  (channels/teams-reaction-feedback.ts) records them as retractions. */
+  readonly removed: readonly string[];
+  /** The AGENT's own message the reaction landed on (the activity's `replyToId`). Teams delivers a
+   *  `messageReaction` only for messages the agent sent, so this names the feedback target. It is
+   *  NOT the turn's anchor — see the `query` comment in {@link routeTeamsStopReaction}. */
+  readonly replyToId?: string;
+  /** WHO reacted (the activity's `from.id`). */
+  readonly reactorId?: string;
+  /** The AGENT's own Bot Framework id (the activity's `recipient.id`) — the fail-closed guard. */
+  readonly agentId?: string;
+  /** The room. On a channel activity this is the REPLY CHAIN id, which is what the stop registry
+   *  keys a Teams turn by (see teams-identity.ts `anchorChannelId`). */
+  readonly conversationId?: string;
+  readonly tenantId?: string;
+  readonly teamsChannelId?: string;
+  readonly teamId?: string;
+  readonly scope?: string;
+}
+
+/** Why the arm did what it did — for the caller's log, never for a person to read. */
+export type TeamsStopOutcome = (
+  | { readonly stopped: false; readonly reason: string }
+  | { readonly stopped: true; readonly outcome: CancelOutcome }
+) & {
+  /** The FEEDBACK write this activity started, present only when it carried a non-stop reaction
+   *  (OPE-1502). It is SETTLED on every path the arm returns from, the cancel included (OPE-1546) —
+   *  unless it outran {@link TEAMS_FEEDBACK_SETTLE_TIMEOUT_MS}, which is the one case a caller that
+   *  ignores it can lose a row. It never rejects.
+   *
+   *  It rides the outcome so a test can name the write it is asserting on, and so a future caller
+   *  that wants to observe the row can. It is NOT a lifetime lever any more: the arm holds its own
+   *  promise open until the write lands, which is what keeps the row inside the host's `waitUntil`
+   *  lifetime without the front knowing this arm has a second consumer at all. */
+  readonly feedback?: Promise<void>;
+};
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function pick(o: unknown, k: string): unknown {
+  return isObject(o) ? o[k] : undefined;
+}
+
+/** Every `type` string in a `reactionsAdded` array, defensively. A malformed member contributes
+ *  nothing rather than throwing — an ingress must not 500 on a body it does not recognise. */
+function reactionTypes(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  const out: string[] = [];
+  for (const member of v) {
+    const t = str(pick(member, "type"));
+    if (t) out.push(t.toLowerCase());
+  }
+  return out;
+}
+
+/**
+ * Parse one Bot Framework activity into a {@link TeamsReactionActivity}, or null when it is not a
+ * reaction activity. NEVER THROWS.
+ *
+ * This reads the RAW parsed body rather than eve's `parseTeamsActivity`, because that parser answers
+ * only for `message` activities — a `messageReaction` comes back as null from it, which is exactly
+ * why the front forwards one to the native channel today and nothing happens.
+ */
+export function parseTeamsReaction(parsed: unknown): TeamsReactionActivity | null {
+  if (!isObject(parsed)) return null;
+  if (parsed["type"] !== "messageReaction") return null;
+  const conversation = parsed["conversation"];
+  const channelData = parsed["channelData"];
+  return {
+    added: reactionTypes(parsed["reactionsAdded"]),
+    removed: reactionTypes(parsed["reactionsRemoved"]),
+    ...(str(parsed["replyToId"]) ? { replyToId: str(parsed["replyToId"])! } : {}),
+    reactorId: str(pick(parsed["from"], "id")),
+    agentId: str(pick(parsed["recipient"], "id")),
+    conversationId: str(pick(conversation, "id")),
+    tenantId: str(parsed["tenantId"]) ?? str(pick(conversation, "tenantId")) ?? str(pick(pick(channelData, "tenant"), "id")),
+    teamsChannelId: str(pick(pick(channelData, "channel"), "id")),
+    teamId: str(pick(pick(channelData, "team"), "id")),
+    scope: str(pick(conversation, "conversationType")),
+  };
+}
+
+/** Injected seams, so parse + guard + cancel is unit-tested without a Bot registration. */
+export interface TeamsStopDeps {
+  readonly attachSession: AttachSessionForCancel;
+  /** Injectable for the test; defaults to the shared `cancelAnchoredTurn`. There is no second cancel
+   *  implementation behind this — the seam exists to observe the call, never to replace it. */
+  readonly cancel?: typeof cancelAnchoredTurn;
+  /** The FEEDBACK arm's sinks (OPE-1502), injectable for the same reason. Defaults to the live
+   *  audit/telemetry sink. See {@link routeTeamsStopReaction} for why the fan-out lives here. */
+  readonly feedback?: TeamsReactionFeedbackDeps;
+}
+
+/** What {@link stopGuard} decided about one activity. */
+type TeamsStopGuard =
+  | { readonly stop: false; readonly reason: string }
+  /** The two ids the cancel needs, POSITIVELY RESOLVED — never re-read off the activity. */
+  | { readonly stop: true; readonly reactorId: string; readonly conversationId: string };
+
+/**
+ * Decide whether one activity is a stop, and say why not when it is not.
+ *
+ * 🔴 PURE, AND THAT IS WHY IT EXISTS. {@link routeTeamsStopReaction} must know whether a cancel is
+ * coming BEFORE it starts the feedback write, so that the write can be awaited on every path that
+ * cancels nothing and fired-and-forgotten on the one path where a person is waiting. Five inline
+ * early returns cannot answer that question ahead of time.
+ *
+ * 🔴 THE REACTOR GUARD FAILS CLOSED. The agent's own reactions ride the same webhook, and behind
+ * `cancel()` a fail-OPEN identity check is a self-cancel. A stop therefore needs a POSITIVELY
+ * RESOLVED agent id and a reactor who is not it. `28:` is the Bot Framework's own prefix for an
+ * application id, so a reactor wearing it is a bot whatever the recipient field says.
+ */
+function stopGuard(rx: TeamsReactionActivity): TeamsStopGuard {
+  // ONLY ON ADD, and only on `TEAMS_STOP_REACTION`. A removal means nothing and must never trigger
+  // anything — the same rule the Slack, Discord and Linear arms keep.
+  if (!rx.added.includes(TEAMS_STOP_REACTION)) return { stop: false, reason: "stop: not the stop reaction" };
+  if (!rx.reactorId) return { stop: false, reason: "stop: no reactor id — refusing to cancel (fail-closed)" };
+  if (!rx.agentId) return { stop: false, reason: "stop: agent identity unresolved — refusing to cancel (fail-closed)" };
+  if (rx.reactorId === rx.agentId || rx.reactorId.startsWith("28:")) {
+    return { stop: false, reason: "stop: the reactor is a bot — never a self-cancel" };
+  }
+  if (!rx.conversationId) return { stop: false, reason: "stop: no conversation — nothing to resolve a turn against" };
+  return { stop: true, reactorId: rx.reactorId, conversationId: rx.conversationId };
+}
+
+/** Start the FEEDBACK write for one activity's non-stop reactions. NEVER REJECTS: a feedback row is
+ *  best-effort on every path, so its failure is swallowed here rather than by each caller. */
+async function writeTeamsReactionFeedback(feedback: TeamsReactionActivity, deps: TeamsStopDeps): Promise<void> {
+  await routeTeamsReactionFeedback(feedback, deps.feedback ?? liveTeamsReactionFeedbackDeps()).catch(() => undefined);
+}
+
+/** How long this arm holds its own promise open for the feedback write. See {@link settleFeedback}. */
+export const TEAMS_FEEDBACK_SETTLE_TIMEOUT_MS = 5000;
+
+/** Wait for the feedback write to settle, with a ceiling.
+ *
+ * The three call sites below await this promise so the row survives the front's `waitUntil` — see
+ * the fan-out block. 🔴 THE CEILING IS WHAT KEEPS THAT FROM BECOMING A LEAK: the awaits extend the
+ * `waitUntil` promise by however long the audit sink takes, which unbounded is however long a stuck
+ * store takes. Past the ceiling the write is abandoned, not cancelled, and may still land — the same
+ * trade the row already made by being best-effort. The write itself never rejects, so nothing is
+ * left unhandled behind the race.
+ *
+ * `teams-stop-test.ts` §7 pins this against a sink that never settles. Without that case the ceiling
+ * is asserted by this comment alone, and a refactor that put a bare `await pending` back would pass
+ * every other assertion in the suite. */
+async function settleFeedback(pending: Promise<void> | undefined): Promise<void> {
+  if (!pending) return;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const ceiling = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, TEAMS_FEEDBACK_SETTLE_TIMEOUT_MS);
+    timer.unref?.();
+  });
+  try {
+    await Promise.race([pending, ceiling]);
+  } finally {
+    // The ordinary path settles the write long before the ceiling; without this the timer would sit
+    // in the loop for the rest of its five seconds on every reaction.
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Route one Teams reaction activity. Cancels the turn running in this conversation, or reports why
+ * not. {@link stopGuard} holds the guards, the fail-closed rule among them.
+ */
+export async function routeTeamsStopReaction(rx: TeamsReactionActivity, deps: TeamsStopDeps): Promise<TeamsStopOutcome> {
+  // ── THE FEEDBACK FAN-OUT (OPE-1502) ────────────────────────────────────────────────────────────
+  //
+  // POSITION IS LOAD-BEARING, and so is the fact that it sits in THIS function rather than in the
+  // front. The front routes EVERY `messageReaction` activity here and acks — it never forwards one —
+  // so this is the one reachable point a second consumer can attach to.
+  //
+  // 🔴 THE SPLIT IS PER REACTION, NOT PER ACTIVITY. `reactionsAdded` and `reactionsRemoved` are
+  // ARRAYS, and one activity can carry an added `angry` beside an added `like`. Only the added
+  // `angry` is the MECHANISM; the rest of that same activity is a person's sentiment and must still
+  // be recorded. Partitioning on the whole activity — "does `added` contain the stop glyph" — would
+  // drop the `like` on the floor. A REMOVED stop glyph is not a stop at all, so it stays feedback,
+  // which is the same rule the Slack and Discord arms keep for ✋.
+  //
+  // 🔴 THE GUARDS DECIDE FIRST, SO A CANCEL IS NEVER HELD BEHIND THE WRITE. A lost OR SLOW feedback
+  // row must never cost a person their stop, and `.catch()` answers only the lost half — an awaited
+  // write in FRONT of the guards holds the cancel for exactly as long as the audit sink takes, and
+  // that sink is the slowest thing this arm touches. So the arm asks `stopGuard` whether a cancel is
+  // coming BEFORE it starts the write, and nothing is awaited between starting the write and calling
+  // `cancel()`. The two then run concurrently and the cancel always lands first.
+  //
+  // 🔴 THE ARM AWAITS THE WRITE AFTER THE CANCEL, WHICH IS WHAT MAKES THE ROW SURVIVE (OPE-1546).
+  // The front hands THIS function's promise to `waitUntil` and awaits no further, so whatever is
+  // still in flight when this promise resolves is at the mercy of a suspending host. Returning with
+  // the write unfinished therefore lost rows on the one path that has a second thing to do — a mixed
+  // `angry`+`like` activity could lose the `like`, and a two-reaction activity its second row. The
+  // close is one `await` here rather than a hook in the front: the write is already started, the
+  // cancel has already happened, and holding this promise open costs the stop nothing that a person
+  // can observe, because the ingress acked before any of this ran. Every path now returns with the
+  // row settled, which is why `TeamsStopOutcome.feedback` no longer states a trade.
+  //
+  // 🔴 THE HOLD IS BOUNDED. "Holding this promise open" is holding the front's `waitUntil` open, and
+  // the thing being waited on is the slowest store this arm touches. The ingress acked before any of
+  // this ran, so a person waits on none of it — but a stuck sink would hold the host's `waitUntil`
+  // lifetime open with no limit, which is a leak rather than a survival trick. `settleFeedback` puts
+  // a ceiling on it.
+  const feedback: TeamsReactionActivity = { ...rx, added: rx.added.filter((type) => type !== TEAMS_STOP_REACTION) };
+  const carries = feedback.added.length > 0 || feedback.removed.length > 0;
+  const guard = stopGuard(rx);
+  const pending = carries ? writeTeamsReactionFeedback(feedback, deps) : undefined;
+  const rider = pending ? { feedback: pending } : {};
+
+  if (!guard.stop) {
+    await settleFeedback(pending);
+    return { stopped: false, reason: guard.reason, ...rider };
+  }
+
+  const partition = resolvePartition({
+    channel: { kind: "teams" },
+    session: {
+      auth: {
+        current: buildTeamsAuth({
+          userId: guard.reactorId,
+          conversationId: guard.conversationId,
+          ...(rx.tenantId ? { tenantId: rx.tenantId } : {}),
+          ...(rx.teamsChannelId ? { channelId: rx.teamsChannelId } : {}),
+          ...(rx.teamId ? { teamId: rx.teamId } : {}),
+          ...(rx.scope ? { scope: rx.scope } : {}),
+        }),
+      },
+    },
+  });
+  const channelKey = turnChannelKey("teams", guard.conversationId);
+  if (!channelKey) {
+    // Still a path that cancels nothing, so the write is settled here like the refusals above.
+    await settleFeedback(pending);
+    return { stopped: false, reason: "stop: no conversation key", ...rider };
+  }
+  const result = await (deps.cancel ?? cancelAnchoredTurn)({
+    org: partition.org,
+    platform: "teams",
+    workspace: partition.workspace,
+    requestedBy: guard.reactorId,
+    via: "reaction",
+    // THE CONVERSATION KEY ONLY. `replyToId` names the AGENT's message, and the anchor registry keys
+    // on the human's triggering message — the two never match, so offering an `anchorKey` here would
+    // be a lookup that always misses. This is the `/oe stop` grain: the newest running turn here.
+    query: { channelKey },
+    attachSession: deps.attachSession,
+  });
+  // AFTER the cancel, never before it — see the fan-out block above. This is the whole of OPE-1546.
+  await settleFeedback(pending);
+  return { stopped: true, outcome: result.outcome, ...rider };
+}