comisai 1.0.44 → 1.0.46

package/node_modules/@comis/channels/dist/msteams/msteams-adapter.js

@@ -0,0 +1,676 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams Channel Adapter: a route-driven ChannelPort implementation.
+ *
+ * Teams delivers activities as HTTPS POSTs, so this adapter holds no socket and
+ * no long-poll. `start()` validates credentials and marks the adapter connected;
+ * inbound activities arrive through `handleWebhookEvents`, which the mounted
+ * gateway ingress calls after it has authenticated the request. Each activity is
+ * normalized, gated against the sender allowlist, and fanned out to the
+ * registered message handlers under a fresh request context.
+ *
+ * Outbound `sendMessage` posts to the Bot Framework Connector REST API with a
+ * cached bearer token: a direct message sends a top-level activity, while a
+ * channel or group reply threads under the parent via `replyToId`.
+ *
+ * The adapter delivers a clean NormalizedMessage — external-content fencing is a
+ * shared executor concern applied to every channel, deliberately not duplicated
+ * here.
+ *
+ * @module
+ */
+import { runWithContext, systemNowMs } from "@comis/core";
+import { err, fromPromise, ok } from "@comis/shared";
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { mapMsTeamsActivityToNormalized, resolveCaptureThreadId, } from "./message-mapper.js";
+import { mapMsTeamsReaction, } from "./msteams-reaction-binder.js";
+import { rebuildConversationReference } from "./msteams-proactive.js";
+import { createMsTeamsConnector, isSafeConversationId, isSafeServiceUrl, postConnectorActivityWithRetry, } from "./msteams-connector.js";
+import { createConnectorTokenProviderFor, } from "./msteams-auth.js";
+import { normalizeCardAction } from "./msteams-actions.js";
+import { buildAttachmentReferenceBody, buildImageActivityBody, buildTextActivityBody, resolveReplyToId, resolveTypingServiceUrl, withTrailingSlash, } from "./msteams-adapter-outbound.js";
+// ---------------------------------------------------------------------------
+// Outbound send helpers
+// ---------------------------------------------------------------------------
+/** Default attachment byte reader — the url is a safePath temp file the outbound handler wrote (no path build here). */
+const defaultReadFile = readFile;
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a Microsoft Teams adapter implementing the ChannelPort interface.
+ *
+ * Route-driven: `start()` validates the three secret-mode credentials and marks
+ * the adapter connected without opening any connection. Inbound activities are
+ * dispatched through `handleWebhookEvents`.
+ */
+export function createMsTeamsAdapter(deps) {
+    const now = deps.now ?? systemNowMs;
+    // The configured credential mode; secret unless the composition root set it.
+    const authMode = deps.authMode ?? "secret";
+    // Cached token provider for the outbound Connector send, minted from the
+    // configured credential — secret (appPassword), certificate (a signed
+    // client-assertion from certPath), or managed identity (the local identity
+    // endpoint). All three share one cache/skew/tenant-guard scaffold; the cert
+    // key, assertion, and every minted token stay out of every log field (T-5).
+    const tokens = createConnectorTokenProviderFor(authMode, {
+        appId: deps.appId,
+        appPassword: deps.appPassword,
+        tenantId: deps.tenantId,
+        certPath: deps.certPath,
+        managedIdentityClientId: deps.managedIdentityClientId,
+        env: deps.env,
+        readFileImpl: deps.certReadFileImpl,
+        logger: deps.logger,
+        fetchImpl: deps.fetchImpl,
+        now: deps.now,
+    });
+    // The configured deployment cloud, threaded into the connector and every
+    // adapter-side serviceUrl callsite so the bearer token is only ever sent to the
+    // exact Connector host for that cloud. Defaults to "public" so nothing regresses.
+    const cloud = deps.cloud ?? "public";
+    // Connector transport: the edit/delete REST mutations + the typing keepalive.
+    // Shares the cached token; the adapter resolves the routing context and drives it.
+    const connector = createMsTeamsConnector({
+        tokens,
+        fetchImpl: deps.fetchImpl,
+        logger: deps.logger,
+        now,
+        timer: deps.timer,
+        cloud,
+    });
+    const handlers = [];
+    // Teams surfaces inbound reactions as messageReaction activities on the same
+    // webhook; the send-reaction port methods stay omitted (Teams exposes no
+    // bot-reaction send API), so only the inbound fanout is wired.
+    const reactionHandlers = [];
+    // Stable channel identity. This webhook adapter has no self-identity fetch
+    // (unlike Slack resolving botUserId at start), so it reports a constant id.
+    const _channelId = "msteams";
+    // Health tracking. `_lastError` is a string because ChannelStatus.error is a
+    // string; the message is captured on failure branches for getStatus().
+    let _connected = false;
+    let _startedAt;
+    let _lastMessageAt;
+    // Inbound-only liveness: bumped ONLY at the inbound sites (message/reaction/
+    // card action), never on an outbound send — so a send-only bot cannot mask a
+    // dead ingress the way the outbound-polluted _lastMessageAt would.
+    let _lastInboundAt;
+    let _lastError;
+    /**
+     * The single sender-authorization gate every inbound path shares — message,
+     * reaction, and card-action. In allowlist mode an inbound is admitted only when
+     * its sender id OR its conversation id is on the allowlist; "open" mode admits
+     * all. One authoritative gate: no path re-implements authorization, so the
+     * default-deny decision is made in exactly one place for every inbound kind.
+     */
+    function isAllowedSender(senderId, channelId) {
+        if (deps.allowMode !== "allowlist")
+            return true;
+        return (deps.allowFrom.includes(senderId) || deps.allowFrom.includes(channelId));
+    }
+    /**
+     * Process a single inbound activity: map → allowlist-gate → record liveness →
+     * fan out to handlers under a fresh request context.
+     */
+    /**
+     * Fan a mapped reaction out to the registered reaction handlers under a fresh
+     * request context; a throwing or rejecting handler is logged and never aborts
+     * the loop or its siblings (mirrors the message fanout).
+     */
+    function fanOutReactions(traceId, reaction) {
+        void runWithContext({
+            traceId,
+            startedAt: now(),
+            channelType: "msteams",
+            tenantId: "default",
+            trustLevel: "admin",
+        }, () => {
+            for (const handler of reactionHandlers) {
+                try {
+                    Promise.resolve(handler(reaction)).catch((handlerErr) => {
+                        deps.logger.error({
+                            err: handlerErr,
+                            hint: "Check the msteams inbound reaction handler",
+                            errorKind: "internal",
+                        }, "Inbound reaction handler error");
+                    });
+                }
+                catch (handlerErr) {
+                    deps.logger.error({
+                        err: handlerErr,
+                        hint: "Check the msteams inbound reaction handler",
+                        errorKind: "internal",
+                    }, "Inbound reaction handler error");
+                }
+            }
+        });
+    }
+    /**
+     * Fan a normalized inbound message out to the registered message handlers under
+     * a fresh request context; a throwing or rejecting handler is logged and never
+     * aborts the loop or its siblings. Shared by the message and card-action paths.
+     */
+    function fanOutMessage(traceId, normalized) {
+        void runWithContext({
+            traceId,
+            startedAt: now(),
+            channelType: "msteams",
+            tenantId: "default",
+            trustLevel: "admin",
+        }, () => {
+            for (const handler of handlers) {
+                try {
+                    Promise.resolve(handler(normalized)).catch((handlerErr) => {
+                        deps.logger.error({
+                            err: handlerErr,
+                            hint: "Check the msteams inbound message handler",
+                            errorKind: "internal",
+                        }, "Inbound message handler error");
+                    });
+                }
+                catch (handlerErr) {
+                    deps.logger.error({
+                        err: handlerErr,
+                        hint: "Check the msteams inbound message handler",
+                        errorKind: "internal",
+                    }, "Inbound message handler error");
+                }
+            }
+        });
+    }
+    /**
+     * Map an inbound messageReaction activity to a NormalizedReaction, gate the
+     * reactor against the same allowlist the message path uses, and fan it out.
+     */
+    function processReaction(activity) {
+        const reaction = mapMsTeamsReaction(activity);
+        if (!reaction)
+            return;
+        if (!isAllowedSender(reaction.reactorId, reaction.channelId)) {
+            deps.logger.warn({
+                channelType: "msteams",
+                hint: "Add the aadObjectId or conversation.id to channels.msteams.allowFrom",
+                errorKind: "precondition",
+            }, "Inbound reaction from non-allowlisted reactor dropped");
+            return;
+        }
+        _lastMessageAt = now();
+        _lastInboundAt = now();
+        // An inbound reaction is an inbound activity too: refresh the routing tuple so
+        // a later proactive send recovers the freshest reference. Key by the same
+        // stripped channelId the message path and a proactive send target; the thread
+        // root is resolved identically so a reaction never clobbers a message capture.
+        captureReference(activity, reaction.channelId, resolveCaptureThreadId(activity));
+        const traceId = randomUUID();
+        deps.logger.debug({ step: "channels-inbound", channelType: "msteams", traceId }, "Inbound reaction");
+        fanOutReactions(traceId, reaction);
+    }
+    /**
+     * Fire-and-forget upsert of the conversation routing tuple on every inbound so a
+     * later proactive send can recover it. The key is `conversationId` — the mapper's
+     * stripped `normalized.channelId` (the ;messageid= thread suffix is carried
+     * separately as `threadId`), NOT the raw `conversation.id`: a proactive send
+     * targets that same stripped channelId, so keying by the raw id would miss on a
+     * threaded reference. Tenant is `channelData.tenant.id` (fallback
+     * `conversation.tenantId`). Skips when there is no store or no serviceUrl to route
+     * with; a capture failure is logged at DEBUG and never breaks inbound delivery.
+     */
+    function captureReference(activity, conversationId, threadId) {
+        const store = deps.conversationStore;
+        if (store === undefined)
+            return;
+        const serviceUrl = activity.serviceUrl;
+        const tenantId = activity.channelData?.tenant?.id ?? activity.conversation.tenantId;
+        if (typeof serviceUrl !== "string" || serviceUrl.length === 0)
+            return;
+        if (typeof tenantId !== "string" || tenantId.length === 0)
+            return;
+        Promise.resolve(store.capture({
+            conversationId,
+            serviceUrl,
+            tenantId,
+            threadId,
+            updatedAt: now(),
+        })).then((result) => {
+            if (!result.ok) {
+                deps.logger.debug({
+                    channelType: "msteams",
+                    hint: "Inspect the conversation store write path",
+                    errorKind: "internal",
+                }, "Conversation reference capture returned an error");
+            }
+        }, (captureErr) => {
+            deps.logger.debug({
+                channelType: "msteams",
+                err: captureErr,
+                hint: "Inspect the conversation store write path",
+                errorKind: "internal",
+            }, "Conversation reference capture threw");
+        });
+    }
+    /**
+     * Resolve the Connector service context for an outbound call. A reply rides the
+     * caller's `extra.serviceUrl` (the 228 path — never consults the store); a
+     * proactive send (no serviceUrl) recovers the stored reference and RE-VALIDATES
+     * its serviceUrl through the host allowlist before use. A miss (or no store)
+     * errs — never a wrong-host default that would 403 or leak the token.
+     */
+    async function resolveConnectorServiceContext(conversationId, options) {
+        const explicit = typeof options?.extra?.serviceUrl === "string"
+            ? options.extra.serviceUrl
+            : undefined;
+        if (explicit !== undefined) {
+            return ok({ serviceUrl: withTrailingSlash(explicit) });
+        }
+        const store = deps.conversationStore;
+        const got = store !== undefined ? await store.get(conversationId) : undefined;
+        if (got === undefined || !got.ok || got.value === undefined) {
+            return err(new Error("no stored conversation reference for a proactive send"));
+        }
+        const rebuilt = rebuildConversationReference(got.value, (url) => isSafeServiceUrl(url, cloud));
+        if (!rebuilt.ok)
+            return err(rebuilt.error);
+        return ok({
+            serviceUrl: withTrailingSlash(rebuilt.value.serviceUrl),
+            threadId: rebuilt.value.threadId,
+        });
+    }
+    /**
+     * Route a card-action invoke: normalize it to a button-callback message (the
+     * normalizer sets the clicker id from the VERIFIED from.aadObjectId and drops
+     * any unrendered verb or missing callback), then gate it through the SAME
+     * sender allowlist the message path uses. An unlisted clicker is dropped before
+     * onMessage — the card action reuses the one default-deny gate and adds no
+     * parallel authorization. No conversation reference is captured: a button
+     * callback is not a fresh inbound to reply to.
+     */
+    function processCardAction(activity) {
+        const result = normalizeCardAction(activity);
+        if (result.message === null) {
+            // Distinguish the benign "not our activity" drop (silent by design — a ping
+            // or a non-card invoke) from the security-relevant rejects, each of which
+            // gets a §2.7 WARN carrying hint + a distinct errorKind so a T-6
+            // arbitrary-verb probe against the approval gate, or a legitimate approver
+            // whose click vanished, is diagnosable via comis explain / fleet. The log
+            // names the reject class and carries NO secret/token/raw-signature — it
+            // mirrors the allowlist-drop WARN shape below.
+            switch (result.reason) {
+                case "ignored":
+                    break;
+                case "unrendered-verb":
+                    deps.logger.warn({
+                        channelType: "msteams",
+                        hint: "Card-action verb is not in the rendered set; a click cannot invoke a method the bot never rendered",
+                        errorKind: "validation",
+                    }, "Inbound card action dropped: unrendered verb");
+                    break;
+                case "missing-callback":
+                    deps.logger.warn({
+                        channelType: "msteams",
+                        hint: "Card-action invoke carried no signed callback; the action is malformed",
+                        errorKind: "validation",
+                    }, "Inbound card action dropped: missing signed callback");
+                    break;
+                case "missing-clicker":
+                    deps.logger.warn({
+                        channelType: "msteams",
+                        hint: "Card-action activity carried no verified aadObjectId; the clicker cannot be authorized",
+                        errorKind: "precondition",
+                    }, "Inbound card action dropped: no verified clicker id");
+                    break;
+            }
+            return;
+        }
+        const normalized = result.message;
+        if (!isAllowedSender(normalized.senderId, normalized.channelId)) {
+            deps.logger.warn({
+                channelType: "msteams",
+                senderId: normalized.senderId,
+                hint: "Add the aadObjectId or conversation.id to channels.msteams.allowFrom",
+                errorKind: "precondition",
+            }, "Inbound from non-allowlisted sender dropped");
+            return;
+        }
+        _lastMessageAt = now();
+        _lastInboundAt = now();
+        const traceId = randomUUID();
+        normalized.metadata.traceId = traceId;
+        deps.logger.info({
+            step: "channels-inbound",
+            channelType: "msteams",
+            messageId: normalized.id,
+            chatId: normalized.channelId,
+            traceId,
+        }, "Inbound card action");
+        fanOutMessage(traceId, normalized);
+    }
+    function processEvent(activity) {
+        // Reactions arrive as messageReaction activities on the same webhook; route
+        // them to the reaction fanout before the message mapper (which skips them).
+        if (activity.type === "messageReaction") {
+            processReaction(activity);
+            return;
+        }
+        // Card-action clicks arrive as invoke activities on the same webhook; route
+        // them to the card-action path before the message mapper (which skips them),
+        // so they traverse the same default-deny gate the message path uses.
+        if (activity.type === "invoke") {
+            processCardAction(activity);
+            return;
+        }
+        const normalized = mapMsTeamsActivityToNormalized(activity);
+        if (!normalized)
+            return;
+        // Sender authorization: drop anyone whose aadObjectId AND conversation id are
+        // both absent from the allowlist before the message reaches the pipeline.
+        if (!isAllowedSender(normalized.senderId, normalized.channelId)) {
+            deps.logger.warn({
+                channelType: "msteams",
+                senderId: normalized.senderId,
+                hint: "Add the aadObjectId or conversation.id to channels.msteams.allowFrom",
+                errorKind: "precondition",
+            }, "Inbound from non-allowlisted sender dropped");
+            return;
+        }
+        _lastMessageAt = now();
+        _lastInboundAt = now();
+        // Capture the routing tuple so a later proactive send can recover it. Key by
+        // the stripped normalized.channelId — the SAME id a proactive send targets —
+        // not the raw conversation.id (which keeps the ;messageid= thread suffix).
+        captureReference(activity, normalized.channelId, normalized.metadata.msteamsThreadId);
+        const traceId = randomUUID();
+        normalized.metadata.traceId = traceId;
+        deps.logger.info({
+            step: "channels-inbound",
+            channelType: "msteams",
+            messageId: normalized.id,
+            chatId: normalized.channelId,
+            traceId,
+        }, "Inbound message");
+        fanOutMessage(traceId, normalized);
+    }
+    /**
+     * Health-state update for any outbound Connector result (the connector/helper
+     * logs the failure branch). Generic over the ok value so the send path (the new
+     * activity id) and the edit/delete path (void) share one health fold.
+     */
+    function recordActivity(result) {
+        if (result.ok) {
+            _lastMessageAt = now();
+            _lastError = undefined;
+        }
+        else {
+            _lastError = result.error.message;
+        }
+        return result;
+    }
+    /**
+     * A send (text or attachment) whose serviceUrl could not be resolved: record +
+     * WARN + err. Shared by sendMessage and sendAttachment so the "no usable service
+     * url" branch is emitted in exactly one place.
+     */
+    function sendContextError(error) {
+        _lastError = error.message;
+        deps.logger.warn({
+            channelType: "msteams",
+            hint: "Pass serviceUrl in extra, or capture an inbound so a proactive send can recover its routing tuple",
+            errorKind: "precondition",
+        }, "Connector send blocked: no usable service url");
+        return err(error);
+    }
+    /** A proactive edit/delete that could not recover a serviceUrl: WARN + record + err. */
+    function mutationContextError(error, op) {
+        _lastError = error.message;
+        deps.logger.warn({
+            channelType: "msteams",
+            op,
+            hint: "Pass serviceUrl in extra, or capture an inbound so the edit/delete can recover its routing tuple",
+            errorKind: "precondition",
+        }, "Connector activity mutation blocked: no usable service url");
+        return err(error);
+    }
+    const adapter = {
+        get channelId() {
+            return _channelId;
+        },
+        get channelType() {
+            return "msteams";
+        },
+        async start() {
+            // Route-driven: the gateway mounts the inbound route externally. The only
+            // start-time work is a credential pre-flight; no connection is opened. The
+            // required per-mode credential is authMode-branched — appId + tenantId are
+            // always required, plus appPassword (secret) / certPath (certificate) /
+            // managedIdentityClientId (managedIdentity). A cert/MI config carries no
+            // appPassword, so gating on it would silently refuse to start.
+            const perModeCredential = authMode === "certificate"
+                ? deps.certPath
+                : authMode === "managedIdentity"
+                    ? deps.managedIdentityClientId
+                    : deps.appPassword;
+            if (!deps.appId.trim() ||
+                !deps.tenantId.trim() ||
+                !(perModeCredential ?? "").trim()) {
+                const credErr = new Error("Teams app credentials (appId, tenantId, and the authMode credential) must not be empty");
+                const credHint = authMode === "certificate"
+                    ? "Set msteams.certPath (certificate mode) and msteams.appId/tenantId"
+                    : authMode === "managedIdentity"
+                        ? "Set msteams.managedIdentityClientId (managed-identity mode) and msteams.appId/tenantId"
+                        : "Set MSTEAMS_APP_PASSWORD (secret mode) and msteams.appId/tenantId";
+                deps.logger.error({
+                    channelType: "msteams",
+                    err: credErr,
+                    hint: credHint,
+                    errorKind: "auth",
+                }, "Adapter start failed");
+                return err(credErr);
+            }
+            _connected = true;
+            _startedAt = now();
+            deps.logger.info({ channelType: "msteams", mode: "webhook" }, "Adapter started");
+            return ok(undefined);
+        },
+        async stop() {
+            // No persistent connection to tear down; cancel any running typing keepalive.
+            connector.stopTyping();
+            _connected = false;
+            deps.logger.info({ channelType: "msteams" }, "Adapter stopped");
+            return ok(undefined);
+        },
+        async sendMessage(conversationId, text, options) {
+            // Reply → the caller's serviceUrl; proactive (none) → the stored reference.
+            // The id/serviceUrl safety gates + token mint + POST + classification live in
+            // the shared connector helper; this method only builds the body + routes it.
+            const ctx = await resolveConnectorServiceContext(conversationId, options);
+            if (!ctx.ok)
+                return sendContextError(ctx.error);
+            const replyToId = resolveReplyToId(options, ctx.value.threadId);
+            const activityBody = buildTextActivityBody(text, replyToId, options);
+            // Send via the bounded retry executor. A reply rides the caller's
+            // serviceUrl; a proactive send re-derived it from the conversation store
+            // above — both already passed the one host-safety gate before the token
+            // mint, so there is a single resolved serviceUrl to POST to.
+            return recordActivity(await postConnectorActivityWithRetry({
+                serviceUrl: ctx.value.serviceUrl,
+                conversationId,
+                activityBody,
+                tokens,
+                fetchImpl: deps.fetchImpl,
+                logger: deps.logger,
+                now,
+                cloud,
+            }, { timer: deps.timer }));
+        },
+        async sendAttachment(conversationId, attachment, options) {
+            // Reuses the sendMessage scaffolding verbatim (routing context → id/serviceUrl
+            // safety → token → POST via postConnectorActivity); only the activity body
+            // differs. Reply → the caller's serviceUrl; proactive (none) → the store.
+            const ctx = await resolveConnectorServiceContext(conversationId, options);
+            if (!ctx.ok)
+                return sendContextError(ctx.error);
+            const replyToId = resolveReplyToId(options, ctx.value.threadId);
+            // Teams inline attachment support is IMAGES ONLY. Bot Framework reliably
+            // renders an inline `data:` URI only for images; a file/video/audio inline
+            // data: URI does not render, and for a multi-MB video base64-inlining reads
+            // the whole file into memory and inflates it +33% past BF's inline limit (a
+            // memory spike + a guaranteed rejection). A non-image attachment is therefore
+            // delivered BY REFERENCE as a plain text message — the bytes are NOT read —
+            // preserving the graceful text delivery the daemon callers had before Teams
+            // implemented sendAttachment (proper file/video delivery is the deferred
+            // FileConsent/SharePoint flow).
+            if (attachment.type !== "image") {
+                const referenceBody = buildAttachmentReferenceBody(attachment, replyToId);
+                deps.logger.debug({
+                    channelType: "msteams",
+                    attachmentType: attachment.type,
+                    hint: "Non-image attachment delivered by reference; Bot Framework renders inline data: URIs for images only",
+                }, "Connector attachment delivered by reference (non-image)");
+                return recordActivity(await postConnectorActivityWithRetry({
+                    serviceUrl: ctx.value.serviceUrl,
+                    conversationId,
+                    activityBody: referenceBody,
+                    tokens,
+                    fetchImpl: deps.fetchImpl,
+                    logger: deps.logger,
+                    now,
+                    cloud,
+                }, { timer: deps.timer }));
+            }
+            // Read the bytes the shared outbound handler already wrote to a safePath temp
+            // file; Teams has no separate upload step, so the image inlines as a data: URI
+            // on the activity. Neither the token nor the data URI is ever logged (T-5).
+            const read = await fromPromise((deps.readFileImpl ?? defaultReadFile)(attachment.url));
+            if (!read.ok) {
+                _lastError = read.error.message;
+                deps.logger.warn({
+                    channelType: "msteams",
+                    hint: "Verify the outbound attachment temp file exists and is readable",
+                    errorKind: "resource",
+                }, "Connector attachment send blocked: could not read the attachment bytes");
+                return err(read.error);
+            }
+            const activityBody = buildImageActivityBody(read.value, attachment, replyToId);
+            return recordActivity(await postConnectorActivityWithRetry({
+                serviceUrl: ctx.value.serviceUrl,
+                conversationId,
+                activityBody,
+                tokens,
+                fetchImpl: deps.fetchImpl,
+                logger: deps.logger,
+                now,
+                cloud,
+            }, { timer: deps.timer }));
+        },
+        /** Expose the cached Connector bearer for the media resolver (delegating getter). */
+        getConnectorToken: () => tokens.getToken(),
+        async editMessage(channelId, messageId, text, options) {
+            // Reply → the caller's serviceUrl; an in-place edit with none recovers the
+            // stored reference (the edit-in-place renderer supplies no serviceUrl).
+            const ctx = await resolveConnectorServiceContext(channelId, options);
+            if (!ctx.ok)
+                return mutationContextError(ctx.error, "edit");
+            return recordActivity(await connector.editActivity(ctx.value.serviceUrl, channelId, messageId, text));
+        },
+        async deleteMessage(channelId, messageId) {
+            // deleteMessage carries no options, so it always recovers the serviceUrl the
+            // inbound captured — exactly how the edit-in-place renderer calls it.
+            const ctx = await resolveConnectorServiceContext(channelId);
+            if (!ctx.ok)
+                return mutationContextError(ctx.error, "delete");
+            return recordActivity(await connector.deleteActivity(ctx.value.serviceUrl, channelId, messageId));
+        },
+        async platformAction(action, params) {
+            if (action === "sendTyping") {
+                // Suppressed during streaming (the streamed text is itself the activity):
+                // cancel any running keepalive and do not start a new one.
+                if (params.streaming === true) {
+                    connector.stopTyping();
+                    return ok({ typing: false });
+                }
+                // No timer injected → the keepalive degrades to a no-op.
+                if (deps.timer === undefined)
+                    return ok({ typing: false });
+                const conversationId = typeof params.chatId === "string"
+                    ? params.chatId
+                    : typeof params.channelId === "string"
+                        ? params.channelId
+                        : undefined;
+                if (conversationId === undefined || !isSafeConversationId(conversationId)) {
+                    return ok({ typing: false });
+                }
+                // Reply-context typing rides the supplied serviceUrl; mid-turn typing with
+                // none recovers it from the store (the orchestrator passes only chatId).
+                const explicitServiceUrl = resolveTypingServiceUrl(params);
+                const ctx = await resolveConnectorServiceContext(conversationId, explicitServiceUrl !== undefined
+                    ? { extra: { serviceUrl: explicitServiceUrl } }
+                    : undefined);
+                if (!ctx.ok || !isSafeServiceUrl(ctx.value.serviceUrl, cloud)) {
+                    return ok({ typing: false });
+                }
+                connector.startTyping(conversationId, ctx.value.serviceUrl);
+                return ok({ typing: true });
+            }
+            if (action === "stopTyping") {
+                connector.stopTyping();
+                return ok({ typing: false });
+            }
+            const unsupportedErr = new Error(`Unsupported action: ${action} on msteams`);
+            deps.logger.warn({
+                channelType: "msteams",
+                err: unsupportedErr,
+                hint: `Action '${action}' is not supported by the Microsoft Teams adapter`,
+                errorKind: "validation",
+            }, "Unsupported platform action");
+            return err(unsupportedErr);
+        },
+        onMessage(handler) {
+            handlers.push(handler);
+        },
+        onReaction(handler) {
+            reactionHandlers.push(handler);
+        },
+        getStatus() {
+            return {
+                connected: _connected,
+                channelId: _channelId,
+                channelType: "msteams",
+                uptime: _connected && _startedAt !== undefined ? now() - _startedAt : undefined,
+                lastMessageAt: _lastMessageAt,
+                lastInboundAt: _lastInboundAt,
+                error: _lastError,
+                connectionMode: "webhook",
+            };
+        },
+        async reconcileSend(_query) {
+            // The Bot Connector REST API exposes no history read, so a crash-
+            // interrupted send can never be *proven* to have landed from here —
+            // proving delivery would need Microsoft Graph (ChannelMessage.Read,
+            // deferred). unresolved is the only honest verdict: the recovery engine
+            // parks it (never a replay → never a double-send), and the exactly-once
+            // guarantee is the outward-send ledger's write-ahead dedup, not this
+            // oracle. Never claim a definitive absence the platform cannot prove.
+            deps.logger.debug({
+                channelType: "msteams",
+                hint: "Bot Connector exposes no history read; proving a send needs Graph ChannelMessage.Read (deferred)",
+            }, "reconcileSend unresolved");
+            return ok({ kind: "unresolved" });
+        },
+        handleWebhookEvents(activities) {
+            for (const activity of activities) {
+                try {
+                    processEvent(activity);
+                }
+                catch (eventErr) {
+                    deps.logger.error({
+                        err: eventErr,
+                        hint: "Check the msteams webhook event handler for unhandled errors",
+                        errorKind: "internal",
+                    }, "msteams: failed to process activity");
+                }
+            }
+        },
+    };
+    return adapter;
+}