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

package/agent/channels/teams-identity.ts

@@ -0,0 +1,395 @@
+// Pure Microsoft Teams→OpenEverywhere identity capture. The Teams channel (teams.ts) calls
+// these to stow RAW Teams facts (tenant/conversation/channel/team ids + scope +
+// membershipType + actor) into the session auth context's `attributes`. The
+// INTERPRETATION of those facts into mode/visibility lives here too (teamsMode/
+// teamsVisibility) — kept beside the capture so the mapper in
+// agent/identity/binding.ts (bindTeams) just calls them, exactly as Slack splits
+// capture (slack-identity.ts) from interpretation (binding.ts). This file imports no
+// eve types — only OpenEverywhere's `SessionMode` string-union — so it's trivially
+// unit-testable. The security-critical decisions are ONE tested place each and both
+// fail closed: teamsVisibility ("is this a team-wide (public) channel?") and
+// teamsTrust ("is this surface positively in-tenant?" — unknown → no verdict, so
+// bindFrom binds it external).
+
+import type { SessionMode, BindableContext, IdentityMapper, RawIdentity } from "@open-everywhere/core/agent/adapter-api.js";
+import { rootDmGrainAttrs } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** Structural match for eve's SessionAuthContext (attributes + principal). */
+export interface OpenEverywhereTeamsAuth {
+  readonly authenticator: string;
+  readonly principalId: string;
+  readonly principalType: string;
+  readonly attributes: Record<string, string>;
+}
+
+export interface TeamsIdentityInput {
+  /** The Teams user (from.id) — the OpenEverywhere principal. */
+  readonly userId: string;
+  /** Azure AD object id of the actor, when carried — a stable cross-tenant user key. */
+  readonly aadObjectId?: string;
+  readonly userName?: string;
+  /** The tenant (org) — becomes the OpenEverywhere `workspace`, the org boundary. */
+  readonly tenantId?: string;
+  /** The conversation — becomes the OpenEverywhere `surface`. */
+  readonly conversationId: string;
+  /** Teams team/channel id (channel conversations only). */
+  readonly channelId?: string;
+  /** Teams team id (channel conversations only). */
+  readonly teamId?: string;
+  /** Bot Connector base URL for proactive post-back. */
+  readonly serviceUrl?: string;
+  /** Normalized conversation scope: "personal" | "groupChat" | "channel" | "unknown". */
+  readonly scope?: string;
+  /** Channel membership type ("standard" | "private" | "shared"), when positively known. */
+  readonly membershipType?: string;
+  /**
+   * The acting user's tenant membership type ("guest" | "member"), positively resolved via the
+   * cached Bot Connector roster probe (teams-roster.ts — the analog of Slack's users.info). A GUEST
+   * is a cross-org / B2B-collaboration account inside the tenant, so it demotes the surface's
+   * trust to `external` exactly as a restricted Slack DM partner does. `undefined` = never
+   * determined (no lookup / lookup failed / field absent) → teamsTrust leaves the existing
+   * channel/vouch verdict intact (fail-closed unless the operator vouches), mirroring Slack.
+   */
+  readonly userType?: string;
+}
+
+/** The attribute the roster verdict is stowed under — ONE spelling, read by `bindTeams` and by the
+ *  front's `teamsAuthorRefuted`. */
+const TEAMS_USER_TYPE_ATTR = "user_type";
+
+/**
+ * Fold a resolved tenant membership type into an ALREADY-BUILT auth capture (OPE-493).
+ *
+ * The front resolves the roster verdict AFTER it has built the capture, because the probe is a
+ * network call and the capture is built synchronously. This is the seam that carries the answer in,
+ * so the attribute name still has exactly one spelling.
+ *
+ * 🔴 NO VERDICT RETURNS THE SAME OBJECT, by reference. That is the fail-open guarantee stated as
+ * code: when the probe cannot answer, nothing downstream can tell the probe ran.
+ */
+export function withTeamsUserType<A extends OpenEverywhereTeamsAuth>(auth: A, userType: string | undefined): A {
+  if (!userType) return auth;
+  return { ...auth, attributes: { ...auth.attributes, [TEAMS_USER_TYPE_ATTR]: userType } };
+}
+
+/** Build the auth context OpenEverywhere dispatches with — raw facts as string attributes. */
+export function buildTeamsAuth(input: TeamsIdentityInput): OpenEverywhereTeamsAuth {
+  const attributes: Record<string, string> = {
+    conversation_id: input.conversationId,
+    user_id: input.userId,
+  };
+  if (input.aadObjectId) attributes.aad_object_id = input.aadObjectId;
+  if (input.userName) attributes.user_name = input.userName;
+  if (input.tenantId) attributes.tenant_id = input.tenantId;
+  if (input.channelId) attributes.channel_id = input.channelId;
+  if (input.teamId) attributes.team_id = input.teamId;
+  if (input.serviceUrl) attributes.service_url = input.serviceUrl;
+  if (input.scope) attributes.scope = input.scope;
+  if (input.membershipType) attributes.membership_type = input.membershipType;
+  if (input.userType) attributes[TEAMS_USER_TYPE_ATTR] = input.userType;
+  // Root-DM grain stamp (window-tool-gating §D-DM, widened to group DMs): a 1:1 (scope "personal")
+  // chat OR a groupChat (⇒ "mpim") is a STANDING seat ⇒ narrowed hands — both are closed multi-party
+  // conversations with no channel identity. teamsMode's "channel" branch (scope "channel"/unknown) is
+  // unambiguously excluded, so a real team channel is never over-narrowed.
+  const teamsScopeMode = teamsMode(input.scope);
+  Object.assign(attributes, rootDmGrainAttrs(teamsScopeMode === "dm" || teamsScopeMode === "mpim"));
+  return { authenticator: "teams", principalId: input.userId, principalType: "teams-user", attributes };
+}
+
+/**
+ * Pull the channel membershipType out of a Bot Framework activity's `channelData`,
+ * which (for channel conversations) may carry `{ channel: { membershipType } }`.
+ * Defensive: channelData is raw JSON, so everything is probed, never assumed. Note
+ * that inbound message activities frequently OMIT membershipType (it's a Graph/Teams
+ * API property, not a guaranteed Activity field) — absence is the common case, and
+ * teamsVisibility fails closed to private on it.
+ */
+export function teamsMembershipType(channelData: Record<string, unknown> | undefined): string | undefined {
+  const ch = (channelData as { channel?: Record<string, unknown> } | undefined)?.channel;
+  if (!ch || typeof ch !== "object") return undefined;
+  const mt = ch["membershipType"];
+  return typeof mt === "string" && mt.length > 0 ? mt : undefined;
+}
+
+/**
+ * The acting user's tenant membership type from a Bot Connector roster member record (or a
+ * Microsoft Graph `/users/{id}` object) — the authoritative "is this a GUEST?" signal, the
+ * Teams analog of Slack's `partnerFactsFromInfo`. Probes `userType` (Graph: "Guest"/"Member")
+ * then `userRole` (Bot roster: "guest" for a guest, else a member role), case-insensitively.
+ * Pure + defensive (raw JSON): a missing/failed lookup, an empty role, or an unrecognised value
+ * all yield `undefined` (no verdict → the existing channel/vouch trust stands, fail-closed
+ * unless vouched). Only a positive "guest" flag → "guest" (→ external demotion); a positively
+ * recognised member/owner/admin role → "member".
+ *
+ * What it PROVES: the tenant classifies this account as a guest (external B2B collaborator) —
+ * demote. What it does NOT prove: that a "member" is inside YOUR org boundary if the deployment
+ * spans multiple tenants; org-internal trust still requires the channel verdict or an operator
+ * vouch. It is a demotion-only signal, never an upgrade.
+ */
+export function teamsUserTypeFromMember(info: unknown): "guest" | "member" | undefined {
+  if (!info || typeof info !== "object") return undefined; // lookup failed / absent → no verdict
+  const o = info as Record<string, unknown>;
+  const raw = o["userType"] ?? o["userRole"]; // Graph userType | Bot Connector roster userRole
+  if (typeof raw !== "string" || raw.length === 0) return undefined; // field absent → no verdict
+  const v = raw.toLowerCase();
+  if (v === "guest") return "guest";
+  if (v === "member" || v === "user" || v === "owner" || v === "admin" || v === "organizer") return "member";
+  return undefined; // unrecognised value → no verdict (fail toward the existing lower/fail-closed tier)
+}
+
+/**
+ * Teams conversation scope → session mode, or UNDEFINED when the scope classifies nothing.
+ *
+ * 🔴 THE UNDEFINED IS THE POINT (OPE-1867). An inbound activity that carries no `conversationType`
+ * — or one Teams spells in a way this mapper does not know — tells us nothing about whether the
+ * conversation is a room or a 1:1 chat with one person. Answering "channel" there is a DEFAULT, not
+ * a reading, and a reader that publishes the surface must be able to tell the two apart: a personal
+ * chat reported as a room names that individual's conversation id in a report posted into a room.
+ * {@link teamsMode} applies the default for every reader that needs a usable value; this function
+ * is what the identity mapper hands the binding, so the provenance survives.
+ */
+export function teamsResolvedMode(scope: string | undefined): SessionMode | undefined {
+  if (scope === "personal") return "dm"; // a 1:1 chat with the bot
+  if (scope === "groupChat") return "mpim"; // an ad-hoc group chat
+  if (scope === "channel") return "channel"; // a team channel
+  return undefined; // "unknown" / unrecognised → nothing classified this conversation
+}
+
+/** Teams conversation scope → session mode, GAP-FILLED to `channel` when nothing classifies it.
+ *  Visibility, trust and the seat-grain stamps all need a definite value and all fail closed on
+ *  their own terms, so the default is right for them. A reader that PUBLISHES the surface wants
+ *  {@link teamsResolvedMode} instead. */
+export function teamsMode(scope: string | undefined): SessionMode {
+  return teamsResolvedMode(scope) ?? "channel";
+}
+
+/**
+ * Teams facts → visibility. FAIL CLOSED, mirroring slackVisibility: anything we
+ * can't positively confirm as a team-wide (standard) channel is treated as
+ * `private`, so a surface's learnings never leak up to shared memory on an
+ * under-specified event. Personal/group chats are never public surfaces. For a team
+ * channel, only `membershipType === "standard"` (the org/team-wide channel everyone
+ * on the team can see) yields `public`; `private`/`shared`/unknown → `private`.
+ * (Inbound activities usually DON'T carry membershipType, so the fail-closed branch
+ * is the normal case for channels — private is the safe default.)
+ */
+export function teamsVisibility(
+  scope: string | undefined,
+  membershipType: string | undefined,
+  mode: SessionMode,
+): Visibility {
+  // 1:1 and group chats are never "public" surfaces.
+  if (mode === "dm" || mode === "mpim") return "private";
+  if (scope === "personal" || scope === "groupChat") return "private";
+  if (membershipType === "standard") return "public"; // an explicit team-wide channel
+  return "private"; // private/shared/unknown channel → fail closed
+}
+
+/**
+ * Teams membership → trust (memory gate). FAIL CLOSED — only POSITIVE facts yield a
+ * verdict. A `shared` channel is a Teams Shared Channel — it can include people from
+ * OTHER tenants/orgs (the Teams analog of Slack Connect) — so it's `external` and gets
+ * no shared memory. A channel positively identified as `standard`/`private` AND carrying
+ * its tenant id is in-tenant → `internal`. Personal/group chats are personal silos
+ * (gate N/A → internal; bindFrom's DM-partner gate still fails an unverified DM partner
+ * closed). ANYTHING ELSE — absent membershipType (the common case: inbound activities
+ * routinely omit it), an unrecognised value, or a missing tenant id — returns
+ * `undefined`, so bindFrom FAILS CLOSED to `external` (shared/org memory gated off)
+ * unless the operator vouches for the deployment with OE_TRUST=internal — the same
+ * layer Discord/Linear use. An ambiguous Teams event must never reach the
+ * shared org brain.
+ *
+ * GUEST DETECTION (OPE-60): a `userType` positively resolved to "guest" (a cross-org / B2B
+ * collaboration account inside the tenant, via the cached roster lookup) DEMOTES to `external`
+ * FIRST — ahead of every other branch, including the personal-silo and standard-channel
+ * `internal` verdicts and the operator vouch (bindFrom's precedence gives a mapper's own
+ * `external` verdict priority over the vouch). This is exactly how Slack demotes a restricted
+ * DM partner. An absent/unknown `userType` (the common case — no lookup, or a lookup that
+ * couldn't confirm) leaves the existing verdict intact, so behaviour is unchanged unless a
+ * guest is positively detected.
+ */
+export function teamsTrust(
+  scope: string | undefined,
+  membershipType: string | undefined,
+  mode: SessionMode,
+  tenantId?: string,
+  userType?: string,
+): Trust | undefined {
+  if (userType === "guest") return "external"; // positively-detected guest → demote (wins over vouch)
+  if (mode === "dm" || mode === "mpim") return "internal"; // personal silo; gate N/A
+  if (scope === "personal" || scope === "groupChat") return "internal";
+  if (membershipType === "shared") return "external"; // cross-tenant Shared Channel
+  if (tenantId && (membershipType === "standard" || membershipType === "private")) {
+    return "internal"; // positively-identified in-tenant channel
+  }
+  return undefined; // unverifiable membership/tenant → bindFrom fails closed to external
+}
+
+/** Local copies of the binding's unions (kept eve-free + import-cycle-free). */
+type Visibility = "public" | "private";
+type Trust = "internal" | "external";
+
+// --- the identity MAPPER (moved out of core identity/binding.ts in OPE-114 stage 4) ---------
+// Interprets the raw facts the Teams channel stowed in auth attributes:
+//   tenant_id, conversation_id, channel_id, team_id, service_url,
+//   scope ("personal"|"groupChat"|"channel"|"unknown"),
+//   membership_type ("standard"|"private"|"shared", when known), user_id.
+// workspace = tenant (the org boundary); surface = conversation. mode/visibility/trust
+// interpretation lives above (teamsMode/teamsVisibility/teamsTrust — the one tested place), same
+// split as Slack. Trust FAILS CLOSED: teamsTrust returns a verdict only on POSITIVE facts (a shared
+// channel → external; a standard/private channel with a tenant id → internal) and `undefined`
+// otherwise, so bindFrom binds an ambiguous Teams event `external` (shared/org memory gated off)
+// unless the operator vouches with OE_TRUST=internal — the same layer Discord/Linear use.
+//
+// The two attribute helpers are LOCAL COPIES of core binding.ts's module-private probes (attr /
+// authPrincipalId) — deliberately not barrel ports (the same posture notion's bindNotion took): they
+// are three-line structural reads over the public BindableContext shape, and a mapper author outside
+// core reads its own platform's attributes itself.
+
+type AuthAttrs = Readonly<Record<string, string | readonly string[]>> | undefined;
+
+function teamsAuthOf(ctx: BindableContext): { attributes?: AuthAttrs; principalId?: string } | null {
+  return ctx.session?.auth?.current ?? ctx.session?.auth?.initiator ?? null;
+}
+
+function teamsAttr(a: AuthAttrs, keys: readonly string[]): string | undefined {
+  if (!a) return undefined;
+  for (const k of keys) {
+    const v = a[k];
+    if (typeof v === "string" && v.length > 0) return v;
+    if (Array.isArray(v) && typeof v[0] === "string" && v[0].length > 0) return v[0];
+  }
+  return undefined;
+}
+
+function teamsAuthPrincipalId(ctx: BindableContext): string | undefined {
+  const pid = teamsAuthOf(ctx)?.principalId;
+  return pid && pid.length > 0 ? pid : undefined;
+}
+
+/**
+ * The trust-registry GROUP rung for a Teams TEAM (OPE-490), or `undefined` when this activity has
+ * no team (a personal or group chat) or the id is not a safe key segment.
+ *
+ * FAIL-CLOSED and REFUSING, never repairing: an id that would need sanitising contributes no rung
+ * at all. Repairing it would risk composing a segment that collides with a real key, and a missing
+ * rung is simply the pre-OPE-490 behaviour.
+ *
+ * Exported for the identity test, which pins the marker spelling — the spelling is a config
+ * contract an operator types into `agent/identity/surfaces.ts`, so it must not drift silently.
+ */
+export function teamsTrustGroup(teamId: string | undefined): { readonly trustGroup: string } | undefined {
+  if (teamId === undefined || !/^[a-zA-Z0-9._-]+$/.test(teamId)) return undefined;
+  return { trustGroup: `team:${teamId}` };
+}
+
+export const bindTeams: IdentityMapper = (ctx): RawIdentity => {
+  const a = teamsAuthOf(ctx)?.attributes;
+  const scope = teamsAttr(a, ["scope"]);
+  const membershipType = teamsAttr(a, ["membership_type", "membershipType"]);
+  const userType = teamsAttr(a, ["user_type", "userType"]); // "guest" | "member" — cached roster probe (teams-roster.ts)
+  const mode = teamsMode(scope);
+  const conversationId = teamsAttr(a, ["conversation_id", "conversationId"]);
+  const serviceUrl = teamsAttr(a, ["service_url", "serviceUrl"]);
+  const tenantId = teamsAttr(a, ["tenant_id", "tenantId"]);
+  return {
+    workspace: tenantId,
+    surface: conversationId,
+    // A channel-scoped Teams CONVERSATION names one reply chain (the conversation id carries
+    // `;messageid=<root>`), so the listable/vouchable/spend-cappable container is the Teams
+    // CHANNEL — domain membership resolves at the channel grain, mirroring the Discord
+    // thread→parent-channel precedent (bindDiscord.domainSurface). Absent (personal/groupChat,
+    // or an activity with no channel id) → fall back to the conversation grain, today's exact
+    // behaviour (bindFrom only surfaces domainSurface when it differs from surface).
+    domainSurface: teamsAttr(a, ["channel_id", "channelId"]),
+    // 🔴 THE RESOLVED mode, not the gap-filled one (OPE-1867). An activity with no recognised
+    // `conversationType` contributes NO mode here; bindFrom still gap-fills `channel`, so every
+    // reader below and downstream is unchanged — but the binding now says the value was a default,
+    // and the one reader that publishes a surface refuses it. `visibility` and `trust` keep taking
+    // the gap-filled `mode` local above, which is what their own fail-closed rules are written for.
+    mode: teamsResolvedMode(scope),
+    // 🔴 THE TEAM RUNG (OPE-490). A Teams channel keys as `teams/<tenant>/<conversationId>` and the
+    // TEAM is nowhere in that key, so an operator could not declare a whole team internal or public
+    // — only enumerate its channels. This contributes the team as a MARKED group segment, which the
+    // trust registry matches as a rung BETWEEN the tenant and the surface
+    // (identity/surface-key-grammar.ts). An operator then writes:
+    //
+    //     defineSurface({ key: "teams/<tenantId>/team:<teamId>", trust: "internal" })
+    //
+    // The vendor word "team" lives HERE, in the Teams bundle, never in core — core composes
+    // `<platform>/<tenant>/<segment>` and validates only the `<marker>:<id>` shape.
+    //
+    // It changes NO domain semantics: the surface key, the domain key and every memory/spend/audit
+    // grain are byte-identical. `teamId` is present only on a CHANNEL activity, so a personal or
+    // group chat contributes no rung and resolves exactly as before.
+    ...(teamsTrustGroup(teamsAttr(a, ["team_id", "teamId"])) ?? {}),
+    visibility: teamsVisibility(scope, membershipType, mode),
+    trust: teamsTrust(scope, membershipType, mode, tenantId, userType),
+    principalId: teamsAuthPrincipalId(ctx) ?? teamsAttr(a, ["user_id", "userId"]),
+    // 🔴 THE ENGAGEMENT-REGISTRY KEY (OPE-1500), the Discord precedent (`bindDiscord.engagementKey`)
+    // in Teams' own vocabulary. It is the CONVERSATION id, which names the REPLY CHAIN in a team
+    // channel (the id carries `;messageid=<root>`) and the CHAT in a group chat — the two containers
+    // an engagement can be kept per on this surface. The same id is this binding's `surface`, so
+    // `teams/<tenant>/<conversationId>` + `<conversationId>` addresses the exact row the seam's wake
+    // gate reads back (channels/teams-engagement.ts). Publishing it here is what lets `stand_down`
+    // mark that row; without it the verb found no anchor and refused on every Teams turn.
+    //
+    // NEVER ON A 1:1 CHAT, and the omission is the honest half — Discord's DM reasoning exactly. A
+    // personal chat is answered unconditionally (the front's DM divert bypasses the engagement gate
+    // by design), so a mark on it would suppress nothing, and `stand_down` says it could not stop
+    // rather than writing a row that changes nothing.
+    ...(teamsMode(scope) !== "dm" && conversationId ? { engagementKey: conversationId } : {}),
+    // 🔴 THE ROOM-GRAIN STOP ANCHOR (OPE-1511), and Teams is the only surface that has one. The
+    // single-window front's Leg A wakes on ANY message in a vouched CHANNEL, including a reply chain
+    // no @mention ever engaged — a room-grain wake, which the conversation-grain key above cannot
+    // address. Publishing the CHANNEL id here is what lets `stand_down` reach the room row that wake
+    // stores (channels/teams-engagement.ts), instead of refusing on a wake the person can plainly
+    // see. The verb marks it only when the conversation grain held no row, so an ordinary
+    // thread-grain stop is unchanged.
+    //
+    // CHANNEL SCOPE ONLY. A personal or group chat has no Leg A — the front diverts both into their
+    // own DM window above `planFor` — so there is no room wake to stop and a mark here would be a
+    // write nobody reads. The value is the raw channel id, for the audit trail; the row's address is
+    // derived from the partition on both sides, so no spelling can drift.
+    ...(mode === "channel" && teamsAttr(a, ["channel_id", "channelId"])
+      ? { roomEngagementKey: teamsAttr(a, ["channel_id", "channelId"]) }
+      : {}),
+    // THE STOP REGISTRY'S ADDRESS FOR THIS TURN (OPE-898) — the CONVERSATION, which on a Teams
+    // channel means the REPLY CHAIN, not the channel. A `messageReaction` activity carries
+    // `conversation.id`, so the reply chain is the only container a stop trigger can name.
+    //
+    // 🔴 IT IS NOT `target.channelId`, even though this binding has one. That field holds the Teams
+    // CHANNEL id, which is a coarser room than the turn ran in and is absent on a personal chat —
+    // so keying the registry on it would both over-reach and leave every DM turn unstoppable.
+    // `anchorChannelId` wins over `target.channelId` in hooks/turn-anchor.ts for exactly this case.
+    ...(conversationId ? { anchorChannelId: conversationId } : {}),
+    // Proactive post-back needs the Bot Connector CONVERSATION REFERENCE (serviceUrl +
+    // conversation id), not a thread anchor — Teams can't cold-address a chat by AAD
+    // user id (Bot Framework requires a reference captured on a prior inbound turn,
+    // which is exactly what this is: every field comes off THIS inbound activity).
+    // `conversationType` (the activity's scope: personal/groupChat/channel) rides along
+    // so a routine FIRE can re-derive mode without guessing from id shapes — the
+    // dispatcher (@open-everywhere/provider-teams register.ts resolveTeamsTarget) stamps it
+    // back as the `scope` attribute this very mapper reads.
+    target:
+      conversationId && serviceUrl
+        ? {
+            serviceUrl,
+            conversationId,
+            tenantId,
+            channelId: teamsAttr(a, ["channel_id", "channelId"]),
+            teamId: teamsAttr(a, ["team_id", "teamId"]),
+            conversationType: scope,
+            // The creator's Azure AD object id (OPE-522) — carried on the STORED target so a routine
+            // created from this turn can be re-checked at fire time (routines/fire-eligibility.ts's
+            // Teams leg): Graph's `/users/{id}` and a channel roster's `userId` are both keyed on
+            // this value, a DIFFERENT identifier from the Bot Framework `from.id` this mapper's own
+            // `principalId` carries (see buildTeamsAuth's `aad_object_id` attribute, captured above).
+            // Absent when the inbound activity didn't carry one (e.g. no Teams AAD linkage) — a
+            // routine created from such a turn simply has no Teams eligibility leg to run, matching
+            // every other "cannot check" case in this module family.
+            aadObjectId: teamsAttr(a, ["aad_object_id", "aadObjectId"]),
+          }
+        : undefined,
+  };
+};

package/agent/channels/teams-input-response.ts

@@ -0,0 +1,129 @@
+// THE TEAMS ARM OF THE HITL-ANSWER ADMISSION (OPE-574).
+//
+// 🔴 THE TEAMS PREMISE IS THE OPPOSITE OF SLACK'S, AND THE TICKET SAID OTHERWISE. eve's Teams
+// channel resolves the hook as `onInputResponse ?? (onMessage === undefined ? defaultOnInputResponse
+// : rejectInput)` and `rejectInput` returns `null` for every submission. OE authors `onMessage`
+// (channels/teams.ts), so on Teams NOBODY could answer a HITL card — every Adaptive-Card submit and
+// every card-valued message was dropped, with no post, no row and no log line. The Slack hole
+// (anyone may answer) does not exist here; a silent dead end did. Authoring this hook closes both
+// at once: it opens the path AND governs it. The two eve behaviours are pinned against the
+// installed dist by `packages/core/scripts/eve-install-integrity-test.ts`.
+//
+// LEG B HAS TEETH HERE. `resolveTeamsUserType` reads the Bot Connector's conversation-member
+// record and returns a POSITIVE `guest`/`member` verdict per person — the same probe the inbound
+// message path already runs on every activity — so a guest answering from an ordinary internal
+// channel is refused. That was the residual approvals/clicker-floor.ts named before OPE-589; Slack
+// closed the same gap with its own probe (`slackClickerIsGuest`), so this is no longer a
+// Teams-only capability. An unresolvable probe returns `undefined` and the leg is INERT: "we could
+// not ask" never becomes a refusal.
+//
+// 🔴 FAIL-OPEN ON A THROW. eve logs a thrown hook and drops the answer, which would put Teams back
+// where it started. Anything unexpected therefore returns the default auth and says so in the log.
+//
+// 🔴 SPEND GATE (OPE-588), ahead of the room/guest admission below. This card action RESUMES a
+// parked turn: a decision to spend more, taken through a button, on a scope nobody asked whether it
+// could afford. Every ordinary ingress door consults the ONE shared spend gate before it dispatches
+// a turn (spend/ingress-gate.ts); eve's own Teams invoke route calls `onInputResponse` and then
+// `.respond()` directly, with no call site of that gate anywhere on the seam — verified against the
+// installed eve/dist. A decline returns `null`, the same reject-the-answer outcome a room/guest
+// refusal already leaves — the request stays PENDING.
+
+import type { TeamsContext, TeamsInputResponseResult, TeamsInvokeActivity, TeamsMessageActivity } from "eve/channels/teams";
+import {
+  admitInputResponse,
+  ingressSpendGate,
+  resolvePartition,
+  type BindableContext,
+  type IngressSpendGateInput,
+  type InputResponseAdmission,
+  type InputResponseScope,
+  type SpendGateDecision,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { buildTeamsAuth, teamsMembershipType } from "./teams-identity.js";
+import { resolveTeamsUserType, teamsHandleRosterProbe } from "./teams-roster.js";
+
+export interface TeamsInputResponseDeps {
+  /** The core admission. Injected in tests; the live default is the shared decision. */
+  readonly admit?: (scope: InputResponseScope) => Promise<InputResponseAdmission>;
+  /** Positive per-member verdict for leg B. Live default is the Bot Connector member probe. */
+  readonly userType?: (activity: TeamsInvokeActivity | TeamsMessageActivity) => Promise<"guest" | "member" | undefined>;
+  /** Render the refusal. Teams has no ephemeral primitive on this handle, so it is a thread post. */
+  readonly notify?: (text: string) => Promise<void>;
+  /** The shared spend-admission decision (OPE-588). Injected in tests; the live default is
+   *  `ingressSpendGate` (spend/ingress-gate.ts) — the SAME function every ordinary ingress door
+   *  consults. */
+  readonly spendGate?: (input: IngressSpendGateInput) => Promise<SpendGateDecision>;
+}
+
+/**
+ * Admit or refuse one eve-owned HITL answer submitted through Teams.
+ *
+ * Returns `{ auth }` on an allow — the same auth shape `onMessage` builds, so an admitted answer
+ * resumes the parked turn under OE's real Teams identity rather than eve's thinner default.
+ * Returns `null` on a refusal, which leaves the request PENDING (eve has no cancel on this seam).
+ */
+export async function admitTeamsInputResponse(
+  ctx: TeamsContext,
+  activity: TeamsInvokeActivity | TeamsMessageActivity,
+  deps: TeamsInputResponseDeps = {},
+): Promise<TeamsInputResponseResult> {
+  const probe = deps.userType ?? ((a) => resolveTeamsUserType(teamsHandleRosterProbe(ctx.teams), a.conversation.id, a.from.id));
+  let auth: ReturnType<typeof buildTeamsAuth> | undefined;
+  try {
+    const userType = await probe(activity);
+    auth = buildTeamsAuth({
+      userId: activity.from.id,
+      aadObjectId: activity.from.aadObjectId,
+      userName: activity.from.name,
+      tenantId: activity.tenantId ?? activity.conversation.tenantId,
+      conversationId: activity.conversation.id,
+      channelId: activity.teamsChannelId,
+      teamId: activity.teamId,
+      serviceUrl: activity.serviceUrl,
+      scope: activity.scope,
+      membershipType: teamsMembershipType(activity.channelData),
+      userType,
+    });
+    const bindable = {
+      channel: { kind: "teams" },
+      session: { auth: { current: auth } },
+    } as BindableContext;
+    const p = resolvePartition(bindable);
+
+    // SPEND GATE (OPE-588) — ahead of the room/guest admission below (see the header note). A
+    // decline returns `null` immediately, before the room/guest floor runs: over budget outranks
+    // identity, the same ordering `channels/unified.ts`'s `windowSpendGate` takes ahead of its own
+    // `resolveInboundAnswer`.
+    const spendGate = deps.spendGate ?? ingressSpendGate;
+    const spendVerdict = await spendGate({
+      bindable,
+      door: "answer",
+      principalId: activity.from.id,
+      post: async (text) => { await ctx.thread.post(text); },
+    });
+    if (spendVerdict === "declined") return null;
+
+    const verdict = await (deps.admit ?? admitInputResponse)({
+      org: p.org,
+      platform: p.platform,
+      workspace: p.workspace,
+      surface: p.surface,
+      surfaceKey: p.surfaceKey,
+      principalId: activity.from.id,
+      // `responses` is deliberately ABSENT: eve decodes the submission AFTER this hook returns, so
+      // Teams cannot know the count. A zero here would read as a measured value in the audit row.
+      ...(userType === undefined ? {} : { answererIsGuest: userType === "guest" }),
+    });
+    if (verdict.ok) return { auth };
+    const notify = deps.notify ?? (async (text: string): Promise<void> => { await ctx.thread.post(text); });
+    await notify(verdict.notice).catch((err: unknown) => {
+      console.error(`[open-everywhere:teams] HITL refusal notice failed to post: ${String(err)}`);
+    });
+    return null;
+  } catch (err) {
+    console.error(`[open-everywhere:teams] HITL answer admission failed softly — accepting the answer: ${String(err)}`);
+    // FAIL-OPEN with whatever auth we managed to build. `null` here would restore eve's silent
+    // `rejectInput`, which is the bug this module exists to close.
+    return { auth: auth ?? null };
+  }
+}

package/agent/channels/teams-message-ops.ts

@@ -0,0 +1,79 @@
+// teams-message-ops — Teams's SurfaceMessageOps (OPE-899): the ancillary message ops core features
+// dispatch through channels/surface-message-ops.ts. Before this file, Teams registered none, so the
+// stop acknowledgement (turn-anchor.ts's `postSurfaceText`) resolved nothing on a Teams turn — the
+// stop control worked (teams-stop.ts, the `angry` reaction), it was just invisible: a person who
+// reacted saw the agent go quiet and read nothing.
+//
+//   - postText    → the SAME Bot-Framework send/reply the mid-turn post arm uses
+//                   (teams-post-arm.ts's `dispatchTeamsReply`, exported for this file — one
+//                   mint/send implementation, never a second copy).
+//   - editMessage → the SAME update-activity call `edit_reply` performs (`editTeamsMessage`).
+//   - NO `postFiles` (register.ts already records: "NO attachment resolver — the Teams surface
+//     carries no attachment plane today"). The optional tier exists exactly for this shape.
+//   - NO `setReaction` (register.ts: "NO reaction surface — Teams has no integration reaction
+//     primitive"). The `angry` reaction (teams-stop.ts) IS Teams's stop affordance; there is no
+//     second glyph to place beside it.
+//
+// THE PROBLEM THIS FILE SOLVES, IN ONE SENTENCE: `SurfaceMessageOps.postText`/`editMessage` are
+// handed only a bare `channelId` (core's `channelId` is Teams's conversation id — see
+// `turn-anchor.ts`'s `turnAnchorAddress`), never a `serviceUrl`, and a Bot-Framework write needs
+// BOTH. `teams-conversation-ref.ts`'s `conversation`-grain address (OPE-899's addition to that
+// module) is the lookup that answers it: every inbound activity, on every scope, stamps a row keyed
+// on its EXACT conversation id, so the reply chain a channel turn anchored on is resolvable here by
+// that same id.
+//
+// `opts.replyToMessageId` on `postText` threads the post via `replyToActivityId` — the SAME field
+// the mid-turn reply arm anchors on. `turn-anchor.ts`'s own cancel-note call passes no such option
+// (a top-level post, like every other surface's cancel note today), so this is exercised by other
+// SurfaceMessageOps consumers (the approval decision notice), not by the stop path itself.
+
+import type { SurfaceMessageOps } from "@open-everywhere/core/agent/adapter-api.js";
+import { dispatchTeamsReply, editTeamsMessage, type TeamsTarget } from "./teams-post-arm.js";
+import { teamsConversationRef } from "./teams-conversation-ref.js";
+import { restoreTeamsConversationId } from "./teams-id-restore.js";
+
+/**
+ * The stored `conversation`-grain reference for `channelId`, or a loud, honest refusal — never a
+ * guessed target. Mirrors `github-message-ops.ts`'s `requireContainer`.
+ *
+ * 🔴 IT RESTORES THE RAW ID FIRST (OPE-1078). `channelId` reaches here in one of two spellings: raw,
+ * from a live turn's own anchor, or the SURFACE-KEY spelling, from a granted `teams:channel/<id>`
+ * address — the only spelling the resource-grant grammar admits. `restoreTeamsConversationId` is the
+ * identity on the first and the index lookup on the second, so both land on the same reference. The
+ * refusal below still names the id the CALLER gave, which is the one an operator can act on.
+ */
+async function requireConversationRef(channelId: string): Promise<{ readonly serviceUrl: string; readonly conversationId: string }> {
+  const ref = await teamsConversationRef(await restoreTeamsConversationId(channelId));
+  if (!ref) {
+    throw new Error(
+      `Teams surface message ops: no conversation reference for "${channelId}" — this deployment has never seen an inbound activity on that id.`,
+    );
+  }
+  return ref;
+}
+
+export const teamsMessageOps: SurfaceMessageOps = {
+  platform: "teams",
+
+  /** Post through the mid-turn reply transport, resolving `serviceUrl` from the stored conversation
+   *  reference. `opts?.replyToMessageId` threads the post — see the header. */
+  async postText(channelId, text, opts) {
+    const { serviceUrl, conversationId } = await requireConversationRef(channelId);
+    const target: TeamsTarget = {
+      platform: "teams",
+      serviceUrl,
+      conversationId,
+      ...(opts?.replyToMessageId ? { replyToActivityId: opts.replyToMessageId } : {}),
+    };
+    return dispatchTeamsReply(target, text);
+  },
+
+  /** Update the given activity in place — the same transport `edit_reply` performs on the reply
+   *  spine, resolving `serviceUrl` the same way `postText` does. It sends the RESOLVED conversation
+   *  id, never the caller's, for the reason `requireConversationRef` states: the caller's may be the
+   *  surface-key spelling, and the Connector accepts only the raw id. */
+  async editMessage(channelId, messageId, text) {
+    const { serviceUrl, conversationId } = await requireConversationRef(channelId);
+    await editTeamsMessage({ platform: "teams", channelId: conversationId, serviceUrl }, messageId, text);
+  },
+};