@gakr-gakr/msteams 0.1.0

package/src/errors.ts

@@ -0,0 +1,270 @@
+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;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  if (err === null) {
+    return "null";
+  }
+  if (err === undefined) {
+    return "undefined";
+  }
+  if (typeof err === "number" || typeof err === "boolean" || typeof err === "bigint") {
+    return String(err);
+  }
+  if (typeof err === "symbol") {
+    return err.description ?? err.toString();
+  }
+  if (typeof err === "function") {
+    return err.name ? `[function ${err.name}]` : "[function]";
+  }
+  try {
+    return JSON.stringify(err) ?? "unknown error";
+  } catch {
+    return "unknown error";
+  }
+}
+
+function extractStatusCode(err: unknown): number | null {
+  if (!isRecord(err)) {
+    return null;
+  }
+  const direct = err.statusCode ?? err.status;
+  if (typeof direct === "number" && Number.isFinite(direct)) {
+    return direct;
+  }
+  if (typeof direct === "string") {
+    const parsed = Number.parseInt(direct, 10);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+
+  const response = err.response;
+  if (isRecord(response)) {
+    const status = response.status;
+    if (typeof status === "number" && Number.isFinite(status)) {
+      return status;
+    }
+    if (typeof status === "string") {
+      const parsed = Number.parseInt(status, 10);
+      if (Number.isFinite(parsed)) {
+        return parsed;
+      }
+    }
+  }
+
+  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;
+  }
+
+  const direct = err.retryAfterMs ?? err.retry_after_ms;
+  if (typeof direct === "number" && Number.isFinite(direct) && direct >= 0) {
+    return direct;
+  }
+
+  const retryAfter = err.retryAfter ?? err.retry_after;
+  if (typeof retryAfter === "number" && Number.isFinite(retryAfter)) {
+    return retryAfter >= 0 ? retryAfter * 1000 : null;
+  }
+  if (typeof retryAfter === "string") {
+    const parsed = Number.parseFloat(retryAfter);
+    if (Number.isFinite(parsed) && parsed >= 0) {
+      return parsed * 1000;
+    }
+  }
+
+  const response = err.response;
+  if (!isRecord(response)) {
+    return null;
+  }
+
+  const headers = response.headers;
+  if (!headers) {
+    return null;
+  }
+
+  if (isRecord(headers)) {
+    const raw = headers["retry-after"] ?? headers["Retry-After"];
+    if (typeof raw === "string") {
+      const parsed = Number.parseFloat(raw);
+      if (Number.isFinite(parsed) && parsed >= 0) {
+        return parsed * 1000;
+      }
+    }
+  }
+
+  // Fetch Headers-like interface
+  if (
+    typeof headers === "object" &&
+    headers !== null &&
+    "get" in headers &&
+    typeof (headers as { get?: unknown }).get === "function"
+  ) {
+    const raw = (headers as { get: (name: string) => string | null }).get("retry-after");
+    if (raw) {
+      const parsed = Number.parseFloat(raw);
+      if (Number.isFinite(parsed) && parsed >= 0) {
+        return parsed * 1000;
+      }
+    }
+  }
+
+  return null;
+}
+
+type MSTeamsSendErrorKind =
+  | "auth"
+  | "throttled"
+  | "transient"
+  | "permanent"
+  | "network"
+  | "unknown";
+
+type MSTeamsSendErrorClassification = {
+  kind: MSTeamsSendErrorKind;
+  statusCode?: number;
+  retryAfterMs?: number;
+  errorCode?: string;
+};
+
+/**
+ * Classify outbound send errors for safe retries and actionable logs.
+ *
+ * Important: We only mark errors as retryable when we have an explicit HTTP
+ * status code that indicates the message was not accepted (e.g. 429, 5xx).
+ * For transport-level errors where delivery is ambiguous, we prefer to avoid
+ * retries to reduce the chance of duplicate posts.
+ */
+export function classifyMSTeamsSendError(err: unknown): MSTeamsSendErrorClassification {
+  const statusCode = extractStatusCode(err);
+  const retryAfterMs = extractRetryAfterMs(err);
+  const errorCode = extractErrorCode(err) ?? undefined;
+
+  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) {
+    return {
+      kind: "throttled",
+      statusCode,
+      retryAfterMs: retryAfterMs ?? undefined,
+      errorCode,
+    };
+  }
+
+  if (statusCode === 408 || (statusCode != null && statusCode >= 500)) {
+    return {
+      kind: "transient",
+      statusCode,
+      retryAfterMs: retryAfterMs ?? undefined,
+      errorCode,
+    };
+  }
+
+  if (statusCode != null && statusCode >= 400) {
+    return { kind: "permanent", statusCode, errorCode };
+  }
+
+  // Transport-level errors (no HTTP status code) — check for well-known
+  // network error codes that indicate egress is blocked (#77674).
+  if (statusCode == null) {
+    const networkCode = isRecord(err) && typeof err.code === "string" ? err.code : null;
+    if (
+      networkCode === "ECONNREFUSED" ||
+      networkCode === "ENOTFOUND" ||
+      networkCode === "EHOSTUNREACH" ||
+      networkCode === "ETIMEDOUT" ||
+      networkCode === "ECONNRESET"
+    ) {
+      return { kind: "network", errorCode: networkCode };
+    }
+  }
+
+  return {
+    kind: "unknown",
+    statusCode: statusCode ?? undefined,
+    retryAfterMs: retryAfterMs ?? undefined,
+    errorCode,
+  };
+}
+
+/**
+ * Detect whether an error is caused by a revoked Proxy.
+ *
+ * The Bot Framework SDK wraps TurnContext in a Proxy that is revoked once the
+ * turn handler returns.  Any later access (e.g. from a debounced callback)
+ * throws a TypeError whose message contains the distinctive "proxy that has
+ * been revoked" string.
+ */
+export function isRevokedProxyError(err: unknown): boolean {
+  if (!(err instanceof TypeError)) {
+    return false;
+  }
+  return /proxy that has been revoked/i.test(err.message);
+}
+
+export function formatMSTeamsSendErrorHint(
+  classification: MSTeamsSendErrorClassification,
+): string | undefined {
+  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";
+  }
+  if (classification.kind === "transient") {
+    return "transient Teams/Bot Framework error; retry may succeed";
+  }
+  if (classification.kind === "network") {
+    return "transport-level failure sending reply to Teams Bot Connector (smba.trafficmanager.net) — check egress firewall rules allow outbound HTTPS to smba.trafficmanager.net";
+  }
+  return undefined;
+}

package/src/feedback-reflection-prompt.ts

@@ -0,0 +1,117 @@
+import { normalizeOptionalLowercaseString } from "autobot/plugin-sdk/string-coerce-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,113 @@
+import fs from "node:fs/promises";
+import { writeJsonFileAtomically } from "autobot/plugin-sdk/json-store";
+
+/** 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 writeJsonFileAtomically(learningsFile, learnings);
+  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;
+}