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

package/dist/agent/channels/teams-fire-eligibility.js

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

package/dist/agent/channels/teams-fire-eligibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams-fire-eligibility.js","sourceRoot":"","sources":["../../../agent/channels/teams-fire-eligibility.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,gFAAgF;AAChF,kGAAkG;AAClG,6FAA6F;AAC7F,wFAAwF;AACxF,EAAE;AACF,+FAA+F;AAC/F,qFAAqF;AACrF,kGAAkG;AAClG,gFAAgF;AAChF,kGAAkG;AAClG,EAAE;AACF,iGAAiG;AACjG,kGAAkG;AAClG,mGAAmG;AACnG,oGAAoG;AACpG,yDAAyD;AACzD,EAAE;AACF,oFAAoF;AACpF,gGAAgG;AAChG,qGAAqG;AACrG,oGAAoG;AACpG,oGAAoG;AACpG,4FAA4F;AAC5F,qGAAqG;AACrG,oGAAoG;AACpG,gGAAgG;AAChG,oGAAoG;AACpG,mFAAmF;AACnF,EAAE;AACF,kGAAkG;AAClG,kGAAkG;AAClG,8FAA8F;AAC9F,gGAAgG;AAChG,+FAA+F;AAC/F,kGAAkG;AAClG,8CAA8C;AAC9C,EAAE;AACF,gGAAgG;AAChG,iGAAiG;AACjG,mGAAmG;AACnG,oGAAoG;AACpG,gGAAgG;AAChG,kEAAkE;AAQlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAA4B,MAAM,iBAAiB,CAAC;AAElF,MAAM,UAAU,GAAG,kCAAkC,CAAC;AAEtD;4EAC4E;AAC5E,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAYlC,8FAA8F;AAC9F,SAAS,UAAU,CAAC,KAAgC;IAClD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,SAAiB,EACjB,SAAiB,EACjB,WAAmB,EACnB,UAA8B,EAC9B,GAAwB;IAExB,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,aAAa,CAAC,CAAC;IACnH,2FAA2F;IAC3F,+FAA+F;IAC/F,6FAA6F;IAC7F,MAAM,WAAW,GAAG,MAAM,gBAAgB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAClE,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACvE,IAAI,CAAC;QACH,IAAI,GAAG,GAAuB,GAAG,UAAU,UAAU,kBAAkB,CAAC,WAAW,CAAC,aAAa,kBAAkB,CAAC,SAAS,CAAC,UAAU,CAAC;QACzI,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,sBAAsB,IAAI,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;YAChE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,CAAoB,CAAC;YACjD,qFAAqF;YACrF,4FAA4F;YAC5F,2FAA2F;YAC3F,oBAAoB;YACpB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,OAAO,UAAU,CAAC,oBAAoB,CAAC,CAAC;YACxE,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;gBAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YAC9E,GAAG,GAAG,OAAO,IAAI,CAAC,iBAAiB,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1F,CAAC;QACD,8FAA8F;QAC9F,iGAAiG;QACjG,iGAAiG;QACjG,8FAA8F;QAC9F,oCAAoC;QACpC,OAAO,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,+DAA+D;IAClG,CAAC;AACH,CAAC;AAED,kGAAkG;AAClG,MAAM,CAAC,MAAM,uBAAuB,GAA6B,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,CAC9G,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,qBAAqB,CAAC,CAAC;AAMjG;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,WAAmB,EAAE,GAAwB;IAC5F,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,UAAU,UAAU,kBAAkB,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAc,CAAC;QACvH,2FAA2F;QAC3F,sFAAsF;QACtF,+FAA+F;QAC/F,IAAI,OAAO,IAAI,EAAE,cAAc,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAChE,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,wEAAwE;IAC5F,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,MAAM,sBAAsB,GAA4B,CAAC,WAAW,EAAE,EAAE,CAAC,0BAA0B,CAAC,WAAW,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/agent/channels/teams-front.d.ts

@@ -0,0 +1,249 @@
+import { type Channel, type RouteHandlerArgs } from "eve/channels";
+import { type TeamsMessageActivity } from "eve/channels/teams";
+import { type OpenEverywhereTeamsAuth } from "./teams-identity.js";
+import { type TeamsRosterProbe } from "./teams-roster.js";
+import { type TeamsReactionActivity, type TeamsStopOutcome } from "./teams-stop.js";
+import { type TeamsEngagementVerdict } from "./teams-engagement.js";
+import { type TeamsSupervisorDeps } from "./teams-supervisor.js";
+import { EventDedupe, ThreadFifo, type ExternalPolicy, type IngestedChatMessage, type AuthorTrustQuery, type SupervisorGrain, type UnifiedWindowWake, type Partition, type AttachSessionForCancel } from "@open-everywhere/core/agent/adapter-api.js";
+/** An HTTP route handler — `RouteHandler` isn't a public eve export, so we mirror its shape
+ *  (the exact slack-front mirror). */
+type RouteHandler = (req: Request, args: RouteHandlerArgs) => Promise<Response>;
+/** The public URL the Bot Framework POSTs every activity to (the bot registration's endpoint). */
+export declare const PUBLIC_TEAMS_ROUTE = "/eve/v1/teams";
+/** The internal path the wrapped `teamsChannel` is mounted at (never hit by Teams directly). */
+export declare const INTERNAL_TEAMS_ROUTE = "/eve/v1/teams/native";
+/** Everything the front resolved for one activity that the window OWNS — null means "forward to
+ *  the native channel" (the byte-identical default). */
+export interface TeamsFrontPlan {
+    readonly window: UnifiedWindowWake;
+    /** The DOMAIN-GRAIN surface key (`teams/<tenant>/<channel>` after the binding's segment
+     *  sanitisation) — the gate/registry/FIFO/audit key. */
+    readonly surfaceKey: string;
+    readonly partition: Partition;
+    readonly grain: SupervisorGrain;
+    readonly auth: OpenEverywhereTeamsAuth;
+}
+/**
+ * FOLD THE ROSTER VERDICT INTO ONE ACTIVITY'S AUTH CAPTURE (OPE-493) — the ONE step both front
+ * dispatch paths take before they stamp, and the reason the front's author leg is no longer inert.
+ *
+ * Until this existed, `resolveTeamsUserType` ran on NO live path. The front owns channel activities
+ * (the shared window) and personal/group chats (the OPE-357 DM divert), and its capture was built
+ * without a `userType` — so a measured B2B guest woke the window rendered as a `peer`
+ * (session wrun_41KZXE4FGK0GPSJB4JNM4KCMHY, 2026-08-15). The verdict now rides the SAME attribute
+ * the native path uses, so `bindTeams` → `teamsTrust` demotes the guest to `external` and the
+ * OPE-489 author leg answers, with no change of their own.
+ *
+ * THREE CALLERS, TWO LATENCY BUDGETS. The two DISPATCH paths run inside the front's
+ * `waitUntil(fifo.enqueue(…))`, so their roster GET lands AFTER the 200 ack and costs the Bot
+ * Framework nothing — they call this unconditionally. {@link liveTeamsExternalGate} runs BEFORE the
+ * ack, so it calls this only when a grain could act on the answer; its own note carries the reasoning.
+ *
+ * COST: one cached GET per (CHANNEL, user) per `identity.dmTrustTtlMs`, never one per message.
+ * `conversation.id` on a CHANNEL activity is the REPLY-CHAIN id (it carries `;messageid=<root>`), and
+ * `resolveTeamsUserType` strips that suffix for the CACHE KEY, so every reply chain in one channel
+ * shares one entry (OPE-572). The id still reaches the CONNECTOR unstripped — exactly as the native
+ * `teamsOnMessage` passes it, which is the shape the 2026-08-15 live probe measured. Whether the
+ * connector ALSO accepts a thread-qualified id is NOT established; one live GET settles it, and a
+ * refusal fails open like any other non-2xx.
+ *
+ * FAIL-OPEN, TOTALLY: a missing serviceUrl, an HTTP error, a transport throw, an unrecognised body —
+ * every one of them returns the capture UNCHANGED, by reference (see `withTeamsUserType`). The
+ * try/catch covers the probe FACTORY as well as the probe, so no roster failure can take a wake off
+ * the air.
+ *
+ * `probeFor` is the test seam: a FACTORY, not a probe, so a test can script "this activity has no
+ * probe at all" (`() => undefined`) distinctly from "the probe answers nothing". Live callers omit
+ * it and get the activity's own serviceUrl probe.
+ */
+export type TeamsRosterProbeFor = (activity: TeamsMessageActivity) => TeamsRosterProbe | undefined;
+/**
+ * The AUTHOR-TRUST question for one activity (OPE-516) — the OPERATOR's own declaration of who is
+ * internal in this tenant.
+ *
+ * 🔴 TEAMS NEEDS IT EVEN THOUGH TEAMS CAN REFUTE. The surface refutation (`teamsAuthorRefuted`) reads
+ * a resolved roster `userRole`, which every front path now resolves (OPE-493). It still does not
+ * answer everywhere: a tenant whose bot credential cannot read the roster gets no verdict, and the
+ * probe only ever REFUTES — it never declares anyone internal. The register is the leg that covers
+ * those. It is additive: an unarmed tenant declares nobody and the leg contributes nothing, so a
+ * deployment that has not armed a register sees no behaviour change at all.
+ *
+ * Returns `{}` when the tenant is unreadable — no tenant key, no arming key, no question to ask.
+ */
+export declare function teamsAuthorFacts(auth: unknown, authorId: string | undefined): {
+    readonly authorTrust?: AuthorTrustQuery;
+};
+/**
+ * The SURFACE's own vendor-external verdict for one activity: this room spans another organisation.
+ *
+ * A Teams SHARED CHANNEL (`channelData.channel.membershipType === "shared"`) is exactly that — it can
+ * hold members from tenants that are not ours, which is why teams-identity.ts already demotes one to
+ * `external` for the memory tier. Absent or any other value means "not reported", which includes "the
+ * activity did not carry channelData": absence of evidence, and this leg fails OPEN.
+ */
+export declare function teamsVendorExternal(a: TeamsMessageActivity): boolean;
+/**
+ * THE EXTERNAL-PARTICIPANT VERDICT for one Teams activity — pure, so the four outcomes are tested
+ * without a Bot-Framework call, a store or a live tenant. The four values name WHAT THE CALLER OWES;
+ * see {@link DiscordExternalVerdict}'s twin in discord-gateway.ts for the full reasoning.
+ *
+ * 🔴 THE AUTHOR GRAIN IS TESTED FIRST, AND THE ORDER MATTERS — the same ruling Discord's verdict
+ * carries. An excluded author in a silenced room is owed a notice they can act on; the room
+ * announcement tells the whole room something about the room instead.
+ */
+export type TeamsExternalVerdict = "proceed" | "withheld-addressed" | "withheld-ambient" | "silent-room";
+export declare function teamsExternalVerdict(input: {
+    readonly policy: ExternalPolicy;
+    readonly author: IngestedChatMessage;
+    /** The activity @mentions the bot, or arrived in a personal chat — an ADDRESSED message is owed
+     *  an answer. */
+    readonly addressed: boolean;
+    /** A personal or group chat. A DM contributes NO room leg: on a DM the trust plane asks about the
+     *  PARTNER, not about the room. */
+    readonly isDm: boolean;
+    /** The SURFACE's vendor-external verdict — {@link teamsVendorExternal}. */
+    readonly vendorExternal: boolean;
+    /** The DOMAIN-grain surface key of the room, for the operator-declared leg. */
+    readonly roomKey: string;
+    /** The GROUP-rung key of the room's team, when the activity names one. */
+    readonly groupKey?: string;
+}): TeamsExternalVerdict;
+/**
+ * The LIVE gate: resolve the verdict for one verified message activity and pay what it owes.
+ * `true` means SUPPRESSED — the caller acks and forwards nothing.
+ *
+ * FAIL-OPEN on an unresolvable identity. If the auth capture or the partition cannot be built there
+ * is no room key, no tenant and no classification to act on, so the activity takes today's path and
+ * the existing branches apply their own fail-closed rules. Every carriage leg in this plane fails
+ * open, and this one has to as well: a config error must not silently take Teams off the air.
+ *
+ * 🔴 THE ROSTER PROBE IS PAID FOR ONLY WHEN THE POLICY CAN USE IT. This gate runs BEFORE the 200 ack,
+ * so a Bot Connector GET here is latency on EVERY activity — including the ones the front only
+ * forwards — and a slow ack makes the Bot Framework redeliver. The shipped grains (`taint` / `engage`)
+ * can suppress nothing, so `externalPolicyIsInert` skips the probe entirely and an un-opted-in
+ * deployment pays exactly what it paid before. An opted-in one pays one cached GET per
+ * (conversation, user) per TTL. This is the same trade `slack-front.ts` makes on its native
+ * `app_mention` forward, through the same predicate.
+ */
+export declare function liveTeamsExternalGate(a: TeamsMessageActivity, probeFor?: TeamsRosterProbeFor): Promise<boolean>;
+/**
+ * Resolve the LIVE single-window plan for one verified message activity, fail-closed: any
+ * config/partition error, the gates off, the privacy floor failing, or a missing reply target
+ * all yield null — the front then FORWARDS to the native channel, byte-identical to today.
+ *
+ * The GRAIN + VOUCH are keyed on the DOMAIN-GRAIN key (`teams/<tenant>/<channel>` — a Teams
+ * conversation id names one REPLY CHAIN, so the listable/vouchable container is the channel;
+ * memory/partition.ts's domainKeyOf resolves it via the binding's domainSurface, mirroring the
+ * Discord thread→parent-channel precedent). Operators list/vouch `teams/<tenant>` or
+ * `teams/<tenant>/<channel-id>` (sanitised segments, same as every stored key).
+ */
+export declare function liveTeamsFrontPlan(a: TeamsMessageActivity): TeamsFrontPlan | null;
+/** Live supervisor deps over the (org, grain.registryKey) channel_session registry — the exact
+ *  notion.ts/linear.ts shape. The wake ALWAYS diverts (teams-supervisor requires the window). */
+/**
+ * EXPORTED FOR THE INGRESS CONTRACT TEST (OPE-1719), not for another caller. `liveTeamsDispatch` is
+ * the only production caller and it is thirty lines below. `scripts/owned-thread-ingress-wiring-test.ts`
+ * drives the `wake` member of THIS object — the real Teams ingress divert — because a test that
+ * reimplemented the wake dep would stay green after somebody moved this leg back to the raw divert,
+ * which is the exact regression the ticket closes.
+ */
+export declare function liveTeamsSupervisorDeps(plan: TeamsFrontPlan, to: RouteHandlerArgs["to"]): TeamsSupervisorDeps;
+/** Injectable seams so the front is testable without live JWT verification / a Bot registration. */
+export interface TeamsFrontOptions {
+    /** Verify one inbound request and return the raw body; throw to reject (401). Defaults to
+     *  eve's `verifyTeamsRequest` with env credentials (MICROSOFT_APP_ID / TEAMS_APP_ID) — the
+     *  same fallback the credential-less teamsChannel uses. */
+    readonly verify?: (req: Request) => Promise<string>;
+    readonly dedupe?: EventDedupe;
+    readonly fifo?: ThreadFifo;
+    readonly now?: () => number;
+    /** Durable first-sighting check (true = proceed). Defaults to the operational store. */
+    readonly markEventSeen?: (org: string, key: string, atIso: string) => Promise<boolean>;
+    /** The single-window plan for one verified activity. Defaults to {@link liveTeamsFrontPlan}
+     *  (grain + fail-closed privacy floor); fail-closed null ⇒ forward, byte-identical. */
+    readonly planFor?: (a: TeamsMessageActivity) => TeamsFrontPlan | null;
+    /** The dispatch executor (defaults to the real supervisor dispatch over the live deps). */
+    readonly dispatch?: (a: TeamsMessageActivity, plan: TeamsFrontPlan, to: RouteHandlerArgs["to"]) => Promise<void>;
+    /** The DM window divert (OPE-357) — defaults to {@link liveTeamsDmDivert}. Injected so the front's
+     *  DM-routing decision (predicate + fail-closed to native) is unit-testable without a live store. */
+    readonly dmDivert?: (a: TeamsMessageActivity, auth: OpenEverywhereTeamsAuth, partition: Partition, to: RouteHandlerArgs["to"]) => Promise<void>;
+    /** The external-participant gate (OPE-507/OPE-504) — `true` suppresses the activity. Defaults to
+     *  {@link liveTeamsExternalGate}; injected so the front's ORDERING (above both branches, so the
+     *  native forward is covered too) is unit-testable without a store or a Bot registration. */
+    readonly externalGate?: (a: TeamsMessageActivity) => Promise<boolean>;
+    /** The stop-reaction arm (OPE-898) — defaults to {@link routeTeamsStopReaction} over eve's cancel
+     *  door. Injected so the front's ORDERING (above `parseTeamsActivity`, which never sees a reaction
+     *  activity) is unit-testable without a live session. */
+    readonly stopReaction?: (rx: TeamsReactionActivity, attachSession: AttachSessionForCancel) => Promise<TeamsStopOutcome>;
+    /** The ambient engagement seam's READ (OPE-1500) — defaults to {@link resolveTeamsEngagement}.
+     *  Injected so the front's ORDERING (above both the DM divert and Leg A, so one message is never
+     *  handled by two legs) is unit-testable without an operational store. */
+    readonly engagementSeam?: (a: TeamsMessageActivity, machineAuthored: boolean) => Promise<TeamsEngagementVerdict>;
+    /** The ambient engagement seam's WRITE — defaults to {@link markTeamsEngaged}. Separate from the
+     *  read so a test can assert that exactly one mention marks exactly one row. */
+    readonly markEngaged?: (a: TeamsMessageActivity) => Promise<string | null>;
+    /** Leg A's ROOM-grain stop READ (OPE-1511) — defaults to {@link teamsRoomWatchStopped}. Injected
+     *  so the front's ORDERING (below the mention re-invitation, above the dispatch) is unit-testable
+     *  without an operational store. */
+    readonly roomStopped?: (partition: Partition) => Promise<boolean>;
+    /** Leg A's ROOM-grain wake row WRITE — defaults to {@link markTeamsRoomWatched}. */
+    readonly markRoomWatched?: (partition: Partition, atIso: string) => Promise<void>;
+    /** The @mention's ROOM-grain re-invitation — defaults to {@link clearTeamsRoomStop}. Separate
+     *  from the read so a test can prove a mention is the way back out of a room stop. */
+    readonly clearRoomStop?: (partition: Partition, atIso: string, engagedBy: string) => Promise<void>;
+}
+/** The live dispatch for one owned activity: per-message trust off the SAME auth capture the
+ *  session binds with, then the teams-supervisor core over the live registry deps.
+ *
+ *  `probeFor` is the roster test seam — see {@link teamsAuthWithUserType}. */
+export declare function liveTeamsDispatch(a: TeamsMessageActivity, plan: TeamsFrontPlan, to: RouteHandlerArgs["to"], probeFor?: TeamsRosterProbeFor): Promise<void>;
+/**
+ * THE DM WINDOW DIVERT (OPE-357) — a Teams personal/group chat lands in its OWN first-class standing
+ * window (channels/dm-seat.ts), the Teams parity of divertDiscordDmToWindow / slack-front's
+ * scheduleDmWake, and the last DM-family surface to first-class (Slack: OPE-351 stages 2+4; Discord:
+ * OPE-356).
+ *
+ * WHAT IT FIXES. Until now a Teams DM ran on eve's native per-conversation token (teams.ts's
+ * onMessage): a session with no window row, and therefore NO DISPATCHABLE ADDRESS. A DM that delegated
+ * could not be told the answer had arrived — `resolveCallerSeat` took the OPE-306 ANCHOR arm and the
+ * worker posted its own report into the DM (the OPE-358 double-post). A window token IS an address, so
+ * the DM seat now gets the whole standing-seat apparatus for free: woken, redriven, rotated (on the DM
+ * thresholds — `OE_DM_SEAT_ROTATE_*`, never the supervisor's), spend-counted and audited through the
+ * seams every other seat already uses. The worker's direct report-back stops the moment the seat
+ * becomes a real window (its caller now resolves via `ownWindowSeat`, not the anchor) — no two voices
+ * in one DM per delegated turn.
+ *
+ * SEPARATE ADMIT SPACE, NOT A FLOOR BYPASS. This never touches `teamsSingleWindowPrivacyOk`: that floor
+ * refuses `scope !== "channel"` outright because a personal/group chat may never join the SHARED
+ * cross-surface window, and it stays exactly that strict. A DM window is a STRUCTURALLY DIFFERENT,
+ * non-shared address space keyed on the DM's own surface key (`getOrCreateDmSeat`), deliverable to its
+ * own DM and nowhere else — which is precisely why it is safe to admit a DM here without weakening the
+ * channel floor (the Discord `isDm`-before-the-single-window-block precedent).
+ *
+ * 🔴 IT BYPASSES THE ENGAGEMENT GATE — a DM is always answered (see {@link buildTeamsDmWake}). The
+ * SPEND gate is NOT bypassed: `divertToUnifiedWindow` runs its own window-door gate (channels/unified.ts
+ * windowSpendGate), which is exactly the choke point every Teams single-window divert already leans on
+ * (Teams has never front-positioned a pre-gate, unlike Discord).
+ *
+ * FAIL-CLOSED: a seat-resolution or dispatch failure PROPAGATES to the FIFO's loud catch. There is
+ * deliberately NO fall-back to the native send — that would answer the human from a second session with
+ * no window row behind it, the very topology this replaces (and the OPE-351 stranding hazard).
+ */
+export declare function liveTeamsDmDivert(a: TeamsMessageActivity, capturedAuth: OpenEverywhereTeamsAuth, partition: Partition, to: RouteHandlerArgs["to"], probeFor?: TeamsRosterProbeFor): Promise<void>;
+/**
+ * Build the front route handler. Verifies (fail-closed 401), classifies, then forwards or
+ * diverts. `innerHandler` is teamsChannel's own POST handler, invoked with a FRESH Request
+ * (re-readable body) + the same {@link RouteHandlerArgs}, so teamsChannel re-verifies and
+ * dispatches exactly as if it owned the URL — byte-identical whenever no plan resolves.
+ */
+export declare function buildTeamsFrontHandler(innerHandler: RouteHandler, opts?: TeamsFrontOptions): RouteHandler;
+/**
+ * Compose the front route with a wrapped `teamsChannel`. `inner` must have been built with
+ * `route: INTERNAL_TEAMS_ROUTE`. Returns the SAME channel value (preserving eve's internal
+ * adapter/receive) with the public front route prepended — so the Bot Framework's URL hits us,
+ * and both routes share one channel name → one session namespace (the frontSlackChannel shape).
+ */
+export declare function frontTeamsChannel<C extends Channel<any, any, any>>(inner: C, opts?: TeamsFrontOptions): C;
+export {};
+//# sourceMappingURL=teams-front.d.ts.map

package/dist/agent/channels/teams-front.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams-front.d.ts","sourceRoot":"","sources":["../../../agent/channels/teams-front.ts"],"names":[],"mappings":"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"}