@openclaw/msteams 2026.3.13 → 2026.5.1-beta.1

package/src/errors.ts

@@ -1,3 +1,7 @@
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 export function formatUnknownError(err: unknown): string {
   if (err instanceof Error) {
     return err.message;
@@ -27,10 +31,6 @@ export function formatUnknownError(err: unknown): string {
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function extractStatusCode(err: unknown): number | null {
   if (!isRecord(err)) {
     return null;
@@ -63,6 +63,32 @@ function extractStatusCode(err: unknown): number | null {
   return null;
 }
 
+function extractErrorCode(err: unknown): string | null {
+  if (!isRecord(err)) {
+    return null;
+  }
+
+  const direct = err.code;
+  if (typeof direct === "string" && direct.trim()) {
+    return direct;
+  }
+
+  const response = err.response;
+  if (!isRecord(response)) {
+    return null;
+  }
+
+  const body = response.body;
+  if (isRecord(body)) {
+    const error = body.error;
+    if (isRecord(error) && typeof error.code === "string" && error.code.trim()) {
+      return error.code;
+    }
+  }
+
+  return null;
+}
+
 function extractRetryAfterMs(err: unknown): number | null {
   if (!isRecord(err)) {
     return null;
@@ -123,12 +149,13 @@ function extractRetryAfterMs(err: unknown): number | null {
   return null;
 }
 
-export type MSTeamsSendErrorKind = "auth" | "throttled" | "transient" | "permanent" | "unknown";
+type MSTeamsSendErrorKind = "auth" | "throttled" | "transient" | "permanent" | "unknown";
 
-export type MSTeamsSendErrorClassification = {
+type MSTeamsSendErrorClassification = {
   kind: MSTeamsSendErrorKind;
   statusCode?: number;
   retryAfterMs?: number;
+  errorCode?: string;
 };
 
 /**
@@ -142,9 +169,17 @@ export type MSTeamsSendErrorClassification = {
 export function classifyMSTeamsSendError(err: unknown): MSTeamsSendErrorClassification {
   const statusCode = extractStatusCode(err);
   const retryAfterMs = extractRetryAfterMs(err);
+  const errorCode = extractErrorCode(err) ?? undefined;
 
-  if (statusCode === 401 || statusCode === 403) {
-    return { kind: "auth", statusCode };
+  if (statusCode === 401) {
+    return { kind: "auth", statusCode, errorCode };
+  }
+
+  if (statusCode === 403) {
+    if (errorCode === "ContentStreamNotAllowed") {
+      return { kind: "permanent", statusCode, errorCode };
+    }
+    return { kind: "auth", statusCode, errorCode };
   }
 
   if (statusCode === 429) {
@@ -152,6 +187,7 @@ export function classifyMSTeamsSendError(err: unknown): MSTeamsSendErrorClassifi
       kind: "throttled",
       statusCode,
       retryAfterMs: retryAfterMs ?? undefined,
+      errorCode,
     };
   }
 
@@ -160,17 +196,19 @@ export function classifyMSTeamsSendError(err: unknown): MSTeamsSendErrorClassifi
       kind: "transient",
       statusCode,
       retryAfterMs: retryAfterMs ?? undefined,
+      errorCode,
     };
   }
 
   if (statusCode != null && statusCode >= 400) {
-    return { kind: "permanent", statusCode };
+    return { kind: "permanent", statusCode, errorCode };
   }
 
   return {
     kind: "unknown",
     statusCode: statusCode ?? undefined,
     retryAfterMs: retryAfterMs ?? undefined,
+    errorCode,
   };
 }
 
@@ -195,6 +233,9 @@ export function formatMSTeamsSendErrorHint(
   if (classification.kind === "auth") {
     return "check msteams appId/appPassword/tenantId (or env vars MSTEAMS_APP_ID/MSTEAMS_APP_PASSWORD/MSTEAMS_TENANT_ID)";
   }
+  if (classification.errorCode === "ContentStreamNotAllowed") {
+    return "Teams expired the content stream; stop streaming earlier and fall back to normal message delivery";
+  }
   if (classification.kind === "throttled") {
     return "Teams throttled the bot; backing off may help";
   }

package/src/feedback-reflection-prompt.ts

@@ -0,0 +1,117 @@
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
+
+/** Max chars of the thumbed-down response to include in the reflection prompt. */
+const MAX_RESPONSE_CHARS = 500;
+
+type ParsedReflectionResponse = {
+  learning: string;
+  followUp: boolean;
+  userMessage?: string;
+};
+
+export function buildReflectionPrompt(params: {
+  thumbedDownResponse?: string;
+  userComment?: string;
+}): string {
+  const parts: string[] = ["A user indicated your previous response wasn't helpful."];
+
+  if (params.thumbedDownResponse) {
+    const truncated =
+      params.thumbedDownResponse.length > MAX_RESPONSE_CHARS
+        ? `${params.thumbedDownResponse.slice(0, MAX_RESPONSE_CHARS)}...`
+        : params.thumbedDownResponse;
+    parts.push(`\nYour response was:\n> ${truncated}`);
+  }
+
+  if (params.userComment) {
+    parts.push(`\nUser's comment: "${params.userComment}"`);
+  }
+
+  parts.push(
+    "\nBriefly reflect: what could you improve? Consider tone, length, " +
+      "accuracy, relevance, and specificity. Reply with a single JSON object " +
+      'only, no markdown or prose, using this exact shape:\n{"learning":"...",' +
+      '"followUp":false,"userMessage":""}\n' +
+      "- learning: a short internal adjustment note (1-2 sentences) for your " +
+      "future behavior in this conversation.\n" +
+      "- followUp: true only if the user needs a direct follow-up message.\n" +
+      "- userMessage: only the exact user-facing message to send; empty string " +
+      "when followUp is false.",
+  );
+
+  return parts.join("\n");
+}
+
+function parseBooleanLike(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    const normalized = normalizeOptionalLowercaseString(value);
+    if (normalized === "true" || normalized === "yes") {
+      return true;
+    }
+    if (normalized === "false" || normalized === "no") {
+      return false;
+    }
+  }
+  return undefined;
+}
+
+function parseStructuredReflectionValue(value: unknown): ParsedReflectionResponse | null {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  const candidate = value as {
+    learning?: unknown;
+    followUp?: unknown;
+    userMessage?: unknown;
+  };
+  const learning = typeof candidate.learning === "string" ? candidate.learning.trim() : undefined;
+  if (!learning) {
+    return null;
+  }
+
+  return {
+    learning,
+    followUp: parseBooleanLike(candidate.followUp) ?? false,
+    userMessage:
+      typeof candidate.userMessage === "string" && candidate.userMessage.trim()
+        ? candidate.userMessage.trim()
+        : undefined,
+  };
+}
+
+export function parseReflectionResponse(text: string): ParsedReflectionResponse | null {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const candidates = [
+    trimmed,
+    ...(trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i)?.slice(1, 2) ?? []),
+  ];
+
+  for (const candidateText of candidates) {
+    const candidate = candidateText.trim();
+    if (!candidate) {
+      continue;
+    }
+    try {
+      const parsed = parseStructuredReflectionValue(JSON.parse(candidate));
+      if (parsed) {
+        return parsed;
+      }
+    } catch {
+      // Fall through to the next parse strategy.
+    }
+  }
+
+  // Safe fallback: keep the internal learning, but never auto-message the user.
+  return {
+    learning: trimmed,
+    followUp: false,
+  };
+}

package/src/feedback-reflection-store.ts

@@ -0,0 +1,114 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/** Default cooldown between reflections per session (5 minutes). */
+export const DEFAULT_COOLDOWN_MS = 300_000;
+
+/** Tracks last reflection time per session to enforce cooldown. */
+const lastReflectionBySession = new Map<string, number>();
+
+/** Maximum cooldown entries before pruning expired ones. */
+const MAX_COOLDOWN_ENTRIES = 500;
+
+function legacySanitizeSessionKey(sessionKey: string): string {
+  return sessionKey.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function encodeSessionKey(sessionKey: string): string {
+  return Buffer.from(sessionKey, "utf8").toString("base64url");
+}
+
+function resolveLearningsFilePath(storePath: string, sessionKey: string): string {
+  return `${storePath}/${encodeSessionKey(sessionKey)}.learnings.json`;
+}
+
+function resolveLegacyLearningsFilePath(storePath: string, sessionKey: string): string {
+  return `${storePath}/${legacySanitizeSessionKey(sessionKey)}.learnings.json`;
+}
+
+async function readLearningsFile(
+  filePath: string,
+): Promise<{ exists: boolean; learnings: string[] }> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(content);
+    return { exists: true, learnings: Array.isArray(parsed) ? parsed : [] };
+  } catch {
+    return { exists: false, learnings: [] };
+  }
+}
+
+/** Prune expired cooldown entries to prevent unbounded memory growth. */
+function pruneExpiredCooldowns(cooldownMs: number): void {
+  if (lastReflectionBySession.size <= MAX_COOLDOWN_ENTRIES) {
+    return;
+  }
+  const now = Date.now();
+  for (const [key, time] of lastReflectionBySession) {
+    if (now - time >= cooldownMs) {
+      lastReflectionBySession.delete(key);
+    }
+  }
+}
+
+/** Check if a reflection is allowed (cooldown not active). */
+export function isReflectionAllowed(sessionKey: string, cooldownMs?: number): boolean {
+  const cooldown = cooldownMs ?? DEFAULT_COOLDOWN_MS;
+  const lastTime = lastReflectionBySession.get(sessionKey);
+  if (lastTime == null) {
+    return true;
+  }
+  return Date.now() - lastTime >= cooldown;
+}
+
+/** Record that a reflection was run for a session. */
+export function recordReflectionTime(sessionKey: string, cooldownMs?: number): void {
+  lastReflectionBySession.set(sessionKey, Date.now());
+  pruneExpiredCooldowns(cooldownMs ?? DEFAULT_COOLDOWN_MS);
+}
+
+/** Clear reflection cooldown tracking (for tests). */
+export function clearReflectionCooldowns(): void {
+  lastReflectionBySession.clear();
+}
+
+/** Store a learning derived from feedback reflection in a session companion file. */
+export async function storeSessionLearning(params: {
+  storePath: string;
+  sessionKey: string;
+  learning: string;
+}): Promise<void> {
+  const learningsFile = resolveLearningsFilePath(params.storePath, params.sessionKey);
+  const legacyLearningsFile = resolveLegacyLearningsFilePath(params.storePath, params.sessionKey);
+  const { exists, learnings: existingLearnings } = await readLearningsFile(learningsFile);
+  const { learnings: legacyLearnings } =
+    exists || legacyLearningsFile === learningsFile
+      ? { learnings: [] as string[] }
+      : await readLearningsFile(legacyLearningsFile);
+
+  let learnings = exists ? existingLearnings : legacyLearnings;
+
+  learnings.push(params.learning);
+  if (learnings.length > 10) {
+    learnings = learnings.slice(-10);
+  }
+
+  await fs.mkdir(path.dirname(learningsFile), { recursive: true });
+  await fs.writeFile(learningsFile, JSON.stringify(learnings, null, 2), "utf-8");
+  if (!exists && legacyLearningsFile !== learningsFile) {
+    await fs.rm(legacyLearningsFile, { force: true }).catch(() => undefined);
+  }
+}
+
+/** Load session learnings for injection into extraSystemPrompt. */
+export async function loadSessionLearnings(
+  storePath: string,
+  sessionKey: string,
+): Promise<string[]> {
+  const learningsFile = resolveLearningsFilePath(storePath, sessionKey);
+  const { exists, learnings } = await readLearningsFile(learningsFile);
+  if (exists) {
+    return learnings;
+  }
+  return (await readLearningsFile(resolveLegacyLearningsFilePath(storePath, sessionKey))).learnings;
+}

package/src/feedback-reflection.test.ts

@@ -0,0 +1,237 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { storeSessionLearning } from "./feedback-reflection-store.js";
+import {
+  buildFeedbackEvent,
+  buildReflectionPrompt,
+  clearReflectionCooldowns,
+  isReflectionAllowed,
+  loadSessionLearnings,
+  parseReflectionResponse,
+  recordReflectionTime,
+} from "./feedback-reflection.js";
+
+describe("buildFeedbackEvent", () => {
+  it("builds a well-formed custom event", () => {
+    const event = buildFeedbackEvent({
+      messageId: "msg-123",
+      value: "negative",
+      comment: "too verbose",
+      sessionKey: "msteams:user1",
+      agentId: "default",
+      conversationId: "19:abc",
+    });
+
+    expect(event.type).toBe("custom");
+    expect(event.event).toBe("feedback");
+    expect(event.value).toBe("negative");
+    expect(event.comment).toBe("too verbose");
+    expect(event.messageId).toBe("msg-123");
+    expect(event.ts).toBeGreaterThan(0);
+  });
+
+  it("omits comment when not provided", () => {
+    const event = buildFeedbackEvent({
+      messageId: "msg-123",
+      value: "positive",
+      sessionKey: "msteams:user1",
+      agentId: "default",
+      conversationId: "19:abc",
+    });
+
+    expect(event.comment).toBeUndefined();
+    expect(event.value).toBe("positive");
+  });
+});
+
+describe("buildReflectionPrompt", () => {
+  it("includes the thumbed-down response", () => {
+    const prompt = buildReflectionPrompt({
+      thumbedDownResponse: "Here is a long explanation...",
+    });
+
+    expect(prompt).toContain("previous response wasn't helpful");
+    expect(prompt).toContain("Here is a long explanation...");
+    expect(prompt).toContain("reflect");
+  });
+
+  it("truncates long responses", () => {
+    const longResponse = "x".repeat(600);
+    const prompt = buildReflectionPrompt({
+      thumbedDownResponse: longResponse,
+    });
+
+    expect(prompt).toContain("...");
+    expect(prompt.length).toBeLessThan(longResponse.length + 500);
+  });
+
+  it("includes user comment when provided", () => {
+    const prompt = buildReflectionPrompt({
+      thumbedDownResponse: "Some response",
+      userComment: "Too wordy",
+    });
+
+    expect(prompt).toContain('User\'s comment: "Too wordy"');
+  });
+
+  it("works without optional params", () => {
+    const prompt = buildReflectionPrompt({});
+    expect(prompt).toContain("previous response wasn't helpful");
+    expect(prompt).toContain('"followUp":false');
+  });
+});
+
+describe("parseReflectionResponse", () => {
+  it("parses strict JSON output", () => {
+    expect(
+      parseReflectionResponse(
+        '{"learning":"Be more direct next time.","followUp":true,"userMessage":"Sorry about that. I will keep it tighter."}',
+      ),
+    ).toEqual({
+      learning: "Be more direct next time.",
+      followUp: true,
+      userMessage: "Sorry about that. I will keep it tighter.",
+    });
+  });
+
+  it("parses JSON inside markdown fences", () => {
+    expect(
+      parseReflectionResponse(
+        '```json\n{"learning":"Ask a clarifying question first.","followUp":false,"userMessage":""}\n```',
+      ),
+    ).toEqual({
+      learning: "Ask a clarifying question first.",
+      followUp: false,
+      userMessage: undefined,
+    });
+  });
+
+  it("falls back to internal-only learning when parsing fails", () => {
+    expect(parseReflectionResponse("Be more concise.\nFollow up: yes.")).toEqual({
+      learning: "Be more concise.\nFollow up: yes.",
+      followUp: false,
+    });
+  });
+});
+
+describe("reflection cooldown", () => {
+  afterEach(() => {
+    clearReflectionCooldowns();
+    vi.restoreAllMocks();
+  });
+
+  it("allows first reflection", () => {
+    expect(isReflectionAllowed("session-1")).toBe(true);
+  });
+
+  it("blocks reflection within cooldown", () => {
+    recordReflectionTime("session-1");
+    expect(isReflectionAllowed("session-1", 60_000)).toBe(false);
+  });
+
+  it("allows reflection after cooldown expires", () => {
+    // Manually set a past timestamp
+    recordReflectionTime("session-1");
+    // Override the map entry to simulate time passing
+    clearReflectionCooldowns();
+    expect(isReflectionAllowed("session-1", 1)).toBe(true);
+  });
+
+  it("tracks sessions independently", () => {
+    recordReflectionTime("session-1");
+    expect(isReflectionAllowed("session-1", 60_000)).toBe(false);
+    expect(isReflectionAllowed("session-2", 60_000)).toBe(true);
+  });
+
+  it("keeps longer custom cooldown entries during pruning", () => {
+    vi.spyOn(Date, "now").mockReturnValue(0);
+    recordReflectionTime("target", 600_000);
+
+    vi.spyOn(Date, "now").mockReturnValue(301_000);
+    for (let index = 0; index <= 500; index += 1) {
+      recordReflectionTime(`session-${index}`, 600_000);
+    }
+
+    expect(isReflectionAllowed("target", 600_000)).toBe(false);
+  });
+});
+
+describe("loadSessionLearnings", () => {
+  let tmpDir: string;
+
+  afterEach(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns empty array when file doesn't exist", async () => {
+    tmpDir = await mkdtemp(path.join(os.tmpdir(), "learnings-test-"));
+    const learnings = await loadSessionLearnings(tmpDir, "nonexistent");
+    expect(learnings).toEqual([]);
+  });
+
+  it("reads existing learnings", async () => {
+    tmpDir = await mkdtemp(path.join(os.tmpdir(), "learnings-test-"));
+    const safeKey = Buffer.from("msteams:user1", "utf8").toString("base64url");
+    const filePath = path.join(tmpDir, `${safeKey}.learnings.json`);
+    await writeFile(filePath, JSON.stringify(["Be concise", "Use examples"]), "utf-8");
+
+    const learnings = await loadSessionLearnings(tmpDir, "msteams:user1");
+    expect(learnings).toEqual(["Be concise", "Use examples"]);
+  });
+
+  it("keeps distinct session keys isolated across the filename persistence boundary", async () => {
+    tmpDir = await mkdtemp(path.join(os.tmpdir(), "learnings-test-"));
+
+    await storeSessionLearning({
+      storePath: tmpDir,
+      sessionKey: "msteams:user1",
+      learning: "Use bullets",
+    });
+    await storeSessionLearning({
+      storePath: tmpDir,
+      sessionKey: "msteams/user1",
+      learning: "Avoid bullets",
+    });
+
+    await expect(loadSessionLearnings(tmpDir, "msteams:user1")).resolves.toEqual(["Use bullets"]);
+    await expect(loadSessionLearnings(tmpDir, "msteams/user1")).resolves.toEqual(["Avoid bullets"]);
+  });
+
+  it("reads and migrates legacy sanitized session learning files", async () => {
+    tmpDir = await mkdtemp(path.join(os.tmpdir(), "learnings-test-"));
+    const legacyFile = path.join(tmpDir, "msteams_user1.learnings.json");
+    await writeFile(legacyFile, JSON.stringify(["Legacy learning"]), "utf-8");
+
+    await expect(loadSessionLearnings(tmpDir, "msteams:user1")).resolves.toEqual([
+      "Legacy learning",
+    ]);
+
+    await storeSessionLearning({
+      storePath: tmpDir,
+      sessionKey: "msteams:user1",
+      learning: "New learning",
+    });
+
+    const migratedFile = path.join(
+      tmpDir,
+      `${Buffer.from("msteams:user1", "utf8").toString("base64url")}.learnings.json`,
+    );
+    await expect(loadSessionLearnings(tmpDir, "msteams:user1")).resolves.toEqual([
+      "Legacy learning",
+      "New learning",
+    ]);
+    await expect(rm(legacyFile, { force: false })).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(loadSessionLearnings(tmpDir, "msteams:user1")).resolves.toEqual([
+      "Legacy learning",
+      "New learning",
+    ]);
+    await expect(loadSessionLearnings(tmpDir, "msteams/user1")).resolves.toEqual([]);
+    await expect(
+      import("node:fs/promises").then((fs) => fs.readFile(migratedFile, "utf-8")),
+    ).resolves.toContain("Legacy learning");
+  });
+});