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

package/agent/channels/teams-origin-codec.ts

@@ -0,0 +1,104 @@
+// The Teams UnifiedWakeOrigin codec + the Bot-Connector serviceUrl host allowlist — MOVED VERBATIM
+// out of core's channels/wake-origin-codecs.ts (OPE-114 stage 4). STORED-DATA COMPATIBILITY IS THE
+// CONTRACT: a Teams origin is JSON-serialised into the durable operational store and fail-closed
+// re-validated on read, so every behaviour here is frozen by core's
+// scripts/wake-origin-fixtures-test.ts (run from the app root with this bundle's boot wiring —
+// scripts/wake-origin-fixtures-boot.ts). Validator tolerances (typeof-only optional checks, extra
+// unknown fields) are LOAD-BEARING for rows already on disk — never tighten them here.
+//
+// The `UnifiedWakeOrigin` TYPE union (including its teams arm) stays in core — it is the wire
+// schema for stored rows; only the codec BEHAVIOUR lives in the bundle, registered by
+// registerTeamsProvider() (../register.ts). `isTrustedTeamsServiceUrl` is exported for the teams
+// post arm (BOTH of its dispatch paths re-validate the serviceUrl before POSTing the Connector
+// token) and applied here on the stored-row `validate` arm — every route by which a serviceUrl can
+// reach a token POST passes it. (There was a third route, the `dmOrigin` DM-delegation-anchor mint
+// arm, which applied the same allowlist; it went with the anchor at OPE-368 — a removed route needs
+// no check.) Core no longer re-exports the predicate (the stale unified-window re-export was removed
+// in stage 4).
+
+import type { UnifiedWakeOrigin, WakeOriginCodec } from "@open-everywhere/core/agent/adapter-api.js";
+
+type TeamsOrigin = Extract<UnifiedWakeOrigin, { platform: "teams" }>;
+
+/** COLON-FREE by construction: a task windowId is `[^:]+` (core channels/window-key.ts), so any colon
+ *  in a raw surface id (Teams' `19:...@thread.v2;messageid=` conversation ids) is folded to `_` —
+ *  deterministic, so spawn + ingress still agree on identity. */
+const noColon = (s: string): string => s.replace(/:/g, "_");
+
+/**
+ * Bot Connector `serviceUrl` host allowlist. The Teams reply POSTs a `client_credentials` bearer
+ * token to `${serviceUrl}/v3/conversations/...`, so the host must be a real Microsoft Bot
+ * Framework endpoint — not merely https. `serviceUrl` rides in off the inbound activity BODY, and
+ * eve's JWT verifier does NOT bind it to the token's `serviceurl` claim, so a scheme-only check
+ * (`startsWith("https://")`) would let a body-supplied `https://evil.example` exfiltrate the
+ * token. Constrain the host to the documented Bot Connector set. Fail-closed on any parse error.
+ */
+export function isTrustedTeamsServiceUrl(serviceUrl: unknown): boolean {
+  if (typeof serviceUrl !== "string") return false;
+  let host: string;
+  try {
+    const u = new URL(serviceUrl);
+    if (u.protocol !== "https:") return false;
+    host = u.hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  // An entry beginning with "." is a dot-anchored suffix; otherwise an exact host.
+  return teamsServiceHostAllowlist().some((h) => (h.startsWith(".") ? host.endsWith(h) : host === h));
+}
+
+/** The GLOBAL (commercial) cloud Bot Connector hosts. Sovereign/national clouds use DIFFERENT
+ *  hosts and are NOT in the default (keeping the default minimal, per the no-extrapolation rule):
+ *  a GCC / GCC High / DoD / 21Vianet operator opts theirs in via OE_TEAMS_SERVICE_HOSTS. Verified
+ *  values (Microsoft Learn, "Send proactive messages"): GCC `smba.infra.gcc.teams.microsoft.com`,
+ *  GCC High `smba.infra.gov.teams.microsoft.us`, DoD `smba.infra.dod.teams.microsoft.us`. */
+const DEFAULT_TEAMS_SERVICE_HOSTS: readonly string[] = [
+  "smba.trafficmanager.net",
+  ".smba.trafficmanager.net",
+  "botframework.com",
+  ".botframework.com",
+];
+
+/** The effective serviceUrl host allowlist = the global default PLUS any operator-supplied
+ *  OE_TEAMS_SERVICE_HOSTS (comma-separated; each entry an exact host or a ".suffix"). This is how
+ *  a sovereign-cloud deployment admits its own Bot Connector host without weakening the default —
+ *  the reply's bearer token only ever POSTs to a MATCHED host, all Microsoft-owned. */
+function teamsServiceHostAllowlist(): readonly string[] {
+  const extra = (process.env.OE_TEAMS_SERVICE_HOSTS ?? "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => s.length > 0);
+  return extra.length > 0 ? [...DEFAULT_TEAMS_SERVICE_HOSTS, ...extra] : DEFAULT_TEAMS_SERVICE_HOSTS;
+}
+
+export const teamsWakeOriginCodec: WakeOriginCodec<TeamsOrigin> = {
+  validate: (o) =>
+    // The Bot Connector bearer token is POSTed to serviceUrl, so it must be a Microsoft Bot
+    // Framework host, not merely https (isTrustedTeamsServiceUrl) — the reply path re-validates
+    // regardless, but a bad host must never survive into the map in the first place.
+    isTrustedTeamsServiceUrl(o.serviceUrl) &&
+    typeof o.conversationId === "string" &&
+    o.conversationId.length > 0 &&
+    (o.replyToActivityId === undefined || typeof o.replyToActivityId === "string") &&
+    (o.tenantId === undefined || typeof o.tenantId === "string"),
+  threadRef: (origin) => ({ channelKey: noColon(`teams/${origin.conversationId}`), threadKey: noColon(origin.replyToActivityId ?? origin.conversationId) }),
+  // replyToActivityId present ⇔ the trigger sits in a reply chain (the chain IS the thread);
+  // absent = a plain conversation send.
+  isThreadScoped: (origin) => typeof origin.replyToActivityId === "string" && origin.replyToActivityId.length > 0,
+  containerId: (origin) => origin.conversationId,
+  // A `dmOrigin` arm lived here (OPE-306 seam, landed OPE-315) to mint a DM delegation anchor's reply
+  // origin from the binding's `target` (`serviceUrl` + `conversationId`). OPE-368 deleted the anchor
+  // and the interface member with it — a Teams personal/group chat now diverts into its own
+  // first-class window (OPE-357), so its origin is minted and STORED at dispatch time like every other
+  // wake. NOTHING WEAKENED BY THE REMOVAL: the serviceUrl host allowlist that arm applied at mint is
+  // ALSO applied by `validate` above (every stored row) and again by the post arm before any Connector
+  // token leaves the process, so `isTrustedTeamsServiceUrl` remains on every route to a token POST.
+  //
+  // NO `placementRef` AND NO `carryPlacement`, AND THAT ABSENCE IS THE DECLARATION (OPE-1826). Teams
+  // keeps its placement INSIDE the conversation identity: `threadRef` keys on `replyToActivityId`,
+  // which is the very activity a reply hangs under, so two origins that pass `sameUnifiedConversation`
+  // already agree about where the answer lands and there is no gap for a carry to fill. Declaring an
+  // axis here would be worse than absent — it would make two origins of ONE thread compare unequal on
+  // a field the thread key has already settled. The position is recorded, and held to account against
+  // the live registry, by the `origin-placement-carry` row in core's identity/surface-parity.ts.
+};

package/agent/channels/teams-post-arm.ts

@@ -0,0 +1,323 @@
+// teams-post-arm — Teams's POST arm for the post-arms registry (OPE-114 stage 1c). Absorbs, VERBATIM,
+// Teams's arms out of the three reply/delivery spines: reply-post.ts (resolveReplyTarget's teams case
+// + dispatchReply's send/reply branch + the teams splitTeamsMessageText chunking used by
+// postTerminalProse), unified-reply.ts (liveTeamsPost, incl. the trusted-serviceUrl re-validation),
+// and unified-redrive.ts (the teams describe/container cases). The transport is eve's own Bot-Framework
+// Connector token (minted from MICROSOFT_APP_ID/PASSWORD) over a HOST-SIDE Connector fetch — see
+// teams-connector.ts's header for why the send/reply/update calls are no longer eve's own
+// `sendTeamsActivity`/`replyToTeamsActivity`/`updateTeamsActivity` (OPE-1237: eve's own transport
+// throws away the response headers, so there is no way to honour a 429's `Retry-After` by wrapping
+// its return value).
+//
+// ONE DELIBERATE DIVERGENCE FROM "VERBATIM" (OPE-315): dispatchTeamsReply now applies the
+// isTrustedTeamsServiceUrl host allowlist its unified sibling always did. That was a real gap, not a
+// stylistic one — see the check's own comment.
+
+import { resolveTeamsAppId, splitTeamsMessageText, TEAMS_MESSAGE_TEXT_MAX_LENGTH } from "eve/channels/teams";
+import {
+  teamsConnectorWrite,
+  sendTeamsActivityBackedOff,
+  replyToTeamsActivityBackedOff,
+  updateTeamsActivityBackedOff,
+} from "./teams-connector.js";
+import { isTrustedTeamsServiceUrl } from "./teams-origin-codec.js";
+import {
+  teamsPersonalConversationRef,
+  teamsSoleTenantRegion,
+  rememberTeamsPersonalConversation,
+  type TeamsConversationRef,
+} from "./teams-conversation-ref.js";
+import { restoreTeamsPersonId } from "./teams-id-restore.js";
+import { markNotApplied, carryFailureSignals } from "@open-everywhere/core/agent/adapter-api.js";
+import type {
+  PostArm,
+  TargetResolveBag,
+  ReplyTarget,
+  UnifiedWakeOrigin,
+  UnifiedReplyDeps,
+  EditLocus,
+  DirectMessageRequest,
+  DirectMessageDelivery,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+/** Exported for `teams-message-ops.ts` (OPE-899) — the SurfaceMessageOps registration reuses this
+ *  exact shape (serviceUrl + conversationId + an optional reply anchor) rather than inventing a
+ *  second one; see `dispatchTeamsReply`'s own export note. */
+export type TeamsTarget = Extract<ReplyTarget, { platform: "teams" }>;
+type TeamsOrigin = Extract<UnifiedWakeOrigin, { platform: "teams" }>;
+
+/** MID-TURN: a Bot-Framework message activity into the captured conversation reference. eve mints the
+ *  Connector token from MICROSOFT_APP_ID/PASSWORD; check the id for an honest early error. Thread onto
+ *  the trigger's root activity when the caller resolved one (a channel/group reply chains via
+ *  replyToTeamsActivity — eve's exact reply semantics, matching the unified arm and channel.thread.post);
+ *  a plain conversation send otherwise (personal chats, or no root id). */
+/** Exported (OPE-899) so `teams-message-ops.ts`'s SurfaceMessageOps `postText` can post through the
+ *  SAME transport this mid-turn reply arm uses, rather than a second copy of the Connector send.
+ *  That module resolves its own `TeamsTarget` from the `conversation`-grain address store
+ *  (`teams-conversation-ref.ts`, OPE-899) instead of from a live binding, but the target shape and
+ *  every refusal below are identical either way. */
+export async function dispatchTeamsReply(target: TeamsTarget, text: string): Promise<string> {
+  // Both pre-flight refusals are DEFINITIVE (OPE-821): the call never leaves this host, so nothing
+  // reached the room and the post spine may release its dedupe claim for an identical retry.
+  if (!process.env.MICROSOFT_APP_ID && !process.env.TEAMS_APP_ID) {
+    throw markNotApplied(new Error("reply couldn't post to Teams — MICROSOFT_APP_ID is not set."));
+  }
+  // 🔴 THE SAME HOST ALLOWLIST THE UNIFIED ARM APPLIES (OPE-315). This path POSTs a client_credentials
+  // Connector bearer token to `target.serviceUrl`, and until now it was the ONE serviceUrl route with
+  // no host check: the stored-origin path is gated by the codec validator (teams-origin-codec.ts) and
+  // re-gated in liveTeamsPost, but a mid-turn target is assembled by resolveTarget from binding
+  // attributes with only a non-empty test. Narrow (it takes a rogue Bot Framework channel on the same
+  // bot registration to place an attacker host there) but the same class as the unified arm's, and
+  // the fix is three lines. Token-free error, mirroring liveTeamsPost's.
+  if (!isTrustedTeamsServiceUrl(target.serviceUrl)) {
+    throw markNotApplied(new Error(`reply couldn't post to Teams — serviceUrl is not a Bot Framework host (conversation ${target.conversationId})`));
+  }
+  const res = target.replyToActivityId
+    ? await replyToTeamsActivityBackedOff({
+        serviceUrl: target.serviceUrl,
+        conversationId: target.conversationId,
+        activityId: target.replyToActivityId,
+        body: { type: "message", text },
+      })
+    : await sendTeamsActivityBackedOff({
+        serviceUrl: target.serviceUrl,
+        conversationId: target.conversationId,
+        body: { type: "message", text },
+      });
+  return res.id;
+}
+
+/** UNIFIED: a Bot-Framework message activity into the frozen conversation reference — the SAME
+ *  transport + env credentials the mid-turn reply arm uses. Anchored into the reply CHAIN via
+ *  replyToTeamsActivity when the origin froze a thread-root activity id (teamsThreadRootActivityId),
+ *  else a plain conversation send. Every target field rides the host-frozen wake origin, never the
+ *  model. */
+async function liveTeamsPost(origin: TeamsOrigin, text: string): Promise<string> {
+  if (!process.env.MICROSOFT_APP_ID && !process.env.TEAMS_APP_ID) {
+    // DEFINITIVE, like the mid-turn arm's pre-flights: nothing left this host.
+    throw markNotApplied(new Error(`unified reply couldn't post to Teams — MICROSOFT_APP_ID is not set (conversation ${origin.conversationId})`));
+  }
+  // Belt-and-braces re-validation (isUnifiedWakeOrigin already enforces it): the Connector bearer
+  // token is POSTed to this host, so it must be a Microsoft Bot Framework endpoint — a scheme-only
+  // https check would let a body-supplied serviceUrl exfiltrate the token.
+  if (!isTrustedTeamsServiceUrl(origin.serviceUrl)) {
+    throw markNotApplied(new Error(`unified reply couldn't post to Teams — serviceUrl is not a Bot Framework host (conversation ${origin.conversationId})`));
+  }
+  let id: string;
+  try {
+    const res = origin.replyToActivityId
+      ? await replyToTeamsActivityBackedOff({
+          serviceUrl: origin.serviceUrl,
+          conversationId: origin.conversationId,
+          activityId: origin.replyToActivityId,
+          body: { type: "message", text },
+        })
+      : await sendTeamsActivityBackedOff({
+          serviceUrl: origin.serviceUrl,
+          conversationId: origin.conversationId,
+          body: { type: "message", text },
+        });
+    id = res.id;
+  } catch (err) {
+    // Token-free error: never echo the transport error body (defensive parity with the other arms).
+    // AMBIGUOUS unless the Connector gave a status to say otherwise (OPE-821) — a send whose answer
+    // never arrived may still have reached the room, so the class carries over rather than being
+    // dropped by the re-wrap. A number is the only thing carried; no body, no URL, no token.
+    throw carryFailureSignals(err, new Error(`unified reply couldn't post to Teams — the Connector post failed (conversation ${origin.conversationId})`));
+  }
+  return id || "unknown";
+}
+
+/**
+ * EDIT (OPE-793): rewrite one of our own posted activities via eve's `updateTeamsActivity` (the Bot
+ * Framework update-activity call), on the SAME transport and credentials the post arms use. The
+ * Teams client shows an "Edited" marker on the activity, so the change is visible in the room.
+ *
+ * THE SAME TRUSTED-HOST ALLOWLIST BOTH POST ARMS APPLY. This call POSTs a client_credentials
+ * Connector bearer token to `locus.serviceUrl`, so it must be a Bot Framework host — the identical
+ * check, for the identical reason, and its absence here would be the OPE-315 gap re-opened on a new
+ * route. The serviceUrl reaches this arm from the session binding or the frozen wake origin (never
+ * model input), and it is re-validated anyway.
+ *
+ * NO SPLIT, like the Discord arm: one activity is one activity, so text past Teams' own cap is
+ * refused rather than truncated. Ownership was decided upstream against the own-post ledger.
+ */
+/** Exported (OPE-899) so `teams-message-ops.ts`'s SurfaceMessageOps `editMessage` reuses this SAME
+ *  update-activity transport rather than a second copy of it. */
+export async function editTeamsMessage(locus: EditLocus, messageId: string, text: string): Promise<void> {
+  // The three pre-flight refusals are DEFINITIVE (OPE-802): the call never leaves this host, so the
+  // message cannot have changed and a fresh `reply` is the right remedy. The Connector failure below
+  // is not — a failed update may still have applied — so it stays unmarked and fails closed.
+  if (!process.env.MICROSOFT_APP_ID && !process.env.TEAMS_APP_ID) {
+    throw markNotApplied(new Error("edit_reply couldn't update the Teams message — MICROSOFT_APP_ID is not set."));
+  }
+  if (!locus.serviceUrl || !isTrustedTeamsServiceUrl(locus.serviceUrl)) {
+    throw markNotApplied(
+      new Error(`edit_reply couldn't update the Teams message — serviceUrl is not a Bot Framework host (conversation ${locus.channelId})`),
+    );
+  }
+  if (text.length > TEAMS_MESSAGE_TEXT_MAX_LENGTH) {
+    throw markNotApplied(
+      new Error(
+        `edit_reply couldn't update the Teams message — the new text is ${text.length} characters and Teams caps one message at ${TEAMS_MESSAGE_TEXT_MAX_LENGTH}. An edit cannot split a message; shorten it, or post a new reply.`,
+      ),
+    );
+  }
+  try {
+    await updateTeamsActivityBackedOff({
+      serviceUrl: locus.serviceUrl,
+      conversationId: locus.channelId,
+      activityId: messageId,
+      body: { type: "message", text },
+    });
+  } catch (err) {
+    // Token-free error, matching both post arms: never echo the transport error body. `err` may now
+    // be the NAMED `RateLimitExhaustedError` (OPE-1237) rather than an ordinary Connector throw —
+    // `carryFailureSignals` copies its `status` (429, always AMBIGUOUS per platform-failure.ts) onto
+    // the wrapped error, the same treatment `liveTeamsPost`'s catch below gives it. That keeps the
+    // 429 case failing closed exactly as an unclassified Connector failure already did — this stays
+    // an improvement in what a caller reading `.status` can tell, never a behaviour change.
+    throw carryFailureSignals(err, new Error(`edit_reply couldn't update the Teams message — the Connector update failed (conversation ${locus.channelId})`));
+  }
+}
+
+/** Teams' own pre-flight: without an app id nothing can mint a Connector token. DEFINITIVE — the
+ *  call never leaves this host — so the caller may retry an identical send once the id is set. */
+function requireTeamsAppCredential(what: string): void {
+  if (!process.env.MICROSOFT_APP_ID && !process.env.TEAMS_APP_ID) {
+    throw markNotApplied(new Error(`${what} couldn't reach Teams — MICROSOFT_APP_ID is not set.`));
+  }
+}
+
+/**
+ * Open (or re-open) the 1:1 chat between the bot and one person — `POST {serviceUrl}/v3/conversations`
+ * with the bot, the member and the tenant.
+ *
+ * IT IS THE ONLY WAY TO COLD-ADDRESS A TEAMS PERSON, and it is why OPE-887 exists: the Bot Framework
+ * has no `conversations.open` keyed on a bare user id, so the deployment must already know a REGION
+ * (`serviceUrl`) and a TENANT before it can ask. Both come from the proactive-address table
+ * (channels/teams-conversation-ref.ts), captured off real inbound activities.
+ *
+ * The create is IDEMPOTENT for a one-member, non-group conversation: Microsoft documents it as
+ * returning the EXISTING 1:1 chat rather than minting a second one. That is a documented fact and not
+ * a measured one — if it turned out to be false, the visible symptom would be a duplicate chat, never
+ * a lost message, and the stored reference below means the call happens at most once per person
+ * anyway.
+ *
+ * 🔴 THE REFUSAL THIS ARM MUST STAY HONEST ABOUT: Microsoft refuses the create when the Teams app is
+ * not installed for that person in the PERSONAL scope. So a Teams DM arm reaches the people who have
+ * the app, and NOT the whole tenant. The error names that, because "the message did not send" without
+ * the reason sends a caller looking in the wrong place.
+ */
+async function openTeamsPersonalConversation(region: { readonly serviceUrl: string; readonly tenantId: string }, principalId: string): Promise<string> {
+  const appId = await resolveTeamsAppId();
+  const res = await teamsConnectorWrite({
+    operation: "conversations.create",
+    serviceUrl: region.serviceUrl,
+    path: "/v3/conversations",
+    method: "POST",
+    body: {
+      isGroup: false,
+      bot: { id: `28:${appId}` },
+      members: [{ id: principalId }],
+      channelData: { tenant: { id: region.tenantId } },
+      tenantId: region.tenantId,
+    },
+  });
+  const id = res.ok && res.body && typeof res.body === "object" ? (res.body as { id?: unknown }).id : undefined;
+  if (typeof id !== "string" || id.length === 0) {
+    // Token-free, and never the Connector's own body: the response can echo request material.
+    throw new Error(
+      `couldn't open a Teams 1:1 chat with that account (Bot Framework answered ${res.status}). Microsoft refuses this when the Teams app is not installed for that person in the personal scope.`,
+    );
+  }
+  return id;
+}
+
+/**
+ * DM (OPE-887): deliver `text` to one person's 1:1 Teams chat. The THIRD provider to implement this
+ * member, after Slack and Discord, and the one whose transport needed a durable seam first.
+ *
+ * WHAT IT COSTS TO GET HERE, in one paragraph. `DirectMessageRequest` names WHO and never WHERE, which
+ * is right and which Slack and Discord satisfy from a bot token alone. Teams cannot: a send needs a
+ * regional `serviceUrl` and a Microsoft-minted conversation id, and neither is derivable from a person
+ * id. So the deployment captures both off inbound activities (channels/teams-conversation-ref.ts) and
+ * this arm reads them back. The caller's contract is unchanged.
+ *
+ * THREE OUTCOMES, and each is a real answer:
+ *   1. a 1:1 reference is stored ⇒ one send.
+ *   2. no 1:1 reference, but this deployment knows exactly one tenant and its region ⇒ open the chat,
+ *      remember it, send.
+ *   3. neither ⇒ REFUSE, loudly and token-free. That is not a defect to paper over: this deployment
+ *      genuinely has no address for that person, and a silent no-op would leave a consent ask
+ *      apparently sent and actually nowhere.
+ *
+ * `actions` ARE IGNORED, deliberately and per the registry's "undefined = unsupported, never faked":
+ * this arm posts a plain message activity, and a Teams button would need an Adaptive Card plus an
+ * invoke route to receive the tap. Core's copy always stands on its own without a button
+ * ({@link DirectMessageAction}'s own rule), so the text delivered here is complete.
+ */
+async function deliverTeamsDirectMessage(input: DirectMessageRequest): Promise<DirectMessageDelivery> {
+  requireTeamsAppCredential("the direct message");
+  // 🔴 RESTORE THE RAW `29:` ID ONCE, HERE, BEFORE ANY USE (OPE-1078). A granted `teams:person/<id>`
+  // address carries the SURFACE-KEY spelling — the only one the resource-grant grammar admits — and
+  // every use below needs the raw Bot Framework id: the stored-reference lookup keys on it, and
+  // `openTeamsPersonalConversation` puts it in the Connector's `members` list, where a wrong spelling
+  // is a refused create rather than a delivered message. A caller that already holds the raw id (the
+  // recipient's own binding) is answered unchanged and pays no store read.
+  const principalId = await restoreTeamsPersonId(input.principalId.trim());
+  if (principalId.length === 0) throw markNotApplied(new Error("the direct message couldn't reach Teams — no account id was given."));
+
+  const stored = await teamsPersonalConversationRef(principalId);
+  let ref: TeamsConversationRef;
+  if (stored) {
+    ref = stored;
+  } else {
+    const region = await teamsSoleTenantRegion();
+    if (!region) {
+      // DEFINITIVE: nothing left this host. Naming the two ways an address is acquired is what lets an
+      // operator act — the alternative is a message that never arrives and no reason why.
+      throw markNotApplied(
+        new Error(
+          "the direct message couldn't reach Teams — this deployment holds no Bot Framework conversation reference for that account, and no single Teams tenant it could open one in. A reference is captured when the person messages the bot, or when the bot sees a channel in exactly one tenant.",
+        ),
+      );
+    }
+    ref = { ...region, conversationId: await openTeamsPersonalConversation(region, principalId) };
+    // Best-effort: a failed write costs a repeated create next time, never a failed send.
+    await rememberTeamsPersonalConversation(principalId, ref);
+  }
+
+  // READ-TIME allowlist, for the same reason every other Teams write applies one: this POSTs a
+  // Connector bearer token to the host. The stored reference was checked on the way in too.
+  if (!isTrustedTeamsServiceUrl(ref.serviceUrl)) {
+    throw markNotApplied(new Error("the direct message couldn't reach Teams — the stored serviceUrl is not a Bot Framework host."));
+  }
+
+  // Teams caps one activity, so a long notice is split exactly as every other Teams post is; the
+  // FIRST part's id is the returned anchor, matching the Discord arm.
+  const parts = splitTeamsMessageText(input.text);
+  let messageId = "";
+  for (const part of parts) {
+    const res = await sendTeamsActivityBackedOff({ serviceUrl: ref.serviceUrl, conversationId: ref.conversationId, body: { type: "message", text: part } });
+    if (messageId.length === 0) messageId = res.id;
+  }
+  return { surfaceId: ref.conversationId, messageId: messageId || "unknown" };
+}
+
+export const teamsPostArm: PostArm = {
+  platform: "teams",
+  resolveTarget: (bag: TargetResolveBag): ReplyTarget | null => {
+    // Proactive Teams sends need the Bot-Framework conversation reference (serviceUrl + conversation
+    // id) the inbound turn captured — you cannot cold-address a Teams chat.
+    const serviceUrl = bag.str("serviceUrl");
+    const conversationId = bag.str("conversationId");
+    return serviceUrl && conversationId ? { platform: "teams", serviceUrl, conversationId } : null;
+  },
+  dispatchReply: (target, text) => dispatchTeamsReply(target as TeamsTarget, text),
+  dispatchUnified: (origin, text, deps: UnifiedReplyDeps) => (deps.postTeams ?? liveTeamsPost)(origin as TeamsOrigin, text),
+  describeRedriveTarget: (origin) => `teams conversation ${(origin as TeamsOrigin).conversationId}`,
+  redriveContainerId: (origin) => (origin as TeamsOrigin).conversationId,
+  editMessage: editTeamsMessage,
+  deliverDirectMessage: deliverTeamsDirectMessage,
+};

package/agent/channels/teams-reaction-feedback.ts

@@ -0,0 +1,127 @@
+// THE TEAMS REACTION-FEEDBACK ARM (OPE-1502) — a reaction on the agent's own message becomes a
+// durable feedback signal, the same way it already does on Slack and Discord.
+//
+// The inbound half is FREE on this surface: Teams already delivers `messageReaction` activities, and
+// the stop arm (channels/teams-stop.ts) already parses them. What was missing is the second consumer
+// — the one that turns a 👍 or a 👎 on the agent's own reply into a row a person can query. This
+// module is that consumer, and it adds NO second parse and NO second ingress: it takes the activity
+// the stop arm already parsed and hands it core's surface-neutral `ingestReaction`.
+//
+// ── WHAT MICROSOFT DELIVERS, AND WHY IT SHAPES THE GUARDS
+//
+//  1. 🔴 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" — learn.microsoft.com, "Conversation
+//     events"). That FENCE is what makes the feedback case the common case here rather than the rare
+//     one: a reaction on somebody else's message never reaches this arm at all.
+//  2. 🔴 `replyToId` NAMES THAT MESSAGE, AND ITS PRESENCE IS THE WHOLE `onBotReply` TEST — WHICH IS
+//     NOT THE CHECK THE OTHER SURFACES MAKE. Slack, Discord and Linear each compare the reacted
+//     message's AUTHOR to the bot's own id. Teams delivers no author for the reacted message, so no
+//     such comparison exists here: the guarantee is Microsoft's fence (point 1), and the code checks
+//     only that a target id is present. An activity carrying `replyToId` for a message the agent did
+//     not write would be recorded as feedback, and nothing in this repository could notice. The
+//     absence of `replyToId` reads as "no message to name" — telemetry only, never a feedback row.
+//  3. THE REACTION VOCABULARY IS SIX FIXED VALUES: `angry`, `heart`, `laugh`, `like`, `sad`,
+//     `surprised`. Core's `classifyEmoji` buckets them; `surprised` is `other`, which is correct —
+//     surprise is not a verdict.
+//  4. The activity carries no message content, so nothing here reads or needs any.
+//
+// ── WHY THE STOP REACTION NEVER REACHES HERE
+//
+// `angry` is this surface's stop trigger (channels/teams-stop.ts). ✋ is a MECHANISM, not feedback,
+// and the same rule holds for the glyph that stands in for it: an ADDED `angry` means "stop this" and
+// must never ALSO be recorded as a sentiment about the message it sits on. The stop arm therefore
+// keeps that activity and this arm never sees it. A REMOVED `angry` is not a stop — nothing cancels
+// on a removal — so it arrives here as an ordinary retraction, exactly as a removed ✋ does on Slack.
+
+import {
+  buildIngestedReaction,
+  ingestReaction,
+  liveReactionSink,
+  resolvePartition,
+  type ReactionIngestOutcome,
+  type ReactionSinkDeps,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { buildTeamsAuth } from "./teams-identity.js";
+import type { TeamsReactionActivity } from "./teams-stop.js";
+
+/** Injected seams, so parse + guard + record is unit-tested against stubs with no Bot registration. */
+export interface TeamsReactionFeedbackDeps {
+  readonly sink: ReactionSinkDeps;
+}
+
+/** Production deps: the live audit/telemetry sink core already owns. There is no Teams-specific
+ *  sink — the whole point of the seam is that the durable row is written in ONE place. */
+export function liveTeamsReactionFeedbackDeps(): TeamsReactionFeedbackDeps {
+  return { sink: liveReactionSink() };
+}
+
+/** The Bot Framework's own prefix for an application id. A reactor wearing it is a bot whatever the
+ *  `recipient` field says — the same belt-and-braces check the stop arm makes. */
+function teamsReactorIsMachine(rx: TeamsReactionActivity): boolean {
+  return rx.reactorId === rx.agentId || rx.reactorId?.startsWith("28:") === true;
+}
+
+/**
+ * Ingest every reaction one Teams `messageReaction` activity carries. Returns one outcome per
+ * reaction — added first, then removed — so a caller's log says what happened to each.
+ *
+ * It NEVER THROWS into the caller: core's sinks are best-effort by contract, and a lost feedback row
+ * must never cost the ingress its ack.
+ *
+ * An activity with nothing to ingest returns an EMPTY array. That is the honest answer for a bot's
+ * own reaction, an activity with no reactor, and an activity naming no conversation — none of the
+ * three is a reaction from a person on a message this deployment can key.
+ */
+export async function routeTeamsReactionFeedback(
+  rx: TeamsReactionActivity,
+  deps: TeamsReactionFeedbackDeps,
+): Promise<readonly ReactionIngestOutcome[]> {
+  // The agent's own reactions ride the same activity stream and are never feedback. 🔴 THE `28:`
+  // PREFIX IS THE LOAD-BEARING HALF of this guard, not the `recipient` comparison: with an
+  // unresolved agent id the prefix is the only thing left, and — unlike the ingest paths on Slack and
+  // Discord, where a missed bot reactor costs a stray telemetry row — a missed one HERE costs a
+  // durable feedback row attributed to a machine, because `onBotReply` rests on a present
+  // `replyToId` rather than on an author comparison (header, point 2).
+  if (!rx.reactorId || teamsReactorIsMachine(rx)) return [];
+  if (!rx.conversationId) return [];
+
+  const partition = resolvePartition({
+    channel: { kind: "teams" },
+    session: {
+      auth: {
+        current: buildTeamsAuth({
+          userId: rx.reactorId,
+          conversationId: rx.conversationId,
+          ...(rx.tenantId ? { tenantId: rx.tenantId } : {}),
+          ...(rx.teamsChannelId ? { channelId: rx.teamsChannelId } : {}),
+          ...(rx.teamId ? { teamId: rx.teamId } : {}),
+          ...(rx.scope ? { scope: rx.scope } : {}),
+        }),
+      },
+    },
+  });
+
+  // A PRESENCE CHECK, not an author comparison — the header's point 2 says why this surface offers
+  // no other, and what that costs. No `replyToId` means no message to name, so the reaction is
+  // telemetry only.
+  const onBotReply = Boolean(rx.replyToId);
+  const outcomes: ReactionIngestOutcome[] = [];
+  for (const [verb, emojis] of [
+    ["added", rx.added],
+    ["removed", rx.removed],
+  ] as const) {
+    for (const emoji of emojis) {
+      const reaction = buildIngestedReaction({
+        surface: "teams",
+        verb,
+        reactorId: rx.reactorId,
+        emoji,
+        target: { channelId: rx.conversationId, messageId: rx.replyToId ?? "" },
+        onBotReply,
+        partition,
+      });
+      outcomes.push(await ingestReaction(reaction, deps.sink));
+    }
+  }
+  return outcomes;
+}