@cuylabs/agent-channel-teams 4.0.0 → 4.2.0

package/dist/proactive-DF5XvDLJ.d.ts

@@ -0,0 +1,258 @@
+import { TurnContext } from '@microsoft/agents-hosting';
+import { Conversation } from '@cuylabs/agent-channel-m365/proactive';
+import { AgentTurnSource, AgentEvent } from '@cuylabs/agent-core';
+import { M365ChannelOptions, M365TurnRequestContext, M365TurnPreparation, M365UserIdentity, M365ChannelAdapter } from '@cuylabs/agent-channel-m365';
+import { TeamsChannelData } from '@microsoft/agents-hosting-extensions-teams';
+import { Activity } from '@microsoft/agents-activity';
+
+interface TeamsInvokeResult<T = unknown> {
+    status: number;
+    body?: T;
+}
+declare function createTeamsInvokeActivity<T = unknown>(result: TeamsInvokeResult<T>): Activity;
+declare function sendTeamsInvoke<T = unknown>(context: TurnContext, body?: T, status?: number): Promise<void>;
+
+type TeamsSurface = "personal" | "channel" | "group" | "meeting" | "unknown";
+type TeamsActivityKind = "message" | "conversation-update" | "members-added" | "members-removed" | "channel-created" | "channel-deleted" | "channel-renamed" | "channel-restored" | "channel-shared" | "channel-unshared" | "team-renamed" | "team-archived" | "team-unarchived" | "team-deleted" | "team-hard-deleted" | "team-restored" | "message-edit" | "message-delete" | "message-restore" | "reaction" | "read-receipt" | "config-fetch" | "config-submit" | "file-consent" | "actionable-message-execute-action" | "adaptive-card-action" | "adaptive-card-search" | "card-submit" | "feedback" | "dialog-open" | "dialog-submit" | "task-fetch" | "task-submit" | "search-command" | "message-extension-query" | "message-extension-query-link" | "message-extension-anonymous-query-link" | "select-result" | "message-extension-select-item" | "message-extension-submit-action" | "message-extension-fetch-task" | "message-extension-query-setting-url" | "message-extension-setting" | "message-extension-card-button-clicked" | "tab-fetch" | "tab-submit" | "invoke" | "meeting-start" | "meeting-end" | "participants-join" | "participants-leave" | "meeting-room-join" | "meeting-room-leave" | "meeting-stage-view" | "meeting-smart-reply" | "meeting-reaction" | "meeting-poll-response" | "meeting-apps-installed" | "meeting-apps-uninstalled" | "meeting-recording-started" | "meeting-recording-stopped" | "meeting-focus-change" | "meeting-screen-share-start" | "meeting-screen-share-stop" | "other";
+interface TeamsActorReference {
+    id?: string;
+    displayName?: string;
+    tenantId?: string;
+    userPrincipalName?: string;
+}
+interface TeamsActivityInfo {
+    channelId: string;
+    conversationId: string;
+    activityId?: string;
+    messageId?: string;
+    replyToId?: string;
+    invokeName?: string;
+    eventType?: string;
+    tenantId?: string;
+    teamId?: string;
+    channelThreadId?: string;
+    meetingId?: string;
+    channelData?: TeamsChannelData;
+    surface: TeamsSurface;
+    kind: TeamsActivityKind;
+    actors: TeamsActorReference[];
+    /**
+     * Whether the inbound activity carries an `activityTreatment: targeted` entity.
+     *
+     * Targeted activities are visible only to the recipient even inside a group
+     * Teams conversation. Set by Teams clients or outgoing helper code through
+     * the `activityTreatment: targeted` entity added in @microsoft/agents-activity 1.5.
+     */
+    targeted: boolean;
+}
+interface TeamsTurnRequestContext extends M365TurnRequestContext {
+    teams: TeamsActivityInfo;
+    channelData?: TeamsChannelData;
+}
+type TeamsTurnPreparation = M365TurnPreparation;
+interface TeamsHandlerContext {
+    turnContext: TurnContext;
+    user: M365UserIdentity;
+    teams: TeamsActivityInfo;
+    channelData?: TeamsChannelData;
+    sessionId: string;
+    source: AgentTurnSource;
+    /**
+     * Start an agent turn inside the current Teams request context.
+     *
+     * This is useful for dialog submit/search-command handlers that still want
+     * to delegate their actual reasoning to agent-core.
+     */
+    runAgent(message: string, options?: {
+        abort?: AbortSignal;
+        system?: string;
+    }): AsyncGenerator<AgentEvent>;
+    /**
+     * Send an invoke response payload back to Teams.
+     */
+    sendInvoke(body?: unknown, status?: number): Promise<void>;
+}
+type TeamsHandlerDecision = void | "continue" | TeamsInvokeResult;
+type TeamsActivityHandler = (context: TeamsHandlerContext) => TeamsHandlerDecision | Promise<TeamsHandlerDecision>;
+interface TeamsConversationUpdateHandlers {
+    conversationUpdate?: TeamsActivityHandler;
+    membersAdded?: TeamsActivityHandler;
+    membersRemoved?: TeamsActivityHandler;
+    channelCreated?: TeamsActivityHandler;
+    channelDeleted?: TeamsActivityHandler;
+    channelRenamed?: TeamsActivityHandler;
+    channelRestored?: TeamsActivityHandler;
+    channelShared?: TeamsActivityHandler;
+    channelUnshared?: TeamsActivityHandler;
+    teamRenamed?: TeamsActivityHandler;
+    teamArchived?: TeamsActivityHandler;
+    teamUnarchived?: TeamsActivityHandler;
+    teamDeleted?: TeamsActivityHandler;
+    teamHardDeleted?: TeamsActivityHandler;
+    teamRestored?: TeamsActivityHandler;
+}
+interface TeamsMessageActivityHandlers {
+    messageEdited?: TeamsActivityHandler;
+    messageDeleted?: TeamsActivityHandler;
+    messageRestored?: TeamsActivityHandler;
+    reaction?: TeamsActivityHandler;
+    readReceipt?: TeamsActivityHandler;
+}
+interface TeamsCardActionHandlers {
+    cardSubmit?: TeamsActivityHandler;
+    adaptiveCardAction?: TeamsActivityHandler;
+    adaptiveCardSearch?: TeamsActivityHandler;
+    feedbackSubmit?: TeamsActivityHandler;
+    fileConsent?: TeamsActivityHandler;
+    actionableMessageExecuteAction?: TeamsActivityHandler;
+}
+interface TeamsConfigHandlers {
+    configFetch?: TeamsActivityHandler;
+    configSubmit?: TeamsActivityHandler;
+}
+interface TeamsTaskModuleHandlers {
+    dialogOpen?: TeamsActivityHandler;
+    dialogSubmit?: TeamsActivityHandler;
+    taskFetch?: TeamsActivityHandler;
+    taskSubmit?: TeamsActivityHandler;
+}
+interface TeamsMessageExtensionHandlers {
+    searchCommand?: TeamsActivityHandler;
+    selectResult?: TeamsActivityHandler;
+    messageExtensionQuery?: TeamsActivityHandler;
+    messageExtensionQueryLink?: TeamsActivityHandler;
+    messageExtensionAnonymousQueryLink?: TeamsActivityHandler;
+    messageExtensionSelectItem?: TeamsActivityHandler;
+    messageExtensionSubmitAction?: TeamsActivityHandler;
+    messageExtensionFetchTask?: TeamsActivityHandler;
+    messageExtensionQuerySettingUrl?: TeamsActivityHandler;
+    messageExtensionSetting?: TeamsActivityHandler;
+    messageExtensionCardButtonClicked?: TeamsActivityHandler;
+}
+interface TeamsTabHandlers {
+    tabFetch?: TeamsActivityHandler;
+    tabSubmit?: TeamsActivityHandler;
+}
+interface TeamsMeetingHandlers {
+    /** Fired when a Teams meeting starts. */
+    meetingStart?: TeamsActivityHandler;
+    /** Fired when a Teams meeting ends. */
+    meetingEnd?: TeamsActivityHandler;
+    /** Fired when participants join a Teams meeting. */
+    participantsJoin?: TeamsActivityHandler;
+    /** Fired when participants leave a Teams meeting. */
+    participantsLeave?: TeamsActivityHandler;
+    /** Fired when a physical meeting room joins a Teams meeting. */
+    meetingRoomJoin?: TeamsActivityHandler;
+    /** Fired when a physical meeting room leaves a Teams meeting. */
+    meetingRoomLeave?: TeamsActivityHandler;
+    /** Fired when the app is viewed in the meeting stage (invoke). */
+    meetingStageView?: TeamsActivityHandler;
+    /** Fired for smart reply recommendations during a meeting (invoke). */
+    meetingSmartReply?: TeamsActivityHandler;
+    /** Fired for emoji reactions during a meeting. */
+    meetingReaction?: TeamsActivityHandler;
+    /** Fired when a poll response is submitted during a meeting. */
+    meetingPollResponse?: TeamsActivityHandler;
+    /** Fired when apps are installed during a meeting. */
+    meetingAppsInstalled?: TeamsActivityHandler;
+    /** Fired when apps are uninstalled during a meeting. */
+    meetingAppsUninstalled?: TeamsActivityHandler;
+    /** Fired when meeting recording starts. */
+    meetingRecordingStarted?: TeamsActivityHandler;
+    /** Fired when meeting recording stops. */
+    meetingRecordingStopped?: TeamsActivityHandler;
+    /** Fired when the meeting focus changes. */
+    meetingFocusChange?: TeamsActivityHandler;
+    /** Fired when screen sharing starts in a meeting. */
+    meetingScreenShareStart?: TeamsActivityHandler;
+    /** Fired when screen sharing stops in a meeting. */
+    meetingScreenShareStop?: TeamsActivityHandler;
+}
+/**
+ * Aggregate Teams handler surface grouped by capability.
+ *
+ * This keeps the public API centered on Teams concepts without exposing
+ * Microsoft's `AgentApplication` routing types.
+ */
+interface TeamsActivityHandlers extends TeamsConversationUpdateHandlers, TeamsMessageActivityHandlers, TeamsCardActionHandlers, TeamsConfigHandlers, TeamsTaskModuleHandlers, TeamsMessageExtensionHandlers, TeamsTabHandlers, TeamsMeetingHandlers {
+    invoke?: TeamsActivityHandler;
+}
+interface TeamsChannelOptions extends Omit<M365ChannelOptions, "prepareTurn"> {
+    /**
+     * Whether malformed Teams channelData should throw while parsing.
+     *
+     * Keep this enabled in tests and strict hosts that want SDK payload drift to
+     * fail fast. Disable it in production bots that should continue handling the
+     * turn with best-effort Teams metadata when an unexpected channelData shape
+     * arrives.
+     *
+     * @default true
+     */
+    strictChannelData?: boolean;
+    /**
+     * Teams-native turn preparation hook. The result is forwarded into the
+     * underlying M365 channel adapter.
+     */
+    prepareTurn?: (request: TeamsTurnRequestContext) => TeamsTurnPreparation | Promise<TeamsTurnPreparation>;
+    /**
+     * Teams-specific activity hooks that run before generic M365 handling.
+     *
+     * Notes:
+     * - the `"feedback"` kind falls through to `cardSubmit` when
+     *   `feedbackSubmit` is not defined
+     * - specialized Teams invoke kinds fall back to grouped handlers such as
+     *   `dialogOpen`, `searchCommand`, or `selectResult` when the narrow handler
+     *   is not provided
+     */
+    handlers?: TeamsActivityHandlers;
+    /**
+     * General-purpose middleware that runs on every turn before cuylabs
+     * processing. Gives raw `TurnContext` access for Microsoft SDK helpers
+     * or custom logic. Call `next()` to continue into the normal handler
+     * pipeline, or return without calling it to short-circuit.
+     */
+    onTurn?: (context: TurnContext, next: () => Promise<void>) => Promise<void>;
+}
+interface TeamsChannelAdapter extends M365ChannelAdapter {
+    /**
+     * The underlying generic M365 adapter used for ordinary message turns.
+     */
+    readonly m365: M365ChannelAdapter;
+}
+
+/**
+ * Proactive messaging primitives for the Teams channel.
+ *
+ * Re-exports the M365 proactive bridge so Teams consumers have a single
+ * import surface, plus a Teams-specific helper that captures a
+ * {@link Conversation} together with the parsed Teams metadata most apps
+ * need at replay time (tenant, surface, team, channel thread, meeting id).
+ *
+ * Use this module when an app needs to send a message into Teams without an
+ * inbound turn — async tool completions, mail dispatcher results,
+ * notifications, scheduled reminders.
+ */
+
+/**
+ * Captured Teams conversation reference plus parsed channel metadata.
+ *
+ * The {@link Conversation} is what `continueM365Conversation` needs to replay
+ * a turn; `teams` is the parsed {@link TeamsActivityInfo} so callers can
+ * persist surface / tenant / team / channel ids alongside the reference for
+ * later routing decisions.
+ */
+interface TeamsProactiveCapture {
+    conversation: Conversation;
+    teams: TeamsActivityInfo;
+}
+/**
+ * Capture a serializable {@link Conversation} from a live Teams turn alongside
+ * the parsed Teams metadata. Validates the captured reference.
+ *
+ * Persist the result to your storage of choice; replay later through
+ * `continueM365Conversation(adapter, capture.conversation, async (ctx) => …)`.
+ */
+declare function captureTeamsConversationReference(context: TurnContext): TeamsProactiveCapture;
+
+export { type TeamsChannelOptions as T, type TeamsChannelAdapter as a, type TeamsActivityInfo as b, type TeamsActivityKind as c, type TeamsActivityHandler as d, type TeamsActivityHandlers as e, type TeamsActorReference as f, type TeamsCardActionHandlers as g, type TeamsConfigHandlers as h, type TeamsConversationUpdateHandlers as i, type TeamsHandlerContext as j, type TeamsHandlerDecision as k, type TeamsInvokeResult as l, type TeamsMeetingHandlers as m, type TeamsMessageActivityHandlers as n, type TeamsMessageExtensionHandlers as o, type TeamsProactiveCapture as p, type TeamsSurface as q, type TeamsTabHandlers as r, type TeamsTaskModuleHandlers as s, type TeamsTurnPreparation as t, type TeamsTurnRequestContext as u, captureTeamsConversationReference as v, createTeamsInvokeActivity as w, sendTeamsInvoke as x };

package/dist/proactive.d.ts

@@ -0,0 +1,7 @@
+import '@microsoft/agents-hosting';
+export { Conversation, ConversationBuilder, ConversationClaims, ConversationReference, ConversationReferenceBuilder, CreateConversationOptions, CreateConversationOptionsBuilder, M365ConversationInput, M365ConversationRecord, ProactiveIdentity, captureM365ConversationReference, continueM365Conversation, restoreM365ConversationReference } from '@cuylabs/agent-channel-m365/proactive';
+export { p as TeamsProactiveCapture, v as captureTeamsConversationReference } from './proactive-DF5XvDLJ.js';
+import '@cuylabs/agent-core';
+import '@cuylabs/agent-channel-m365';
+import '@microsoft/agents-hosting-extensions-teams';
+import '@microsoft/agents-activity';

package/dist/proactive.js

@@ -0,0 +1,21 @@
+import {
+  Conversation,
+  ConversationBuilder,
+  ConversationReferenceBuilder,
+  CreateConversationOptionsBuilder,
+  captureM365ConversationReference,
+  captureTeamsConversationReference,
+  continueM365Conversation,
+  restoreM365ConversationReference
+} from "./chunk-MBDHSFBF.js";
+import "./chunk-B5KRH22J.js";
+export {
+  Conversation,
+  ConversationBuilder,
+  ConversationReferenceBuilder,
+  CreateConversationOptionsBuilder,
+  captureM365ConversationReference,
+  captureTeamsConversationReference,
+  continueM365Conversation,
+  restoreM365ConversationReference
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-channel-teams",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Teams-native channel layer for @cuylabs/agent-core built on top of @cuylabs/agent-channel-m365",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +15,11 @@
       "types": "./dist/extensions.d.ts",
       "import": "./dist/extensions.js",
       "default": "./dist/extensions.js"
+    },
+    "./proactive": {
+      "types": "./dist/proactive.d.ts",
+      "import": "./dist/proactive.js",
+      "default": "./dist/proactive.js"
     }
   },
   "files": [
@@ -23,23 +28,28 @@
     "README.md"
   ],
   "dependencies": {
-    "@microsoft/agents-hosting-extensions-teams": "^1.4.2",
-    "@cuylabs/agent-channel-m365": "^4.0.0",
-    "@cuylabs/agent-core": "^4.0.0"
+    "@microsoft/agents-hosting-extensions-teams": "^1.5.0",
+    "@cuylabs/agent-channel-m365": "^4.2.0",
+    "@cuylabs/agent-core": "^4.2.0"
   },
   "peerDependencies": {
-    "@microsoft/agents-activity": "^1.4.2",
-    "@microsoft/agents-hosting": "^1.4.2",
+    "@microsoft/agents-activity": "^1.5.0",
+    "@microsoft/agents-hosting": "^1.5.0",
+    "@microsoft/agents-telemetry": "^1.5.0",
     "express": ">=4.21.0 || >=5.0.0"
   },
   "peerDependenciesMeta": {
+    "@microsoft/agents-telemetry": {
+      "optional": true
+    },
     "express": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@microsoft/agents-activity": "^1.4.2",
-    "@microsoft/agents-hosting": "^1.4.2",
+    "@microsoft/agents-activity": "^1.5.0",
+    "@microsoft/agents-hosting": "^1.5.0",
+    "@microsoft/agents-telemetry": "^1.5.0",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     "express": "^5.2.1",
@@ -69,8 +79,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/extensions.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts src/extensions.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts src/extensions.ts src/proactive.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/extensions.ts src/proactive.ts --format esm --dts --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",