@dbx-tools/teams 0.3.44 → 0.4.0

package/lib/src/defaults.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Interceptor defaults for the Teams plugin.
+ *
+ * Building a card is a pure transform, but it still runs through
+ * `Plugin.execute()` so it shares the app's telemetry / timeout posture; the
+ * one operation that does I/O is posting a card to a Teams incoming webhook.
+ * The settings are kept here rather than at the call sites so the caching /
+ * retry / timeout posture of each is reviewable in one place.
+ *
+ * @module
+ */
+/**
+ * The `PluginExecuteConfig` slice this package sets. Mirrored structurally
+ * because AppKit's `PluginExecuteConfig` lives behind a subpath its `exports`
+ * map does not publish, so the nominal type cannot be imported. Written as a
+ * type alias rather than an interface so it stays assignable to the nominal
+ * type's index signature.
+ */
+export type TeamsExecuteConfig = {
+    cache?: {
+        enabled?: boolean;
+        ttl?: number;
+        cacheKey?: (string | number | object)[];
+    };
+    retry?: {
+        enabled?: boolean;
+        attempts?: number;
+        initialDelay?: number;
+        maxDelay?: number;
+    };
+    timeout?: number;
+};
+/**
+ * The `PluginExecutionSettings` shape accepted by AppKit's `Plugin.execute()`.
+ * Mirrored structurally for the same reason as {@link TeamsExecuteConfig}.
+ */
+export type TeamsExecutionSettings = {
+    default: TeamsExecuteConfig;
+    user?: TeamsExecuteConfig;
+};
+/** Ceiling on how long a single card build may take. */
+export declare const BUILD_TIMEOUT_MS = 5000;
+/** Ceiling on how long a single webhook POST may take. */
+export declare const POST_TIMEOUT_MS = 15000;
+/** Attempts allowed for a webhook POST, including the first. */
+export declare const POST_ATTEMPTS = 3;
+/** Execution settings for building a card (a pure, in-process transform). */
+export declare const TEAMS_BUILD_SETTINGS: TeamsExecutionSettings;
+/**
+ * Ceiling on one conversation turn. Generous relative to the other two: a turn
+ * spans a full agent call (model latency plus any tool the agent runs), so it is
+ * bounded by the same order of magnitude as a chat request rather than a
+ * transform.
+ */
+export declare const TURN_TIMEOUT_MS = 120000;
+/** Execution settings for one Teams conversation turn (an agent call). */
+export declare const TEAMS_TURN_SETTINGS: TeamsExecutionSettings;
+/** Execution settings for posting a card to a Teams incoming webhook. */
+export declare const TEAMS_POST_SETTINGS: TeamsExecutionSettings;

package/lib/src/defaults.js

@@ -0,0 +1,61 @@
+/**
+ * Interceptor defaults for the Teams plugin.
+ *
+ * Building a card is a pure transform, but it still runs through
+ * `Plugin.execute()` so it shares the app's telemetry / timeout posture; the
+ * one operation that does I/O is posting a card to a Teams incoming webhook.
+ * The settings are kept here rather than at the call sites so the caching /
+ * retry / timeout posture of each is reviewable in one place.
+ *
+ * @module
+ */
+/** Ceiling on how long a single card build may take. */
+export const BUILD_TIMEOUT_MS = 5_000;
+/** Ceiling on how long a single webhook POST may take. */
+export const POST_TIMEOUT_MS = 15_000;
+/** Attempts allowed for a webhook POST, including the first. */
+export const POST_ATTEMPTS = 3;
+/** Execution settings for building a card (a pure, in-process transform). */
+export const TEAMS_BUILD_SETTINGS = {
+    default: {
+        // Cache disabled: the build is cheap and deterministic, so a cache would
+        // add a cross-identity key surface for no measurable saving.
+        cache: { enabled: false },
+        // Retry disabled: the transform performs no I/O, so a failure is
+        // deterministic and a second attempt would fail identically.
+        retry: { enabled: false },
+        timeout: BUILD_TIMEOUT_MS,
+    },
+};
+/**
+ * Ceiling on one conversation turn. Generous relative to the other two: a turn
+ * spans a full agent call (model latency plus any tool the agent runs), so it is
+ * bounded by the same order of magnitude as a chat request rather than a
+ * transform.
+ */
+export const TURN_TIMEOUT_MS = 120_000;
+/** Execution settings for one Teams conversation turn (an agent call). */
+export const TEAMS_TURN_SETTINGS = {
+    default: {
+        // Cache disabled: a turn is conversational and stateful - the same text in
+        // a different conversation must not replay an earlier card.
+        cache: { enabled: false },
+        // Retry disabled: a turn may have run tools with side effects before it
+        // failed, and re-running the model would double them.
+        retry: { enabled: false },
+        timeout: TURN_TIMEOUT_MS,
+    },
+};
+/** Execution settings for posting a card to a Teams incoming webhook. */
+export const TEAMS_POST_SETTINGS = {
+    default: {
+        // Cache disabled: a post is a side effect, not a value. Replaying a cached
+        // result would report a delivery that never happened.
+        cache: { enabled: false },
+        // Retry enabled: a webhook POST is idempotent enough that a transient 5xx
+        // or timeout at the Teams edge is worth one or two more attempts.
+        retry: { enabled: true, attempts: POST_ATTEMPTS },
+        timeout: POST_TIMEOUT_MS,
+    },
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVmYXVsdHMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZGVmYXVsdHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7R0FVRztBQXdCSCx3REFBd0Q7QUFDeEQsTUFBTSxDQUFDLE1BQU0sZ0JBQWdCLEdBQUcsS0FBSyxDQUFDO0FBRXRDLDBEQUEwRDtBQUMxRCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsTUFBTSxDQUFDO0FBRXRDLGdFQUFnRTtBQUNoRSxNQUFNLENBQUMsTUFBTSxhQUFhLEdBQUcsQ0FBQyxDQUFDO0FBRS9CLDZFQUE2RTtBQUM3RSxNQUFNLENBQUMsTUFBTSxvQkFBb0IsR0FBMkI7SUFDMUQsT0FBTyxFQUFFO1FBQ1AseUVBQXlFO1FBQ3pFLDZEQUE2RDtRQUM3RCxLQUFLLEVBQUUsRUFBRSxPQUFPLEVBQUUsS0FBSyxFQUFFO1FBQ3pCLGlFQUFpRTtRQUNqRSw2REFBNkQ7UUFDN0QsS0FBSyxFQUFFLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRTtRQUN6QixPQUFPLEVBQUUsZ0JBQWdCO0tBQzFCO0NBQ0YsQ0FBQztBQUVGOzs7OztHQUtHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sZUFBZSxHQUFHLE9BQU8sQ0FBQztBQUV2QywwRUFBMEU7QUFDMUUsTUFBTSxDQUFDLE1BQU0sbUJBQW1CLEdBQTJCO0lBQ3pELE9BQU8sRUFBRTtRQUNQLDJFQUEyRTtRQUMzRSw0REFBNEQ7UUFDNUQsS0FBSyxFQUFFLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRTtRQUN6Qix3RUFBd0U7UUFDeEUsc0RBQXNEO1FBQ3RELEtBQUssRUFBRSxFQUFFLE9BQU8sRUFBRSxLQUFLLEVBQUU7UUFDekIsT0FBTyxFQUFFLGVBQWU7S0FDekI7Q0FDRixDQUFDO0FBRUYseUVBQXlFO0FBQ3pFLE1BQU0sQ0FBQyxNQUFNLG1CQUFtQixHQUEyQjtJQUN6RCxPQUFPLEVBQUU7UUFDUCwyRUFBMkU7UUFDM0Usc0RBQXNEO1FBQ3RELEtBQUssRUFBRSxFQUFFLE9BQU8sRUFBRSxLQUFLLEVBQUU7UUFDekIsMEVBQTBFO1FBQzFFLGtFQUFrRTtRQUNsRSxLQUFLLEVBQUUsRUFBRSxPQUFPLEVBQUUsSUFBSSxFQUFFLFFBQVEsRUFBRSxhQUFhLEVBQUU7UUFDakQsT0FBTyxFQUFFLGVBQWU7S0FDekI7Q0FDRixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBJbnRlcmNlcHRvciBkZWZhdWx0cyBmb3IgdGhlIFRlYW1zIHBsdWdpbi5cbiAqXG4gKiBCdWlsZGluZyBhIGNhcmQgaXMgYSBwdXJlIHRyYW5zZm9ybSwgYnV0IGl0IHN0aWxsIHJ1bnMgdGhyb3VnaFxuICogYFBsdWdpbi5leGVjdXRlKClgIHNvIGl0IHNoYXJlcyB0aGUgYXBwJ3MgdGVsZW1ldHJ5IC8gdGltZW91dCBwb3N0dXJlOyB0aGVcbiAqIG9uZSBvcGVyYXRpb24gdGhhdCBkb2VzIEkvTyBpcyBwb3N0aW5nIGEgY2FyZCB0byBhIFRlYW1zIGluY29taW5nIHdlYmhvb2suXG4gKiBUaGUgc2V0dGluZ3MgYXJlIGtlcHQgaGVyZSByYXRoZXIgdGhhbiBhdCB0aGUgY2FsbCBzaXRlcyBzbyB0aGUgY2FjaGluZyAvXG4gKiByZXRyeSAvIHRpbWVvdXQgcG9zdHVyZSBvZiBlYWNoIGlzIHJldmlld2FibGUgaW4gb25lIHBsYWNlLlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG4vKipcbiAqIFRoZSBgUGx1Z2luRXhlY3V0ZUNvbmZpZ2Agc2xpY2UgdGhpcyBwYWNrYWdlIHNldHMuIE1pcnJvcmVkIHN0cnVjdHVyYWxseVxuICogYmVjYXVzZSBBcHBLaXQncyBgUGx1Z2luRXhlY3V0ZUNvbmZpZ2AgbGl2ZXMgYmVoaW5kIGEgc3VicGF0aCBpdHMgYGV4cG9ydHNgXG4gKiBtYXAgZG9lcyBub3QgcHVibGlzaCwgc28gdGhlIG5vbWluYWwgdHlwZSBjYW5ub3QgYmUgaW1wb3J0ZWQuIFdyaXR0ZW4gYXMgYVxuICogdHlwZSBhbGlhcyByYXRoZXIgdGhhbiBhbiBpbnRlcmZhY2Ugc28gaXQgc3RheXMgYXNzaWduYWJsZSB0byB0aGUgbm9taW5hbFxuICogdHlwZSdzIGluZGV4IHNpZ25hdHVyZS5cbiAqL1xuZXhwb3J0IHR5cGUgVGVhbXNFeGVjdXRlQ29uZmlnID0ge1xuICBjYWNoZT86IHsgZW5hYmxlZD86IGJvb2xlYW47IHR0bD86IG51bWJlcjsgY2FjaGVLZXk/OiAoc3RyaW5nIHwgbnVtYmVyIHwgb2JqZWN0KVtdIH07XG4gIHJldHJ5PzogeyBlbmFibGVkPzogYm9vbGVhbjsgYXR0ZW1wdHM/OiBudW1iZXI7IGluaXRpYWxEZWxheT86IG51bWJlcjsgbWF4RGVsYXk/OiBudW1iZXIgfTtcbiAgdGltZW91dD86IG51bWJlcjtcbn07XG5cbi8qKlxuICogVGhlIGBQbHVnaW5FeGVjdXRpb25TZXR0aW5nc2Agc2hhcGUgYWNjZXB0ZWQgYnkgQXBwS2l0J3MgYFBsdWdpbi5leGVjdXRlKClgLlxuICogTWlycm9yZWQgc3RydWN0dXJhbGx5IGZvciB0aGUgc2FtZSByZWFzb24gYXMge0BsaW5rIFRlYW1zRXhlY3V0ZUNvbmZpZ30uXG4gKi9cbmV4cG9ydCB0eXBlIFRlYW1zRXhlY3V0aW9uU2V0dGluZ3MgPSB7XG4gIGRlZmF1bHQ6IFRlYW1zRXhlY3V0ZUNvbmZpZztcbiAgdXNlcj86IFRlYW1zRXhlY3V0ZUNvbmZpZztcbn07XG5cbi8qKiBDZWlsaW5nIG9uIGhvdyBsb25nIGEgc2luZ2xlIGNhcmQgYnVpbGQgbWF5IHRha2UuICovXG5leHBvcnQgY29uc3QgQlVJTERfVElNRU9VVF9NUyA9IDVfMDAwO1xuXG4vKiogQ2VpbGluZyBvbiBob3cgbG9uZyBhIHNpbmdsZSB3ZWJob29rIFBPU1QgbWF5IHRha2UuICovXG5leHBvcnQgY29uc3QgUE9TVF9USU1FT1VUX01TID0gMTVfMDAwO1xuXG4vKiogQXR0ZW1wdHMgYWxsb3dlZCBmb3IgYSB3ZWJob29rIFBPU1QsIGluY2x1ZGluZyB0aGUgZmlyc3QuICovXG5leHBvcnQgY29uc3QgUE9TVF9BVFRFTVBUUyA9IDM7XG5cbi8qKiBFeGVjdXRpb24gc2V0dGluZ3MgZm9yIGJ1aWxkaW5nIGEgY2FyZCAoYSBwdXJlLCBpbi1wcm9jZXNzIHRyYW5zZm9ybSkuICovXG5leHBvcnQgY29uc3QgVEVBTVNfQlVJTERfU0VUVElOR1M6IFRlYW1zRXhlY3V0aW9uU2V0dGluZ3MgPSB7XG4gIGRlZmF1bHQ6IHtcbiAgICAvLyBDYWNoZSBkaXNhYmxlZDogdGhlIGJ1aWxkIGlzIGNoZWFwIGFuZCBkZXRlcm1pbmlzdGljLCBzbyBhIGNhY2hlIHdvdWxkXG4gICAgLy8gYWRkIGEgY3Jvc3MtaWRlbnRpdHkga2V5IHN1cmZhY2UgZm9yIG5vIG1lYXN1cmFibGUgc2F2aW5nLlxuICAgIGNhY2hlOiB7IGVuYWJsZWQ6IGZhbHNlIH0sXG4gICAgLy8gUmV0cnkgZGlzYWJsZWQ6IHRoZSB0cmFuc2Zvcm0gcGVyZm9ybXMgbm8gSS9PLCBzbyBhIGZhaWx1cmUgaXNcbiAgICAvLyBkZXRlcm1pbmlzdGljIGFuZCBhIHNlY29uZCBhdHRlbXB0IHdvdWxkIGZhaWwgaWRlbnRpY2FsbHkuXG4gICAgcmV0cnk6IHsgZW5hYmxlZDogZmFsc2UgfSxcbiAgICB0aW1lb3V0OiBCVUlMRF9USU1FT1VUX01TLFxuICB9LFxufTtcblxuLyoqXG4gKiBDZWlsaW5nIG9uIG9uZSBjb252ZXJzYXRpb24gdHVybi4gR2VuZXJvdXMgcmVsYXRpdmUgdG8gdGhlIG90aGVyIHR3bzogYSB0dXJuXG4gKiBzcGFucyBhIGZ1bGwgYWdlbnQgY2FsbCAobW9kZWwgbGF0ZW5jeSBwbHVzIGFueSB0b29sIHRoZSBhZ2VudCBydW5zKSwgc28gaXQgaXNcbiAqIGJvdW5kZWQgYnkgdGhlIHNhbWUgb3JkZXIgb2YgbWFnbml0dWRlIGFzIGEgY2hhdCByZXF1ZXN0IHJhdGhlciB0aGFuIGFcbiAqIHRyYW5zZm9ybS5cbiAqL1xuZXhwb3J0IGNvbnN0IFRVUk5fVElNRU9VVF9NUyA9IDEyMF8wMDA7XG5cbi8qKiBFeGVjdXRpb24gc2V0dGluZ3MgZm9yIG9uZSBUZWFtcyBjb252ZXJzYXRpb24gdHVybiAoYW4gYWdlbnQgY2FsbCkuICovXG5leHBvcnQgY29uc3QgVEVBTVNfVFVSTl9TRVRUSU5HUzogVGVhbXNFeGVjdXRpb25TZXR0aW5ncyA9IHtcbiAgZGVmYXVsdDoge1xuICAgIC8vIENhY2hlIGRpc2FibGVkOiBhIHR1cm4gaXMgY29udmVyc2F0aW9uYWwgYW5kIHN0YXRlZnVsIC0gdGhlIHNhbWUgdGV4dCBpblxuICAgIC8vIGEgZGlmZmVyZW50IGNvbnZlcnNhdGlvbiBtdXN0IG5vdCByZXBsYXkgYW4gZWFybGllciBjYXJkLlxuICAgIGNhY2hlOiB7IGVuYWJsZWQ6IGZhbHNlIH0sXG4gICAgLy8gUmV0cnkgZGlzYWJsZWQ6IGEgdHVybiBtYXkgaGF2ZSBydW4gdG9vbHMgd2l0aCBzaWRlIGVmZmVjdHMgYmVmb3JlIGl0XG4gICAgLy8gZmFpbGVkLCBhbmQgcmUtcnVubmluZyB0aGUgbW9kZWwgd291bGQgZG91YmxlIHRoZW0uXG4gICAgcmV0cnk6IHsgZW5hYmxlZDogZmFsc2UgfSxcbiAgICB0aW1lb3V0OiBUVVJOX1RJTUVPVVRfTVMsXG4gIH0sXG59O1xuXG4vKiogRXhlY3V0aW9uIHNldHRpbmdzIGZvciBwb3N0aW5nIGEgY2FyZCB0byBhIFRlYW1zIGluY29taW5nIHdlYmhvb2suICovXG5leHBvcnQgY29uc3QgVEVBTVNfUE9TVF9TRVRUSU5HUzogVGVhbXNFeGVjdXRpb25TZXR0aW5ncyA9IHtcbiAgZGVmYXVsdDoge1xuICAgIC8vIENhY2hlIGRpc2FibGVkOiBhIHBvc3QgaXMgYSBzaWRlIGVmZmVjdCwgbm90IGEgdmFsdWUuIFJlcGxheWluZyBhIGNhY2hlZFxuICAgIC8vIHJlc3VsdCB3b3VsZCByZXBvcnQgYSBkZWxpdmVyeSB0aGF0IG5ldmVyIGhhcHBlbmVkLlxuICAgIGNhY2hlOiB7IGVuYWJsZWQ6IGZhbHNlIH0sXG4gICAgLy8gUmV0cnkgZW5hYmxlZDogYSB3ZWJob29rIFBPU1QgaXMgaWRlbXBvdGVudCBlbm91Z2ggdGhhdCBhIHRyYW5zaWVudCA1eHhcbiAgICAvLyBvciB0aW1lb3V0IGF0IHRoZSBUZWFtcyBlZGdlIGlzIHdvcnRoIG9uZSBvciB0d28gbW9yZSBhdHRlbXB0cy5cbiAgICByZXRyeTogeyBlbmFibGVkOiB0cnVlLCBhdHRlbXB0czogUE9TVF9BVFRFTVBUUyB9LFxuICAgIHRpbWVvdXQ6IFBPU1RfVElNRU9VVF9NUyxcbiAgfSxcbn07XG4iXX0=

package/lib/src/messaging.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The Teams messaging endpoint's turn: what happens between Azure Bot Service
+ * POSTing an activity and a card appearing in the channel.
+ *
+ * Split out from `conversation.ts` because the two callers have genuinely
+ * different contracts. `conversation.ts` runs a turn and RETURNS the reply, which
+ * is what a direct HTTP caller (or the in-repo preview UI) wants. A real channel
+ * cannot work that way: Bot Service ignores the response body and expects a fast
+ * `200`, so this module acknowledges first and delivers the reply out-of-band
+ * through the Connector API.
+ *
+ * The sequence for a `message` activity:
+ *
+ *   1. validate the inbound JWT and pin the reply destination to the
+ *      token's `serviceUrl` (see `auth.ts`);
+ *   2. return `200` immediately - Bot Service retries an activity it thinks
+ *      timed out, and a duplicate turn means a duplicate card;
+ *   3. show the typing indicator, run the agent, and POST the card back.
+ *
+ * Step 2 is why this is fire-and-forget rather than awaited: a card-producing
+ * agent turn takes seconds to tens of seconds, far longer than the ~15s Bot
+ * Service allows a bot to acknowledge.
+ *
+ * @module
+ */
+import { activity as activityContract } from "@dbx-tools/shared-teams";
+import { type CardAgentLike, type CardContextFactory } from "./conversation.js";
+/** Resolved bot credentials a delivered turn needs. */
+export interface BotCredentials {
+    /** Entra app (client) id of the bot registration. */
+    appId: string;
+    /** Client secret for {@link appId}. */
+    appPassword: string;
+    /** Tenant id for a single-tenant bot. */
+    appTenantId?: string;
+}
+/** Everything {@link deliverTurn} needs to answer one inbound activity. */
+export interface DeliverTurnOptions {
+    /** The agent that composes the card. */
+    agent: CardAgentLike;
+    /** The validated inbound activity. */
+    activity: activityContract.Activity;
+    /** Bot credentials used to fetch the outbound Connector token. */
+    credentials: BotCredentials;
+    /**
+     * Reply destination, already validated against the inbound token. Passing this
+     * explicitly (rather than reading `activity.serviceUrl`) keeps the security
+     * decision in the caller, where the token is in scope.
+     */
+    serviceUrl: string;
+    /**
+     * Builds the agent's per-turn request context, so the delivered turn has the
+     * same tool reach (Genie and every other user-scoped tool) as a chat turn.
+     */
+    createRequestContext?: CardContextFactory;
+    /** Cancels the turn (process shutdown, or a test tearing down). */
+    signal?: AbortSignal;
+}
+/**
+ * Read the reply destination off an inbound activity, if it names a usable one.
+ *
+ * `serviceUrl` rides on the activity as a plain string, so it is validated
+ * against the verified token's own `serviceurl` claim before anything
+ * authenticated is sent there.
+ */
+export declare const resolveServiceUrl: (activity: activityContract.Activity, tokenServiceUrl?: string) => string | null;
+/**
+ * Run one turn and deliver the card back through the Connector API.
+ *
+ * Awaited by nobody on the request path (the route has already answered `200`),
+ * so this owns its own error handling: a failure posts {@link FAILURE_TEXT} to
+ * the channel and is logged, never rethrown into an unhandled rejection.
+ */
+export declare const deliverTurn: (options: DeliverTurnOptions) => Promise<void>;

package/lib/src/messaging.js

@@ -0,0 +1,114 @@
+/**
+ * The Teams messaging endpoint's turn: what happens between Azure Bot Service
+ * POSTing an activity and a card appearing in the channel.
+ *
+ * Split out from `conversation.ts` because the two callers have genuinely
+ * different contracts. `conversation.ts` runs a turn and RETURNS the reply, which
+ * is what a direct HTTP caller (or the in-repo preview UI) wants. A real channel
+ * cannot work that way: Bot Service ignores the response body and expects a fast
+ * `200`, so this module acknowledges first and delivers the reply out-of-band
+ * through the Connector API.
+ *
+ * The sequence for a `message` activity:
+ *
+ *   1. validate the inbound JWT and pin the reply destination to the
+ *      token's `serviceUrl` (see `auth.ts`);
+ *   2. return `200` immediately - Bot Service retries an activity it thinks
+ *      timed out, and a duplicate turn means a duplicate card;
+ *   3. show the typing indicator, run the agent, and POST the card back.
+ *
+ * Step 2 is why this is fire-and-forget rather than awaited: a card-producing
+ * agent turn takes seconds to tens of seconds, far longer than the ~15s Bot
+ * Service allows a bot to acknowledge.
+ *
+ * @module
+ */
+import { error, log } from "@dbx-tools/shared-core";
+import { connectorToken, isAllowedServiceUrl } from "./auth.js";
+import { sendActivity, sendTyping } from "./connector.js";
+import { runCardTurn } from "./conversation.js";
+const logger = log.logger("teams:messaging");
+/**
+ * Message shown in the channel when a turn fails.
+ *
+ * A bot that silently drops a failed turn looks broken - the user sees their
+ * message land and nothing come back, forever. A short apology is posted instead
+ * so the conversation stays legible; the real error goes to the logs.
+ */
+const FAILURE_TEXT = "Sorry - I could not put together an answer for that. Please try again.";
+/**
+ * Read the reply destination off an inbound activity, if it names a usable one.
+ *
+ * `serviceUrl` rides on the activity as a plain string, so it is validated
+ * against the verified token's own `serviceurl` claim before anything
+ * authenticated is sent there.
+ */
+export const resolveServiceUrl = (activity, tokenServiceUrl) => {
+    const raw = activity.serviceUrl;
+    const candidate = typeof raw === "string" ? raw.trim() : "";
+    if (!candidate)
+        return null;
+    return isAllowedServiceUrl(candidate, tokenServiceUrl) ? candidate : null;
+};
+/**
+ * Run one turn and deliver the card back through the Connector API.
+ *
+ * Awaited by nobody on the request path (the route has already answered `200`),
+ * so this owns its own error handling: a failure posts {@link FAILURE_TEXT} to
+ * the channel and is logged, never rethrown into an unhandled rejection.
+ */
+export const deliverTurn = async (options) => {
+    const { agent, activity, credentials, serviceUrl } = options;
+    const conversationId = activity.conversation?.id;
+    if (!conversationId) {
+        logger.warn("dropping activity with no conversation id");
+        return;
+    }
+    const base = {
+        serviceUrl,
+        conversationId,
+        ...(activity.id ? { replyToId: activity.id } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
+    let token;
+    try {
+        token = await connectorToken({
+            appId: credentials.appId,
+            appPassword: credentials.appPassword,
+            ...(credentials.appTenantId ? { appTenantId: credentials.appTenantId } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    catch (err) {
+        // No token means nothing can be delivered - not even the apology - so this
+        // is the one failure that can only be logged.
+        logger.error("could not obtain a connector token", { error: error.errorMessage(err) });
+        return;
+    }
+    const target = { ...base, token };
+    await sendTyping(target);
+    try {
+        const activities = await runCardTurn(agent, activity, {
+            ...(options.createRequestContext
+                ? { createRequestContext: options.createRequestContext }
+                : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        for (const reply of activities) {
+            await sendActivity(reply, target);
+        }
+        logger.info("turn delivered", { conversation: conversationId, replies: activities.length });
+    }
+    catch (err) {
+        logger.error("turn failed", { conversation: conversationId, error: error.errorMessage(err) });
+        try {
+            await sendActivity({ type: "message", text: FAILURE_TEXT }, target);
+        }
+        catch (postErr) {
+            logger.error("could not report the failure to the channel", {
+                error: error.errorMessage(postErr),
+            });
+        }
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWVzc2FnaW5nLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL21lc3NhZ2luZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBd0JHO0FBRUgsT0FBTyxFQUFFLEtBQUssRUFBRSxHQUFHLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUVwRCxPQUFPLEVBQUUsY0FBYyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sUUFBUSxDQUFDO0FBQzdELE9BQU8sRUFBRSxZQUFZLEVBQUUsVUFBVSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQ3ZELE9BQU8sRUFBRSxXQUFXLEVBQStDLE1BQU0sZ0JBQWdCLENBQUM7QUFFMUYsTUFBTSxNQUFNLEdBQUcsR0FBRyxDQUFDLE1BQU0sQ0FBQyxpQkFBaUIsQ0FBQyxDQUFDO0FBRTdDOzs7Ozs7R0FNRztBQUNILE1BQU0sWUFBWSxHQUFHLHdFQUF3RSxDQUFDO0FBbUM5Rjs7Ozs7O0dBTUc7QUFDSCxNQUFNLENBQUMsTUFBTSxpQkFBaUIsR0FBRyxDQUMvQixRQUFtQyxFQUNuQyxlQUF3QixFQUNULEVBQUU7SUFDakIsTUFBTSxHQUFHLEdBQUksUUFBcUMsQ0FBQyxVQUFVLENBQUM7SUFDOUQsTUFBTSxTQUFTLEdBQUcsT0FBTyxHQUFHLEtBQUssUUFBUSxDQUFDLENBQUMsQ0FBQyxHQUFHLENBQUMsSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztJQUM1RCxJQUFJLENBQUMsU0FBUztRQUFFLE9BQU8sSUFBSSxDQUFDO0lBQzVCLE9BQU8sbUJBQW1CLENBQUMsU0FBUyxFQUFFLGVBQWUsQ0FBQyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQztBQUM1RSxDQUFDLENBQUM7QUFFRjs7Ozs7O0dBTUc7QUFDSCxNQUFNLENBQUMsTUFBTSxXQUFXLEdBQUcsS0FBSyxFQUFFLE9BQTJCLEVBQWlCLEVBQUU7SUFDOUUs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QUksRUFBRSxTQUFTLEVBQUUsSUFBSSxFQUFFLFlBQVksRUFBRSxFQUFFLE1BQU0sQ0FBQyxDQUFDO1FBQ3RFLENBQUM7UUFBQyxPQUFPLE9BQU8sRUFBRSxDQUFDO1lBQ2pCLE1BQU0sQ0FBQyxLQUFLLENBQUMsNkNBQTZDLEVBQUU7Z0JBQzFELEtBQUssRUFBRSxLQUFLLENBQUMsWUFBWSxDQUFDLE9BQU8sQ0FBQzthQUNuQyxDQUFDLENBQUM7UUFDTCxDQUFDO0lBQ0gsQ0FBQztBQUNILENBQUMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogVGhlIFRlYW1zIG1lc3NhZ2luZyBlbmRwb2ludCdzIHR1cm46IHdoYXQgaGFwcGVucyBiZXR3ZWVuIEF6dXJlIEJvdCBTZXJ2aWNlXG4gKiBQT1NUaW5nIGFuIGFjdGl2aXR5IGFuZCBhIGNhcmQgYXBwZWFyaW5nIGluIHRoZSBjaGFubmVsLlxuICpcbiAqIFNwbGl0IG91dCBmcm9tIGBjb252ZXJzYXRpb24udHNgIGJlY2F1c2UgdGhlIHR3byBjYWxsZXJzIGhhdmUgZ2VudWluZWx5XG4gKiBkaWZmZXJlbnQgY29udHJhY3RzLiBgY29udmVyc2F0aW9uLnRzYCBydW5zIGEgdHVybiBhbmQgUkVUVVJOUyB0aGUgcmVwbHksIHdoaWNoXG4gKiBpcyB3aGF0IGEgZGlyZWN0IEhUVFAgY2FsbGVyIChvciB0aGUgaW4tcmVwbyBwcmV2aWV3IFVJKSB3YW50cy4gQSByZWFsIGNoYW5uZWxcbiAqIGNhbm5vdCB3b3JrIHRoYXQgd2F5OiBCb3QgU2VydmljZSBpZ25vcmVzIHRoZSByZXNwb25zZSBib2R5IGFuZCBleHBlY3RzIGEgZmFzdFxuICogYDIwMGAsIHNvIHRoaXMgbW9kdWxlIGFja25vd2xlZGdlcyBmaXJzdCBhbmQgZGVsaXZlcnMgdGhlIHJlcGx5IG91dC1vZi1iYW5kXG4gKiB0aHJvdWdoIHRoZSBDb25uZWN0b3IgQVBJLlxuICpcbiAqIFRoZSBzZXF1ZW5jZSBmb3IgYSBgbWVzc2FnZWAgYWN0aXZpdHk6XG4gKlxuICogICAxLiB2YWxpZGF0ZSB0aGUgaW5ib3VuZCBKV1QgYW5kIHBpbiB0aGUgcmVwbHkgZGVzdGluYXRpb24gdG8gdGhlXG4gKiAgICAgIHRva2VuJ3MgYHNlcnZpY2VVcmxgIChzZWUgYGF1dGgudHNgKTtcbiAqICAgMi4gcmV0dXJuIGAyMDBgIGltbWVkaWF0ZWx5IC0gQm90IFNlcnZpY2UgcmV0cmllcyBhbiBhY3Rpdml0eSBpdCB0aGlua3NcbiAqICAgICAgdGltZWQgb3V0LCBhbmQgYSBkdXBsaWNhdGUgdHVybiBtZWFucyBhIGR1cGxpY2F0ZSBjYXJkO1xuICogICAzLiBzaG93IHRoZSB0eXBpbmcgaW5kaWNhdG9yLCBydW4gdGhlIGFnZW50LCBhbmQgUE9TVCB0aGUgY2FyZCBiYWNrLlxuICpcbiAqIFN0ZXAgMiBpcyB3aHkgdGhpcyBpcyBmaXJlLWFuZC1mb3JnZXQgcmF0aGVyIHRoYW4gYXdhaXRlZDogYSBjYXJkLXByb2R1Y2luZ1xuICogYWdlbnQgdHVybiB0YWtlcyBzZWNvbmRzIHRvIHRlbnMgb2Ygc2Vjb25kcywgZmFyIGxvbmdlciB0aGFuIHRoZSB+MTVzIEJvdFxuICogU2VydmljZSBhbGxvd3MgYSBib3QgdG8gYWNrbm93bGVkZ2UuXG4gKlxuICogQG1vZHVsZVxuICovXG5cbmltcG9ydCB7IGVycm9yLCBsb2cgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtY29yZVwiO1xuaW1wb3J0IHsgYWN0aXZpdHkgYXMgYWN0aXZpdHlDb250cmFjdCB9IGZyb20gXCJAZGJ4LXRvb2xzL3NoYXJlZC10ZWFtc1wiO1xuaW1wb3J0IHsgY29ubmVjdG9yVG9rZW4sIGlzQWxsb3dlZFNlcnZpY2VVcmwgfSBmcm9tIFwiLi9hdXRoXCI7XG5pbXBvcnQgeyBzZW5kQWN0aXZpdHksIHNlbmRUeXBpbmcgfSBmcm9tIFwiLi9jb25uZWN0b3JcIjtcbmltcG9ydCB7IHJ1bkNhcmRUdXJuLCB0eXBlIENhcmRBZ2VudExpa2UsIHR5cGUgQ2FyZENvbnRleHRGYWN0b3J5IH0gZnJvbSBcIi4vY29udmVyc2F0aW9uXCI7XG5cbmNvbnN0IGxvZ2dlciA9IGxvZy5sb2dnZXIoXCJ0ZWFtczptZXNzYWdpbmdcIik7XG5cbi8qKlxuICogTWVzc2FnZSBzaG93biBpbiB0aGUgY2hhbm5lbCB3aGVuIGEgdHVybiBmYWlscy5cbiAqXG4gKiBBIGJvdCB0aGF0IHNpbGVudGx5IGRyb3BzIGEgZmFpbGVkIHR1cm4gbG9va3MgYnJva2VuIC0gdGhlIHVzZXIgc2VlcyB0aGVpclxuICogbWVzc2FnZSBsYW5kIGFuZCBub3RoaW5nIGNvbWUgYmFjaywgZm9yZXZlci4gQSBzaG9ydCBhcG9sb2d5IGlzIHBvc3RlZCBpbnN0ZWFkXG4gKiBzbyB0aGUgY29udmVyc2F0aW9uIHN0YXlzIGxlZ2libGU7IHRoZSByZWFsIGVycm9yIGdvZXMgdG8gdGhlIGxvZ3MuXG4gKi9cbmNvbnN0IEZBSUxVUkVfVEVYVCA9IFwiU29ycnkgLSBJIGNvdWxkIG5vdCBwdXQgdG9nZXRoZXIgYW4gYW5zd2VyIGZvciB0aGF0LiBQbGVhc2UgdHJ5IGFnYWluLlwiO1xuXG4vKiogUmVzb2x2ZWQgYm90IGNyZWRlbnRpYWxzIGEgZGVsaXZlcmVkIHR1cm4gbmVlZHMuICovXG5leHBvcnQgaW50ZXJmYWNlIEJvdENyZWRlbnRpYWxzIHtcbiAgLyoqIEVudHJhIGFwcCAoY2xpZW50KSBpZCBvZiB0aGUgYm90IHJlZ2lzdHJhdGlvbi4gKi9cbiAgYXBwSWQ6IHN0cmluZztcbiAgLyoqIENsaWVudCBzZWNyZXQgZm9yIHtAbGluayBhcHBJZH0uICovXG4gIGFwcFBhc3N3b3JkOiBzdHJpbmc7XG4gIC8qKiBUZW5hbnQgaWQgZm9yIGEgc2luZ2xlLXRlbmFudCBib3QuICovXG4gIGFwcFRlbmFudElkPzogc3RyaW5nO1xufVxuXG4vKiogRXZlcnl0aGluZyB7QGxpbmsgZGVsaXZlclR1cm59IG5lZWRzIHRvIGFuc3dlciBvbmUgaW5ib3VuZCBhY3Rpdml0eS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgRGVsaXZlclR1cm5PcHRpb25zIHtcbiAgLyoqIFRoZSBhZ2VudCB0aGF0IGNvbXBvc2VzIHRoZSBjYXJkLiAqL1xuICBhZ2VudDogQ2FyZEFnZW50TGlrZTtcbiAgLyoqIFRoZSB2YWxpZGF0ZWQgaW5ib3VuZCBhY3Rpdml0eS4gKi9cbiAgYWN0aXZpdHk6IGFjdGl2aXR5Q29udHJhY3QuQWN0aXZpdHk7XG4gIC8qKiBCb3QgY3JlZGVudGlhbHMgdXNlZCB0byBmZXRjaCB0aGUgb3V0Ym91bmQgQ29ubmVjdG9yIHRva2VuLiAqL1xuICBjcmVkZW50aWFsczogQm90Q3JlZGVudGlhbHM7XG4gIC8qKlxuICAgKiBSZXBseSBkZXN0aW5hdGlvbiwgYWxyZWFkeSB2YWxpZGF0ZWQgYWdhaW5zdCB0aGUgaW5ib3VuZCB0b2tlbi4gUGFzc2luZyB0aGlzXG4gICAqIGV4cGxpY2l0bHkgKHJhdGhlciB0aGFuIHJlYWRpbmcgYGFjdGl2aXR5LnNlcnZpY2VVcmxgKSBrZWVwcyB0aGUgc2VjdXJpdHlcbiAgICogZGVjaXNpb24gaW4gdGhlIGNhbGxlciwgd2hlcmUgdGhlIHRva2VuIGlzIGluIHNjb3BlLlxuICAgKi9cbiAgc2VydmljZVVybDogc3RyaW5nO1xuICAvKipcbiAgICogQnVpbGRzIHRoZSBhZ2VudCdzIHBlci10dXJuIHJlcXVlc3QgY29udGV4dCwgc28gdGhlIGRlbGl2ZXJlZCB0dXJuIGhhcyB0aGVcbiAgICogc2FtZSB0b29sIHJlYWNoIChHZW5pZSBhbmQgZXZlcnkgb3RoZXIgdXNlci1zY29wZWQgdG9vbCkgYXMgYSBjaGF0IHR1cm4uXG4gICAqL1xuICBjcmVhdGVSZXF1ZXN0Q29udGV4dD86IENhcmRDb250ZXh0RmFjdG9yeTtcbiAgLyoqIENhbmNlbHMgdGhlIHR1cm4gKHByb2Nlc3Mgc2h1dGRvd24sIG9yIGEgdGVzdCB0ZWFyaW5nIGRvd24pLiAqL1xuICBzaWduYWw/OiBBYm9ydFNpZ25hbDtcbn1cblxuLyoqXG4gKiBSZWFkIHRoZSByZXBseSBkZXN0aW5hdGlvbiBvZmYgYW4gaW5ib3VuZCBhY3Rpdml0eSwgaWYgaXQgbmFtZXMgYSB1c2FibGUgb25lLlxuICpcbiAqIGBzZXJ2aWNlVXJsYCByaWRlcyBvbiB0aGUgYWN0aXZpdHkgYXMgYSBwbGFpbiBzdHJpbmcsIHNvIGl0IGlzIHZhbGlkYXRlZFxuICogYWdhaW5zdCB0aGUgdmVyaWZpZWQgdG9rZW4ncyBvd24gYHNlcnZpY2V1cmxgIGNsYWltIGJlZm9yZSBhbnl0aGluZ1xuICogYXV0aGVudGljYXRlZCBpcyBzZW50IHRoZXJlLlxuICovXG5leHBvcnQgY29uc3QgcmVzb2x2ZVNlcnZpY2VVcmwgPSAoXG4gIGFjdGl2aXR5OiBhY3Rpdml0eUNvbnRyYWN0LkFjdGl2aXR5LFxuICB0b2tlblNlcnZpY2VVcmw/OiBzdHJpbmcsXG4pOiBzdHJpbmcgfCBudWxsID0+IHtcbiAgY29uc3QgcmF3ID0gKGFjdGl2aXR5IGFzIHsgc2VydmljZVVybD86IHVua25vd24gfSkuc2VydmljZVVybDtcbiAgY29uc3QgY2FuZGlkYXRlID0gdHlwZW9mIHJhdyA9PT0gXCJzdHJpbmdcIiA/IHJhdy50cmltKCkgOiBcIlwiO1xuICBpZiAoIWNhbmRpZGF0ZSkgcmV0dXJuIG51bGw7XG4gIHJldHVybiBpc0FsbG93ZWRTZXJ2aWNlVXJsKGNhbmRpZGF0ZSwgdG9rZW5TZXJ2aWNlVXJsKSA/IGNhbmRpZGF0ZSA6IG51bGw7XG59O1xuXG4vKipcbiAqIFJ1biBvbmUgdHVybiBhbmQgZGVsaXZlciB0aGUgY2FyZCBiYWNrIHRocm91Z2ggdGhlIENvbm5lY3RvciBBUEkuXG4gKlxuICogQXdhaXRlZCBieSBub2JvZHkgb24gdGhlIHJlcXVlc3QgcGF0aCAodGhlIHJvdXRlIGhhcyBhbHJlYWR5IGFuc3dlcmVkIGAyMDBgKSxcbiAqIHNvIHRoaXMgb3ducyBpdHMgb3duIGVycm9yIGhhbmRsaW5nOiBhIGZhaWx1cmUgcG9zdHMge0BsaW5rIEZBSUxVUkVfVEVYVH0gdG9cbiAqIHRoZSBjaGFubmVsIGFuZCBpcyBsb2dnZWQsIG5ldmVyIHJldGhyb3duIGludG8gYW4gdW5oYW5kbGVkIHJlamVjdGlvbi5cbiAqL1xuZXhwb3J0IGNvbnN0IGRlbGl2ZXJUdXJuID0gYXN5bmMgKG9wdGlvbnM6IERlbGl2ZXJUdXJuT3B0aW9ucyk6IFByb21pc2U8dm9pZD4gPT4ge1xuICBjb25zdCB7IGFnZW50LCBhY3Rpdml0eSwgY3JlZGVudGlhbHMsIHNlcnZpY2VVcmwgfSA9IG9wdGlvbnM7XG4gIGNvbnN0IGNvbnZlcnNhdGlvbklkID0gYWN0aXZpdHkuY29udmVyc2F0aW9uPy5pZDtcbiAgaWYgKCFjb252ZXJzYXRpb25JZCkge1xuICAgIGxvZ2dlci53YXJuKFwiZHJvcHBpbmcgYWN0aXZpdHkgd2l0aCBubyBjb252ZXJzYXRpb24gaWRcIik7XG4gICAgcmV0dXJuO1xuICB9XG5cbiAgY29uc3QgYmFzZSA9IHtcbiAgICBzZXJ2aWNlVXJsLFxuICAgIGNvbnZlcnNhdGlvbklkLFxuICAgIC4uLihhY3Rpdml0eS5pZCA/IHsgcmVwbHlUb0lkOiBhY3Rpdml0eS5pZCB9IDoge30pLFxuICAgIC4uLihvcHRpb25zLnNpZ25hbCA/IHsgc2lnbmFsOiBvcHRpb25zLnNpZ25hbCB9IDoge30pLFxuICB9O1xuXG4gIGxldCB0b2tlbjogc3RyaW5nO1xuICB0cnkge1xuICAgIHRva2VuID0gYXdhaXQgY29ubmVjdG9yVG9rZW4oe1xuICAgICAgYXBwSWQ6IGNyZWRlbnRpYWxzLmFwcElkLFxuICAgICAgYXBwUGFzc3dvcmQ6IGNyZWRlbnRpYWxzLmFwcFBhc3N3b3JkLFxuICAgICAgLi4uKGNyZWRlbnRpYWxzLmFwcFRlbmFudElkID8geyBhcHBUZW5hbnRJZDogY3JlZGVudGlhbHMuYXBwVGVuYW50SWQgfSA6IHt9KSxcbiAgICAgIC4uLihvcHRpb25zLnNpZ25hbCA/IHsgc2lnbmFsOiBvcHRpb25zLnNpZ25hbCB9IDoge30pLFxuICAgIH0pO1xuICB9IGNhdGNoIChlcnIpIHtcbiAgICAvLyBObyB0b2tlbiBtZWFucyBub3RoaW5nIGNhbiBiZSBkZWxpdmVyZWQgLSBub3QgZXZlbiB0aGUgYXBvbG9neSAtIHNvIHRoaXNcbiAgICAvLyBpcyB0aGUgb25lIGZhaWx1cmUgdGhhdCBjYW4gb25seSBiZSBsb2dnZWQuXG4gICAgbG9nZ2VyLmVycm9yKFwiY291bGQgbm90IG9idGFpbiBhIGNvbm5lY3RvciB0b2tlblwiLCB7IGVycm9yOiBlcnJvci5lcnJvck1lc3NhZ2UoZXJyKSB9KTtcbiAgICByZXR1cm47XG4gIH1cblxuICBjb25zdCB0YXJnZXQgPSB7IC4uLmJhc2UsIHRva2VuIH07XG4gIGF3YWl0IHNlbmRUeXBpbmcodGFyZ2V0KTtcblxuICB0cnkge1xuICAgIGNvbnN0IGFjdGl2aXRpZXMgPSBhd2FpdCBydW5DYXJkVHVybihhZ2VudCwgYWN0aXZpdHksIHtcbiAgICAgIC4uLihvcHRpb25zLmNyZWF0ZVJlcXVlc3RDb250ZXh0XG4gICAgICAgID8geyBjcmVhdGVSZXF1ZXN0Q29udGV4dDogb3B0aW9ucy5jcmVhdGVSZXF1ZXN0Q29udGV4dCB9XG4gICAgICAgIDoge30pLFxuICAgICAgLi4uKG9wdGlvbnMuc2lnbmFsID8geyBzaWduYWw6IG9wdGlvbnMuc2lnbmFsIH0gOiB7fSksXG4gICAgfSk7XG4gICAgZm9yIChjb25zdCByZXBseSBvZiBhY3Rpdml0aWVzKSB7XG4gICAgICBhd2FpdCBzZW5kQWN0aXZpdHkocmVwbHksIHRhcmdldCk7XG4gICAgfVxuICAgIGxvZ2dlci5pbmZvKFwidHVybiBkZWxpdmVyZWRcIiwgeyBjb252ZXJzYXRpb246IGNvbnZlcnNhdGlvbklkLCByZXBsaWVzOiBhY3Rpdml0aWVzLmxlbmd0aCB9KTtcbiAgfSBjYXRjaCAoZXJyKSB7XG4gICAgbG9nZ2VyLmVycm9yKFwidHVybiBmYWlsZWRcIiwgeyBjb252ZXJzYXRpb246IGNvbnZlcnNhdGlvbklkLCBlcnJvcjogZXJyb3IuZXJyb3JNZXNzYWdlKGVycikgfSk7XG4gICAgdHJ5IHtcbiAgICAgIGF3YWl0IHNlbmRBY3Rpdml0eSh7IHR5cGU6IFwibWVzc2FnZVwiLCB0ZXh0OiBGQUlMVVJFX1RFWFQgfSwgdGFyZ2V0KTtcbiAgICB9IGNhdGNoIChwb3N0RXJyKSB7XG4gICAgICBsb2dnZXIuZXJyb3IoXCJjb3VsZCBub3QgcmVwb3J0IHRoZSBmYWlsdXJlIHRvIHRoZSBjaGFubmVsXCIsIHtcbiAgICAgICAgZXJyb3I6IGVycm9yLmVycm9yTWVzc2FnZShwb3N0RXJyKSxcbiAgICAgIH0pO1xuICAgIH1cbiAgfVxufTtcbiJdfQ==

package/lib/src/plugin.d.ts

@@ -0,0 +1,185 @@
+/**
+ * AppKit plugin (registered name: `teams`) that owns the Teams Adaptive Card
+ * runtime - the resolved card version and the optional incoming-webhook URL the
+ * {@link teamsCardTool} and the AppKit `teams.createCard` tool read. Registering
+ * it resolves and logs the effective config (which card version is in force,
+ * whether a webhook is wired up) so a misconfiguration is visible in the boot
+ * logs rather than on the first card, and installs the plugin's `execute()` as
+ * the runtime's executor so every build / post picks up AppKit's cache / retry /
+ * timeout / telemetry chain.
+ *
+ * The plugin is also a `ToolProvider`, so an AppKit agent can reach a
+ * `teams.createCard` tool directly; the {@link teamsCardTool} export is the same
+ * capability for a Mastra agent. Both share the runtime primed here.
+ *
+ * The plugin mounts four routes under its base path (`/api/teams`):
+ *
+ *   - `POST /messages` is the REAL Microsoft Teams messaging endpoint - the URL
+ *     an Azure Bot registration points at. It validates the Bot Service JWT,
+ *     acknowledges immediately, and delivers the agent's card back over the
+ *     Connector API. This is the route that makes a Teams channel able to chat
+ *     with the app's agents, the same way the Mastra plugin exposes MCP at a
+ *     path.
+ *   - `POST /activity` runs the same turn SYNCHRONOUSLY, answering with the
+ *     reply activities in the response body. It needs no bot registration, so
+ *     it is what a local client (the in-repo preview chat), a test, or any
+ *     non-Teams caller uses.
+ *   - `POST /card` compiles a {@link card.CardSpec} into an Adaptive Card
+ *     document (the preview page posts here).
+ *   - `POST /post` pushes a compiled card to the configured Teams incoming
+ *     webhook when one is set.
+ *
+ * Mirrors the node-email add-on's shape.
+ *
+ * @module
+ */
+import { Plugin, type IAppRouter } from "@databricks/appkit";
+import { type AgentToolDefinition, type ToolProvider } from "@databricks/appkit/beta";
+import { card } from "@dbx-tools/shared-teams";
+import { type TeamsPluginConfig } from "./config.js";
+/**
+ * AppKit plugin that configures the Adaptive Card builder used by the
+ * `create_teams_card` tool, and exposes card building as an AppKit agent tool.
+ *
+ * @example
+ * ```ts
+ * import { createApp, server } from "@databricks/appkit";
+ * import { plugin as teamsPlugin } from "@dbx-tools/teams";
+ *
+ * await createApp({
+ *   plugins: [
+ *     server(),
+ *     teamsPlugin.teams({ webhookUrl: process.env.TEAMS_WEBHOOK_URL }),
+ *   ],
+ * });
+ * ```
+ */
+export declare class TeamsPlugin extends Plugin<TeamsPluginConfig> implements ToolProvider {
+    static manifest: {
+        name: "teams";
+        displayName: string;
+        description: string;
+        stability: "beta";
+        resources: {
+            required: never[];
+            optional: never[];
+        };
+        config: {
+            schema: import("json-schema").JSONSchema7;
+        };
+    };
+    /**
+     * The tool this plugin offers to an AppKit agent.
+     *
+     * Marked `autoInheritable`: building a card is a pure, side-effect-free
+     * transform (nothing leaves the building), so it is safe to hand to any
+     * agent by default - unlike a send.
+     *
+     * `execute` re-parses its arguments with the local schema: AppKit validates
+     * against the same schema first, but re-parsing is what gives the body typed
+     * arguments instead of `unknown`.
+     */
+    private readonly tools;
+    /**
+     * Prime the shared runtime from this plugin's config (over env), route the
+     * tool's builds through this plugin's interceptor chain, and log the
+     * effective config so the resolved card version and whether a webhook is
+     * wired up are obvious at boot.
+     */
+    setup(): Promise<void>;
+    /** Drop the shared runtime. Idempotent. */
+    shutdown(): Promise<void>;
+    /**
+     * Mount the card-building and card-posting routes under the plugin base
+     * path (`/api/teams`). `POST /card` is what the dev display page calls to
+     * preview a card live; `POST /post` pushes a compiled card to the configured
+     * Teams incoming webhook.
+     *
+     * Neither route is wrapped in `asUser(req)`: compiling a card is a pure
+     * transform of the request body and posting goes to a preconfigured webhook,
+     * so neither reads workspace data on the caller's behalf and neither needs an
+     * OBO token. Wrapping them would make the routes throw
+     * `AuthenticationError` whenever the user-token header is absent (a local
+     * `curl`, a health probe), which - since AppKit does not catch a rejection
+     * raised inside the handler - takes the process down rather than answering
+     * 401.
+     */
+    injectRoutes(router: IAppRouter): void;
+    exports(): {
+        /**
+         * Compile a card spec into an Adaptive Card document. For agent-driven
+         * builds use {@link teamsCardTool} instead.
+         */
+        buildCard: (spec: card.CardSpec, signal?: AbortSignal) => Promise<card.CardResult>;
+        /**
+         * Post a compiled card to the configured Teams incoming webhook. Throws
+         * when no webhook is configured.
+         */
+        postCard: (cardDocument: card.AdaptiveCard, signal?: AbortSignal) => Promise<void>;
+    };
+    /** AppKit `ToolProvider`: the tool definitions offered to an agent. */
+    getAgentTools(): AgentToolDefinition[];
+    /**
+     * AppKit `ToolProvider`: run one tool call. Arguments are validated against
+     * the tool's schema first, and a validation failure comes back as an
+     * LLM-friendly string so the model can correct itself on the next turn.
+     */
+    executeAgentTool(name: string, args: unknown, signal?: AbortSignal): Promise<unknown>;
+    /**
+     * Handle one inbound request from Azure Bot Service on `POST /messages`.
+     *
+     * The order of operations is dictated by how Bot Service behaves, not by
+     * convenience:
+     *
+     *   1. **Refuse when unconfigured.** With no `appId` there is no audience to
+     *      validate a token against, so the endpoint cannot be operated safely;
+     *      it answers 503 rather than processing an unauthenticated activity.
+     *   2. **Validate the JWT before parsing the body.** The token is the only
+     *      trust boundary this endpoint has.
+     *   3. **Pin the reply destination to the token.** `serviceUrl` arrives in the
+     *      body, and replies carry the bot's credentials, so it is only honored
+     *      when it matches the verified token.
+     *   4. **Answer 200 immediately, then run the agent.** Bot Service times out
+     *      an unacknowledged activity in seconds and RETRIES it; a card takes far
+     *      longer than that, and a retry would post a duplicate card.
+     *
+     * Activities that carry no prompt (`typing`, `conversationUpdate`, an
+     * attachment-only message) are acknowledged and dropped - exactly what a bot
+     * does with them.
+     */
+    private handleMessage;
+    /** Compile a card, validating the request body against the spec schema. */
+    private executeBuild;
+    /**
+     * Run one conversation turn: validate the inbound activity, resolve the agent
+     * from the sibling agent plugin, and answer with card-carrying activities.
+     *
+     * Resolution failures are reported distinctly because they have different
+     * fixes: 503 when no agent plugin is mounted at all (a wiring problem), 404
+     * when the caller named an `agentId` that is not registered (a request
+     * problem).
+     */
+    private executeTurn;
+    /**
+     * Compile then post a card, validating the request body against the spec
+     * schema. The compile is folded INTO the executed callback so a throw from
+     * either half (a build failure, or `postCard` refusing because no webhook is
+     * configured) comes back as a failed {@link ExecutionResult} the route can
+     * answer with, rather than escaping the handler as an unhandled rejection.
+     */
+    private executePost;
+}
+/**
+ * Register the Teams plugin.
+ *
+ * @example
+ * ```ts
+ * import { createApp, server } from "@databricks/appkit";
+ * import { plugin as teamsPlugin } from "@dbx-tools/teams";
+ *
+ * await createApp({
+ *   plugins: [server(), teamsPlugin.teams()],
+ * });
+ * ```
+ */
+export declare const teams: import("@databricks/appkit").ToPlugin<typeof TeamsPlugin, TeamsPluginConfig, "teams">;