@cuylabs/agent-channel-teams 3.1.0 → 3.2.1

package/README.md

@@ -134,6 +134,36 @@ Teams handler handles the invoke, the adapter returns an explicit `501`.
 Build common Teams dialog/search invoke bodies without making callers hand-roll
 raw payload objects.
 
+### Interactive Request Cards
+
+`createTeamsApprovalRequestCard(...)`,
+`createTeamsHumanInputRequestCard(...)`, and
+`parseTeamsInputRequestSubmit(...)` provide the Teams UI pieces for approval and
+human-input requests. They are intentionally state-free: `agent-server` should
+own pending request state and turn resolution, while Teams renders cards and
+passes submit payloads back to `server.respondToInputRequest(...)`.
+
+```ts
+import {
+  createTeamsApprovalRequestCard,
+  parseTeamsInputRequestSubmit,
+} from "@cuylabs/agent-channel-teams";
+
+server.subscribe(async (notification) => {
+  if (notification.type !== "input/request") return;
+  if (notification.request.kind !== "approval") return;
+
+  await sendCardToTeams(
+    createTeamsApprovalRequestCard(notification.request),
+  );
+});
+
+const submit = parseTeamsInputRequestSubmit(ctx.turnContext.activity.value);
+if (submit) {
+  server.respondToInputRequest(submit.requestId, submit.payload);
+}
+```
+
 ## TeamsInfo and Typed Channel Data
 
 The curated Teams helper surface is available directly from the main barrel. If

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AgentEvent } from '@cuylabs/agent-core';
+import { AgentEvent, ApprovalRequest, HumanInputRequest, ApprovalAction, ApprovalRememberScope, HumanInputResponse } from '@cuylabs/agent-core';
 import { M365ChannelOptions, M365TurnRequestContext, M365TurnPreparation, M365UserIdentity, M365TurnSource, M365ChannelAdapter, M365AmbientTurnContext } from '@cuylabs/agent-channel-m365';
 import { TurnContext, AuthConfiguration, CloudAdapter } from '@microsoft/agents-hosting';
 import { TeamsChannelData } from '@microsoft/agents-hosting-extensions-teams';
@@ -295,6 +295,44 @@ interface TeamsDialogMessageBody {
 declare function createTeamsDialog(dialog: TeamsDialogDefinition): TeamsDialogResponse;
 declare function createTeamsDialogMessage(message: string): TeamsDialogMessageBody;
 
+declare const TEAMS_INPUT_REQUEST_APPROVAL_VERB = "cuylabs.agent.input.approval";
+declare const TEAMS_INPUT_REQUEST_HUMAN_VERB = "cuylabs.agent.input.human";
+type TeamsInputRequestVerb = typeof TEAMS_INPUT_REQUEST_APPROVAL_VERB | typeof TEAMS_INPUT_REQUEST_HUMAN_VERB;
+interface TeamsInputRequestEnvelope<TRequest> {
+    request: TRequest;
+    sessionId?: string;
+    turnId?: string;
+}
+type TeamsApprovalCardRequest = ApprovalRequest | TeamsInputRequestEnvelope<ApprovalRequest>;
+type TeamsHumanInputCardRequest = HumanInputRequest | TeamsInputRequestEnvelope<HumanInputRequest>;
+interface TeamsApprovalCardOptions {
+    title?: string;
+    includeArguments?: boolean;
+    maxArgumentChars?: number;
+}
+interface TeamsHumanInputCardOptions {
+    title?: string;
+}
+type TeamsResolveInputPayload = {
+    kind: "approval";
+    action: ApprovalAction;
+    feedback?: string;
+    rememberScope?: ApprovalRememberScope;
+} | {
+    kind: "human";
+    response: HumanInputResponse;
+};
+interface TeamsInputRequestSubmit {
+    verb: TeamsInputRequestVerb;
+    requestId: string;
+    sessionId?: string;
+    turnId?: string;
+    payload: TeamsResolveInputPayload;
+}
+declare function createTeamsApprovalRequestCard(input: TeamsApprovalCardRequest, options?: TeamsApprovalCardOptions): Attachment;
+declare function createTeamsHumanInputRequestCard(input: TeamsHumanInputCardRequest, options?: TeamsHumanInputCardOptions): Attachment;
+declare function parseTeamsInputRequestSubmit(value: unknown): TeamsInputRequestSubmit | undefined;
+
 interface ParseTeamsActivityOptions {
     strictChannelData?: boolean;
 }
@@ -322,4 +360,4 @@ declare const TEAMS_MEETING_INVOKE_NAMES: Readonly<Record<string, TeamsActivityK
 declare function parseTeamsActivity(context: TurnContext, options?: ParseTeamsActivityOptions): TeamsActivityInfo;
 declare function parseTeamsActivitySafe(context: TurnContext): TeamsActivityInfo;
 
-export { type MountTeamsAgentOptions, type MountTeamsAgentResult, type ParseTeamsActivityOptions, TEAMS_ACTIONABLE_MESSAGE_NAMES, TEAMS_ADAPTIVE_CARD_ACTION_NAMES, TEAMS_ADAPTIVE_CARD_SEARCH_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, type TeamsActivityHandler, type TeamsActivityHandlers, type TeamsActivityInfo, type TeamsActivityKind, type TeamsActorReference, type TeamsAmbientTurnContext, type TeamsCardActionHandlers, type TeamsChannelAdapter, type TeamsChannelOptions, type TeamsConfigHandlers, type TeamsConversationUpdateHandlers, type TeamsDialogDefinition, type TeamsDialogMessageBody, type TeamsDialogResponse, type TeamsDialogSize, type TeamsHandlerContext, type TeamsHandlerDecision, type TeamsInvokeResult, type TeamsMeetingHandlers, type TeamsMessageActivityHandlers, type TeamsMessageExtensionHandlers, type TeamsSearchAttachment, type TeamsSearchLayout, type TeamsSearchMessageBody, type TeamsSearchResponse, type TeamsSearchResult, type TeamsSearchResultBody, type TeamsSearchResultType, type TeamsSurface, type TeamsTabHandlers, type TeamsTaskModuleHandlers, type TeamsTurnPreparation, type TeamsTurnRequestContext, createTeamsChannelAdapter, createTeamsDialog, createTeamsDialogMessage, createTeamsInvokeActivity, createTeamsSearchMessage, createTeamsSearchResult, currentTeamsTurnContext, mountTeamsAgent, parseTeamsActivity, parseTeamsActivitySafe, runWithTeamsTurnContext, sendTeamsInvoke };
+export { type MountTeamsAgentOptions, type MountTeamsAgentResult, type ParseTeamsActivityOptions, TEAMS_ACTIONABLE_MESSAGE_NAMES, TEAMS_ADAPTIVE_CARD_ACTION_NAMES, TEAMS_ADAPTIVE_CARD_SEARCH_NAMES, TEAMS_CARD_ACTION_SUBMIT_NAMES, TEAMS_CONFIG_FETCH_NAMES, TEAMS_CONFIG_SUBMIT_NAMES, TEAMS_CONVERSATION_UPDATE_EVENT_NAMES, TEAMS_FILE_CONSENT_NAMES, TEAMS_INPUT_REQUEST_APPROVAL_VERB, TEAMS_INPUT_REQUEST_HUMAN_VERB, 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, type TeamsActivityHandler, type TeamsActivityHandlers, type TeamsActivityInfo, type TeamsActivityKind, type TeamsActorReference, type TeamsAmbientTurnContext, type TeamsApprovalCardOptions, type TeamsApprovalCardRequest, type TeamsCardActionHandlers, type TeamsChannelAdapter, type TeamsChannelOptions, type TeamsConfigHandlers, type TeamsConversationUpdateHandlers, type TeamsDialogDefinition, type TeamsDialogMessageBody, type TeamsDialogResponse, type TeamsDialogSize, type TeamsHandlerContext, type TeamsHandlerDecision, type TeamsHumanInputCardOptions, type TeamsHumanInputCardRequest, type TeamsInputRequestEnvelope, type TeamsInputRequestSubmit, type TeamsInputRequestVerb, type TeamsInvokeResult, type TeamsMeetingHandlers, type TeamsMessageActivityHandlers, type TeamsMessageExtensionHandlers, type TeamsResolveInputPayload, type TeamsSearchAttachment, type TeamsSearchLayout, type TeamsSearchMessageBody, type TeamsSearchResponse, type TeamsSearchResult, type TeamsSearchResultBody, type TeamsSearchResultType, type TeamsSurface, type TeamsTabHandlers, type TeamsTaskModuleHandlers, type TeamsTurnPreparation, type TeamsTurnRequestContext, createTeamsApprovalRequestCard, createTeamsChannelAdapter, createTeamsDialog, createTeamsDialogMessage, createTeamsHumanInputRequestCard, createTeamsInvokeActivity, createTeamsSearchMessage, createTeamsSearchResult, currentTeamsTurnContext, mountTeamsAgent, parseTeamsActivity, parseTeamsActivitySafe, parseTeamsInputRequestSubmit, runWithTeamsTurnContext, sendTeamsInvoke };

package/dist/index.js

@@ -768,6 +768,368 @@ function createTeamsDialogMessage(message) {
     }
   };
 }
+
+// src/interactive-requests.ts
+var TEAMS_INPUT_REQUEST_APPROVAL_VERB = "cuylabs.agent.input.approval";
+var TEAMS_INPUT_REQUEST_HUMAN_VERB = "cuylabs.agent.input.human";
+var ADAPTIVE_CARD_CONTENT_TYPE = "application/vnd.microsoft.card.adaptive";
+var DEFAULT_MAX_ARGUMENT_CHARS = 1200;
+function createTeamsApprovalRequestCard(input, options = {}) {
+  const { request, sessionId, turnId } = normalizeInputRequest(input);
+  const body = [
+    {
+      type: "TextBlock",
+      size: "Medium",
+      weight: "Bolder",
+      text: options.title ?? "Approval required",
+      wrap: true
+    },
+    {
+      type: "FactSet",
+      facts: [
+        { title: "Tool", value: request.tool },
+        { title: "Risk", value: request.risk }
+      ]
+    },
+    {
+      type: "TextBlock",
+      text: request.description,
+      wrap: true
+    }
+  ];
+  if (options.includeArguments ?? true) {
+    const formattedArgs = formatToolArguments(
+      request.args,
+      options.maxArgumentChars ?? DEFAULT_MAX_ARGUMENT_CHARS
+    );
+    if (formattedArgs) {
+      body.push({
+        type: "TextBlock",
+        text: formattedArgs,
+        wrap: true,
+        fontType: "Monospace",
+        isSubtle: true
+      });
+    }
+  }
+  const rememberScopes = normalizeRememberScopes(request);
+  if (rememberScopes.length > 0) {
+    body.push({
+      type: "Input.ChoiceSet",
+      id: "rememberScope",
+      label: "Remember scope",
+      style: "compact",
+      value: request.defaultRememberScope ?? rememberScopes[0],
+      choices: rememberScopes.map((scope) => ({
+        title: labelRememberScope(scope),
+        value: scope
+      }))
+    });
+  }
+  body.push({
+    type: "Input.Text",
+    id: "feedback",
+    label: "Feedback",
+    isMultiline: true,
+    isRequired: false,
+    placeholder: "Optional"
+  });
+  const baseData = {
+    requestId: request.id,
+    sessionId,
+    ...turnId ? { turnId } : {}
+  };
+  const actions = [
+    {
+      type: "Action.Submit",
+      title: "Approve",
+      data: {
+        ...baseData,
+        verb: TEAMS_INPUT_REQUEST_APPROVAL_VERB,
+        action: "allow"
+      }
+    },
+    {
+      type: "Action.Submit",
+      title: "Deny",
+      data: {
+        ...baseData,
+        verb: TEAMS_INPUT_REQUEST_APPROVAL_VERB,
+        action: "deny"
+      }
+    }
+  ];
+  if (rememberScopes.length > 0) {
+    actions.push({
+      type: "Action.Submit",
+      title: "Remember",
+      data: {
+        ...baseData,
+        verb: TEAMS_INPUT_REQUEST_APPROVAL_VERB,
+        action: "remember"
+      }
+    });
+  }
+  return createAdaptiveCardAttachment(body, actions);
+}
+function createTeamsHumanInputRequestCard(input, options = {}) {
+  const { request, sessionId, turnId } = normalizeInputRequest(input);
+  const body = [
+    {
+      type: "TextBlock",
+      size: "Medium",
+      weight: "Bolder",
+      text: options.title ?? request.title,
+      wrap: true
+    },
+    {
+      type: "TextBlock",
+      text: request.question,
+      wrap: true
+    }
+  ];
+  const baseData = {
+    requestId: request.id,
+    sessionId,
+    ...turnId ? { turnId } : {}
+  };
+  if (request.kind === "choice") {
+    body.push({
+      type: "Input.ChoiceSet",
+      id: "selected",
+      label: request.title,
+      style: request.allowMultiple ? "expanded" : "compact",
+      isMultiSelect: request.allowMultiple ?? false,
+      choices: (request.options ?? []).map((option) => ({
+        title: option.label,
+        value: option.value ?? option.label
+      }))
+    });
+  } else if (request.kind === "text") {
+    body.push({
+      type: "Input.Text",
+      id: "text",
+      label: request.title,
+      isMultiline: true,
+      placeholder: request.placeholder ?? "Type a response"
+    });
+  } else {
+    body.push({
+      type: "Input.Text",
+      id: "text",
+      label: "Details",
+      isMultiline: true,
+      isRequired: false,
+      placeholder: request.placeholder ?? "Optional"
+    });
+  }
+  const actions = request.kind === "confirm" ? [
+    {
+      type: "Action.Submit",
+      title: request.confirmLabel ?? "Confirm",
+      data: {
+        ...baseData,
+        verb: TEAMS_INPUT_REQUEST_HUMAN_VERB,
+        responseKind: "confirm",
+        confirmed: true
+      }
+    },
+    {
+      type: "Action.Submit",
+      title: request.denyLabel ?? "Cancel",
+      data: {
+        ...baseData,
+        verb: TEAMS_INPUT_REQUEST_HUMAN_VERB,
+        responseKind: "confirm",
+        confirmed: false
+      }
+    }
+  ] : [
+    {
+      type: "Action.Submit",
+      title: request.confirmLabel ?? "Submit",
+      data: {
+        ...baseData,
+        verb: TEAMS_INPUT_REQUEST_HUMAN_VERB,
+        responseKind: request.kind
+      }
+    }
+  ];
+  return createAdaptiveCardAttachment(body, actions);
+}
+function parseTeamsInputRequestSubmit(value) {
+  const data = readSubmitData(value);
+  const verb = readString2(data, "verb");
+  const requestId = readString2(data, "requestId");
+  if (!requestId || verb !== TEAMS_INPUT_REQUEST_APPROVAL_VERB && verb !== TEAMS_INPUT_REQUEST_HUMAN_VERB) {
+    return void 0;
+  }
+  const sessionId = readString2(data, "sessionId");
+  const turnId = readString2(data, "turnId");
+  if (verb === TEAMS_INPUT_REQUEST_APPROVAL_VERB) {
+    const action = readApprovalAction(data);
+    if (!action) {
+      return void 0;
+    }
+    const feedback = readTrimmedString(data, "feedback");
+    const rememberScope = action === "remember" ? readRememberScope(data) : void 0;
+    return {
+      verb,
+      requestId,
+      ...sessionId ? { sessionId } : {},
+      ...turnId ? { turnId } : {},
+      payload: {
+        kind: "approval",
+        action,
+        ...feedback ? { feedback } : {},
+        ...rememberScope ? { rememberScope } : {}
+      }
+    };
+  }
+  const response = readHumanInputResponse(data);
+  if (!response) {
+    return void 0;
+  }
+  return {
+    verb,
+    requestId,
+    ...sessionId ? { sessionId } : {},
+    ...turnId ? { turnId } : {},
+    payload: {
+      kind: "human",
+      response
+    }
+  };
+}
+function createAdaptiveCardAttachment(body, actions) {
+  return {
+    contentType: ADAPTIVE_CARD_CONTENT_TYPE,
+    content: {
+      type: "AdaptiveCard",
+      version: "1.5",
+      body,
+      actions
+    }
+  };
+}
+function normalizeInputRequest(input) {
+  if ("request" in input) {
+    return {
+      request: input.request,
+      sessionId: input.sessionId ?? input.request.sessionId,
+      ...input.turnId ? { turnId: input.turnId } : {}
+    };
+  }
+  return {
+    request: input,
+    sessionId: input.sessionId
+  };
+}
+function formatToolArguments(args, maxChars) {
+  let formatted;
+  try {
+    formatted = JSON.stringify(args, null, 2);
+  } catch {
+    return "";
+  }
+  if (!formatted || formatted === "undefined") {
+    return "";
+  }
+  if (formatted.length <= maxChars) {
+    return formatted;
+  }
+  return `${formatted.slice(0, Math.max(0, maxChars - 1))}...`;
+}
+function normalizeRememberScopes(request) {
+  const allowed = /* @__PURE__ */ new Set([
+    "session",
+    "project",
+    "user"
+  ]);
+  return (request.rememberScopes ?? []).filter((scope) => allowed.has(scope));
+}
+function labelRememberScope(scope) {
+  switch (scope) {
+    case "session":
+      return "This session";
+    case "project":
+      return "This project";
+    case "user":
+      return "My user";
+  }
+}
+function readSubmitData(value) {
+  const record = asRecord(value);
+  const nested = asRecord(record?.data);
+  return {
+    ...nested ?? {},
+    ...record ?? {}
+  };
+}
+function readHumanInputResponse(data) {
+  const responseKind = readString2(data, "responseKind");
+  switch (responseKind) {
+    case "text": {
+      const text = readString2(data, "text") ?? "";
+      return { kind: "text", text };
+    }
+    case "confirm": {
+      const confirmed = readBoolean(data, "confirmed");
+      if (confirmed === void 0) {
+        return void 0;
+      }
+      const text = readString2(data, "text") ?? (confirmed ? "confirmed" : "denied");
+      return { kind: "confirm", confirmed, text };
+    }
+    case "choice": {
+      const selected = readSelectedValues(data, "selected");
+      return { kind: "choice", selected, text: selected.join(", ") };
+    }
+    default:
+      return void 0;
+  }
+}
+function readApprovalAction(data) {
+  const action = readString2(data, "action");
+  return action === "allow" || action === "deny" || action === "remember" ? action : void 0;
+}
+function readRememberScope(data) {
+  const scope = readString2(data, "rememberScope");
+  return scope === "session" || scope === "project" || scope === "user" ? scope : void 0;
+}
+function readSelectedValues(data, key) {
+  const value = data[key];
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+}
+function readTrimmedString(data, key) {
+  return readString2(data, key)?.trim() || void 0;
+}
+function readString2(data, key) {
+  const value = data?.[key];
+  return typeof value === "string" ? value : void 0;
+}
+function readBoolean(data, key) {
+  const value = data[key];
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (value === "true") {
+    return true;
+  }
+  if (value === "false") {
+    return false;
+  }
+  return void 0;
+}
+function asRecord(value) {
+  return value && typeof value === "object" ? value : void 0;
+}
 export {
   TEAMS_ACTIONABLE_MESSAGE_NAMES,
   TEAMS_ADAPTIVE_CARD_ACTION_NAMES,
@@ -777,6 +1139,8 @@ export {
   TEAMS_CONFIG_SUBMIT_NAMES,
   TEAMS_CONVERSATION_UPDATE_EVENT_NAMES,
   TEAMS_FILE_CONSENT_NAMES,
+  TEAMS_INPUT_REQUEST_APPROVAL_VERB,
+  TEAMS_INPUT_REQUEST_HUMAN_VERB,
   TEAMS_MEETING_EVENT_NAMES,
   TEAMS_MEETING_INVOKE_NAMES,
   TEAMS_MESSAGE_EXTENSION_CARD_BUTTON_CLICKED_NAMES,
@@ -792,9 +1156,11 @@ export {
   TEAMS_TASK_MODULE_SUBMIT_NAMES,
   TeamsAttachmentDownloader,
   TeamsInfo,
+  createTeamsApprovalRequestCard,
   createTeamsChannelAdapter,
   createTeamsDialog,
   createTeamsDialogMessage,
+  createTeamsHumanInputRequestCard,
   createTeamsInvokeActivity,
   createTeamsSearchMessage,
   createTeamsSearchResult,
@@ -803,6 +1169,7 @@ export {
   parseTeamsActivity,
   parseTeamsActivitySafe,
   parseTeamsChannelData,
+  parseTeamsInputRequestSubmit,
   runWithTeamsTurnContext,
   sendTeamsInvoke
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-channel-teams",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Teams-native channel layer for @cuylabs/agent-core built on top of @cuylabs/agent-channel-m365",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,8 +24,8 @@
   ],
   "dependencies": {
     "@microsoft/agents-hosting-extensions-teams": "^1.4.2",
-    "@cuylabs/agent-channel-m365": "^3.1.0",
-    "@cuylabs/agent-core": "^3.1.0"
+    "@cuylabs/agent-channel-m365": "^3.2.1",
+    "@cuylabs/agent-core": "^3.2.1"
   },
   "peerDependencies": {
     "@microsoft/agents-activity": "^1.4.2",