comisai 1.0.44 → 1.0.46

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

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams card-action normalizer.
+ *
+ * Turns a Bot Framework "adaptiveCard/action" invoke into a button-callback
+ * NormalizedMessage the inbound approval path already understands — or drops it
+ * (returning the reason) when the activity is not a well-formed, rendered card
+ * action, so the adapter can make the security-relevant rejects observable.
+ *
+ * Two trust decisions live here, and only these two:
+ *
+ *  - the clicker identity is sourced ONLY from the verified activity
+ *    (`from.aadObjectId`, established when the ingress validated the Bot
+ *    Framework JWT) — never from the client-controllable `value.action.data`; and
+ *  - the incoming `verb` must be one this bot actually renders
+ *    (`RENDERED_VERBS`) — an unknown verb never becomes a message.
+ *
+ * What this module deliberately does NOT do: it never authorizes the clicker
+ * (default-deny is the existing allowFrom gate on the verified senderId) and
+ * never verifies the callback signature (the downstream router's constant-time
+ * HMAC / session / expiry / replay checks own that). The signed `data.cb` is
+ * passed through opaquely as `metadata.callbackData`.
+ *
+ * @module
+ */
+import { systemNowMs } from "@comis/core";
+import { randomUUID } from "node:crypto";
+import { stripMessageIdSuffix } from "./message-mapper.js";
+/** The invoke `name` a card-action click carries. */
+const CARD_ACTION_INVOKE_NAME = "adaptiveCard/action";
+/**
+ * The verb the approval card renders on its buttons. Shared by the renderer
+ * that stamps it onto the card and the validator here, so the two never drift.
+ */
+export const MSTEAMS_APPROVAL_VERB = "comis.approval.resolve";
+/**
+ * The CLOSED set of verbs this bot actually renders onto cards. A card-action
+ * invoke carrying any other verb is dropped before it becomes a message — a
+ * click cannot invoke a method that was never rendered.
+ */
+export const RENDERED_VERBS = [MSTEAMS_APPROVAL_VERB];
+/**
+ * Normalize a Bot Framework card-action invoke into a button-callback message.
+ *
+ * Returns `{ message }` on success, or `{ message: null, reason }` when the
+ * activity is not an adaptiveCard/action invoke (`ignored`), the verb is not in
+ * {@link RENDERED_VERBS} (`unrendered-verb`), the signed callback is missing
+ * (`missing-callback`), or `from.aadObjectId` is absent (`missing-clicker`).
+ * The reason lets the caller log the security-relevant rejects per §2.7 while
+ * this function stays a pure mapper.
+ *
+ * @param activity - A Bot Framework invoke activity (already JWT-validated)
+ * @returns A button-callback message, or a drop carrying its reason
+ */
+export function normalizeCardAction(activity) {
+    if (activity.type !== "invoke" || activity.name !== CARD_ACTION_INVOKE_NAME) {
+        return { message: null, reason: "ignored" };
+    }
+    // The verb must be one the bot rendered; an unknown or absent verb never
+    // becomes a message.
+    const verb = activity.value?.action?.verb;
+    if (verb === undefined || !RENDERED_VERBS.includes(verb)) {
+        return { message: null, reason: "unrendered-verb" };
+    }
+    // The signed wire string, passed through opaquely — verified downstream.
+    const cb = activity.value?.action?.data?.cb;
+    if (typeof cb !== "string" || cb.length === 0) {
+        return { message: null, reason: "missing-callback" };
+    }
+    // The clicker id is the verified directory id off the validated activity —
+    // never anything under `value.action.data` (client-controllable).
+    const senderId = activity.from?.aadObjectId;
+    if (senderId === undefined || senderId.length === 0) {
+        return { message: null, reason: "missing-clicker" };
+    }
+    return {
+        message: {
+            id: randomUUID(),
+            channelType: "msteams",
+            channelId: stripMessageIdSuffix(activity.conversation.id),
+            senderId,
+            text: cb,
+            timestamp: systemNowMs(),
+            attachments: [],
+            metadata: {
+                isButtonCallback: true,
+                callbackData: cb,
+                messageId: activity.id,
+            },
+        },
+    };
+}

package/node_modules/@comis/channels/dist/msteams/msteams-activity.d.ts

@@ -0,0 +1,39 @@
+import type { ChannelActivityRenderer, ActivityRenderError, ChannelPort, TimerPort, ClockPort, ActivityStatusMarkers } from "@comis/core";
+import type { ActivityRenderActions } from "../shared/strategies/actions.js";
+import { type SignCallbackData } from "../shared/strategies/approval-render.js";
+/**
+ * Classify a raw Connector failure into the closed {@link ActivityRenderError}
+ * union by its STRUCTURAL numeric `status`. Reads `status`/`retryAfter` off the
+ * error itself and, when the adapter wrapped the failure in
+ * `new Error(msg, { cause })`, off `error.cause`. The status is consulted ONLY
+ * to pick the variant — never rendered or logged, and no token/body is copied in.
+ */
+export declare function classifyMSTeamsError(e: unknown): ActivityRenderError;
+/** Optional timer used by the local 429 retry buffer. Omit it and a 429 simply propagates. */
+export interface MSTeamsRenderActionsDeps {
+    timer?: TimerPort;
+}
+/**
+ * Build the {@link ActivityRenderActions} for a Teams conversation. `edit`/`delete`
+ * guard the optional port methods and classify Connector errors structurally;
+ * `delete` is the delete-on-success op. When a `timer` is supplied, a
+ * `rate_limited` edit schedules a single bounded retry of the LATEST text.
+ */
+export declare function makeMSTeamsRenderActions(adapter: ChannelPort, channelId: string, deps?: MSTeamsRenderActionsDeps): ActivityRenderActions;
+/**
+ * Create the Teams EditPlace activity renderer — wires the
+ * {@link createEditPlaceRenderer} with the per-conversation render-actions
+ * adapter. The daemon composition root constructs this with its runtime
+ * `TimerPort` / `ClockPort` and the conversation id.
+ *
+ * `signCallbackData` is the secret-bound signer injected at the composition root:
+ * the renderer CONSUMES it to build the signed approval button rows and never
+ * imports the orchestrator package. When omitted, an approval frame degrades to
+ * a button-less text prompt.
+ */
+export declare function createMSTeamsActivityRenderer(adapter: ChannelPort, channelId: string, deps: {
+    timer: TimerPort;
+    clock: ClockPort;
+    signCallbackData?: SignCallbackData;
+    markers?: ActivityStatusMarkers;
+}): ChannelActivityRenderer;

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

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Microsoft Teams EditPlace activity renderer.
+ *
+ * Structurally mirrors the Slack renderer — only the error classifier differs.
+ * Three parts:
+ *
+ *   1. `classifyMSTeamsError` — the per-platform net-new logic. It maps a
+ *      Bot Framework Connector failure onto the CLOSED `ActivityRenderError`
+ *      union — never the send-path observability error taxonomy, which reports
+ *      `errorKind` / `retryable` for logging rather than a render variant. It
+ *      reads the STRUCTURAL numeric `status` (and an
+ *      optional `retryAfter` in seconds) off the error itself and — when the
+ *      adapter wrapped the failure in `new Error(msg, { cause })` — off
+ *      `error.cause`. The Connector edit/delete failure branch attaches
+ *      `{ status, retryAfter? }` to the returned Error so this classifier can
+ *      pick the variant and the retry buffer can back off; the status is
+ *      consulted ONLY to choose the variant — never rendered or logged as
+ *      activity text, and no token/header/body is copied into the payload.
+ *      Mapping: `429` → rate_limited; `401`/`403` → permission; `404` (activity
+ *      gone) → not_supported:edit (drop edits); anything else → internal.
+ *
+ *   2. `makeMSTeamsRenderActions` — the `ActivityRenderActions` adapter. `send`
+ *      posts the placeholder and forwards the signed approval buttons when an
+ *      approval frame produced them (a DISPLAY affordance — the
+ *      InteractiveCallbackRouter owns resolution).
+ *      `edit`/`delete` GUARD the optional `ChannelPort` methods (early
+ *      `not_supported` — never a non-null `!` cluster) and map every `.error`
+ *      through `classifyMSTeamsError`. `delete` is the required delete-on-success
+ *      op. All paths return `Result`; nothing throws across the boundary.
+ *
+ *   3. `createMSTeamsActivityRenderer` — wires the shared
+ *      `createEditPlaceRenderer` (the debounce / edit / delete-after-delivery
+ *      state machine). It does NOT re-implement any rendering logic.
+ *
+ * 429 backoff (mirrors the Slack renderer): the channels package depends on
+ * `core` + `shared` only — no observability substrate — so the buffer is a LOCAL
+ * fixed-cap latest-text slot with a `retryAfterMs`-gated retry through the
+ * injected `TimerPort` (the handle is `unref`'d and `cancel()`-able — never a raw
+ * timer clear). It coalesces to the latest text and never grows unbounded; a
+ * `not_supported` (activity-gone) edit drops all further edits.
+ */
+import { ok, err } from "@comis/shared";
+import { createEditPlaceRenderer } from "../shared/strategies/edit-place.js";
+import { buildApprovalButtons, } from "../shared/strategies/approval-render.js";
+/**
+ * Classify a raw Connector failure into the closed {@link ActivityRenderError}
+ * union by its STRUCTURAL numeric `status`. Reads `status`/`retryAfter` off the
+ * error itself and, when the adapter wrapped the failure in
+ * `new Error(msg, { cause })`, off `error.cause`. The status is consulted ONLY
+ * to pick the variant — never rendered or logged, and no token/body is copied in.
+ */
+export function classifyMSTeamsError(e) {
+    const direct = (e ?? {});
+    // Prefer the status attached directly; when absent, unwrap the cause the
+    // adapter attached (`new Error(msg, { cause })`).
+    const te = direct.status === undefined && direct.cause != null
+        ? (direct.cause ?? direct)
+        : direct;
+    const status = te.status;
+    if (status === 429) {
+        return { kind: "rate_limited", retryAfterMs: (te.retryAfter ?? 1) * 1000 };
+    }
+    if (status === 401 || status === 403) {
+        // Content-free: only the numeric status, never a token/header/body.
+        return { kind: "permission", detail: `connector status ${status}` };
+    }
+    if (status === 404) {
+        // The activity is gone — stop editing entirely.
+        return { kind: "not_supported", capability: "edit" };
+    }
+    return { kind: "internal", cause: e };
+}
+/** Latest-text retry cap — a 429 storm coalesces to the latest text; we never replay a backlog. */
+const MAX_RETRY_ATTEMPTS = 4;
+/**
+ * Build the {@link ActivityRenderActions} for a Teams conversation. `edit`/`delete`
+ * guard the optional port methods and classify Connector errors structurally;
+ * `delete` is the delete-on-success op. When a `timer` is supplied, a
+ * `rate_limited` edit schedules a single bounded retry of the LATEST text.
+ */
+export function makeMSTeamsRenderActions(adapter, channelId, deps = {}) {
+    const { timer } = deps;
+    // --- Local bounded 429 buffer (single latest-text slot + single retry) ---
+    let pendingText;
+    let pendingId;
+    let retryHandle;
+    let retryAttempts = 0;
+    let editsDropped = false;
+    function cancelRetry() {
+        if (retryHandle && !retryHandle.cancelled)
+            retryHandle.cancel();
+        retryHandle = undefined;
+    }
+    async function attemptEdit(id, text) {
+        if (editsDropped)
+            return err({ kind: "not_supported", capability: "edit" });
+        if (!adapter.editMessage)
+            return err({ kind: "not_supported", capability: "edit" });
+        const r = await adapter.editMessage(channelId, id, text);
+        if (r.ok) {
+            cancelRetry();
+            pendingText = undefined;
+            retryAttempts = 0;
+            return ok(undefined);
+        }
+        const classified = classifyMSTeamsError(r.error);
+        if (classified.kind === "not_supported") {
+            // Activity gone → stop editing entirely.
+            editsDropped = true;
+            cancelRetry();
+            pendingText = undefined;
+            return err(classified);
+        }
+        if (classified.kind === "rate_limited" && timer !== undefined) {
+            pendingText = text;
+            pendingId = id;
+            scheduleRetry(timer, classified.retryAfterMs);
+        }
+        return err(classified);
+    }
+    function scheduleRetry(t, retryAfterMs) {
+        if (retryAttempts >= MAX_RETRY_ATTEMPTS) {
+            cancelRetry();
+            pendingText = undefined;
+            return;
+        }
+        cancelRetry();
+        retryAttempts += 1;
+        retryHandle = t.setTimeout(() => {
+            const text = pendingText;
+            const id = pendingId;
+            retryHandle = undefined;
+            if (text === undefined || id === undefined || editsDropped)
+                return;
+            void attemptEdit(id, text);
+        }, retryAfterMs);
+        retryHandle.unref();
+    }
+    return {
+        async send(text, opts) {
+            // The placeholder carries the signed approval buttons when an approval
+            // frame produced them (each button's callback_data is the wire string
+            // v1.<choice>.<shortId>.<hmac>); a non-approval / absent-signer frame
+            // forwards none, leaving a bare text activity. Buttons are a DISPLAY
+            // affordance — the InteractiveCallbackRouter owns resolution.
+            const r = await adapter.sendMessage(channelId, text, opts?.buttons !== undefined ? { buttons: opts.buttons } : undefined);
+            return r.ok ? ok(r.value) : err(classifyMSTeamsError(r.error));
+        },
+        async edit(id, text) {
+            return attemptEdit(id, text);
+        },
+        async delete(id) {
+            cancelRetry();
+            pendingText = undefined;
+            // The required delete-on-success op (gated on deliveredAtMs by the
+            // EditPlace finalize).
+            if (!adapter.deleteMessage)
+                return err({ kind: "not_supported", capability: "delete" });
+            const r = await adapter.deleteMessage(channelId, id);
+            return r.ok ? ok(undefined) : err(classifyMSTeamsError(r.error));
+        },
+    };
+}
+/**
+ * Create the Teams EditPlace activity renderer — wires the
+ * {@link createEditPlaceRenderer} with the per-conversation render-actions
+ * adapter. The daemon composition root constructs this with its runtime
+ * `TimerPort` / `ClockPort` and the conversation id.
+ *
+ * `signCallbackData` is the secret-bound signer injected at the composition root:
+ * the renderer CONSUMES it to build the signed approval button rows and never
+ * imports the orchestrator package. When omitted, an approval frame degrades to
+ * a button-less text prompt.
+ */
+export function createMSTeamsActivityRenderer(adapter, channelId, deps) {
+    const { signCallbackData } = deps;
+    return createEditPlaceRenderer({
+        actions: makeMSTeamsRenderActions(adapter, channelId, { timer: deps.timer }),
+        timer: deps.timer,
+        clock: deps.clock,
+        markers: deps.markers,
+        // Approval frame → signed native button rows. The signer is the only path to
+        // the callback wire; without it, no buttons are painted.
+        buildButtons: signCallbackData === undefined
+            ? undefined
+            : (events) => events.flatMap((event) => buildApprovalButtons(event, signCallbackData)),
+    });
+}

package/node_modules/@comis/channels/dist/msteams/msteams-adapter-outbound.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure outbound helpers for the Microsoft Teams adapter.
+ *
+ * Each function here reads only its arguments — no closure over adapter state,
+ * the injected clock, or `deps` — so they live in this sibling module and are
+ * unit-tested in isolation, keeping the adapter module within its size budget.
+ *
+ * @module
+ */
+import type { AttachmentPayload, SendMessageOptions } from "@comis/core";
+/** Ensure a service base URL ends in a single trailing slash for path composition. */
+export declare function withTrailingSlash(raw: string): string;
+/**
+ * Build the outbound text-activity body: rewrite id-shape-valid `@[Name](id)`
+ * markup into `<at>…</at>` tags + paired mention entities (text with no valid
+ * mention markup is left byte-identical), thread under `replyToId` when present,
+ * and attach ONE Adaptive Card only when buttons/cards are present (so a plain
+ * text send stays the bare `{ type, text }` shape — no attachments key).
+ */
+export declare function buildTextActivityBody(text: string, replyToId: string | undefined, options?: SendMessageOptions): Record<string, unknown>;
+/**
+ * Build the by-reference text body for a NON-image attachment. Bot Framework
+ * renders an inline `data:` URI only for images, so a file/video/audio is
+ * delivered as a plain text message naming the caption + filename — the bytes are
+ * never read (avoids the multi-MB inline blowup). Threads under `replyToId`.
+ */
+export declare function buildAttachmentReferenceBody(attachment: AttachmentPayload, replyToId: string | undefined): Record<string, unknown>;
+/**
+ * Build the image-attachment body: inline the bytes as a `data:` URI (Teams has
+ * no separate upload step), carrying the caption as text and the filename as the
+ * attachment name when present. Threads under `replyToId`. Neither the bytes nor
+ * the data URI are ever logged (T-5) — they live only on the returned body.
+ */
+export declare function buildImageActivityBody(bytes: Buffer, attachment: AttachmentPayload, replyToId: string | undefined): Record<string, unknown>;
+/**
+ * Resolve the reply target. A Teams direct message is always sent top-level, so
+ * a `dm` chatType forces no replyToId even when the caller supplies one (the
+ * delivery layer stamps a reply target on every inbound). Channel and group
+ * replies thread under the parent via replyToId; a proactive send with no
+ * explicit reply target threads under the stored thread root (channel/group
+ * references carry one, a 1:1 does not — so a DM stays top-level).
+ */
+export declare function resolveReplyToId(options?: SendMessageOptions, fallbackThreadId?: string): string | undefined;
+/** Extract an explicit typing serviceUrl from the action params (direct or under extra). */
+export declare function resolveTypingServiceUrl(params: Record<string, unknown>): string | undefined;

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

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pure outbound helpers for the Microsoft Teams adapter.
+ *
+ * Each function here reads only its arguments — no closure over adapter state,
+ * the injected clock, or `deps` — so they live in this sibling module and are
+ * unit-tested in isolation, keeping the adapter module within its size budget.
+ *
+ * @module
+ */
+import { buildMentionEntities } from "./mentions.js";
+import { renderMSTeamsCardAttachment } from "./msteams-rich-renderer.js";
+/** Ensure a service base URL ends in a single trailing slash for path composition. */
+export function withTrailingSlash(raw) {
+    return raw.endsWith("/") ? raw : `${raw}/`;
+}
+/**
+ * Build the outbound text-activity body: rewrite id-shape-valid `@[Name](id)`
+ * markup into `<at>…</at>` tags + paired mention entities (text with no valid
+ * mention markup is left byte-identical), thread under `replyToId` when present,
+ * and attach ONE Adaptive Card only when buttons/cards are present (so a plain
+ * text send stays the bare `{ type, text }` shape — no attachments key).
+ */
+export function buildTextActivityBody(text, replyToId, options) {
+    const built = buildMentionEntities(text);
+    const body = { type: "message", text: built.text };
+    if (built.entities.length > 0)
+        body.entities = built.entities;
+    if (replyToId !== undefined)
+        body.replyToId = replyToId;
+    const hasButtons = (options?.buttons?.length ?? 0) > 0;
+    const hasCards = (options?.cards?.length ?? 0) > 0;
+    if (hasButtons || hasCards) {
+        body.attachments = [
+            renderMSTeamsCardAttachment(options?.cards ?? [], options?.buttons ?? []),
+        ];
+    }
+    return body;
+}
+/**
+ * Build the by-reference text body for a NON-image attachment. Bot Framework
+ * renders an inline `data:` URI only for images, so a file/video/audio is
+ * delivered as a plain text message naming the caption + filename — the bytes are
+ * never read (avoids the multi-MB inline blowup). Threads under `replyToId`.
+ */
+export function buildAttachmentReferenceBody(attachment, replyToId) {
+    const label = attachment.fileName !== undefined && attachment.fileName.length > 0
+        ? attachment.fileName
+        : "a file";
+    const referenceText = (attachment.caption !== undefined && attachment.caption.length > 0
+        ? `${attachment.caption}\n`
+        : "") +
+        `[${label}] — Teams inline delivery currently supports images only; this attachment is available on the server.`;
+    const body = { type: "message", text: referenceText };
+    if (replyToId !== undefined)
+        body.replyToId = replyToId;
+    return body;
+}
+/**
+ * Build the image-attachment body: inline the bytes as a `data:` URI (Teams has
+ * no separate upload step), carrying the caption as text and the filename as the
+ * attachment name when present. Threads under `replyToId`. Neither the bytes nor
+ * the data URI are ever logged (T-5) — they live only on the returned body.
+ */
+export function buildImageActivityBody(bytes, attachment, replyToId) {
+    const mime = attachment.mimeType ?? "image/png";
+    const body = {
+        type: "message",
+        ...(attachment.caption ? { text: attachment.caption } : {}),
+        attachments: [
+            {
+                contentType: mime,
+                contentUrl: `data:${mime};base64,${bytes.toString("base64")}`,
+                ...(attachment.fileName ? { name: attachment.fileName } : {}),
+            },
+        ],
+    };
+    if (replyToId !== undefined)
+        body.replyToId = replyToId;
+    return body;
+}
+/**
+ * Resolve the reply target. A Teams direct message is always sent top-level, so
+ * a `dm` chatType forces no replyToId even when the caller supplies one (the
+ * delivery layer stamps a reply target on every inbound). Channel and group
+ * replies thread under the parent via replyToId; a proactive send with no
+ * explicit reply target threads under the stored thread root (channel/group
+ * references carry one, a 1:1 does not — so a DM stays top-level).
+ */
+export function resolveReplyToId(options, fallbackThreadId) {
+    // Honor "DM → top-level": never thread a direct message, whatever was passed.
+    if (options?.extra?.chatType === "dm")
+        return undefined;
+    if (typeof options?.replyTo === "string" && options.replyTo.length > 0) {
+        return options.replyTo;
+    }
+    const fromExtra = options?.extra?.replyToId;
+    if (typeof fromExtra === "string" && fromExtra.length > 0)
+        return fromExtra;
+    return typeof fallbackThreadId === "string" && fallbackThreadId.length > 0
+        ? fallbackThreadId
+        : undefined;
+}
+/** Extract an explicit typing serviceUrl from the action params (direct or under extra). */
+export function resolveTypingServiceUrl(params) {
+    const direct = typeof params.serviceUrl === "string" ? params.serviceUrl : undefined;
+    const extra = params.extra;
+    const fromExtra = typeof extra === "object" &&
+        extra !== null &&
+        typeof extra.serviceUrl === "string"
+        ? extra.serviceUrl
+        : undefined;
+    return direct ?? fromExtra;
+}

package/node_modules/@comis/channels/dist/msteams/msteams-adapter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 type { ChannelPort, ComisLogger, EnvPort, MsTeamsConversationStorePort, TimerPort } from "@comis/core";
+import { type Result } from "@comis/shared";
+import { type TeamsActivity } from "./message-mapper.js";
+import { type MsTeamsCloud } from "./msteams-connector.js";
+import { type ConnectorAuthMode } from "./msteams-auth.js";
+/** Dependencies for the Microsoft Teams adapter. */
+export interface MsTeamsAdapterDeps {
+    /** Credential mode for the outbound token: secret (appPassword) / certificate (certPath) / managedIdentity. Absent → secret. */
+    authMode?: ConnectorAuthMode;
+    /** Bot application (client) id. */
+    appId: string;
+    /** Bot application secret — sent only on the token request, never logged. Empty in cert/managed-identity mode. */
+    appPassword: string;
+    /** Single-tenant directory id — required for the client-credentials grant. */
+    tenantId: string;
+    /** Certificate mode: absolute path to a PEM bundling the private key + certificate (never logged). */
+    certPath?: string;
+    /** Managed-identity mode: the user-assigned identity's client id. */
+    managedIdentityClientId?: string;
+    /** Managed-identity App-Service identity endpoint + rotating header accessor (read live per mint). Absent → IMDS, no env. */
+    env?: EnvPort;
+    /** PEM reader for certificate mode (default fs readFile utf8); distinct from readFileImpl (attachment Buffer). Test seam. */
+    certReadFileImpl?: (path: string) => Promise<string>;
+    /** Deployment cloud selecting the exact Connector host set the token may reach; threaded to every serviceUrl callsite. Absent → "public". */
+    cloud?: MsTeamsCloud;
+    /** Sender ids (aadObjectId) and/or conversation ids allowed to reach handlers. */
+    allowFrom: string[];
+    /** "allowlist" (default) drops unknown senders; "open" processes any sender. */
+    allowMode: "allowlist" | "open";
+    /** Logger for the inbound/outbound boundary matrix. */
+    logger: ComisLogger;
+    /** Injected fetch, defaulting to the global; lets a unit test stub the send. */
+    fetchImpl?: typeof fetch;
+    /** Injected attachment-byte reader (default: node:fs/promises readFile); lets a test run sendAttachment disk-free. */
+    readFileImpl?: (path: string) => Promise<Buffer>;
+    /** Injected clock in ms, defaulting to systemNowMs; makes timing deterministic. */
+    now?: () => number;
+    /**
+     * Injected timer for the typing keepalive. OPTIONAL — mirrors the `now`/`fetchImpl`
+     * seams so the composition root stays typecheck-clean before it supplies its runtime
+     * timers; when absent the typing keepalive degrades to a no-op (never a raw setTimeout).
+     */
+    timer?: TimerPort;
+    /**
+     * Persisted conversation-reference store. OPTIONAL — every inbound captures the
+     * routing tuple here, and a proactive send (no caller serviceUrl) recovers it.
+     * When absent, capture is skipped and a proactive send errs (never a wrong-host
+     * default). Injected by the composition root as the core port type.
+     */
+    conversationStore?: MsTeamsConversationStorePort;
+}
+/**
+ * The Teams adapter handle. Extends the base ChannelPort with the route-driven
+ * `handleWebhookEvents` driver the gateway ingress calls; `handleWebhookEvents`
+ * is deliberately NOT on the base ChannelPort (mirrors the LINE handle).
+ */
+export interface MsTeamsAdapterHandle extends ChannelPort {
+    /** Process authenticated inbound Teams activities from the gateway ingress. */
+    handleWebhookEvents(activities: TeamsActivity[]): void;
+    /** The cached Connector bearer, exposed so the media resolver can authenticate a hosted-content fetch. */
+    getConnectorToken(): Promise<Result<string, Error>>;
+}
+/**
+ * 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 declare function createMsTeamsAdapter(deps: MsTeamsAdapterDeps): MsTeamsAdapterHandle;