@openclaw/msteams 2026.3.13 → 2026.5.2-beta.1

package/src/feedback-reflection.ts

@@ -0,0 +1,283 @@
+/**
+ * Background reflection triggered by negative user feedback (thumbs-down).
+ *
+ * Flow:
+ * 1. User thumbs-down -> invoke handler acks immediately
+ * 2. This module runs in the background (fire-and-forget)
+ * 3. Reads recent session context
+ * 4. Sends a synthetic reflection prompt to the agent
+ * 5. Stores the derived learning in session
+ * 6. Optionally sends a proactive follow-up to the user
+ */
+
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
+import {
+  dispatchReplyFromConfigWithSettledDispatcher,
+  type OpenClawConfig,
+} from "../runtime-api.js";
+import type { StoredConversationReference } from "./conversation-store.js";
+import { formatUnknownError } from "./errors.js";
+import { buildReflectionPrompt, parseReflectionResponse } from "./feedback-reflection-prompt.js";
+import {
+  DEFAULT_COOLDOWN_MS,
+  clearReflectionCooldowns,
+  isReflectionAllowed,
+  loadSessionLearnings,
+  recordReflectionTime,
+  storeSessionLearning,
+} from "./feedback-reflection-store.js";
+import type { MSTeamsAdapter } from "./messenger.js";
+import { buildConversationReference } from "./messenger.js";
+import type { MSTeamsMonitorLogger } from "./monitor-types.js";
+import { getMSTeamsRuntime } from "./runtime.js";
+
+type FeedbackEvent = {
+  type: "custom";
+  event: "feedback";
+  ts: number;
+  messageId: string;
+  value: "positive" | "negative";
+  comment?: string;
+  sessionKey: string;
+  agentId: string;
+  conversationId: string;
+  reflectionLearning?: string;
+};
+
+export function buildFeedbackEvent(params: {
+  messageId: string;
+  value: "positive" | "negative";
+  comment?: string;
+  sessionKey: string;
+  agentId: string;
+  conversationId: string;
+}): FeedbackEvent {
+  return {
+    type: "custom",
+    event: "feedback",
+    ts: Date.now(),
+    messageId: params.messageId,
+    value: params.value,
+    comment: params.comment,
+    sessionKey: params.sessionKey,
+    agentId: params.agentId,
+    conversationId: params.conversationId,
+  };
+}
+
+type RunFeedbackReflectionParams = {
+  cfg: OpenClawConfig;
+  adapter: MSTeamsAdapter;
+  appId: string;
+  conversationRef: StoredConversationReference;
+  sessionKey: string;
+  agentId: string;
+  conversationId: string;
+  feedbackMessageId: string;
+  thumbedDownResponse?: string;
+  userComment?: string;
+  log: MSTeamsMonitorLogger;
+};
+
+function buildReflectionContext(params: {
+  cfg: OpenClawConfig;
+  conversationId: string;
+  sessionKey: string;
+  reflectionPrompt: string;
+}) {
+  const core = getMSTeamsRuntime();
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(params.cfg);
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "Teams",
+    from: "system",
+    body: params.reflectionPrompt,
+    envelope: envelopeOptions,
+  });
+
+  return {
+    ctxPayload: core.channel.reply.finalizeInboundContext({
+      Body: body,
+      BodyForAgent: params.reflectionPrompt,
+      RawBody: params.reflectionPrompt,
+      CommandBody: params.reflectionPrompt,
+      From: `msteams:system:${params.conversationId}`,
+      To: `conversation:${params.conversationId}`,
+      SessionKey: params.sessionKey,
+      ChatType: "direct" as const,
+      SenderName: "system",
+      SenderId: "system",
+      Provider: "msteams" as const,
+      Surface: "msteams" as const,
+      Timestamp: Date.now(),
+      WasMentioned: true,
+      CommandAuthorized: false,
+      OriginatingChannel: "msteams" as const,
+      OriginatingTo: `conversation:${params.conversationId}`,
+    }),
+  };
+}
+
+function createReflectionCaptureDispatcher(params: {
+  cfg: OpenClawConfig;
+  agentId: string;
+  log: MSTeamsMonitorLogger;
+}) {
+  const core = getMSTeamsRuntime();
+  let response = "";
+  const noopTypingCallbacks = {
+    onReplyStart: async () => {},
+    onIdle: () => {},
+    onCleanup: () => {},
+  };
+
+  const { dispatcher, replyOptions } = core.channel.reply.createReplyDispatcherWithTyping({
+    deliver: async (payload) => {
+      if (payload.text) {
+        response += (response ? "\n" : "") + payload.text;
+      }
+    },
+    typingCallbacks: noopTypingCallbacks,
+    humanDelay: core.channel.reply.resolveHumanDelayConfig(params.cfg, params.agentId),
+    onError: (err) => {
+      params.log.debug?.("reflection reply error", { error: formatUnknownError(err) });
+    },
+  });
+
+  return {
+    dispatcher,
+    replyOptions,
+    readResponse: () => response,
+  };
+}
+
+async function sendReflectionFollowUp(params: {
+  adapter: MSTeamsAdapter;
+  appId: string;
+  conversationRef: StoredConversationReference;
+  userMessage: string;
+}): Promise<void> {
+  const baseRef = buildConversationReference(params.conversationRef);
+  const proactiveRef = { ...baseRef, activityId: undefined };
+
+  await params.adapter.continueConversation(params.appId, proactiveRef, async (ctx) => {
+    await ctx.sendActivity({
+      type: "message",
+      text: params.userMessage,
+    });
+  });
+}
+
+/**
+ * Run a background reflection after negative feedback.
+ * This is designed to be called fire-and-forget (don't await in the invoke handler).
+ */
+export async function runFeedbackReflection(params: RunFeedbackReflectionParams): Promise<void> {
+  const { cfg, log, sessionKey } = params;
+  const cooldownMs = cfg.channels?.msteams?.feedbackReflectionCooldownMs ?? DEFAULT_COOLDOWN_MS;
+  if (!isReflectionAllowed(sessionKey, cooldownMs)) {
+    log.debug?.("skipping reflection (cooldown active)", { sessionKey });
+    return;
+  }
+
+  const reflectionPrompt = buildReflectionPrompt({
+    thumbedDownResponse: params.thumbedDownResponse,
+    userComment: params.userComment,
+  });
+  const runtime = getMSTeamsRuntime();
+  const storePath = runtime.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: params.agentId,
+  });
+  const { ctxPayload } = buildReflectionContext({
+    cfg,
+    conversationId: params.conversationId,
+    sessionKey: params.sessionKey,
+    reflectionPrompt,
+  });
+
+  const capture = createReflectionCaptureDispatcher({
+    cfg,
+    agentId: params.agentId,
+    log,
+  });
+
+  try {
+    await dispatchReplyFromConfigWithSettledDispatcher({
+      ctxPayload,
+      cfg,
+      dispatcher: capture.dispatcher,
+      onSettled: () => {},
+      replyOptions: capture.replyOptions,
+    });
+  } catch (err) {
+    log.error("reflection dispatch failed", { error: formatUnknownError(err) });
+    return;
+  }
+
+  const reflectionResponse = capture.readResponse().trim();
+  if (!reflectionResponse) {
+    log.debug?.("reflection produced no output");
+    return;
+  }
+
+  const parsedReflection = parseReflectionResponse(reflectionResponse);
+  if (!parsedReflection) {
+    log.debug?.("reflection produced no structured output");
+    return;
+  }
+
+  recordReflectionTime(sessionKey, cooldownMs);
+  log.info("reflection complete", {
+    sessionKey,
+    responseLength: reflectionResponse.length,
+    followUp: parsedReflection.followUp,
+  });
+
+  try {
+    await storeSessionLearning({
+      storePath,
+      sessionKey: params.sessionKey,
+      learning: parsedReflection.learning,
+    });
+  } catch (err) {
+    log.debug?.("failed to store reflection learning", { error: formatUnknownError(err) });
+  }
+
+  const conversationType = normalizeOptionalLowercaseString(
+    params.conversationRef.conversation?.conversationType,
+  );
+  const shouldNotify =
+    conversationType === "personal" &&
+    parsedReflection.followUp &&
+    Boolean(parsedReflection.userMessage);
+
+  if (!shouldNotify) {
+    if (parsedReflection.followUp && conversationType !== "personal") {
+      log.debug?.("skipping reflection follow-up outside direct message", {
+        sessionKey,
+        conversationType,
+      });
+    }
+    return;
+  }
+
+  try {
+    await sendReflectionFollowUp({
+      adapter: params.adapter,
+      appId: params.appId,
+      conversationRef: params.conversationRef,
+      userMessage: parsedReflection.userMessage!,
+    });
+    log.info("sent reflection follow-up", { sessionKey });
+  } catch (err) {
+    log.debug?.("failed to send reflection follow-up", { error: formatUnknownError(err) });
+  }
+}
+
+export {
+  buildReflectionPrompt,
+  clearReflectionCooldowns,
+  isReflectionAllowed,
+  loadSessionLearnings,
+  parseReflectionResponse,
+  recordReflectionTime,
+};

package/src/file-consent-helpers.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
 import { prepareFileConsentActivity, requiresFileConsent } from "./file-consent-helpers.js";
+import {
+  clearPendingUploads,
+  getPendingUpload,
+  getPendingUploadCount,
+  removePendingUpload,
+  storePendingUpload,
+} from "./pending-uploads.js";
 import * as pendingUploads from "./pending-uploads.js";
 
 describe("requiresFileConsent", () => {
@@ -241,3 +248,79 @@ describe("prepareFileConsentActivity", () => {
     expect(result.activity.type).toBe("message");
   });
 });
+
+describe("msteams pending uploads", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    clearPendingUploads();
+  });
+
+  afterEach(() => {
+    clearPendingUploads();
+    vi.useRealTimers();
+  });
+
+  it("stores uploads, exposes them by id, and tracks count", () => {
+    const id = storePendingUpload({
+      buffer: Buffer.from("hello"),
+      filename: "hello.txt",
+      contentType: "text/plain",
+      conversationId: "conv-1",
+    });
+
+    expect(getPendingUploadCount()).toBe(1);
+    expect(getPendingUpload(id)).toEqual(
+      expect.objectContaining({
+        id,
+        filename: "hello.txt",
+        contentType: "text/plain",
+        conversationId: "conv-1",
+      }),
+    );
+  });
+
+  it("removes uploads explicitly and ignores empty ids", () => {
+    const id = storePendingUpload({
+      buffer: Buffer.from("hello"),
+      filename: "hello.txt",
+      conversationId: "conv-1",
+    });
+
+    removePendingUpload(undefined);
+    expect(getPendingUploadCount()).toBe(1);
+
+    removePendingUpload(id);
+    expect(getPendingUpload(id)).toBeUndefined();
+    expect(getPendingUploadCount()).toBe(0);
+  });
+
+  it("expires uploads by ttl even if the timeout callback has not been observed yet", () => {
+    const id = storePendingUpload({
+      buffer: Buffer.from("hello"),
+      filename: "hello.txt",
+      conversationId: "conv-1",
+    });
+
+    vi.advanceTimersByTime(5 * 60 * 1000 + 1);
+
+    expect(getPendingUpload(id)).toBeUndefined();
+    expect(getPendingUploadCount()).toBe(0);
+  });
+
+  it("clears all uploads for test cleanup", () => {
+    storePendingUpload({
+      buffer: Buffer.from("a"),
+      filename: "a.txt",
+      conversationId: "conv-1",
+    });
+    storePendingUpload({
+      buffer: Buffer.from("b"),
+      filename: "b.txt",
+      conversationId: "conv-2",
+    });
+
+    clearPendingUploads();
+
+    expect(getPendingUploadCount()).toBe(0);
+  });
+});

package/src/file-consent-helpers.ts

@@ -9,23 +9,48 @@
  * and messenger.ts (reply path) to avoid duplication.
  */
 
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
 import { buildFileConsentCard } from "./file-consent.js";
+import { storePendingUploadFs } from "./pending-uploads-fs.js";
 import { storePendingUpload } from "./pending-uploads.js";
 
-export type FileConsentMedia = {
+type FileConsentMedia = {
   buffer: Buffer;
   filename: string;
   contentType?: string;
 };
 
-export type FileConsentActivityResult = {
+type FileConsentActivityResult = {
   activity: Record<string, unknown>;
   uploadId: string;
 };
 
+function buildConsentActivity(params: {
+  media: FileConsentMedia;
+  description?: string;
+  uploadId: string;
+}): Record<string, unknown> {
+  const { media, description, uploadId } = params;
+  const consentCard = buildFileConsentCard({
+    filename: media.filename,
+    description: description || `File: ${media.filename}`,
+    sizeInBytes: media.buffer.length,
+    context: { uploadId },
+  });
+  return {
+    type: "message",
+    attachments: [consentCard],
+  };
+}
+
 /**
  * Prepare a FileConsentCard activity for large files or non-images in personal chats.
  * Returns the activity object and uploadId - caller is responsible for sending.
+ *
+ * This variant only writes to the in-memory store. Use it when the caller and
+ * the `fileConsent/invoke` handler share the same process (for example the
+ * messenger reply path). For proactive CLI sends where the invoke arrives in
+ * a different process, use {@link prepareFileConsentActivityFs} instead.
  */
 export function prepareFileConsentActivity(params: {
   media: FileConsentMedia;
@@ -41,18 +66,46 @@ export function prepareFileConsentActivity(params: {
     conversationId,
   });
 
-  const consentCard = buildFileConsentCard({
+  const activity = buildConsentActivity({ media, description, uploadId });
+  return { activity, uploadId };
+}
+
+/**
+ * Prepare a FileConsentCard activity and persist the pending upload to the
+ * filesystem so a different process can read it when the user accepts.
+ *
+ * This is used by the proactive CLI `message send --media` path: the CLI
+ * process sends the card and exits, but the `fileConsent/invoke` callback is
+ * delivered to the long-lived gateway monitor process. The FS-backed store
+ * bridges those two processes. The in-memory store is also populated so
+ * same-process flows keep the fast path.
+ */
+export async function prepareFileConsentActivityFs(params: {
+  media: FileConsentMedia;
+  conversationId: string;
+  description?: string;
+}): Promise<FileConsentActivityResult> {
+  const { media, conversationId, description } = params;
+
+  // Populate the in-memory store first so the uploadId is consistent, then
+  // mirror the same entry to the FS store under the same id so an invoke
+  // handler in another process can find it.
+  const uploadId = storePendingUpload({
+    buffer: media.buffer,
     filename: media.filename,
-    description: description || `File: ${media.filename}`,
-    sizeInBytes: media.buffer.length,
-    context: { uploadId },
+    contentType: media.contentType,
+    conversationId,
   });
 
-  const activity: Record<string, unknown> = {
-    type: "message",
-    attachments: [consentCard],
-  };
+  await storePendingUploadFs({
+    id: uploadId,
+    buffer: media.buffer,
+    filename: media.filename,
+    contentType: media.contentType,
+    conversationId,
+  });
 
+  const activity = buildConsentActivity({ media, description, uploadId });
   return { activity, uploadId };
 }
 
@@ -66,7 +119,7 @@ export function requiresFileConsent(params: {
   bufferSize: number;
   thresholdBytes: number;
 }): boolean {
-  const isPersonal = params.conversationType?.toLowerCase() === "personal";
+  const isPersonal = normalizeOptionalLowercaseString(params.conversationType) === "personal";
   const isImage = params.contentType?.startsWith("image/") ?? false;
   const isLargeFile = params.bufferSize >= params.thresholdBytes;
   return isPersonal && (isLargeFile || !isImage);

package/src/file-consent-invoke.ts

@@ -0,0 +1,150 @@
+import { formatUnknownError } from "./errors.js";
+import { buildFileInfoCard, parseFileConsentInvoke, uploadToConsentUrl } from "./file-consent.js";
+import { normalizeMSTeamsConversationId } from "./inbound.js";
+import type { MSTeamsMonitorLogger } from "./monitor-types.js";
+import { getPendingUploadFs, removePendingUploadFs } from "./pending-uploads-fs.js";
+import { getPendingUpload, removePendingUpload } from "./pending-uploads.js";
+import { withRevokedProxyFallback } from "./revoked-context.js";
+import type { MSTeamsTurnContext } from "./sdk-types.js";
+
+/**
+ * Handle fileConsent/invoke activities for large file uploads.
+ */
+async function handleMSTeamsFileConsentInvoke(
+  context: MSTeamsTurnContext,
+  log: MSTeamsMonitorLogger,
+): Promise<boolean> {
+  const expiredUploadMessage =
+    "The file upload request has expired. Please try sending the file again.";
+  const activity = context.activity;
+  if (activity.type !== "invoke" || activity.name !== "fileConsent/invoke") {
+    return false;
+  }
+
+  const consentResponse = parseFileConsentInvoke(activity);
+  if (!consentResponse) {
+    log.debug?.("invalid file consent invoke", { value: activity.value });
+    return false;
+  }
+
+  const uploadId =
+    typeof consentResponse.context?.uploadId === "string"
+      ? consentResponse.context.uploadId
+      : undefined;
+  // Prefer the in-memory store (same-process reply path); fall back to the
+  // FS-backed store so CLI `message send --media` flows work even when the
+  // invoke callback is delivered to a different process.
+  const inMemoryFile = getPendingUpload(uploadId);
+  const fsFile = inMemoryFile ? undefined : await getPendingUploadFs(uploadId);
+  const pendingFile:
+    | {
+        buffer: Buffer;
+        filename: string;
+        contentType?: string;
+        conversationId: string;
+        consentCardActivityId?: string;
+      }
+    | undefined = inMemoryFile ?? fsFile;
+  if (pendingFile) {
+    const pendingConversationId = normalizeMSTeamsConversationId(pendingFile.conversationId);
+    const invokeConversationId = normalizeMSTeamsConversationId(activity.conversation?.id ?? "");
+    if (!invokeConversationId || pendingConversationId !== invokeConversationId) {
+      log.info("file consent conversation mismatch", {
+        uploadId,
+        expectedConversationId: pendingConversationId,
+        receivedConversationId: invokeConversationId || undefined,
+      });
+      if (consentResponse.action === "accept") {
+        await context.sendActivity(expiredUploadMessage);
+      }
+      return true;
+    }
+  }
+
+  if (consentResponse.action === "accept" && consentResponse.uploadInfo) {
+    if (pendingFile) {
+      log.debug?.("user accepted file consent, uploading", {
+        uploadId,
+        filename: pendingFile.filename,
+        size: pendingFile.buffer.length,
+      });
+
+      try {
+        await uploadToConsentUrl({
+          url: consentResponse.uploadInfo.uploadUrl,
+          buffer: pendingFile.buffer,
+          contentType: pendingFile.contentType,
+        });
+
+        const fileInfoCard = buildFileInfoCard({
+          filename: consentResponse.uploadInfo.name,
+          contentUrl: consentResponse.uploadInfo.contentUrl,
+          uniqueId: consentResponse.uploadInfo.uniqueId,
+          fileType: consentResponse.uploadInfo.fileType,
+        });
+
+        if (!pendingFile.consentCardActivityId) {
+          await context.sendActivity({
+            type: "message",
+            attachments: [fileInfoCard],
+          });
+        }
+
+        if (pendingFile.consentCardActivityId) {
+          try {
+            await context.updateActivity({
+              id: pendingFile.consentCardActivityId,
+              type: "message",
+              attachments: [fileInfoCard],
+            });
+          } catch {
+            await context.sendActivity({
+              type: "message",
+              attachments: [fileInfoCard],
+            });
+          }
+        }
+
+        log.info("file upload complete", {
+          uploadId,
+          filename: consentResponse.uploadInfo.name,
+          uniqueId: consentResponse.uploadInfo.uniqueId,
+        });
+      } catch (err) {
+        log.error("file upload failed", { uploadId, error: formatUnknownError(err) });
+        await context.sendActivity("File upload failed. Please try again.");
+      } finally {
+        removePendingUpload(uploadId);
+        await removePendingUploadFs(uploadId);
+      }
+    } else {
+      log.debug?.("pending file not found for consent", { uploadId });
+      await context.sendActivity(expiredUploadMessage);
+    }
+  } else {
+    log.debug?.("user declined file consent", { uploadId });
+    removePendingUpload(uploadId);
+    await removePendingUploadFs(uploadId);
+  }
+
+  return true;
+}
+
+export async function respondToMSTeamsFileConsentInvoke(
+  context: MSTeamsTurnContext,
+  log: MSTeamsMonitorLogger,
+): Promise<void> {
+  await context.sendActivity({ type: "invokeResponse", value: { status: 200 } });
+
+  try {
+    await withRevokedProxyFallback({
+      run: async () => await handleMSTeamsFileConsentInvoke(context, log),
+      onRevoked: async () => true,
+      onRevokedLog: () => {
+        log.debug?.("turn context revoked during file consent invoke; skipping delayed response");
+      },
+    });
+  } catch (err) {
+    log.debug?.("file consent handler error", { error: formatUnknownError(err) });
+  }
+}