@copilotkit/channels-teams 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Atai Barkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @copilotkit/channels-teams
+
+The **Microsoft Teams platform adapter** for [`@copilotkit/channels`](../channels). It's a
+concrete `PlatformAdapter` that plugs Teams into the platform-agnostic bot
+engine, exactly like [`@copilotkit/channels-slack`](../channels-slack) does for Slack. You
+write your bot once with `createBot` (handlers, JSX, tools, context) and run it
+on Teams by adding this adapter.
+
+It is built on the **Microsoft 365 Agents SDK** (`@microsoft/agents-hosting`),
+the successor to the Bot Framework SDK.
+
+## Install
+
+```sh
+pnpm add @copilotkit/channels @copilotkit/channels-ui @copilotkit/channels-teams
+```
+
+## Quickstart
+
+```ts
+import { createBot } from "@copilotkit/channels";
+import { teams } from "@copilotkit/channels-teams";
+
+const bot = createBot({
+  adapters: [teams({ port: 3978 })],
+});
+
+bot.onMessage(({ thread, message }) => thread.post(`Echo: ${message.text}`));
+
+await bot.start(); // POST /api/messages now listening on :3978
+```
+
+Then point the **Microsoft 365 Agents Playground** at it. No Microsoft
+credentials are required for local development:
+
+```sh
+npx @microsoft/m365agentsplayground   # opens http://localhost:56150
+```
+
+The Playground connects to `http://127.0.0.1:3978/api/messages` and gives you a
+Teams-like chat UI to test against. See [`examples/teams`](../../examples/teams)
+for a complete, runnable echo bot, and the
+[Microsoft Teams guide](../../showcase/shell-docs/src/content/docs/frontends/teams.mdx)
+for sideloading into real Teams via Azure Bot Service.
+
+## How it maps onto the `PlatformAdapter` contract
+
+- **Ingress:** a `CloudAdapter` receives Teams activities at
+  `POST /api/messages` (stood up by an Express server). Each `message` activity
+  is normalized into `sink.onTurn(...)`. Uploaded files ride along as
+  attachments: `buildFileContentParts` downloads them (a `file.download.info`
+  URL, or a `data:`/https media URL) and hands the agent multimodal content
+  parts — CSV/JSON/text as decoded text, images and PDFs as binary. That's what
+  makes "upload a CSV → get a chart" work. Note Teams only delivers uploaded
+  files to a bot in **1:1 (personal) chat** (requires `supportsFiles: true` in
+  the app manifest); in a channel or group chat Teams does NOT send the file to
+  the bot at all, so chart-from-data there means pasting the data inline.
+- **Egress:** structured/interactive UI is rendered to an **Adaptive Card**
+  (1.5) and sent as an attachment; a reply that collapses to plain text is sent
+  as a normal text activity (a bare `Echo: hi` shouldn't be a card). Both go out
+  on the live `TurnContext` _within the originating turn_. The engine awaits the
+  whole turn handler, so a reply (or a full `runAgent()` loop) completes before
+  the HTTP response closes. (Out-of-turn / proactive sends fall back to
+  `CloudAdapter.continueConversation` via the captured conversation reference.)
+- **Files out:** `postFile` posts a file to the conversation. An image (e.g. a
+  rendered chart PNG) is sent as an inline attachment via a `data:` URI, so it
+  renders directly in the thread — the bot-slack `postFile` parallel.
+- **Streaming:** text replies stream **by message edit** (Teams' baseline
+  model). It posts the first content, then `updateActivity` edits the same
+  message as the buffer grows (throttled and serialised; see
+  `TeamsMessageStream`), after a typing indicator. Native token streaming is a
+  later enhancement.
+- **Agent runs:** `createRunRenderer` bridges AG-UI events to Teams. Each text
+  message is streamed by edit, and tool calls plus interrupts are captured for
+  the run loop.
+- **History:** Teams does not hand the bot a queryable transcript, so an
+  in-memory `TeamsConversationStore` keeps one per conversation and seeds each
+  agent run with it. Swap in a durable `ConversationStore` for production.
+
+## Options
+
+```ts
+teams({
+  port: 3978, // POST /api/messages port (Playground default)
+  clientId, // Microsoft app id; omit for anonymous local dev
+  clientSecret, // omit for anonymous local dev
+  tenantId, // omit for multi-tenant / anonymous
+  interruptEventNames, // custom-event names treated as agent interrupts
+});
+```
+
+Credentials also resolve from the `clientId` / `clientSecret` / `tenantId`
+environment variables (the names the M365 Agents SDK reads).
+
+## Status & roadmap
+
+Implemented: message ingress; **Adaptive Card rendering** of the bot-ui
+vocabulary (`<Header>`, `<Section>`/`<Markdown>`, `<Fields>`, `<Table>`,
+`<Image>`, `<Actions>`/`<Button>`, `<Select>`, `<Input>`, `<Context>`) with a
+plain-text path for bare replies and a Markdown table fallback; **streamed-by-
+edit** text replies with a typing indicator; `runAgent` tool-call / interrupt
+capture; **card-action round-trip + HITL** (below); conversation history;
+`update` / `delete`. Verified in the M365 Agents Playground.
+
+**Card-action round-trip + HITL.** Adaptive Card `Action.Submit` clicks arrive
+as Message activities carrying the action `data` in `activity.value`;
+`decodeInteraction` parses our opaque `ckActionId` + button value and routes them
+to `sink.onInteraction`, which resolves the engine's `awaitChoice` waiter and
+runs the button's `onClick` (e.g. to edit the picker in place). A tool handler
+that calls `await thread.awaitChoice(<Card/>)` therefore gates the agent on a
+human decision; see `examples/teams` for an approve/reject demo. Ingress and
+interaction decoding derive the conversation key from one shared helper
+(`conversationKeyOf`) so the waiter always resolves.
+
+**Async turn handoff.** When credentialed, ingress acks the inbound turn
+immediately and runs the agent on a detached `continueConversation` context, so
+an `awaitChoice` suspend can outlive the Teams turn window (approval minutes
+later). In the anonymous local Playground (where `continueConversation` has no
+app id) the run uses the inbound turn context, which localhost holds open across
+the suspend. Waiters are in-memory (v1), so they don't survive a process restart.
+
+Planned follow-ups (the architecture leaves room for each):
+
+- **Native token streaming:** token-by-token replies via the SDK's
+  `StreamingResponse` (`queueInformativeUpdate` / `queueTextChunk` / `endStream`),
+  vs. the current post-then-edit model.
+- **Durable HITL waiters:** persist pending `awaitChoice` state so approvals
+  survive a restart (today they're in-memory).
+- **User lookup** (Microsoft Graph) and **arbitrary non-image file upload** via
+  the Teams/Graph file-consent flow (today `postFile` handles inline images).
+
+## Exports
+
+`teams`, `TeamsAdapter`, `TeamsAdapterOptions`, `TeamsReplyTarget`,
+`ConversationKey`; `TeamsConversationStore`; `createRunRenderer`;
+`conversationKeyOf` / `parseCardAction`; `renderTeamsMarkdown`;
+`renderAdaptiveCard` / `AdaptiveCard` / `isPlainText` /
+`ADAPTIVE_CARD_CONTENT_TYPE`; `TEAMS_LIMITS`; `TeamsMessageStream`;
+`createTeamsServer` / `TeamsServer` / `TeamsServerConfig`;
+`SanitizingHttpAgent`; `buildFileContentParts` / `TeamsAttachmentRef` /
+`FileDeliveryConfig`.

package/dist/adapter.d.ts

@@ -0,0 +1,133 @@
+import type { PlatformAdapter, SurfaceCapabilities, IngressSink, InteractionEvent, RunRenderer, ReplyTarget, ConversationStore, MessageRef, PlatformUser, UserQuery } from "@copilotkit/channels";
+import type { BotNode, ThreadMessage } from "@copilotkit/channels-ui";
+import type { AdaptiveCard } from "./render/adaptive-card.js";
+import type { TeamsAdapterOptions } from "./types.js";
+/** Native render output: a plain text activity or an Adaptive Card attachment. */
+type TeamsActivityPayload = {
+    text: string;
+} | {
+    card: AdaptiveCard;
+};
+/**
+ * Microsoft Teams `PlatformAdapter`.
+ *
+ * Ingress: a `CloudAdapter` receives Teams activities at `POST /api/messages`
+ * (M365 Agents SDK). The inbound HTTP turn is **acked immediately**; the agent
+ * run is handed off to a detached `continueConversation` so it can outlive the
+ * turn. This is required for HITL, where `awaitChoice` suspends the run until a user
+ * clicks an Adaptive Card button (possibly minutes later). That detached
+ * `continueConversation` provides a stable `TurnContext` the whole run streams
+ * on, exactly as the Slack adapter runs in the background off a web client.
+ *
+ * Adaptive Card `Action.Submit` clicks arrive as Message activities carrying
+ * the action `data` in `activity.value`; those are decoded and routed to
+ * `sink.onInteraction` to resolve the waiter. This path needs no Microsoft
+ * credentials in the local M365 Agents Playground.
+ */
+export declare class TeamsAdapter implements PlatformAdapter {
+    private readonly opts;
+    readonly platform = "teams";
+    readonly capabilities: SurfaceCapabilities;
+    readonly ackDeadlineMs = 15000;
+    private readonly store;
+    private cloud;
+    private server;
+    private sink;
+    constructor(opts?: TeamsAdapterOptions);
+    start(sink: IngressSink): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Normalize an inbound activity, ack the HTTP turn immediately, and drive the
+     * work into the engine on a **detached** `continueConversation` so it can
+     * outlive this turn (HITL suspends the run until a later click).
+     */
+    private handleActivity;
+    /**
+     * Resolve a message's uploaded files into AG-UI content parts. Personal chats
+     * deliver the file inline (the Teams bot file API), which `buildFileContentParts`
+     * handles; a channel doesn't include the file at all, so we fetch it through
+     * Microsoft Graph when credentials are configured (group chats aren't wired
+     * up yet). Failures are logged, never thrown.
+     */
+    private collectInboundFileParts;
+    /** App-only Graph credentials, when all three are configured. */
+    private graphCredentials;
+    /** Pull the team/channel/message ids Graph needs out of a channel activity. */
+    private channelMessageRef;
+    /**
+     * Concise operational log for the inbound-file pipeline: how many parts we
+     * built and any skip reasons. Deliberately content-free — it never logs file
+     * bytes, decoded text, or SharePoint URLs.
+     */
+    private logFileParts;
+    /** Whether we can send proactively (out-of-turn). Requires a Microsoft app id. */
+    private canGoProactive;
+    /**
+     * Run `fn` against a proactive `TurnContext` opened by `continueConversation`,
+     * detached from any inbound HTTP turn. Fire-and-forget: the caller acks the
+     * inbound turn immediately and this runs (and may suspend at `awaitChoice`)
+     * in the background. Errors are logged, never surfaced to the inbound turn.
+     */
+    private runDetached;
+    /** Open a proactive `TurnContext` for the conversation and await `fn`. */
+    private withProactive;
+    /**
+     * Render IR to a native payload: plain text when it collapses to text,
+     * otherwise an Adaptive Card. (A bare `Echo: hi` is a text bubble; structured
+     * or interactive UI becomes a card.)
+     */
+    render(ir: BotNode[]): TeamsActivityPayload;
+    post(target: ReplyTarget, ir: BotNode[]): Promise<MessageRef>;
+    update(ref: MessageRef, ir: BotNode[]): Promise<void>;
+    /**
+     * Stream a text reply by message edit: post the first content, then
+     * `updateActivity` the same message as the buffer grows (throttled). This is
+     * Teams' baseline streaming model: no native token streaming.
+     */
+    stream(target: ReplyTarget, chunks: AsyncIterable<string>): Promise<MessageRef>;
+    delete(ref: MessageRef): Promise<void>;
+    /**
+     * Post a file to the conversation. Teams renders an image inline when it's
+     * sent as an attachment whose `contentUrl` is a `data:` URI, so we base64 the
+     * bytes into one — exactly what `render_chart`/`render_diagram` need to drop a
+     * PNG into the thread (the bot-slack `postFile` parallel). Non-image bytes are
+     * still attached with their inferred MIME; whether Teams previews them is up
+     * to the client. Sends on the live turn context, or proactively by reference.
+     */
+    postFile(target: ReplyTarget, { bytes, filename, altText, }: {
+        bytes: Uint8Array;
+        filename: string;
+        title?: string;
+        altText?: string;
+    }): Promise<{
+        ok: boolean;
+        fileId?: string;
+        error?: string;
+    }>;
+    createRunRenderer(target: ReplyTarget): RunRenderer;
+    decodeInteraction(raw: unknown): InteractionEvent | undefined;
+    lookupUser(_q: UserQuery): Promise<PlatformUser | undefined>;
+    get conversationStore(): ConversationStore;
+    /** Return the conversation transcript the adapter has accumulated. */
+    getMessages(target: ReplyTarget): Promise<ThreadMessage[]>;
+    /** Send plain Markdown text, preferring the live turn context. */
+    private sendText;
+    /** Send an Adaptive Card as a message attachment on the live turn. */
+    private sendCard;
+    /** Edit a previously-posted text activity in place (streamed-by-edit). */
+    private updateText;
+    /** Fire a typing indicator (shown while the agent works). */
+    private sendTyping;
+    /**
+     * Send a typing indicator now and keep re-sending it every few seconds until
+     * the returned stop fn is called. Teams' typing indicator lapses after a few
+     * seconds, so a single ping can't cover slow work (a Graph download, a chart
+     * render) where nothing posts in between. Returns a stop fn; call it in a
+     * `finally` so the timer is always cleared.
+     */
+    private startTypingHeartbeat;
+}
+/** Construct a Microsoft Teams `PlatformAdapter`. */
+export declare function teams(opts?: TeamsAdapterOptions): TeamsAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}