@open-everywhere/provider-teams 0.4.0 → 0.6.0

package/agent/approvals/teams-card.ts

@@ -0,0 +1,189 @@
+// Pure Teams renderers + the action-data codec for the approval card (OPE-2424) — the Teams sibling
+// of core's card.ts (Slack Block Kit) and the Discord bundle's discord-card.ts. PURE by the same
+// doctrine: no I/O, nothing async. The card is a CODE-RENDERED VIEW of the FROZEN args, never model
+// text. The I/O half (the Connector poster and the invoke handler) lives in teams-flow.ts.
+//
+// Teams differs from Slack and Discord in three ways, and all three are handled here:
+//   - The card is an ADAPTIVE CARD attachment on a message activity. The body is TextBlocks, and the
+//     buttons are `Action.Execute` actions.
+//   - `Action.Execute` (Universal Actions), not `Action.Submit`. A tap arrives as an `invoke` activity
+//     named `adaptiveCard/action`, and the HTTP response to that invoke can carry a REPLACEMENT card
+//     (the decided render) or a message only the clicker sees (a refusal). That is the same response
+//     shape Discord's interaction reply has, so the click path maps one resolution to one response.
+//   - The payload rides the action's `data` object, not an id string. The org rides there too, for
+//     the reason Slack puts it in the button `value`: the click handler needs the org BEFORE it can
+//     look the row up. The data key is distinct from eve's own HITL key (`eve_input`), so the front
+//     route can tell an OE approval tap from an eve HITL answer without a second check.
+
+import type { CardOptionTone, PendingActionRow } from "@open-everywhere/core/agent/adapter-api.js";
+import { approvalLabel, optionsWithoutConfirm, pendingCardLayout, plainSummaryForRow } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The `invoke` activity name Teams gives an `Action.Execute` tap. */
+export const TEAMS_ADAPTIVE_CARD_ACTION_INVOKE = "adaptiveCard/action";
+
+/** The `verb` every OE approval action carries. The decision rides `data`, so one verb covers all. */
+export const OE_TEAMS_APPROVAL_VERB = "oe-approval";
+
+/** The `data` key every OE approval action carries. Distinct from eve's HITL key (`eve_input`). */
+export const OE_TEAMS_APPROVAL_DATA_KEY = "oe_teams_approval";
+
+/** The Adaptive Card attachment content type. */
+export const TEAMS_ADAPTIVE_CARD_CONTENT_TYPE = "application/vnd.microsoft.card.adaptive";
+
+/** Universal Actions (`Action.Execute`) need schema 1.4 or later. */
+const ADAPTIVE_CARD_VERSION = "1.4";
+
+/**
+ * Every verb a Teams approval action can carry — the same closed set the Discord bundle uses, and a
+ * SUBSET of core's `ApprovalDecision`. `contradict` is the judge-lift notice's one button: it decides
+ * nothing, it records an overrule of a verdict whose act has already run.
+ */
+export type TeamsApprovalDecision = "approve" | "reject" | "approve_session" | "contradict";
+
+/** The closed verb set as a VALUE, so build and parse cannot drift apart. */
+const TEAMS_APPROVAL_DECISIONS: readonly TeamsApprovalDecision[] = ["approve", "reject", "approve_session", "contradict"];
+
+/** One decoded OE approval action payload. */
+export interface TeamsApprovalAction {
+  readonly id: string;
+  readonly decision: TeamsApprovalDecision;
+  readonly org: string;
+}
+
+/** One Adaptive Card element or action. Loosely typed on purpose, as card.ts's SlackBlock is. */
+export interface AdaptiveElement {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+/** One rendered Adaptive Card. */
+export interface TeamsAdaptiveCard {
+  readonly type: "AdaptiveCard";
+  readonly $schema: string;
+  readonly version: string;
+  readonly body: readonly AdaptiveElement[];
+  readonly actions?: readonly AdaptiveElement[];
+}
+
+/** The `data` object of one OE approval action. */
+export function buildTeamsApprovalData(row: Pick<PendingActionRow, "id" | "org">, decision: TeamsApprovalDecision): Record<string, unknown> {
+  return { [OE_TEAMS_APPROVAL_DATA_KEY]: { id: row.id, decision, org: row.org } };
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function nonEmpty(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Decode an OE approval payload from an action's `data` object. Returns null for anything else —
+ * a foreign data object, a missing id or org, or a decision outside the closed set — so a caller
+ * reads "not parseable" as "not ours" with no second check (core's parseApprovalAction does the same).
+ */
+export function parseTeamsApprovalData(data: unknown): TeamsApprovalAction | null {
+  if (!isObject(data)) return null;
+  const payload = data[OE_TEAMS_APPROVAL_DATA_KEY];
+  if (!isObject(payload)) return null;
+  const id = nonEmpty(payload["id"]);
+  const org = nonEmpty(payload["org"]);
+  const decision = payload["decision"];
+  if (!id || !org || typeof decision !== "string") return null;
+  if (!TEAMS_APPROVAL_DECISIONS.includes(decision as TeamsApprovalDecision)) return null;
+  return { id, decision: decision as TeamsApprovalDecision, org };
+}
+
+function textBlock(text: string, extra: Record<string, unknown> = {}): AdaptiveElement {
+  return { type: "TextBlock", text, wrap: true, ...extra };
+}
+
+function card(body: readonly AdaptiveElement[], actions?: readonly AdaptiveElement[]): TeamsAdaptiveCard {
+  return {
+    type: "AdaptiveCard",
+    $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+    version: ADAPTIVE_CARD_VERSION,
+    body,
+    ...(actions && actions.length > 0 ? { actions } : {}),
+  };
+}
+
+function execute(row: Pick<PendingActionRow, "id" | "org">, title: string, decision: TeamsApprovalDecision, style?: "positive" | "destructive"): AdaptiveElement {
+  return {
+    type: "Action.Execute",
+    title,
+    verb: OE_TEAMS_APPROVAL_VERB,
+    data: buildTeamsApprovalData(row, decision),
+    ...(style ? { style } : {}),
+  };
+}
+
+/** The shared card body: header, then one TextBlock per summary line, then the provenance line. */
+function cardBody(header: string, summaryLines: readonly string[], footer: string): AdaptiveElement[] {
+  return [
+    textBlock(header, { weight: "Bolder", size: "Medium" }),
+    ...summaryLines.map((line) => textBlock(line)),
+    textBlock(footer, { isSubtle: true, size: "Small" }),
+  ];
+}
+
+/** An approval card's body: the PLAIN SENTENCE first (OPE-2434), then the `Approval requested: <kind>` label, the summary lines and the provenance line. The sentence went through core's `plainValue`, so it carries no markdown a TextBlock would render. */
+function approvalCardBody(row: PendingActionRow, summaryLines: readonly string[], footer: string): AdaptiveElement[] {
+  return [
+    textBlock(plainSummaryForRow(row), { weight: "Bolder", size: "Medium" }),
+    textBlock(approvalLabel(row.kind), { isSubtle: true, size: "Small", spacing: "None" }),
+    ...summaryLines.map((line) => textBlock(line)),
+    textBlock(footer, { isSubtle: true, size: "Small" }),
+  ];
+}
+
+const OPTION_STYLE: Record<CardOptionTone, "positive" | "destructive" | undefined> = { primary: "positive", danger: "destructive", neutral: undefined };
+
+/**
+ * The card for a still-pending action: the plain sentence, the summary, "requested by / expires", and one `Action.Execute` per layout option. Mirrors card.ts's pendingCardBlocks. The requester is the Bot Framework principal id, because an Adaptive Card mention needs the person's display name, and the frozen row carries only the id.
+ * The OPTIONS come from core's card layout (OPE-53, OPE-2363: only a ROUTINE's card gets the middle grant option), so Slack, Discord and Teams cannot disagree. OPE-2456's rule option needs a confirmation before the click. This renderer sends an `Action.Execute` tap with none, so it leaves that option out.
+ */
+export function pendingTeamsCard(row: PendingActionRow, summaryLines: readonly string[]): TeamsAdaptiveCard {
+  const layout = pendingCardLayout(row, summaryLines);
+  // This card's `Action.Execute` tap is sent with no confirmation first, so the rule option (OPE-2456) is left out here.
+  const actions = optionsWithoutConfirm(layout.options).map((o) => execute(row, o.label, o.verb, OPTION_STYLE[o.tone]));
+  return card(approvalCardBody(row, summaryLines, `Requested by ${layout.requestedBy} · ${layout.expiry}`), actions);
+}
+
+/**
+ * The card once a decision has landed: the same sentence and summary, no actions, one outcome line. It decides
+ * nothing — it renders what the caller already CAS-decided. `deciderLabel` is the name the click
+ * activity carried, when the caller has one; the row's principal id otherwise.
+ */
+export function decidedTeamsCard(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string, deciderLabel?: string): TeamsAdaptiveCard {
+  const who = deciderLabel ?? row.decidedBy ?? "unknown";
+  const decided =
+    row.status === "approved"
+      ? `✅ Approved by ${who} · ${outcomeLine}`
+      : row.status === "rejected"
+        ? `❌ Rejected by ${who}${outcomeLine === "rejected" ? "" : ` · ${outcomeLine}`}`
+        : "⏰ Expired";
+  return card(approvalCardBody(row, summaryLines, decided));
+}
+
+/**
+ * The judge-lift notice (OPE-1103 on Discord, OPE-2424 here): the trace of an act the armed judge
+ * lifted, with the one "This should not have run" button. NOT an approval card — no Approve, no
+ * Reject, no expiry line — because the act has already run.
+ */
+export function judgeLiftNoticeTeamsCard(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string): TeamsAdaptiveCard {
+  return card(
+    cardBody(
+      `Ran without asking: ${row.kind}`,
+      summaryLines,
+      `⚡ Auto-approved by the approval judge — no card was posted and this has already run · ${outcomeLine}`,
+    ),
+    [execute(row, "This should not have run", "contradict", "destructive")],
+  );
+}
+
+/** One Adaptive Card as a message-activity attachment. */
+export function teamsCardAttachment(c: TeamsAdaptiveCard): { readonly contentType: string; readonly content: TeamsAdaptiveCard } {
+  return { contentType: TEAMS_ADAPTIVE_CARD_CONTENT_TYPE, content: c };
+}

package/agent/approvals/teams-flow.ts

@@ -0,0 +1,467 @@
+// The Teams I/O half of the approval flow (OPE-2424) — the sibling of core's Slack wiring and the
+// Discord bundle's discord-flow.ts, and it funnels through the SAME platform-neutral decide core
+// (`resolveApprovalClick`). Nothing here decides: the CAS, the approver policy, the clicker gate, the
+// halt arrow, the execute and every audit row stay in core. This file renders and transports.
+//
+//   postTeamsApprovalCard()     — the CardPoster this bundle registers. It renders the pure card
+//                                 (teams-card.ts) and sends it through the Bot Connector into the
+//                                 card's conversation. NEVER throws (CardPoster contract): a failure
+//                                 resolves undefined, and requestApproval expires the pending.
+//   postTeamsJudgeLiftNotice()  — the JudgeLiftNoticePoster: the trace of an act the armed judge
+//                                 lifted, with the one "This should not have run" button. Same
+//                                 transport, and it is best-effort, because the act has already run.
+//   handleTeamsApprovalInvoke() — called by the front route (channels/teams-front.ts) for one
+//                                 VERIFIED `adaptiveCard/action` invoke that carries an OE approval
+//                                 payload. It owns the tap end to end and returns the invoke
+//                                 response body. NEVER throws: Teams shows an error over a tap whose
+//                                 invoke does not answer.
+//   teamsDecisionFeedback       — the two decision-feedback legs core's sweep and session-grant
+//                                 release call for a Teams card (core approvals/flow.ts
+//                                 `registerDecisionFeedbackSurface`).
+//
+// 🔴 THE TAP IS AUTHENTICATED BEFORE IT REACHES THIS FILE. The front route verifies the Bot Framework
+// JWT (eve's `verifyTeamsRequest`) on EVERY request and answers 401 before it parses the body, so an
+// unsigned or forged invoke never reaches `handleTeamsApprovalInvoke`. It is the same verifier, on
+// the same handler, that admits a message activity.
+//
+// 🔴 WHAT THE TOKEN PROVES, AND WHAT IT DOES NOT. The token proves that the Bot Framework service
+// relayed the request to this app id. It does not bind the body, and it is the same token for EVERY
+// channel on the bot registration (`teams-origin-codec.ts` records the same limit). So this file
+// accepts a tap ONLY when the activity's own `channelId` is `msteams`: a Web Chat or Direct Line
+// client sets `from` and `channelData` itself, and a tap from there must never reach the decide core
+// as a Teams person. The clicker, the tenant and the room are then read off a Teams activity that
+// Microsoft relayed; the card's data payload names only the org and the pending id. A tap with no
+// tenant is refused rather than decided with the clicker gate switched off.
+//
+// WHY THE RESPONSE IS THE UI (Discord's shape, not Slack's): an `Action.Execute` tap is answered by
+// the invoke response itself. A card body REPLACES the card (the decided render, no buttons), and a
+// message body shows a note to the clicker alone (a refusal, with the card left live for someone who
+// can decide it). The decision FEEDBACK — the fresh notice beside the card and the decision wake —
+// runs under the route's `waitUntil` when there is one, because nothing in the response depends on it.
+
+import type { TeamsInvokeActivity } from "eve/channels/teams";
+import {
+  resolveApprovalClick,
+  deliverDecisionFeedback,
+  clickerFloorRefusalNotice,
+  judgeContradictionNotice,
+  getOperationalStore,
+  surfaceKeySegment,
+  type ApprovalClickResolution,
+  type ApprovalOutcome,
+  type DecisionFeedbackSurface,
+  type DecisionWakeDeps,
+  type PendingActionRow,
+  type UnifiedWakeOrigin,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import {
+  TEAMS_ADAPTIVE_CARD_ACTION_INVOKE,
+  TEAMS_ADAPTIVE_CARD_CONTENT_TYPE,
+  decidedTeamsCard,
+  judgeLiftNoticeTeamsCard,
+  parseTeamsApprovalData,
+  pendingTeamsCard,
+  teamsCardAttachment,
+  type TeamsAdaptiveCard,
+  type TeamsApprovalAction,
+} from "./teams-card.js";
+import { sendTeamsActivityBackedOff, updateTeamsActivityBackedOff } from "../channels/teams-connector.js";
+import { teamsChannelGrainConversationId, teamsConversationRef, type TeamsConversationRef } from "../channels/teams-conversation-ref.js";
+import { restoreTeamsConversationId } from "../channels/teams-id-restore.js";
+import { isTrustedTeamsServiceUrl } from "../channels/teams-origin-codec.js";
+import { resolveTeamsUserType, teamsServiceUrlRosterProbe } from "../channels/teams-roster.js";
+
+function log(msg: string): void {
+  console.log(`[open-everywhere:teams-approvals] ${msg}`);
+}
+
+// --- the transport seams ------------------------------------------------------------------------
+
+/** The Connector send this file uses, injectable so a test drives it without Teams. */
+export type TeamsSend = (input: { readonly serviceUrl: string; readonly conversationId: string; readonly body: unknown }) => Promise<{ id: string }>;
+/** The Connector update this file uses, injectable for the same reason. */
+export type TeamsUpdate = (input: {
+  readonly serviceUrl: string;
+  readonly conversationId: string;
+  readonly activityId: string;
+  readonly body: unknown;
+}) => Promise<{ id: string }>;
+
+/** Injectable seams for the poster and the row-addressed notice. Live callers pass none. */
+export interface TeamsPostDeps {
+  readonly send?: TeamsSend;
+  /** The stored conversation reference for a card's `channelId`. Live default: the raw-id restore
+   *  (`teams-id-restore.ts`) and then the `conversation`-grain address (`teams-conversation-ref.ts`). */
+  readonly resolveRef?: (channelId: string) => Promise<TeamsConversationRef | undefined>;
+}
+
+async function liveResolveRef(channelId: string): Promise<TeamsConversationRef | undefined> {
+  return teamsConversationRef(await restoreTeamsConversationId(channelId));
+}
+
+/**
+ * The conversation reference a card's `channelId` resolves to, or undefined. The read half of the
+ * address store already refuses an untrusted `serviceUrl`; the check here is the same allowlist again,
+ * so an injected resolver cannot hand this file a host the store would refuse.
+ */
+async function cardConversation(channelId: string, deps: TeamsPostDeps): Promise<TeamsConversationRef | undefined> {
+  const ref = await (deps.resolveRef ?? liveResolveRef)(channelId);
+  return ref && isTrustedTeamsServiceUrl(ref.serviceUrl) ? ref : undefined;
+}
+
+// --- the posters ----------------------------------------------------------------------------------
+
+/**
+ * Render the approval card and send it into `row.channelId` through the Bot Connector. Resolves the
+ * posted activity id, or undefined on ANY failure: no channel id, no stored conversation reference
+ * (this deployment never saw an inbound activity there), a missing Bot credential, a Connector error.
+ * NEVER throws.
+ *
+ * WHERE IT LANDS. `row.channelId` is the Teams CHANNEL id (bindTeams' `target.channelId`), so the card
+ * posts as a NEW post in the channel, not inside the reply chain that asked. bindTeams sets no
+ * `threadTs` on purpose (about twenty consumers read that field as a Slack thread_ts), so the row
+ * carries no chain to thread under. The tool result names the card, and the decision notice threads
+ * under the card itself.
+ */
+export async function postTeamsApprovalCard(row: PendingActionRow, summaryLines: readonly string[], deps: TeamsPostDeps = {}): Promise<string | undefined> {
+  return postTeamsCardMessage(row, deps, "approval card", () => pendingTeamsCard(row, summaryLines));
+}
+
+/**
+ * THE JUDGE-LIFT NOTICE POSTER: the room's trace of an act the armed judge lifted, with the overrule
+ * button. Best-effort by contract — the frozen args have already run, so a failed post is logged and
+ * resolves void. The audit rows (`approval.autoapproved`, `approval.judge.verdict`) land either way.
+ */
+export async function postTeamsJudgeLiftNotice(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string, deps: TeamsPostDeps = {}): Promise<void> {
+  await postTeamsCardMessage(row, deps, "judge-lift notice", () => judgeLiftNoticeTeamsCard(row, summaryLines, outcomeLine));
+}
+
+async function postTeamsCardMessage(row: PendingActionRow, deps: TeamsPostDeps, what: string, render: () => TeamsAdaptiveCard): Promise<string | undefined> {
+  if (!row.channelId) {
+    log(`no channel id on the pending row — nothing to post the ${what} to`);
+    return undefined;
+  }
+  try {
+    const ref = await cardConversation(row.channelId, deps);
+    if (!ref) {
+      log(`no conversation reference for the ${what}'s channel — this deployment has never seen an inbound activity there`);
+      return undefined;
+    }
+    const posted = await (deps.send ?? sendTeamsActivityBackedOff)({
+      serviceUrl: ref.serviceUrl,
+      conversationId: ref.conversationId,
+      body: { type: "message", attachments: [teamsCardAttachment(render())] },
+    });
+    return posted.id.length > 0 ? posted.id : undefined;
+  } catch (err) {
+    // Token-free: the Connector seam's errors carry a status and ids, never a bearer token.
+    log(`Teams ${what} post failed: ${(err as Error)?.message ?? String(err)}`);
+    return undefined;
+  }
+}
+
+// --- the row-addressed feedback legs (the sweep and the session-grant release) -------------------
+
+/**
+ * The decision notice for a row with NO click in hand — a TTL expiry or a session-grant release. It
+ * posts into the card's own conversation at the grain the card was sent to. It does not try to thread
+ * under the card: a reply-chain address needs a vendor id shape this file would have to guess, and the
+ * click path below threads exactly, off the invoke's own conversation id. Throws on failure; core's
+ * `deliverDecisionFeedback` swallows a notice failure.
+ */
+export async function postTeamsRowDecisionNotice(row: PendingActionRow, text: string, deps: TeamsPostDeps = {}): Promise<unknown> {
+  const ref = await cardConversation(row.channelId, deps);
+  if (!ref) throw new Error("no Teams conversation reference for the card's channel");
+  return (deps.send ?? sendTeamsActivityBackedOff)({ serviceUrl: ref.serviceUrl, conversationId: ref.conversationId, body: { type: "message", text } });
+}
+
+/** The decision-wake target for a row with no click in hand. Null when the card's conversation has no
+ *  stored reference or the row has no `postedTo`. The authority frozen at proposal still wins over it. */
+export async function teamsRowWakeTarget(row: PendingActionRow, deps: TeamsPostDeps = {}): Promise<{ surfaceKey: string; origin: UnifiedWakeOrigin } | null> {
+  if (!row.postedTo) return null;
+  try {
+    const ref = await cardConversation(row.channelId, deps);
+    if (!ref) return null;
+    return { surfaceKey: row.postedTo, origin: { platform: "teams", serviceUrl: ref.serviceUrl, conversationId: ref.conversationId, tenantId: ref.tenantId } };
+  } catch {
+    return null;
+  }
+}
+
+/** The legs this bundle registers with core (`registerDecisionFeedbackSurface`). */
+export const teamsDecisionFeedback: DecisionFeedbackSurface = {
+  postNotice: (row, text) => postTeamsRowDecisionNotice(row, text),
+  wakeTarget: (row) => teamsRowWakeTarget(row),
+};
+
+// --- the invoke (the tap) -------------------------------------------------------------------------
+
+/** What one OE approval tap carries. Every field but `action` comes off the relayed Teams activity
+ *  (`channelId === "msteams"`, see the header), never out of the card's data payload. The JWT proves
+ *  the relay, not the body. */
+export interface TeamsApprovalInvoke {
+  readonly action: TeamsApprovalAction;
+  /** The Bot Framework user id of the person who tapped (`from.id`) — the principal id bindTeams uses. */
+  readonly clickerId?: string;
+  /** The display name Teams sent with the tap, for the decided card only. Never an authority input. */
+  readonly clickerName?: string;
+  readonly tenantId?: string;
+  /** The Teams channel the tap happened in (`channelData.channel.id`), when it was a channel. */
+  readonly teamsChannelId?: string;
+  /** The conversation the card lives in, at the grain Teams reports it (a channel card's own reply chain). */
+  readonly conversationId: string;
+  readonly serviceUrl: string;
+  /** The card's own activity id, when Teams carries it on the invoke. */
+  readonly replyToId?: string;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function nonEmpty(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Probe one parsed activity for an OE approval tap: an `invoke` named `adaptiveCard/action` whose
+ * `value.action.data` carries the OE payload. Returns null for anything else — an eve HITL answer, a
+ * different invoke, a message — which the front forwards to the native channel untouched. NEVER throws.
+ */
+export function parseTeamsApprovalInvoke(activity: unknown): TeamsApprovalInvoke | null {
+  if (!isObject(activity) || activity["type"] !== "invoke") return null;
+  const invoke = activity as unknown as TeamsInvokeActivity;
+  if (invoke.name !== TEAMS_ADAPTIVE_CARD_ACTION_INVOKE) return null;
+  // The Teams channel only — see the header. Read off the raw activity: eve's parsed shape drops it.
+  const raw = isObject(invoke.raw) ? invoke.raw : (activity as Record<string, unknown>);
+  if (raw["channelId"] !== "msteams") return null;
+  const value = isObject(invoke.value) ? invoke.value : undefined;
+  const actionObj = value && isObject(value["action"]) ? value["action"] : undefined;
+  const action = parseTeamsApprovalData(actionObj?.["data"]);
+  if (!action) return null;
+  const conversationId = nonEmpty(invoke.conversation?.id);
+  const serviceUrl = nonEmpty(invoke.serviceUrl);
+  if (!conversationId || !serviceUrl) return null;
+  const clickerId = nonEmpty(invoke.from?.id);
+  const clickerName = nonEmpty(invoke.from?.name);
+  const tenantId = nonEmpty(invoke.tenantId) ?? nonEmpty(invoke.conversation?.tenantId);
+  const teamsChannelId = nonEmpty(invoke.teamsChannelId);
+  const replyToId = nonEmpty(invoke.replyToId);
+  return {
+    action,
+    conversationId,
+    serviceUrl,
+    ...(clickerId ? { clickerId } : {}),
+    ...(clickerName ? { clickerName } : {}),
+    ...(tenantId ? { tenantId } : {}),
+    ...(teamsChannelId ? { teamsChannelId } : {}),
+    ...(replyToId ? { replyToId } : {}),
+  };
+}
+
+/**
+ * The room the tap PHYSICALLY happened in, as `teams/<tenant>/<channel>` — core's clicker gate reads
+ * it (leg C compares its channel segment with the row's `channelId`). It comes from the relayed
+ * Teams activity: the channel id, else the channel grain of the conversation id. Undefined without a
+ * tenant or a room. 🔴 The handler REFUSES such a tap rather than passing no click context: core
+ * reserves "no click context" for the headless control plane, and it switches every clicker-gate leg
+ * off.
+ *
+ * TWO SPELLINGS OF ONE ROOM. A card the venue walk posted in its own room carries the RAW channel id;
+ * a card redirected to a domain's roster entry carries the roster's SURFACE-KEY spelling. Both
+ * spellings below are derived from the TAP's own channel id, so the row only chooses which spelling
+ * of the same click room to compare. `teams-id-restore.ts` states the bound: two raw ids that share a
+ * spelling are already one id to this deployment.
+ */
+export function teamsClickSurfaceKey(invoke: TeamsApprovalInvoke, row: Pick<PendingActionRow, "channelId"> | null): string | undefined {
+  const room = invoke.teamsChannelId ?? teamsChannelGrainConversationId(invoke.conversationId);
+  if (!invoke.tenantId || !room) return undefined;
+  const spelling = surfaceKeySegment(room);
+  const channel = row && row.channelId !== room && row.channelId === spelling ? spelling : room;
+  return `teams/${invoke.tenantId}/${channel}`;
+}
+
+/** One `adaptiveCard/action` invoke response body. */
+export interface TeamsInvokeResponseBody {
+  readonly statusCode: 200;
+  readonly type: string;
+  readonly value: unknown;
+}
+
+const TEAMS_MESSAGE_RESPONSE_TYPE = "application/vnd.microsoft.activity.message";
+
+function messageResponse(text: string): TeamsInvokeResponseBody {
+  return { statusCode: 200, type: TEAMS_MESSAGE_RESPONSE_TYPE, value: text };
+}
+
+function cardResponse(card: TeamsAdaptiveCard): TeamsInvokeResponseBody {
+  return { statusCode: 200, type: TEAMS_ADAPTIVE_CARD_CONTENT_TYPE, value: card };
+}
+
+/**
+ * Map one decide resolution to the invoke response — the Teams rendering of what core's Slack handler
+ * renders as calls. PURE, so it is tested as a matrix.
+ *   decided / expired → the decided card REPLACES the pending one (no buttons left to tap).
+ *   denied, clicker-denied, halted → a note to the clicker alone; the card stays live and the row
+ *                       stays pending, so a person who may decide it still can.
+ *   contradicted      → a note to the clicker; the notice card stays, because it is the room's trace.
+ *   unknown           → a note, with the Slack card-text wording.
+ *   the silent branches (a stale re-tap, a lost race, an unregistered kind) → a short note that
+ *                       nothing changed. An invoke must answer with something, and re-rendering a card
+ *                       from a stale row could overwrite the winner's decided card.
+ */
+export function teamsResponseFor(res: ApprovalClickResolution, deciderLabel?: string): TeamsInvokeResponseBody {
+  switch (res.outcome) {
+    case "unknown":
+      return messageResponse("This approval request is no longer known (it may have already been decided or has aged out).");
+    case "not-pending":
+    case "expired-race":
+    case "lost-race":
+      return messageResponse("Nothing changed — this request was already decided.");
+    case "unregistered-kind":
+      return messageResponse("Nothing changed — this deployment cannot decide this kind of request.");
+    case "expired":
+      return cardResponse(decidedTeamsCard(res.row, res.summaryLines, "expired"));
+    case "denied":
+      return messageResponse("Only a domain/org admin can decide this request. It is still pending.");
+    case "clicker-denied":
+      return messageResponse(clickerFloorRefusalNotice(res.reason));
+    case "halted":
+      return messageResponse(res.notice);
+    case "contradicted":
+      return messageResponse(judgeContradictionNotice(res.contradiction));
+    case "decided":
+      return cardResponse(decidedTeamsCard(res.row, res.summaryLines, res.outcomeLine, deciderLabel));
+  }
+}
+
+/** Test seams for the tap. Live callers pass only `waitUntil`. */
+export interface TeamsApprovalDeps {
+  /** The decide core. Live default: `resolveApprovalClick`. */
+  readonly resolve?: typeof resolveApprovalClick;
+  /** Leg D's positive per-clicker verdict. Live default: the Bot Connector member probe the inbound
+   *  message path and the HITL answer path already use. `undefined` leaves leg D inert. */
+  readonly userType?: (invoke: TeamsApprovalInvoke) => Promise<"guest" | "member" | undefined>;
+  /** Reads the row ONLY to pick the spelling of the click room (see {@link teamsClickSurfaceKey}). */
+  readonly readRow?: (org: string, id: string) => Promise<PendingActionRow | null>;
+  readonly send?: TeamsSend;
+  readonly update?: TeamsUpdate;
+  readonly decisionWake?: DecisionWakeDeps;
+  /** The route's own `waitUntil`. PRESENT ⇒ the feedback and core's session-grant release run off
+   *  the response path. ABSENT ⇒ both are awaited first, which is correct and slower. */
+  readonly waitUntil?: (p: Promise<unknown>) => void;
+}
+
+async function liveUserType(invoke: TeamsApprovalInvoke): Promise<"guest" | "member" | undefined> {
+  if (!invoke.clickerId) return undefined;
+  return resolveTeamsUserType(teamsServiceUrlRosterProbe(invoke.serviceUrl), invoke.conversationId, invoke.clickerId);
+}
+
+/**
+ * Handle one VERIFIED OE approval tap and return the invoke response body. The approver policy is
+ * core's: the config-as-code roster, matched as `teams/<from.id>` (Teams is not a tenant-scoped
+ * person-id space, identity/principal-key.ts), with no platform-native admin leg — a Teams team owner
+ * is not an OE authority. This call states its platform rather than letting core infer it. NEVER throws.
+ */
+export async function handleTeamsApprovalInvoke(invoke: TeamsApprovalInvoke, deps: TeamsApprovalDeps = {}): Promise<TeamsInvokeResponseBody> {
+  const { action } = invoke;
+  try {
+    if (!invoke.clickerId) {
+      console.error(`[open-everywhere:teams-approvals] approval tap on ${action.id} carries no user id — ignoring the tap`);
+      return messageResponse("Couldn't read who clicked — this decision was not applied.");
+    }
+    const clickerId = invoke.clickerId;
+    if (!invoke.tenantId) {
+      console.error(`[open-everywhere:teams-approvals] approval tap on ${action.id} carries no tenant — refusing the tap`);
+      return messageResponse("Couldn't read where this was clicked — this decision was not applied.");
+    }
+    // Leg D's verdict, resolved BEFORE the decide call so a positive guest verdict cannot race a lost
+    // CAS. A thrown probe degrades to "no verdict", never to an aborted tap.
+    const userType = await (deps.userType ?? liveUserType)(invoke).catch(() => undefined);
+    const known = await (deps.readRow ?? ((org: string, id: string) => getOperationalStore().getPendingAction(org, id)))(action.org, action.id).catch(() => null);
+    const surfaceKey = teamsClickSurfaceKey(invoke, known);
+    if (!surfaceKey) return messageResponse("Couldn't read where this was clicked — this decision was not applied.");
+
+    const res = await (deps.resolve ?? resolveApprovalClick)({
+      org: action.org,
+      id: action.id,
+      decision: action.decision,
+      clickerId,
+      clickerPlatform: "teams",
+      clickerTenant: invoke.tenantId,
+      clickContext: { surfaceKey },
+      ...(userType === undefined ? {} : { clickerIsGuest: userType === "guest" }),
+      ...(deps.waitUntil ? { waitUntil: deps.waitUntil } : {}),
+    });
+
+    const pending = decisionFeedback(invoke, res, deps);
+    if (pending !== undefined) {
+      if (deps.waitUntil === undefined) {
+        await pending;
+      } else {
+        deps.waitUntil(
+          pending.catch((err: unknown) => {
+            log(`deferred decision feedback failed for ${action.id}: ${(err as Error)?.message ?? String(err)}`);
+          }),
+        );
+      }
+    }
+    return teamsResponseFor(res, invoke.clickerName);
+  } catch (err) {
+    console.error(`[open-everywhere:teams-approvals] tap handling failed softly for ${action.id}: ${String(err)}`);
+    return messageResponse("Something went wrong handling this click — the decision was not applied.");
+  }
+}
+
+/**
+ * The decision FEEDBACK for a decided or expired tap: a fresh notice in the card's own conversation
+ * (the card replacement is an edit, which backscroll does not show), an update of the card message so
+ * a viewer who did not tap also sees the decided render, and the decision wake. Undefined for every
+ * other resolution. Every leg is best-effort.
+ */
+function decisionFeedback(invoke: TeamsApprovalInvoke, res: ApprovalClickResolution, deps: TeamsApprovalDeps): Promise<void> | undefined {
+  if (res.outcome !== "decided" && res.outcome !== "expired") return undefined;
+  const row = res.row;
+  const outcomeLine = res.outcome === "expired" ? "expired" : res.outcomeLine;
+  const send = deps.send ?? sendTeamsActivityBackedOff;
+  // The invoke's own conversation IS the card's conversation (a channel card's own reply chain). Its
+  // serviceUrl is the relayed activity's, which the token does NOT bind, so the allowlist below is the
+  // guard for every Connector call here, each of which carries a bearer token.
+  const trusted = isTrustedTeamsServiceUrl(invoke.serviceUrl);
+  const postNotice = async (text: string): Promise<unknown> => {
+    if (!trusted) throw new Error("the tap's serviceUrl is not a Bot Framework host");
+    return send({ serviceUrl: invoke.serviceUrl, conversationId: invoke.conversationId, body: { type: "message", text } });
+  };
+  const target: { surfaceKey: string; origin: UnifiedWakeOrigin } | null =
+    row.postedTo && trusted
+      ? {
+          surfaceKey: row.postedTo,
+          origin: { platform: "teams", serviceUrl: invoke.serviceUrl, conversationId: invoke.conversationId, ...(invoke.tenantId ? { tenantId: invoke.tenantId } : {}) },
+        }
+      : null;
+  const updateCard = async (): Promise<void> => {
+    const activityId = row.messageTs ?? invoke.replyToId;
+    if (!trusted || !activityId) return;
+    const card = decidedTeamsCard(row, res.summaryLines, outcomeLine, res.outcome === "decided" ? invoke.clickerName : undefined);
+    await (deps.update ?? updateTeamsActivityBackedOff)({
+      serviceUrl: invoke.serviceUrl,
+      conversationId: invoke.conversationId,
+      activityId,
+      body: { type: "message", id: activityId, attachments: [teamsCardAttachment(card)] },
+    }).catch((err: unknown) => log(`decided-card update failed for ${row.id}: ${(err as Error)?.message ?? String(err)}`));
+  };
+  const feedback = deliverDecisionFeedback(
+    {
+      row,
+      summaryLines: res.summaryLines,
+      outcome: res.outcome === "expired" ? "expired" : (row.status as ApprovalOutcome),
+      outcomeLine,
+      executed: res.outcome === "expired" ? "none" : res.executed,
+      ...(res.outcome === "decided" ? { clickerId: invoke.clickerId } : {}),
+      target,
+      postNotice,
+    },
+    deps.decisionWake,
+  );
+  return Promise.all([updateCard(), feedback]).then(() => undefined);
+}