@kodelyth/msteams 2026.5.42 → 2026.6.2

package/src/streaming-message.ts

@@ -1,327 +0,0 @@
-/**
- * Teams streaming message using the streaminfo entity protocol.
- *
- * Follows the official Teams SDK pattern:
- * 1. First chunk → POST a typing activity with streaminfo entity (streamType: "streaming")
- * 2. Subsequent chunks → POST typing activities with streaminfo + incrementing streamSequence
- * 3. Finalize → POST a message activity with streaminfo (streamType: "final")
- *
- * Uses the shared draft-stream-loop for throttling (avoids rate limits).
- */
-
-import { createDraftStreamLoop, type DraftStreamLoop } from "klaw/plugin-sdk/channel-lifecycle";
-import { readStringValue } from "klaw/plugin-sdk/string-coerce-runtime";
-
-/** Default throttle interval between stream updates (ms).
- * Teams docs recommend buffering tokens for 1.5-2s; limit is 1 req/s. */
-const DEFAULT_THROTTLE_MS = 1500;
-
-/** Minimum chars before sending the first streaming message. */
-const MIN_INITIAL_CHARS = 20;
-
-/** Teams message text limit. */
-const TEAMS_MAX_CHARS = 4000;
-
-/**
- * Stop streaming before Teams expires the content stream server-side.
- * The exact service limit is opaque, so stay comfortably under it.
- */
-const MAX_STREAM_AGE_MS = 45_000;
-
-type StreamSendFn = (activity: Record<string, unknown>) => Promise<unknown>;
-
-type TeamsStreamOptions = {
-  /** Function to send an activity (POST to Bot Framework). */
-  sendActivity: StreamSendFn;
-  /** Whether to enable feedback loop on the final message. */
-  feedbackLoopEnabled?: boolean;
-  /** Throttle interval in ms. Default: 600. */
-  throttleMs?: number;
-  /** Called on errors during streaming. */
-  onError?: (err: unknown) => void;
-};
-
-import { AI_GENERATED_ENTITY } from "./ai-entity.js";
-import { formatUnknownError } from "./errors.js";
-
-function extractId(response: unknown): string | undefined {
-  if (response && typeof response === "object" && "id" in response) {
-    return readStringValue((response as { id?: unknown }).id);
-  }
-  return undefined;
-}
-
-function buildStreamInfoEntity(
-  streamId: string | undefined,
-  streamType: "informative" | "streaming" | "final",
-  streamSequence?: number,
-): Record<string, unknown> {
-  const entity: Record<string, unknown> = {
-    type: "streaminfo",
-    streamType,
-  };
-  // streamId is only present after the first chunk (returned by the service)
-  if (streamId) {
-    entity.streamId = streamId;
-  }
-  // streamSequence must be present for start/continue, but NOT for final
-  if (streamSequence != null) {
-    entity.streamSequence = streamSequence;
-  }
-  return entity;
-}
-
-export class TeamsHttpStream {
-  private sendActivity: StreamSendFn;
-  private feedbackLoopEnabled: boolean;
-  private onError?: (err: unknown) => void;
-
-  private accumulatedText = "";
-  private streamId: string | undefined = undefined;
-  private sequenceNumber = 0;
-  private stopped = false;
-  private finalized = false;
-  private streamFailed = false;
-  private lastStreamedText = "";
-  private finalMessageId: string | undefined = undefined;
-  private streamStartedAt: number | undefined = undefined;
-  private loop: DraftStreamLoop;
-
-  constructor(options: TeamsStreamOptions) {
-    this.sendActivity = options.sendActivity;
-    this.feedbackLoopEnabled = options.feedbackLoopEnabled ?? false;
-    this.onError = options.onError;
-
-    this.loop = createDraftStreamLoop({
-      throttleMs: options.throttleMs ?? DEFAULT_THROTTLE_MS,
-      isStopped: () => this.stopped,
-      sendOrEditStreamMessage: (text) => this.pushStreamChunk(text),
-    });
-  }
-
-  /**
-   * Send an informative status update (blue progress bar in Teams).
-   * Call this immediately when a message is received, before LLM starts generating.
-   * Establishes the stream so subsequent chunks continue from this stream ID.
-   */
-  async sendInformativeUpdate(text: string): Promise<void> {
-    if (this.stopped || this.finalized) {
-      return;
-    }
-
-    this.sequenceNumber++;
-
-    const activity: Record<string, unknown> = {
-      type: "typing",
-      text,
-      entities: [buildStreamInfoEntity(this.streamId, "informative", this.sequenceNumber)],
-    };
-
-    try {
-      const response = await this.sendActivity(activity);
-      if (!this.streamId) {
-        this.streamId = extractId(response);
-      }
-    } catch (err) {
-      this.onError?.(err);
-    }
-  }
-
-  /**
-   * Ingest partial text from the LLM token stream.
-   * Called by onPartialReply — accumulates text and throttles updates.
-   */
-  update(text: string): void {
-    if (this.stopped || this.finalized) {
-      return;
-    }
-    this.accumulatedText = text;
-
-    // Wait for minimum chars before first send (avoids push notification flicker)
-    if (!this.streamId && this.accumulatedText.length < MIN_INITIAL_CHARS) {
-      return;
-    }
-
-    // Text exceeded Teams limit — finalize immediately with what we have
-    // so the user isn't left waiting while the LLM keeps generating.
-    if (this.accumulatedText.length > TEAMS_MAX_CHARS) {
-      this.streamFailed = true;
-      void this.finalize();
-      return;
-    }
-
-    // Stop early before Teams expires the stream server-side. finalize() will
-    // close the stream with the last good content, and reply-stream-controller
-    // will deliver any remaining suffix via normal fallback delivery.
-    if (this.streamStartedAt && Date.now() - this.streamStartedAt >= MAX_STREAM_AGE_MS) {
-      this.streamFailed = true;
-      void this.finalize();
-      return;
-    }
-
-    // Don't append cursor — Teams requires each chunk to be a prefix of subsequent chunks.
-    // The cursor character would cause "content should contain previously streamed content" errors.
-    this.loop.update(this.accumulatedText);
-  }
-
-  /**
-   * Replace an informative progress update with final answer text.
-   * Returns false when the stream could not safely carry the final text, so
-   * callers can deliver the answer through the normal Teams message path.
-   */
-  async replaceInformativeWithFinal(text: string): Promise<boolean> {
-    if (this.stopped || this.finalized) {
-      return false;
-    }
-    this.update(text);
-    await this.loop.flush();
-    await this.finalize();
-    return !this.streamFailed && this.hasContent;
-  }
-
-  /**
-   * Finalize the stream — send the final message activity.
-   */
-  async finalize(): Promise<string | undefined> {
-    if (this.finalized) {
-      return this.finalMessageId;
-    }
-    this.finalized = true;
-    this.stopped = true;
-    this.loop.stop();
-    await this.loop.waitForInFlight();
-
-    // If no text was streamed (e.g. agent sent a card via tool instead of
-    // streaming text), just return. Teams auto-clears the informative progress
-    // bar after its streaming timeout. Sending an empty final message fails
-    // with 403.
-    if (!this.accumulatedText.trim()) {
-      return this.finalMessageId;
-    }
-
-    // If streaming failed (>4000 chars or POST errors), close the stream
-    // with the last successfully streamed text so Teams removes the "Stop"
-    // button and replaces the partial chunks. deliver() handles the complete
-    // response since hasContent returns false when streamFailed is true.
-    if (this.streamFailed) {
-      if (this.streamId) {
-        try {
-          const response = await this.sendActivity({
-            type: "message",
-            text: this.lastStreamedText || "",
-            channelData: { feedbackLoopEnabled: this.feedbackLoopEnabled },
-            entities: [AI_GENERATED_ENTITY, buildStreamInfoEntity(this.streamId, "final")],
-          });
-          this.finalMessageId = extractId(response);
-        } catch {
-          // Best effort — stream will auto-close after Teams timeout
-        }
-      }
-      return this.finalMessageId;
-    }
-
-    // Send final message activity.
-    // Per the spec: type=message, streamType=final, NO streamSequence.
-    try {
-      const entities: Array<Record<string, unknown>> = [AI_GENERATED_ENTITY];
-      if (this.streamId) {
-        entities.push(buildStreamInfoEntity(this.streamId, "final"));
-      }
-
-      const finalActivity: Record<string, unknown> = {
-        type: "message",
-        text: this.accumulatedText,
-        channelData: {
-          feedbackLoopEnabled: this.feedbackLoopEnabled,
-        },
-        entities,
-      };
-
-      const response = await this.sendActivity(finalActivity);
-      this.finalMessageId = extractId(response);
-    } catch (err) {
-      this.streamFailed = true;
-      this.onError?.(err);
-    }
-    return this.finalMessageId;
-  }
-
-  /** Whether streaming successfully delivered content (at least one chunk sent, not failed). */
-  get hasContent(): boolean {
-    return this.accumulatedText.length > 0 && !this.streamFailed;
-  }
-
-  /** Whether streaming failed and fallback delivery is needed. */
-  get isFailed(): boolean {
-    return this.streamFailed;
-  }
-
-  /** Number of characters successfully streamed before failure. */
-  get streamedLength(): number {
-    return this.lastStreamedText.length;
-  }
-
-  /** Whether the stream has been finalized. */
-  get isFinalized(): boolean {
-    return this.finalized;
-  }
-
-  /** Platform id returned by the final message activity, when available. */
-  get messageId(): string | undefined {
-    return this.finalMessageId;
-  }
-
-  /** Stream id returned by the first streaminfo activity, when available. */
-  get previewStreamId(): string | undefined {
-    return this.streamId;
-  }
-
-  /** Whether streaming fell back (not used in this implementation). */
-  get isFallback(): boolean {
-    return false;
-  }
-
-  /**
-   * Send a single streaming chunk as a typing activity with streaminfo.
-   * Per the Teams REST API spec:
-   * - First chunk: no streamId, streamSequence=1 → returns 201 with { id: streamId }
-   * - Subsequent chunks: include streamId, increment streamSequence → returns 202
-   */
-  private async pushStreamChunk(text: string): Promise<boolean> {
-    if (this.stopped && !this.finalized) {
-      return false;
-    }
-
-    this.sequenceNumber++;
-
-    const activity: Record<string, unknown> = {
-      type: "typing",
-      text,
-      entities: [buildStreamInfoEntity(this.streamId, "streaming", this.sequenceNumber)],
-    };
-
-    try {
-      const response = await this.sendActivity(activity);
-      if (!this.streamStartedAt) {
-        this.streamStartedAt = Date.now();
-      }
-      if (!this.streamId) {
-        this.streamId = extractId(response);
-      }
-      this.lastStreamedText = text;
-      return true;
-    } catch (err) {
-      const axiosData = (err as { response?: { data?: unknown; status?: number } })?.response;
-      const statusCode = axiosData?.status ?? (err as { statusCode?: number })?.statusCode;
-      const responseBody = axiosData?.data ? JSON.stringify(axiosData.data).slice(0, 300) : "";
-      const msg = formatUnknownError(err);
-      this.onError?.(
-        new Error(
-          `stream POST failed (HTTP ${statusCode ?? "?"}): ${msg}${responseBody ? ` body=${responseBody}` : ""}`,
-        ),
-      );
-      this.streamFailed = true;
-      return false;
-    }
-  }
-}

package/src/test-runtime.ts

@@ -1,16 +0,0 @@
-import os from "node:os";
-import path from "node:path";
-import type { PluginRuntime } from "../runtime-api.js";
-
-export const msteamsRuntimeStub = {
-  state: {
-    resolveStateDir: (env: NodeJS.ProcessEnv = process.env, homedir?: () => string) => {
-      const override = env.KLAW_STATE_DIR?.trim() || env.KLAW_STATE_DIR?.trim();
-      if (override) {
-        return override;
-      }
-      const resolvedHome = homedir ? homedir() : os.homedir();
-      return path.join(resolvedHome, ".klaw");
-    },
-  },
-} as unknown as PluginRuntime;

package/src/thread-parent-context.test.ts

@@ -1,224 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { GraphThreadMessage } from "./graph-thread.js";
-import {
-  resetThreadParentContextCachesForTest,
-  fetchParentMessageCached,
-  formatParentContextEvent,
-  markParentContextInjected,
-  shouldInjectParentContext,
-  summarizeParentMessage,
-} from "./thread-parent-context.js";
-
-describe("summarizeParentMessage", () => {
-  it("returns undefined for missing message", () => {
-    expect(summarizeParentMessage(undefined)).toBeUndefined();
-  });
-
-  it("returns undefined when body is blank", () => {
-    const msg: GraphThreadMessage = {
-      id: "p1",
-      from: { user: { displayName: "Alice" } },
-      body: { content: "   ", contentType: "text" },
-    };
-    expect(summarizeParentMessage(msg)).toBeUndefined();
-  });
-
-  it("extracts sender + plain text", () => {
-    const msg: GraphThreadMessage = {
-      id: "p1",
-      from: { user: { displayName: "Alice" } },
-      body: { content: "Hello world", contentType: "text" },
-    };
-    expect(summarizeParentMessage(msg)).toEqual({ sender: "Alice", text: "Hello world" });
-  });
-
-  it("strips HTML for html contentType", () => {
-    const msg: GraphThreadMessage = {
-      id: "p1",
-      from: { user: { displayName: "Bob" } },
-      body: { content: "<p>Hi <b>there</b></p>", contentType: "html" },
-    };
-    expect(summarizeParentMessage(msg)).toEqual({ sender: "Bob", text: "Hi there" });
-  });
-
-  it("collapses whitespace in text contentType", () => {
-    const msg: GraphThreadMessage = {
-      id: "p1",
-      from: { user: { displayName: "Carol" } },
-      body: { content: "line one\n  line two\t\ttrailing", contentType: "text" },
-    };
-    expect(summarizeParentMessage(msg)).toEqual({
-      sender: "Carol",
-      text: "line one line two trailing",
-    });
-  });
-
-  it("falls back to application displayName", () => {
-    const msg: GraphThreadMessage = {
-      id: "p1",
-      from: { application: { displayName: "BotApp" } },
-      body: { content: "heads up", contentType: "text" },
-    };
-    expect(summarizeParentMessage(msg)).toEqual({ sender: "BotApp", text: "heads up" });
-  });
-
-  it("falls back to unknown when sender is missing", () => {
-    const msg: GraphThreadMessage = {
-      id: "p1",
-      body: { content: "orphan", contentType: "text" },
-    };
-    expect(summarizeParentMessage(msg)).toEqual({ sender: "unknown", text: "orphan" });
-  });
-
-  it("truncates overly long parent text", () => {
-    const msg: GraphThreadMessage = {
-      id: "p1",
-      from: { user: { displayName: "Dana" } },
-      body: { content: "x".repeat(1000), contentType: "text" },
-    };
-    const summary = summarizeParentMessage(msg);
-    expect(summary?.text.length).toBeLessThanOrEqual(400);
-    expect(summary?.text.endsWith("…")).toBe(true);
-  });
-});
-
-describe("formatParentContextEvent", () => {
-  it("formats as Replying to @sender: body", () => {
-    expect(formatParentContextEvent({ sender: "Alice", text: "hello there" })).toBe(
-      "Replying to @Alice: hello there",
-    );
-  });
-});
-
-describe("fetchParentMessageCached", () => {
-  beforeEach(() => {
-    resetThreadParentContextCachesForTest();
-  });
-
-  it("invokes the fetcher on first call", async () => {
-    const mockMsg: GraphThreadMessage = {
-      id: "p1",
-      body: { content: "hi", contentType: "text" },
-    };
-    const fetcher = vi.fn(async () => mockMsg);
-
-    const result = await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-
-    expect(result).toEqual(mockMsg);
-    expect(fetcher).toHaveBeenCalledTimes(1);
-    expect(fetcher).toHaveBeenCalledWith("tok", "g1", "c1", "p1");
-  });
-
-  it("returns cached value on repeat fetch without invoking fetcher", async () => {
-    const mockMsg: GraphThreadMessage = {
-      id: "p1",
-      body: { content: "hi", contentType: "text" },
-    };
-    const fetcher = vi.fn(async () => mockMsg);
-
-    await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-    await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-    const third = await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-
-    expect(fetcher).toHaveBeenCalledTimes(1);
-    expect(third).toEqual(mockMsg);
-  });
-
-  it("caches undefined (Graph error) so failures do not re-fetch on burst", async () => {
-    const fetcher = vi.fn(async () => undefined);
-
-    const first = await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-    const second = await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-
-    expect(first).toBeUndefined();
-    expect(second).toBeUndefined();
-    expect(fetcher).toHaveBeenCalledTimes(1);
-  });
-
-  it("scopes cache by groupId/channelId/parentId", async () => {
-    const fetcher = vi.fn(async (_tok, _g, _c, parentId) => ({
-      id: parentId,
-      body: { content: `content-${parentId}`, contentType: "text" },
-    }));
-
-    await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-    await fetchParentMessageCached("tok", "g1", "c1", "p2", fetcher);
-    await fetchParentMessageCached("tok", "g2", "c1", "p1", fetcher);
-
-    expect(fetcher).toHaveBeenCalledTimes(3);
-  });
-
-  it("re-fetches after TTL expires", async () => {
-    vi.useFakeTimers();
-    try {
-      const fetcher = vi.fn(async () => ({
-        id: "p1",
-        body: { content: "hi", contentType: "text" },
-      }));
-
-      await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-      // 5 min TTL: advance just beyond.
-      vi.advanceTimersByTime(5 * 60 * 1000 + 1);
-      await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-
-      expect(fetcher).toHaveBeenCalledTimes(2);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it("evicts oldest entries when exceeding the 100-entry cap", async () => {
-    const fetcher = vi.fn(async (_tok, _g, _c, parentId) => ({
-      id: String(parentId),
-      body: { content: `v-${parentId}`, contentType: "text" },
-    }));
-
-    // Fill cache with 100 distinct parents.
-    for (let i = 0; i < 100; i += 1) {
-      await fetchParentMessageCached("tok", "g1", "c1", `p${i}`, fetcher);
-    }
-    expect(fetcher).toHaveBeenCalledTimes(100);
-
-    // First entry should still be cached (no evictions yet).
-    await fetchParentMessageCached("tok", "g1", "c1", "p0", fetcher);
-    expect(fetcher).toHaveBeenCalledTimes(100);
-
-    // Push one more distinct parent to trigger an eviction.
-    // The just-touched p0 is now the newest; the next-oldest (p1) should be evicted.
-    await fetchParentMessageCached("tok", "g1", "c1", "p100", fetcher);
-    expect(fetcher).toHaveBeenCalledTimes(101);
-
-    // Fetching p1 again should miss the cache.
-    await fetchParentMessageCached("tok", "g1", "c1", "p1", fetcher);
-    expect(fetcher).toHaveBeenCalledTimes(102);
-
-    // p0 is still cached because we refreshed it.
-    await fetchParentMessageCached("tok", "g1", "c1", "p0", fetcher);
-    expect(fetcher).toHaveBeenCalledTimes(102);
-  });
-});
-
-describe("shouldInjectParentContext / markParentContextInjected", () => {
-  beforeEach(() => {
-    resetThreadParentContextCachesForTest();
-  });
-
-  it("returns true for first observation", () => {
-    expect(shouldInjectParentContext("session-1", "parent-1")).toBe(true);
-  });
-
-  it("returns false after marking the same parent", () => {
-    markParentContextInjected("session-1", "parent-1");
-    expect(shouldInjectParentContext("session-1", "parent-1")).toBe(false);
-  });
-
-  it("returns true again when a different parent appears in the session", () => {
-    markParentContextInjected("session-1", "parent-1");
-    expect(shouldInjectParentContext("session-1", "parent-2")).toBe(true);
-  });
-
-  it("dedupe is scoped per session key", () => {
-    markParentContextInjected("session-1", "parent-1");
-    expect(shouldInjectParentContext("session-2", "parent-1")).toBe(true);
-  });
-});