@cuylabs/agent-channel-teams 0.10.0 → 0.12.0

package/dist/index.js

@@ -1,3 +1,9 @@
+import {
+  TeamsAttachmentDownloader,
+  TeamsInfo,
+  parseTeamsChannelData
+} from "./chunk-B5KRH22J.js";
+
 // src/adapter.ts
 import {
   createM365ChannelAdapter,
@@ -38,6 +44,86 @@ function detectSurface(conversationType, meetingId, teamId) {
   if (conversationType === "groupChat") return "group";
   return "unknown";
 }
+function includesName(names, candidate) {
+  return !!candidate && names.includes(candidate);
+}
+function parseTypedChannelData(channelData) {
+  if (!channelData) return void 0;
+  return parseTeamsChannelData(channelData);
+}
+var TEAMS_CONFIG_FETCH_NAMES = ["config/fetch"];
+var TEAMS_CONFIG_SUBMIT_NAMES = ["config/submit"];
+var TEAMS_FILE_CONSENT_NAMES = ["fileConsent/invoke"];
+var TEAMS_ACTIONABLE_MESSAGE_NAMES = [
+  "actionableMessage/executeAction"
+];
+var TEAMS_TASK_MODULE_FETCH_NAMES = [
+  "task/fetch",
+  "composeExtension/fetchTask"
+];
+var TEAMS_TASK_MODULE_SUBMIT_NAMES = ["task/submit"];
+var TEAMS_TAB_FETCH_NAMES = ["tab/fetch"];
+var TEAMS_TAB_SUBMIT_NAMES = ["tab/submit"];
+var TEAMS_MESSAGE_EXTENSION_QUERY_NAMES = [
+  "composeExtension/query",
+  "composeExtension/queryLink",
+  "composeExtension/anonymousQueryLink"
+];
+var TEAMS_MESSAGE_EXTENSION_SUBMIT_ACTION_NAMES = [
+  "composeExtension/submitAction"
+];
+var TEAMS_MESSAGE_EXTENSION_FETCH_TASK_NAMES = [
+  "composeExtension/fetchTask"
+];
+var TEAMS_MESSAGE_EXTENSION_QUERY_SETTING_URL_NAMES = [
+  "composeExtension/querySettingUrl"
+];
+var TEAMS_MESSAGE_EXTENSION_SETTING_NAMES = [
+  "composeExtension/setting"
+];
+var TEAMS_MESSAGE_EXTENSION_CARD_BUTTON_CLICKED_NAMES = [
+  "composeExtension/onCardButtonClicked"
+];
+var TEAMS_MESSAGE_EXTENSION_SELECT_NAMES = [
+  "composeExtension/selectItem"
+];
+var TEAMS_CARD_ACTION_SUBMIT_NAMES = ["message/submitAction"];
+var TEAMS_CONVERSATION_UPDATE_EVENT_NAMES = {
+  channelCreated: "channel-created",
+  channelDeleted: "channel-deleted",
+  channelRenamed: "channel-renamed",
+  channelRestored: "channel-restored",
+  channelShared: "channel-shared",
+  channelUnshared: "channel-unshared",
+  teamRenamed: "team-renamed",
+  teamArchived: "team-archived",
+  teamUnarchived: "team-unarchived",
+  teamDeleted: "team-deleted",
+  teamHardDeleted: "team-hard-deleted",
+  teamRestored: "team-restored"
+};
+var TEAMS_MEETING_EVENT_NAMES = {
+  "application/vnd.microsoft.readReceipt": "read-receipt",
+  "application/vnd.microsoft.meetingStart": "meeting-start",
+  "application/vnd.microsoft.meetingEnd": "meeting-end",
+  "application/vnd.microsoft.meetingParticipantJoin": "participants-join",
+  "application/vnd.microsoft.meetingParticipantLeave": "participants-leave",
+  "application/vnd.microsoft.meetingRoomJoin": "meeting-room-join",
+  "application/vnd.microsoft.meetingRoomLeave": "meeting-room-leave",
+  "application/vnd.microsoft.meetingReaction": "meeting-reaction",
+  "application/vnd.microsoft.meetingPollResponse": "meeting-poll-response",
+  "application/vnd.microsoft.meetingAppsInstalled": "meeting-apps-installed",
+  "application/vnd.microsoft.meetingAppsUninstalled": "meeting-apps-uninstalled",
+  "application/vnd.microsoft.meetingRecordingStarted": "meeting-recording-started",
+  "application/vnd.microsoft.meetingRecordingStopped": "meeting-recording-stopped",
+  "application/vnd.microsoft.meetingFocusChange": "meeting-focus-change",
+  "application/vnd.microsoft.meetingScreenShareStart": "meeting-screen-share-start",
+  "application/vnd.microsoft.meetingScreenShareStop": "meeting-screen-share-stop"
+};
+var TEAMS_MEETING_INVOKE_NAMES = {
+  "application/vnd.microsoft.meetingStageView": "meeting-stage-view",
+  "application/vnd.microsoft.meetingSmartReply": "meeting-smart-reply"
+};
 function detectKind(context, eventType) {
   const { activity } = context;
   const payload = asObject(activity.value);
@@ -48,6 +134,15 @@ function detectKind(context, eventType) {
     case ActivityTypes2.MessageReaction:
       return "reaction";
     case ActivityTypes2.ConversationUpdate:
+      if (Array.isArray(activity.membersAdded) && activity.membersAdded.length > 0) {
+        return "members-added";
+      }
+      if (Array.isArray(activity.membersRemoved) && activity.membersRemoved.length > 0) {
+        return "members-removed";
+      }
+      if (eventType && eventType in TEAMS_CONVERSATION_UPDATE_EVENT_NAMES) {
+        return TEAMS_CONVERSATION_UPDATE_EVENT_NAMES[eventType];
+      }
       return "conversation-update";
     case ActivityTypes2.MessageUpdate:
       if (eventType === "editMessage") return "message-edit";
@@ -56,16 +151,71 @@ function detectKind(context, eventType) {
     case ActivityTypes2.MessageDelete:
       if (eventType === "softDeleteMessage") return "message-delete";
       return "other";
+    case ActivityTypes2.Event:
+      if (invokeName && invokeName in TEAMS_MEETING_EVENT_NAMES) {
+        return TEAMS_MEETING_EVENT_NAMES[invokeName];
+      }
+      return "other";
     case ActivityTypes2.Invoke:
-      if (invokeName === "task/fetch" || invokeName === "composeExtension/fetchTask") {
-        return "dialog-open";
+      if (invokeName && invokeName in TEAMS_MEETING_INVOKE_NAMES) {
+        return TEAMS_MEETING_INVOKE_NAMES[invokeName];
+      }
+      if (includesName(TEAMS_CONFIG_FETCH_NAMES, invokeName)) {
+        return "config-fetch";
+      }
+      if (includesName(TEAMS_CONFIG_SUBMIT_NAMES, invokeName)) {
+        return "config-submit";
+      }
+      if (includesName(TEAMS_FILE_CONSENT_NAMES, invokeName)) {
+        return "file-consent";
+      }
+      if (includesName(TEAMS_ACTIONABLE_MESSAGE_NAMES, invokeName)) {
+        return "actionable-message-execute-action";
+      }
+      if (includesName(TEAMS_TASK_MODULE_FETCH_NAMES, invokeName)) {
+        return invokeName === "composeExtension/fetchTask" ? "message-extension-fetch-task" : "task-fetch";
+      }
+      if (includesName(TEAMS_TASK_MODULE_SUBMIT_NAMES, invokeName)) {
+        return "task-submit";
+      }
+      if (includesName(TEAMS_TAB_FETCH_NAMES, invokeName)) {
+        return "tab-fetch";
       }
-      if (invokeName === "task/submit") return "dialog-submit";
-      if (invokeName === "composeExtension/query" || invokeName === "composeExtension/queryLink" || invokeName === "composeExtension/anonymousQueryLink") {
-        return "search-command";
+      if (includesName(TEAMS_TAB_SUBMIT_NAMES, invokeName)) {
+        return "tab-submit";
       }
-      if (invokeName === "composeExtension/selectItem") return "select-result";
-      if (invokeName === "message/submitAction" || invokeName === "composeExtension/submitAction") {
+      if (includesName(TEAMS_MESSAGE_EXTENSION_QUERY_NAMES, invokeName)) {
+        switch (invokeName) {
+          case "composeExtension/queryLink":
+            return "message-extension-query-link";
+          case "composeExtension/anonymousQueryLink":
+            return "message-extension-anonymous-query-link";
+          default:
+            return "message-extension-query";
+        }
+      }
+      if (includesName(TEAMS_MESSAGE_EXTENSION_SELECT_NAMES, invokeName)) {
+        return "message-extension-select-item";
+      }
+      if (includesName(TEAMS_MESSAGE_EXTENSION_SUBMIT_ACTION_NAMES, invokeName)) {
+        return "message-extension-submit-action";
+      }
+      if (includesName(
+        TEAMS_MESSAGE_EXTENSION_QUERY_SETTING_URL_NAMES,
+        invokeName
+      )) {
+        return "message-extension-query-setting-url";
+      }
+      if (includesName(TEAMS_MESSAGE_EXTENSION_SETTING_NAMES, invokeName)) {
+        return "message-extension-setting";
+      }
+      if (includesName(
+        TEAMS_MESSAGE_EXTENSION_CARD_BUTTON_CLICKED_NAMES,
+        invokeName
+      )) {
+        return "message-extension-card-button-clicked";
+      }
+      if (includesName(TEAMS_CARD_ACTION_SUBMIT_NAMES, invokeName)) {
         return payload?.actionName === "feedback" ? "feedback" : "card-submit";
       }
       return "invoke";
@@ -94,14 +244,15 @@ function parseActors(channelData) {
 function parseTeamsActivity(context) {
   const { activity } = context;
   const channelData = asObject(activity.channelData);
+  const parsedChannelData = parseTypedChannelData(channelData);
   const team = asObject(channelData?.team);
   const channel = asObject(channelData?.channel);
   const tenant = asObject(channelData?.tenant);
   const meeting = asObject(channelData?.meeting);
-  const eventType = readString(channelData, "eventType");
+  const eventType = parsedChannelData?.eventType ?? readString(channelData, "eventType");
   const conversationType = typeof activity.conversation?.conversationType === "string" ? activity.conversation.conversationType : void 0;
-  const teamId = readString(team, "aadGroupId") ?? readString(team, "id");
-  const meetingId = readString(meeting, "id");
+  const teamId = parsedChannelData?.team?.aadGroupId ?? parsedChannelData?.team?.id ?? readString(team, "aadGroupId") ?? readString(team, "id");
+  const meetingId = parsedChannelData?.meeting?.id ?? readString(meeting, "id");
   const surface = detectSurface(
     conversationType,
     meetingId,
@@ -115,9 +266,10 @@ function parseTeamsActivity(context) {
     replyToId: activity.replyToId ?? void 0,
     invokeName: activity.name ?? void 0,
     eventType,
-    tenantId: readString(tenant, "id") ?? activity.conversation?.tenantId,
+    tenantId: parsedChannelData?.tenant?.id ?? readString(tenant, "id") ?? activity.conversation?.tenantId,
     teamId,
-    channelThreadId: readString(channel, "id"),
+    channelData: parsedChannelData,
+    channelThreadId: parsedChannelData?.channel?.id ?? readString(channel, "id"),
     meetingId,
     surface,
     kind: detectKind(context, eventType),
@@ -131,13 +283,18 @@ function createTeamsChannelAdapter(options) {
     prepareTurn,
     handlers,
     onInvoke: fallbackInvoke,
+    onTurn: onTurnHook,
     ...baseOptions
   } = options;
   const base = createM365ChannelAdapter({
     ...baseOptions,
     prepareTurn: async (request) => {
       const teams = parseTeamsActivity(request.turnContext);
-      const prepared = prepareTurn ? await prepareTurn({ ...request, teams }) : void 0;
+      const prepared = prepareTurn ? await prepareTurn({
+        ...request,
+        teams,
+        channelData: teams.channelData
+      }) : void 0;
       return {
         ...prepared ?? {},
         scopeName: prepared?.scopeName?.trim() || "teams-activity",
@@ -160,34 +317,45 @@ function createTeamsChannelAdapter(options) {
     },
     onInvoke: async (context) => {
       const teams = parseTeamsActivity(context);
-      const handled = await dispatchTeamsHandler(
+      const dispatch = await dispatchTeamsHandler(
         handlers,
         teams.kind,
         await createHandlerContext(options, base, context, teams)
       );
-      if (!handled && fallbackInvoke) {
+      if (!dispatch.handled && fallbackInvoke) {
         await fallbackInvoke(context);
+      } else if (!dispatch.handled) {
+        await sendTeamsInvoke(context, void 0, 501);
       }
     }
   });
-  async function handler(context) {
+  async function coreHandler(context) {
     const teams = parseTeamsActivity(context);
     if (teams.channelId !== "msteams") {
       await base.handler(context);
       return;
     }
-    if (context.activity.type === ActivityTypes3.MessageUpdate || context.activity.type === ActivityTypes3.MessageDelete || context.activity.type === ActivityTypes3.MessageReaction) {
-      const handled = await dispatchTeamsHandler(
+    const isTeamsSpecificEvent = context.activity.type === ActivityTypes3.Event && teams.kind !== "other";
+    const isTeamsSpecificActivity = context.activity.type === ActivityTypes3.ConversationUpdate || context.activity.type === ActivityTypes3.MessageUpdate || context.activity.type === ActivityTypes3.MessageDelete || context.activity.type === ActivityTypes3.MessageReaction || isTeamsSpecificEvent;
+    if (isTeamsSpecificActivity) {
+      const dispatch = await dispatchTeamsHandler(
         handlers,
         teams.kind,
         await createHandlerContext(options, base, context, teams)
       );
-      if (handled) {
+      if (dispatch.handled) {
         return;
       }
     }
     await base.handler(context);
   }
+  async function handler(context) {
+    if (onTurnHook) {
+      await onTurnHook(context, () => coreHandler(context));
+    } else {
+      await coreHandler(context);
+    }
+  }
   return {
     ...base,
     handler,
@@ -208,10 +376,11 @@ async function createHandlerContext(options, base, turnContext, teams = parseTea
     teams,
     context: { teams }
   };
-  return {
+  const context = {
     turnContext,
     user,
     teams,
+    channelData: teams.channelData,
     sessionId,
     source,
     runAgent(message, runOptions) {
@@ -224,20 +393,60 @@ async function createHandlerContext(options, base, turnContext, teams = parseTea
       );
     },
     async sendInvoke(body, status = 200) {
+      setInvokeResponseSent(context, true);
       await sendTeamsInvoke(turnContext, body, status);
     }
   };
+  setInvokeResponseSent(context, false);
+  return context;
 }
 async function dispatchTeamsHandler(handlers, kind, context) {
   const handler = resolveHandler(handlers, kind);
   if (!handler) {
-    return false;
+    return { handled: false };
   }
   const result = await handler(context);
-  return result !== "continue";
+  if (context.turnContext.activity.type === ActivityTypes3.Invoke && result !== "continue") {
+    if (!getInvokeResponseSent(context) && isTeamsInvokeResult(result)) {
+      await context.sendInvoke(result.body, result.status);
+    } else if (!getInvokeResponseSent(context) && result === void 0) {
+      await context.sendInvoke();
+    }
+  }
+  return { handled: result !== "continue" };
 }
 function resolveHandler(handlers, kind) {
   switch (kind) {
+    case "conversation-update":
+      return handlers?.conversationUpdate;
+    case "members-added":
+      return handlers?.membersAdded ?? handlers?.conversationUpdate;
+    case "members-removed":
+      return handlers?.membersRemoved ?? handlers?.conversationUpdate;
+    case "channel-created":
+      return handlers?.channelCreated ?? handlers?.conversationUpdate;
+    case "channel-deleted":
+      return handlers?.channelDeleted ?? handlers?.conversationUpdate;
+    case "channel-renamed":
+      return handlers?.channelRenamed ?? handlers?.conversationUpdate;
+    case "channel-restored":
+      return handlers?.channelRestored ?? handlers?.conversationUpdate;
+    case "channel-shared":
+      return handlers?.channelShared ?? handlers?.conversationUpdate;
+    case "channel-unshared":
+      return handlers?.channelUnshared ?? handlers?.conversationUpdate;
+    case "team-renamed":
+      return handlers?.teamRenamed ?? handlers?.conversationUpdate;
+    case "team-archived":
+      return handlers?.teamArchived ?? handlers?.conversationUpdate;
+    case "team-unarchived":
+      return handlers?.teamUnarchived ?? handlers?.conversationUpdate;
+    case "team-deleted":
+      return handlers?.teamDeleted ?? handlers?.conversationUpdate;
+    case "team-hard-deleted":
+      return handlers?.teamHardDeleted ?? handlers?.conversationUpdate;
+    case "team-restored":
+      return handlers?.teamRestored ?? handlers?.conversationUpdate;
     case "message-edit":
       return handlers?.messageEdited;
     case "message-delete":
@@ -246,6 +455,16 @@ function resolveHandler(handlers, kind) {
       return handlers?.messageRestored;
     case "reaction":
       return handlers?.reaction;
+    case "read-receipt":
+      return handlers?.readReceipt;
+    case "config-fetch":
+      return handlers?.configFetch ?? handlers?.invoke;
+    case "config-submit":
+      return handlers?.configSubmit ?? handlers?.invoke;
+    case "file-consent":
+      return handlers?.fileConsent ?? handlers?.invoke;
+    case "actionable-message-execute-action":
+      return handlers?.actionableMessageExecuteAction ?? handlers?.invoke;
     case "feedback":
       return handlers?.feedbackSubmit ?? handlers?.cardSubmit;
     case "card-submit":
@@ -256,14 +475,83 @@ function resolveHandler(handlers, kind) {
       return handlers?.dialogSubmit;
     case "search-command":
       return handlers?.searchCommand;
+    case "message-extension-query":
+      return handlers?.messageExtensionQuery ?? handlers?.searchCommand;
+    case "message-extension-query-link":
+      return handlers?.messageExtensionQueryLink ?? handlers?.searchCommand;
+    case "message-extension-anonymous-query-link":
+      return handlers?.messageExtensionAnonymousQueryLink ?? handlers?.searchCommand;
     case "select-result":
       return handlers?.selectResult;
+    case "message-extension-select-item":
+      return handlers?.messageExtensionSelectItem ?? handlers?.selectResult;
+    case "message-extension-submit-action":
+      return handlers?.messageExtensionSubmitAction ?? handlers?.cardSubmit;
+    case "message-extension-fetch-task":
+      return handlers?.messageExtensionFetchTask ?? handlers?.dialogOpen;
+    case "message-extension-query-setting-url":
+      return handlers?.messageExtensionQuerySettingUrl ?? handlers?.invoke;
+    case "message-extension-setting":
+      return handlers?.messageExtensionSetting ?? handlers?.invoke;
+    case "message-extension-card-button-clicked":
+      return handlers?.messageExtensionCardButtonClicked ?? handlers?.invoke;
+    case "task-fetch":
+      return handlers?.taskFetch ?? handlers?.dialogOpen;
+    case "task-submit":
+      return handlers?.taskSubmit ?? handlers?.dialogSubmit;
+    case "tab-fetch":
+      return handlers?.tabFetch ?? handlers?.invoke;
+    case "tab-submit":
+      return handlers?.tabSubmit ?? handlers?.invoke;
     case "invoke":
       return handlers?.invoke;
+    case "meeting-start":
+      return handlers?.meetingStart;
+    case "meeting-end":
+      return handlers?.meetingEnd;
+    case "participants-join":
+      return handlers?.participantsJoin;
+    case "participants-leave":
+      return handlers?.participantsLeave;
+    case "meeting-room-join":
+      return handlers?.meetingRoomJoin;
+    case "meeting-room-leave":
+      return handlers?.meetingRoomLeave;
+    case "meeting-stage-view":
+      return handlers?.meetingStageView;
+    case "meeting-smart-reply":
+      return handlers?.meetingSmartReply;
+    case "meeting-reaction":
+      return handlers?.meetingReaction;
+    case "meeting-poll-response":
+      return handlers?.meetingPollResponse;
+    case "meeting-apps-installed":
+      return handlers?.meetingAppsInstalled;
+    case "meeting-apps-uninstalled":
+      return handlers?.meetingAppsUninstalled;
+    case "meeting-recording-started":
+      return handlers?.meetingRecordingStarted;
+    case "meeting-recording-stopped":
+      return handlers?.meetingRecordingStopped;
+    case "meeting-focus-change":
+      return handlers?.meetingFocusChange;
+    case "meeting-screen-share-start":
+      return handlers?.meetingScreenShareStart;
+    case "meeting-screen-share-stop":
+      return handlers?.meetingScreenShareStop;
     default:
       return void 0;
   }
 }
+function isTeamsInvokeResult(value) {
+  return !!value && typeof value === "object" && "status" in value;
+}
+function getInvokeResponseSent(context) {
+  return context.__invokeResponseSent === true;
+}
+function setInvokeResponseSent(context, value) {
+  context.__invokeResponseSent = value;
+}
 function resolveSource(options) {
   if (options.source) return options.source;
   if (options.agent) return options.agent;
@@ -329,9 +617,7 @@ async function mountTeamsAgent(source, options = {}) {
     app: providedApp,
     ...adapterOptions
   } = options;
-  const authConfig = hostingModule.getAuthConfigWithDefaults(
-    providedAuthConfig
-  );
+  const authConfig = hostingModule.getAuthConfigWithDefaults(providedAuthConfig);
   const cloudAdapter = providedAdapter ?? new hostingModule.CloudAdapter(authConfig);
   const expressApp = providedApp ?? expressModule.default();
   const channelAdapter = createTeamsChannelAdapter({
@@ -354,8 +640,9 @@ async function mountTeamsAgent(source, options = {}) {
   let server;
   if (port !== null) {
     const onListen = () => {
-      console.log(
-        `Teams agent listening on port ${port} \u2014 appId: ${authConfig.clientId ?? "(not set)"}`
+      process.stdout.write(
+        `Teams agent listening on port ${port} \u2014 appId: ${authConfig.clientId ?? "(not set)"}
+`
       );
     };
     server = host ? expressApp.listen(port, host, onListen) : expressApp.listen(port, onListen);
@@ -446,6 +733,27 @@ function createTeamsDialogMessage(message) {
   };
 }
 export {
+  TEAMS_ACTIONABLE_MESSAGE_NAMES,
+  TEAMS_CARD_ACTION_SUBMIT_NAMES,
+  TEAMS_CONFIG_FETCH_NAMES,
+  TEAMS_CONFIG_SUBMIT_NAMES,
+  TEAMS_CONVERSATION_UPDATE_EVENT_NAMES,
+  TEAMS_FILE_CONSENT_NAMES,
+  TEAMS_MEETING_EVENT_NAMES,
+  TEAMS_MEETING_INVOKE_NAMES,
+  TEAMS_MESSAGE_EXTENSION_CARD_BUTTON_CLICKED_NAMES,
+  TEAMS_MESSAGE_EXTENSION_FETCH_TASK_NAMES,
+  TEAMS_MESSAGE_EXTENSION_QUERY_NAMES,
+  TEAMS_MESSAGE_EXTENSION_QUERY_SETTING_URL_NAMES,
+  TEAMS_MESSAGE_EXTENSION_SELECT_NAMES,
+  TEAMS_MESSAGE_EXTENSION_SETTING_NAMES,
+  TEAMS_MESSAGE_EXTENSION_SUBMIT_ACTION_NAMES,
+  TEAMS_TAB_FETCH_NAMES,
+  TEAMS_TAB_SUBMIT_NAMES,
+  TEAMS_TASK_MODULE_FETCH_NAMES,
+  TEAMS_TASK_MODULE_SUBMIT_NAMES,
+  TeamsAttachmentDownloader,
+  TeamsInfo,
   createTeamsChannelAdapter,
   createTeamsDialog,
   createTeamsDialogMessage,
@@ -455,6 +763,7 @@ export {
   currentTeamsTurnContext,
   mountTeamsAgent,
   parseTeamsActivity,
+  parseTeamsChannelData,
   runWithTeamsTurnContext,
   sendTeamsInvoke
 };

package/docs/README.md

@@ -0,0 +1,33 @@
+# @cuylabs/agent-channel-teams Docs
+
+Use this doc set when you are building Teams-native workflows on top of the
+generic M365 transport layer and want to stay on the cuylabs execution model
+instead of adopting Microsoft `AgentApplication`.
+
+## Doc Map
+
+| Document                               | Purpose                                                                                |
+| -------------------------------------- | -------------------------------------------------------------------------------------- |
+| [architecture.md](./architecture.md)   | Layering between `agent-core`, `agent-channel-m365`, and `agent-channel-teams`         |
+| [handler-model.md](./handler-model.md) | Handler groups, meeting routing, invoke flows, and `onTurn` middleware                 |
+| [teams-helpers.md](./teams-helpers.md) | `TeamsInfo`, typed channel data, safe DTOs, and when to use the `./extensions` subpath |
+
+## Source Map
+
+- `src/adapter.ts`
+  - `createTeamsChannelAdapter()`, Teams-specific dispatch, `onTurn`, Teams handler context
+- `src/teams-activity.ts`
+  - parsed Teams metadata, event-name constants, typed channel data projection
+- `src/types.ts`
+  - public Teams handler groups, context contracts, Teams-specific options
+- `src/extensions.ts`
+  - curated Teams helper and DTO bridge from `@microsoft/agents-hosting-extensions-teams`
+- `src/responses.ts`
+  - Teams dialog and message-extension response builders
+
+## Suggested Reading Order
+
+1. Start with the package [README.md](../README.md) for quick usage.
+2. Read [architecture.md](./architecture.md) to understand the bridge boundary.
+3. Read [handler-model.md](./handler-model.md) when wiring handlers.
+4. Read [teams-helpers.md](./teams-helpers.md) when you need Teams REST helpers or typed channel data.

package/docs/architecture.md

@@ -0,0 +1,71 @@
+# Teams Bridge Architecture
+
+`@cuylabs/agent-channel-teams` is the Teams-native facade that sits on top of
+`@cuylabs/agent-channel-m365`.
+
+It exists so you can add Teams concepts such as meeting events, message
+extensions, task modules, typed channel data, and Teams helper APIs without
+moving your app to Microsoft `AgentApplication` as the runtime model.
+
+## Layer Split
+
+| Layer               | Package                                      | Responsibility                                                                      |
+| ------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Execution           | `@cuylabs/agent-core`                        | Agentic loop, tools, sessions, inference, middleware                                |
+| Generic transport   | `@cuylabs/agent-channel-m365`                | Activity Protocol transport, `TurnContext` bridge, session mapping, event streaming |
+| Teams-native facade | `@cuylabs/agent-channel-teams`               | Teams parsing, Teams handlers, Teams response builders, Teams helper bridge         |
+| SDK helpers         | `@microsoft/agents-hosting-extensions-teams` | Teams REST helpers, typed channel data, DTOs                                        |
+
+## Architectural Boundary
+
+The key rule is:
+
+- use Microsoft Teams extensions as implementation building blocks
+- do not expose Microsoft `AgentApplication` router classes as the app-facing model
+
+That means `agent-channel-teams` can safely re-expose:
+
+- `TeamsInfo`
+- `parseTeamsChannelData`
+- typed Teams DTOs
+- Teams event-name mappings
+
+But it intentionally avoids making these part of the public cuylabs programming
+model:
+
+- `TeamsAgentExtension`
+- `Meeting`
+- `MessageExtension`
+- `TaskModule`
+- other `AgentApplication` or `ActivityHandler`-oriented abstractions
+
+## Request Flow
+
+```text
+Teams
+  -> @microsoft/agents-hosting
+  -> @cuylabs/agent-channel-m365
+  -> @cuylabs/agent-channel-teams
+  -> @cuylabs/agent-core
+```
+
+## What `agent-channel-teams` Adds
+
+Compared with `agent-channel-m365`, this package adds:
+
+- Teams-specific parsed metadata via `parseTeamsActivity()`
+- typed `channelData` projection into handler and `prepareTurn()` contexts
+- Teams-native handler groups for meetings, task modules, message extensions,
+  feedback, and message edits
+- Teams invoke response helpers and response builders
+- a curated Teams helper facade built around `TeamsInfo`
+
+## Why This Is The Enterprise Boundary
+
+This layering lets you:
+
+- keep `agent-core` as the only execution engine
+- keep `agent-channel-m365` generic and reusable across Activity clients
+- add Teams-specific capabilities without forking the runtime model
+- consume Microsoft Teams helper code without leaking Microsoft routing
+  abstractions into app code