@cuylabs/agent-channel-teams 0.10.0 → 0.12.0

package/docs/handler-model.md

@@ -0,0 +1,165 @@
+# Teams Handler Model
+
+`agent-channel-teams` keeps the app-facing API centered on cuylabs handlers and
+context objects, not Microsoft router classes.
+
+## Primary Entry Point
+
+Use `createTeamsChannelAdapter()` when you need Teams-native behavior on top of
+the generic M365 transport.
+
+Ordinary message turns still flow through the underlying M365 adapter. Teams
+specific activities are intercepted by the Teams layer first.
+
+## Handler Capability Groups
+
+The handler surface is grouped by capability:
+
+- `TeamsConversationUpdateHandlers`
+- `TeamsMessageActivityHandlers`
+- `TeamsCardActionHandlers`
+- `TeamsConfigHandlers`
+- `TeamsTaskModuleHandlers`
+- `TeamsMessageExtensionHandlers`
+- `TeamsTabHandlers`
+- `TeamsMeetingHandlers`
+
+`TeamsActivityHandlers` composes all of these into one shape for convenience.
+
+This grouping is meant to reflect Teams concepts rather than Microsoft
+`AgentApplication` routing classes.
+
+## Handler Context
+
+Every Teams handler gets a `TeamsHandlerContext` with:
+
+- `turnContext` for raw SDK access when needed
+- `teams` for parsed Teams-specific activity metadata
+- `channelData` for typed Teams channel data
+- `runAgent()` to delegate work back into `agent-core`
+- `sendInvoke()` to respond with a Teams invoke payload
+
+Invoke handlers may either call `sendInvoke(...)` or return a `TeamsInvokeResult`
+(`{ status, body }`). If a handled invoke returns nothing, the adapter sends an
+empty `200` acknowledgement. If no Teams handler handles the invoke, the Teams
+layer returns `501`.
+
+Example:
+
+```ts
+handlers: {
+  async taskSubmit(ctx) {
+    const payload = JSON.stringify(ctx.turnContext.activity.value);
+    const events = ctx.runAgent(`Handle this Teams dialog payload:\n${payload}`);
+    let text = "";
+
+    for await (const event of events) {
+      if (event.type === "text-delta") {
+        text += event.text;
+      }
+    }
+
+    return {
+      status: 200,
+      body: createTeamsDialogMessage(text),
+    };
+  },
+}
+```
+
+## `prepareTurn()` Context
+
+`prepareTurn()` receives both the parsed `teams` metadata and the typed
+`channelData` projection. Use this when you need tenant IDs, meeting IDs, or
+other Teams-specific context in the agent scope or system prompt.
+
+```ts
+prepareTurn: ({ teams, channelData, user }) => ({
+  system: `Help ${user.userName} in tenant ${channelData?.tenant?.id ?? teams.tenantId}.`,
+});
+```
+
+## Meeting Routing
+
+The Teams layer maps the Microsoft meeting event names into cuylabs handler
+slots.
+
+- Event activities map through `TEAMS_MEETING_EVENT_NAMES`
+- Invoke meeting activities map through `TEAMS_MEETING_INVOKE_NAMES`
+
+Meeting-specific handlers include:
+
+- `meetingStart`
+- `meetingEnd`
+- `participantsJoin`
+- `participantsLeave`
+- `meetingStageView`
+- `meetingSmartReply`
+- and the rest of the supported meeting event set
+
+## Conversation Updates
+
+Teams conversation updates are no longer flattened into a single generic bucket.
+The handler surface supports both the coarse and specific shapes:
+
+- `conversationUpdate`
+- `membersAdded`
+- `membersRemoved`
+- `channelCreated`
+- `channelDeleted`
+- `channelRenamed`
+- `channelRestored`
+- `channelShared`
+- `channelUnshared`
+- `teamRenamed`
+- `teamArchived`
+- `teamUnarchived`
+- `teamDeleted`
+- `teamHardDeleted`
+- `teamRestored`
+
+## Task Modules, Message Extensions, Tabs, And Config
+
+The Teams layer supports both grouped Teams concepts and the narrower invoke
+families that exist in Microsoft's SDK:
+
+- `dialogOpen`
+- `dialogSubmit`
+- `searchCommand`
+- `selectResult`
+- `cardSubmit`
+- `feedbackSubmit`
+- `taskFetch`
+- `taskSubmit`
+- `messageExtensionQuery`
+- `messageExtensionQueryLink`
+- `messageExtensionAnonymousQueryLink`
+- `messageExtensionSelectItem`
+- `messageExtensionSubmitAction`
+- `messageExtensionFetchTask`
+- `messageExtensionQuerySettingUrl`
+- `messageExtensionSetting`
+- `messageExtensionCardButtonClicked`
+- `configFetch`
+- `configSubmit`
+- `tabFetch`
+- `tabSubmit`
+- `fileConsent`
+- `actionableMessageExecuteAction`
+
+The adapter still falls back from the narrow names into the grouped handlers
+where that is the ergonomic default, so existing `dialogOpen`, `searchCommand`,
+and `selectResult` handlers keep working.
+
+## `onTurn` Middleware
+
+Use `onTurn(context, next)` when you need a pre-handler hook with full
+`TurnContext` access.
+
+Typical uses:
+
+- logging or observability
+- host-specific short-circuiting
+- calling SDK helpers before cuylabs processing begins
+
+If you do not call `next()`, normal Teams and M365 processing is skipped.

package/docs/teams-helpers.md

@@ -0,0 +1,91 @@
+# Teams Helpers And Typed Data
+
+`@cuylabs/agent-channel-teams` exposes a curated safe slice of
+`@microsoft/agents-hosting-extensions-teams` so callers can use Teams helper
+APIs without adopting Microsoft `AgentApplication` as the app model.
+
+## Main Helper Exports
+
+Available from the main package:
+
+- `TeamsInfo`
+- `TeamsAttachmentDownloader`
+- `parseTeamsChannelData`
+- Teams channel data DTOs
+- Teams event-name constants
+- Teams team, tenant, notification, and meeting-related types that fit the
+  public bridge
+
+The same helper surface is also available from:
+
+```ts
+import {
+  TeamsInfo,
+  parseTeamsChannelData,
+} from "@cuylabs/agent-channel-teams/extensions";
+```
+
+Use the main package when you want the simplest app-facing import path. Use the
+subpath when you want to make the helper grouping explicit in your codebase.
+
+## Typed Channel Data
+
+`parseTeamsChannelData()` validates and returns Teams channel data with the SDK
+types:
+
+```ts
+import { parseTeamsChannelData } from "@cuylabs/agent-channel-teams";
+
+const channelData = parseTeamsChannelData(turnContext.activity.channelData);
+console.log(channelData.team?.id, channelData.tenant?.id);
+```
+
+This parsing is strict by design. The adapter now uses the same strict parsing
+path internally, so malformed Teams channel data fails fast instead of being
+silently downgraded to `undefined`.
+
+The Teams adapter also projects parsed channel data automatically into:
+
+- `TeamsActivityInfo.channelData`
+- `TeamsHandlerContext.channelData`
+- `TeamsTurnRequestContext.channelData`
+
+That means you often do not need to call `parseTeamsChannelData()` yourself.
+
+## `TeamsInfo`
+
+Use `TeamsInfo` when you need Teams REST and connector-backed helpers from the
+same `TurnContext` already flowing through the cuylabs adapter layer.
+
+Examples:
+
+```ts
+const details = await TeamsInfo.getTeamDetails(ctx.turnContext);
+const members = await TeamsInfo.getPagedMembers(ctx.turnContext);
+const participant = await TeamsInfo.getMeetingParticipant(ctx.turnContext);
+```
+
+When the incoming activity carries files or hosted content, `TeamsAttachmentDownloader`
+is also available from the curated surface for attachment-oriented flows.
+
+This is the main reason `@microsoft/agents-hosting-extensions-teams` is a
+required dependency of `agent-channel-teams`: the helper surface is part of the
+supported bridge contract, not an optional afterthought.
+
+## Public Boundary
+
+The curated helper bridge intentionally excludes Microsoft runtime routing
+objects such as:
+
+- `TeamsAgentExtension`
+- `Meeting`
+- `MessageExtension`
+- `TaskModule`
+
+Those classes are useful inside Microsoft's `AgentApplication` model, but the
+cuylabs bridge keeps app code centered on:
+
+- `createTeamsChannelAdapter()`
+- Teams handler groups
+- Teams helper functions and DTOs
+- `agent-core` as the only execution engine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-channel-teams",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Teams-native channel layer for @cuylabs/agent-core built on top of @cuylabs/agent-channel-m365",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,19 +10,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./extensions": {
+      "types": "./dist/extensions.d.ts",
+      "import": "./dist/extensions.js",
+      "default": "./dist/extensions.js"
     }
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
   "dependencies": {
-    "@cuylabs/agent-channel-m365": "^0.10.0",
-    "@cuylabs/agent-core": "^0.10.0"
+    "@microsoft/agents-activity": "^1.4.2",
+    "@microsoft/agents-hosting": "^1.4.2",
+    "@microsoft/agents-hosting-extensions-teams": "^1.4.2",
+    "@cuylabs/agent-channel-m365": "^0.12.0",
+    "@cuylabs/agent-core": "^0.12.0"
   },
   "peerDependencies": {
-    "@microsoft/agents-activity": ">=0.1.0",
-    "@microsoft/agents-hosting": ">=0.1.0",
     "express": ">=4.21.0 || >=5.0.0"
   },
   "peerDependenciesMeta": {
@@ -31,8 +38,6 @@
     }
   },
   "devDependencies": {
-    "@microsoft/agents-activity": "^1.4.2",
-    "@microsoft/agents-hosting": "^1.4.2",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     "express": "^5.2.1",
@@ -62,8 +67,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts src/extensions.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/extensions.ts --format esm --dts --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",