@patimweb/pi-teams 1.0.0

package/src/tools/teams-read-thread.ts

@@ -0,0 +1,88 @@
+/**
+ * teams_read_thread — the opening post and all replies of one channel thread.
+ */
+
+import { Type } from "typebox";
+import { getChannelMessage, listChannelReplies } from "../graph/messages.ts";
+import { formatMessage } from "../utils/formatting.ts";
+import { requireChannel } from "./resolve.ts";
+import {
+	AccountParam,
+	LimitParam,
+	TenantParam,
+	connectionFor,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsReadThreadTool = {
+	name: "teams_read_thread",
+	description:
+		"Read one conversation thread in a Microsoft Teams channel: the opening post plus every reply, " +
+		"oldest first. Get the messageId from teams_read_channel or teams_search_messages.",
+	parameters: Type.Object({
+		channel: Type.String({ description: "Channel name or ID, or a 'Team/Channel' path" }),
+		messageId: Type.String({ description: "ID of the thread's opening message" }),
+		team: Type.Optional(Type.String({ description: "Team name or ID (omit when using a path)" })),
+		account: AccountParam,
+		tenant: TenantParam,
+		limit: LimitParam,
+	}),
+	promptSnippet: "Read a Teams channel thread with all replies",
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			channel: string;
+			messageId: string;
+			team?: string;
+			account?: string;
+			tenant?: string;
+			limit?: number;
+		},
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const { team, channel } = await requireChannel(conn, params.team, params.channel, "read", signal);
+
+			const root = await getChannelMessage(conn, channel, params.messageId, signal);
+			if (!root) {
+				return errorResult(
+					`Message ${params.messageId} not found in ${team.displayName}/${channel.displayName}.`,
+				);
+			}
+
+			const replies = await listChannelReplies(conn, channel, params.messageId, {
+				max: params.limit ?? 50,
+				signal,
+			});
+
+			const lines = [
+				`## Thread in ${team.displayName}/${channel.displayName}`,
+				"",
+				formatMessage(root),
+				"",
+				`### ${replies.length} repl${replies.length === 1 ? "y" : "ies"}`,
+				"",
+			];
+
+			// Graph returns replies newest first; a conversation reads the other way.
+			for (const reply of [...replies].reverse()) {
+				lines.push(formatMessage(reply), "");
+			}
+
+			return textResult(lines.join("\n").trimEnd(), {
+				teamId: team.id,
+				channelId: channel.id,
+				messageId: params.messageId,
+				replyCount: replies.length,
+			});
+		});
+	},
+};

package/src/tools/teams-search-messages.ts

@@ -0,0 +1,71 @@
+/**
+ * teams_search_messages — full-text search across the user's Teams history.
+ */
+
+import { Type } from "typebox";
+import { formatSearchHits, searchMessages } from "../graph/search.ts";
+import { hasAccess } from "../safety/index.ts";
+import {
+	AccountParam,
+	LimitParam,
+	TenantParam,
+	connectionFor,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsSearchMessagesTool = {
+	name: "teams_search_messages",
+	description:
+		"Search the signed-in user's Microsoft Teams messages — chats and channels — with the Microsoft Search " +
+		"API. Plain keywords work; so do qualifiers such as from:anna@contoso.com. " +
+		"Use this to find a conversation before reading or replying to it.",
+	parameters: Type.Object({
+		query: Type.String({ description: "Search terms, e.g. 'deployment friday' or 'from:anna@contoso.com budget'" }),
+		account: AccountParam,
+		tenant: TenantParam,
+		limit: LimitParam,
+	}),
+	promptSnippet: "Search the user's Teams messages",
+	promptGuidelines: [
+		"Use teams_search_messages when the user refers to something said in Teams without naming the chat or channel.",
+		"Search hits carry messageId plus the chat or channel ID — pass those to teams_read_thread or teams_read_chat for full context.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: { query: string; account?: string; tenant?: string; limit?: number },
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const hits = await searchMessages(conn, params.query, { max: params.limit ?? 25, signal });
+
+			// Search bypasses the listing endpoints, so the rules are applied to the
+			// results: a denied channel must not leak through a search box.
+			const visible = hits.filter((hit) => {
+				if (hit.channelIdentity?.channelId) {
+					return hasAccess(conn, "read", "channels", [
+						hit.channelIdentity.channelId,
+						hit.channelIdentity.teamId,
+					]);
+				}
+				if (hit.chatId) return hasAccess(conn, "read", "chats", [hit.chatId]);
+				return true;
+			});
+
+			const hidden = hits.length - visible.length;
+			const note = hidden > 0 ? `\n\n_${hidden} hit(s) hidden by your scope rules._` : "";
+
+			return textResult(`${formatSearchHits(visible, params.query)}${note}`, {
+				query: params.query,
+				count: visible.length,
+				hidden,
+			});
+		});
+	},
+};

package/src/tools/teams-send-channel-message.ts

@@ -0,0 +1,250 @@
+/**
+ * teams_send_channel_message — start a new post in a channel, as the user.
+ * teams_reply_channel_message — reply inside an existing thread.
+ *
+ * Both live here because they share the mention resolution and the audit
+ * shape; splitting them would mean two copies of the part that matters.
+ */
+
+import { Type } from "typebox";
+import { replyToChannelMessage, sendChannelMessage } from "../graph/messages.ts";
+import { resolveUserId } from "../graph/me.ts";
+import { auditWrite } from "../safety/audit.ts";
+import { assertAccess } from "../safety/index.ts";
+import { truncate } from "../utils/formatting.ts";
+import { requireChannel } from "./resolve.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	connectionLabel,
+	currentUser,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+import type { PersonRef } from "../types.ts";
+import type { TeamsConnection } from "../config/index.ts";
+
+/** Resolve mention references and check each against the write rules. */
+async function resolveMentions(
+	conn: TeamsConnection,
+	references: string[] | undefined,
+	signal?: AbortSignal,
+): Promise<{ mentions: PersonRef[]; error?: string }> {
+	const mentions: PersonRef[] = [];
+	for (const reference of references ?? []) {
+		const person = await resolveUserId(conn, reference, signal);
+		if (!person) {
+			return {
+				mentions,
+				error: `Could not resolve "${reference}" to a person. Use teams_find_user to look them up.`,
+			};
+		}
+		assertAccess(conn, "write", "people", person.displayName, [
+			person.displayName,
+			person.upn,
+			person.mail,
+			person.id,
+		]);
+		mentions.push(person);
+	}
+	return { mentions };
+}
+
+const sharedParams = {
+	channel: Type.String({ description: "Channel name or ID, or a 'Team/Channel' path" }),
+	team: Type.Optional(Type.String({ description: "Team name or ID (omit when using a path)" })),
+	body: Type.String({ description: "Message text. Plain text unless 'html' is true." }),
+	account: AccountParam,
+	tenant: TenantParam,
+	mentions: Type.Optional(
+		Type.Array(Type.String(), { description: "People to @-mention, by name, UPN or e-mail" }),
+	),
+	importance: Type.Optional(Type.String({ description: "'normal' (default), 'high' or 'urgent'" })),
+	html: Type.Optional(Type.Boolean({ description: "Treat 'body' as raw HTML instead of plain text" })),
+};
+
+export const teamsSendChannelMessageTool = {
+	name: "teams_send_channel_message",
+	description:
+		"Post a new message in a Microsoft Teams channel as the signed-in user. It appears exactly as if the " +
+		"user posted it. Give the channel as a 'Team/Channel' path or pass 'team' separately. " +
+		"'subject' starts a titled post; use teams_reply_channel_message to answer inside an existing thread.",
+	parameters: Type.Object({
+		...sharedParams,
+		subject: Type.Optional(Type.String({ description: "Optional post title" })),
+	}),
+	promptSnippet: "Post a message in a Teams channel as the user",
+	promptGuidelines: [
+		"Write in the user's voice — the post is attributed to them, not to an assistant.",
+		"Show the exact text and the target channel before posting when there is any ambiguity.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			channel: string;
+			team?: string;
+			body: string;
+			subject?: string;
+			account?: string;
+			tenant?: string;
+			mentions?: string[];
+			importance?: string;
+			html?: boolean;
+		},
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			if (!params.body.trim()) return errorResult("Refusing to post an empty message.");
+
+			const { team, channel } = await requireChannel(conn, params.team, params.channel, "write", signal);
+			const { mentions, error } = await resolveMentions(conn, params.mentions, signal);
+			if (error) return errorResult(error);
+
+			const me = await currentUser(conn, signal).catch(() => undefined);
+			const target = `${team.displayName}/${channel.displayName}`;
+
+			try {
+				const sent = await sendChannelMessage(
+					conn,
+					channel,
+					{
+						body: params.body,
+						html: params.html,
+						subject: params.subject,
+						importance: params.importance,
+						mentions,
+					},
+					signal,
+				);
+
+				auditWrite(conn.audit, {
+					tool: "teams_send_channel_message",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: `channel:${target}`,
+					summary: truncate(params.body, 200),
+				});
+
+				return textResult(
+					[
+						`✅ Posted in **${target}** as ${me?.displayName ?? "you"} (${connectionLabel(conn)}).`,
+						"",
+						`> ${truncate(params.body, 300)}`,
+						"",
+						`messageId: ${sent.id}`,
+					].join("\n"),
+					{ teamId: team.id, channelId: channel.id, messageId: sent.id },
+				);
+			} catch (err) {
+				auditWrite(conn.audit, {
+					tool: "teams_send_channel_message",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: `channel:${target}`,
+					summary: truncate(params.body, 200),
+					error: err instanceof Error ? err.message : String(err),
+				});
+				throw err;
+			}
+		});
+	},
+};
+
+export const teamsReplyChannelMessageTool = {
+	name: "teams_reply_channel_message",
+	description:
+		"Reply inside an existing Microsoft Teams channel thread as the signed-in user. " +
+		"Get the messageId from teams_read_channel, teams_read_thread or teams_search_messages. " +
+		"Replying keeps the conversation in one thread instead of starting a new post.",
+	parameters: Type.Object({
+		...sharedParams,
+		messageId: Type.String({ description: "ID of the thread's opening message" }),
+	}),
+	promptSnippet: "Reply in a Teams channel thread as the user",
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			channel: string;
+			team?: string;
+			messageId: string;
+			body: string;
+			account?: string;
+			tenant?: string;
+			mentions?: string[];
+			importance?: string;
+			html?: boolean;
+		},
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			if (!params.body.trim()) return errorResult("Refusing to post an empty reply.");
+
+			const { team, channel } = await requireChannel(conn, params.team, params.channel, "write", signal);
+			const { mentions, error } = await resolveMentions(conn, params.mentions, signal);
+			if (error) return errorResult(error);
+
+			const me = await currentUser(conn, signal).catch(() => undefined);
+			const target = `${team.displayName}/${channel.displayName}`;
+
+			try {
+				const sent = await replyToChannelMessage(
+					conn,
+					channel,
+					params.messageId,
+					{
+						body: params.body,
+						html: params.html,
+						importance: params.importance,
+						mentions,
+					},
+					signal,
+				);
+
+				auditWrite(conn.audit, {
+					tool: "teams_reply_channel_message",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: `channel:${target}#${params.messageId}`,
+					summary: truncate(params.body, 200),
+				});
+
+				return textResult(
+					[
+						`✅ Replied in **${target}** (thread ${params.messageId}) as ${me?.displayName ?? "you"}.`,
+						"",
+						`> ${truncate(params.body, 300)}`,
+						"",
+						`messageId: ${sent.id}`,
+					].join("\n"),
+					{ teamId: team.id, channelId: channel.id, messageId: sent.id, threadId: params.messageId },
+				);
+			} catch (err) {
+				auditWrite(conn.audit, {
+					tool: "teams_reply_channel_message",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: `channel:${target}#${params.messageId}`,
+					summary: truncate(params.body, 200),
+					error: err instanceof Error ? err.message : String(err),
+				});
+				throw err;
+			}
+		});
+	},
+};

package/src/tools/teams-send-chat-message.ts

@@ -0,0 +1,152 @@
+/**
+ * teams_send_chat_message — send a message in a chat, as the user.
+ *
+ * This is the sharpest tool in the box: what it writes is indistinguishable
+ * from the user typing it. Hence the order of operations — resolve the chat,
+ * check the chat rules, check every participant against the people rules,
+ * resolve the mentions, send, then record the audit entry.
+ */
+
+import { Type } from "typebox";
+import { sendChatMessage } from "../graph/messages.ts";
+import { resolveUserId } from "../graph/me.ts";
+import { auditWrite } from "../safety/audit.ts";
+import { assertAccess } from "../safety/index.ts";
+import { truncate } from "../utils/formatting.ts";
+import { requireChat } from "./resolve.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	connectionLabel,
+	currentUser,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+interface SendChatParams {
+	chat: string;
+	body: string;
+	account?: string;
+	tenant?: string;
+	mentions?: string[];
+	importance?: string;
+	html?: boolean;
+}
+
+export const teamsSendChatMessageTool = {
+	name: "teams_send_chat_message",
+	description:
+		"Send a message in a Microsoft Teams chat as the signed-in user. The message appears exactly as if the " +
+		"user typed it. Accepts a chat ID, group chat topic, or participant name/e-mail. " +
+		"Use 'mentions' with names or e-mail addresses to @-mention people — write '@Display Name' in the body " +
+		"where the mention should appear.",
+	parameters: Type.Object({
+		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
+		body: Type.String({ description: "Message text. Plain text unless 'html' is true." }),
+		account: AccountParam,
+		tenant: TenantParam,
+		mentions: Type.Optional(
+			Type.Array(Type.String(), {
+				description: "People to @-mention, by name, UPN or e-mail",
+			}),
+		),
+		importance: Type.Optional(
+			Type.String({ description: "'normal' (default), 'high' or 'urgent'" }),
+		),
+		html: Type.Optional(
+			Type.Boolean({ description: "Treat 'body' as raw HTML instead of plain text" }),
+		),
+	}),
+	promptSnippet: "Send a message in a Teams chat as the user",
+	promptGuidelines: [
+		"Write the message in the user's voice — it is sent from their account, not from an assistant.",
+		"Show the user the exact text before sending when the intent is even slightly ambiguous.",
+		"Do not add signatures, disclaimers, or a note that the message was written by an AI unless the user asks.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: SendChatParams,
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+
+			if (!params.body.trim()) return errorResult("Refusing to send an empty message.");
+
+			const chat = await requireChat(conn, params.chat, "write", signal);
+
+			// Mentions address people directly, so they are checked individually
+			// even when the chat itself is allowed.
+			const mentions = [];
+			for (const reference of params.mentions ?? []) {
+				const person = await resolveUserId(conn, reference, signal);
+				if (!person) {
+					return errorResult(
+						`Could not resolve "${reference}" to a person. Use teams_find_user to look them up.`,
+					);
+				}
+				assertAccess(conn, "write", "people", person.displayName, [
+					person.displayName,
+					person.upn,
+					person.mail,
+					person.id,
+				]);
+				mentions.push(person);
+			}
+
+			const me = await currentUser(conn, signal).catch(() => undefined);
+
+			try {
+				const sent = await sendChatMessage(
+					conn,
+					chat.id,
+					{
+						body: params.body,
+						html: params.html,
+						importance: params.importance,
+						mentions,
+					},
+					signal,
+				);
+
+				auditWrite(conn.audit, {
+					tool: "teams_send_chat_message",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: `chat:${chat.label}`,
+					summary: truncate(params.body, 200),
+				});
+
+				return textResult(
+					[
+						`✅ Message sent to **${chat.label}** as ${me?.displayName ?? "you"} (${connectionLabel(conn)}).`,
+						"",
+						`> ${truncate(params.body, 300)}`,
+						"",
+						`messageId: ${sent.id}`,
+					].join("\n"),
+					{ chatId: chat.id, messageId: sent.id },
+				);
+			} catch (err) {
+				auditWrite(conn.audit, {
+					tool: "teams_send_chat_message",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: `chat:${chat.label}`,
+					summary: truncate(params.body, 200),
+					error: err instanceof Error ? err.message : String(err),
+				});
+				throw err;
+			}
+		});
+	},
+};