@patimweb/pi-teams 1.2.0 → 1.3.1

package/src/tools/teams-delete-message.ts

@@ -1,15 +1,19 @@
 /**
- * teams_delete_message — soft-delete one of the user's own messages.
+ * teams_delete_message — take back a message the user sent in a chat.
  *
  * Graph only permits this for the sender, which is also the only case that
  * makes sense here: pi may take back something it said in the user's name, not
  * edit anyone else's history.
+ *
+ * Chats only. Deleting a channel post needs the `ChannelMessage.ReadWrite`
+ * scope, which this package does not request — a channel post is deleted in
+ * Teams, or edited into what it should have said.
  */
 
 import { Type } from "typebox";
 import { softDeleteMessage, undoSoftDeleteMessage } from "../graph/messages.ts";
 import { auditWrite } from "../safety/audit.ts";
-import { requireChannel, requireChat } from "./resolve.ts";
+import { requireChat } from "./resolve.ts";
 import {
 	AccountParam,
 	TenantParam,
@@ -21,38 +25,31 @@ import {
 	type ToolContext,
 	type ToolResult,
 } from "./shared.ts";
-import type { MessageLocation } from "../types.ts";
 
 export const teamsDeleteMessageTool = {
 	name: "teams_delete_message",
 	description:
-		"Delete a message the signed-in user sent in Microsoft Teams (soft delete, exactly like deleting it in " +
-		"the app). Specify 'chat' or 'channel' (plus 'team') to say where it lives. " +
-		"Set undo: true to restore a message that was soft-deleted. Only the sender's own messages can be deleted.",
+		"Delete a message the signed-in user sent in a Microsoft Teams chat (soft delete, exactly like deleting " +
+		"it in the app). Set undo: true to restore a message that was soft-deleted. " +
+		"Only the sender's own messages can be deleted, and only in chats — a channel post cannot be deleted " +
+		"through Graph with the permissions pi asks for.",
 	parameters: Type.Object({
 		messageId: Type.String({ description: "ID of the message to delete" }),
-		chat: Type.Optional(Type.String({ description: "Chat ID or name, when the message is in a chat" })),
-		channel: Type.Optional(
-			Type.String({ description: "Channel name/ID or 'Team/Channel' path, when it is in a channel" }),
-		),
-		team: Type.Optional(Type.String({ description: "Team name or ID" })),
-		replyId: Type.Optional(
-			Type.String({ description: "Reply ID, when deleting a reply inside a channel thread" }),
-		),
+		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
 		undo: Type.Optional(Type.Boolean({ description: "Restore a previously deleted message" })),
 		account: AccountParam,
 		tenant: TenantParam,
 	}),
 	promptSnippet: "Delete a message the user sent in Teams",
+	promptGuidelines: [
+		"Prefer teams_update_message over deleting and resending: an edit keeps the message in place, a delete leaves a gap and the replacement arrives as a new notification.",
+	],
 
 	async execute(
 		_toolCallId: string,
 		params: {
 			messageId: string;
-			chat?: string;
-			channel?: string;
-			team?: string;
-			replyId?: string;
+			chat: string;
 			undo?: boolean;
 			account?: string;
 			tenant?: string;
@@ -63,37 +60,13 @@ export const teamsDeleteMessageTool = {
 	): Promise<ToolResult> {
 		return run(async () => {
 			const conn = connectionFor(ctx, params.account, params.tenant);
-
-			let location: MessageLocation;
-			let target: string;
-
-			if (params.chat) {
-				const chat = await requireChat(conn, params.chat, "write", signal);
-				location = { kind: "chat", chatId: chat.id };
-				target = `chat:${chat.label}`;
-			} else if (params.channel) {
-				const { team, channel } = await requireChannel(conn, params.team, params.channel, "write", signal);
-				location = {
-					kind: "channel",
-					teamId: team.id,
-					teamName: team.displayName,
-					channelId: channel.id,
-					channelName: channel.displayName,
-				};
-				target = `channel:${team.displayName}/${channel.displayName}`;
-			} else {
-				return errorResult("Specify either 'chat' or 'channel' so pi knows where the message lives.");
-			}
-
-			// Graph needs an explicit user id for the chat form of this action, and
-			// only the sender may delete — so failing here is better than a 403.
 			const me = await currentUser(conn, signal);
+			const chat = await requireChat(conn, params.chat, "write", signal);
 
-			const options = { replyId: params.replyId, signal };
 			if (params.undo) {
-				await undoSoftDeleteMessage(conn, location, params.messageId, me.id, options);
+				await undoSoftDeleteMessage(conn, chat.id, params.messageId, me.id, { signal });
 			} else {
-				await softDeleteMessage(conn, location, params.messageId, me.id, options);
+				await softDeleteMessage(conn, chat.id, params.messageId, me.id, { signal });
 			}
 
 			auditWrite(conn.audit, {
@@ -101,13 +74,13 @@ export const teamsDeleteMessageTool = {
 				account: conn.account,
 				tenant: conn.tenant,
 				actor: me.upn,
-				target,
+				target: `chat:${chat.label}`,
 				summary: `${params.undo ? "restored" : "deleted"} message ${params.messageId}`,
 			});
 
 			return textResult(
-				`✅ Message ${params.messageId} ${params.undo ? "restored" : "deleted"} in ${target}.`,
-				{ messageId: params.messageId, undone: !!params.undo },
+				`✅ Message ${params.messageId} ${params.undo ? "restored" : "deleted"} in "${chat.label}".`,
+				{ messageId: params.messageId, chatId: chat.id, undone: !!params.undo },
 			);
 		});
 	},

package/src/tools/teams-inbox.ts

@@ -47,6 +47,7 @@ export const teamsInboxTool = {
 	promptGuidelines: [
 		"Use teams_inbox for open-ended catch-up questions about Teams.",
 		"Summarize what is waiting and who is waiting on it; do not reply to anything unless the user asks.",
+		"After a catch-up, offer to clear the list with teams_mark_read — never mark a chat read unasked.",
 	],
 
 	async execute(

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

@@ -0,0 +1,84 @@
+/**
+ * teams_mark_read — move the read cursor of a chat.
+ *
+ * "Mark as read" is the one piece of chat state a delegated token may change
+ * on the user's behalf, and it is the natural end of a catch-up: pi summarizes
+ * the inbox, then clears it. It is a mutation all the same — the chat stops
+ * being bold, and where the tenant shows read receipts, the sender sees that
+ * it was opened.
+ */
+
+import { Type } from "typebox";
+import { setChatReadState } from "../graph/chats.ts";
+import { auditWrite } from "../safety/audit.ts";
+import { requireChat } from "./resolve.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	currentUser,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsMarkReadTool = {
+	name: "teams_mark_read",
+	description:
+		"Mark a Microsoft Teams chat as read — or unread again — as the signed-in user, exactly like opening " +
+		"or re-marking it in the app. Accepts a chat ID, a group chat topic, or a participant's name/e-mail. " +
+		"Set read: false to make the chat unread again. Channels have no equivalent: channel posts cannot be " +
+		"marked read or unread.",
+	parameters: Type.Object({
+		chat: Type.String({
+			description: "Chat ID, group chat topic, or a participant's name/e-mail",
+		}),
+		read: Type.Optional(
+			Type.Boolean({
+				description: "true (default) marks the chat read, false marks it unread again",
+			}),
+		),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Mark a Teams chat read or unread",
+	promptGuidelines: [
+		"Use teams_mark_read for 'mark that as read', 'clear my inbox', 'mark it unread again'.",
+		"Marking a chat read is visible to the sender where the tenant shows read receipts, so do it when asked, not on your own initiative.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: { chat: string; read?: boolean; account?: string; tenant?: string },
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const me = await currentUser(conn, signal);
+
+			// "write": this changes state in Teams, so the write rules apply —
+			// a chat pi may read but not write is one whose unread marker stays.
+			const chat = await requireChat(conn, params.chat, "write", signal);
+			const read = params.read !== false;
+
+			await setChatReadState(conn, chat.id, me, read, { signal });
+
+			auditWrite(conn.audit, {
+				tool: "teams_mark_read",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me.upn,
+				target: `chat:${chat.label}`,
+				summary: `marked chat as ${read ? "read" : "unread"}`,
+			});
+
+			return textResult(
+				`✅ "${chat.label}" marked as ${read ? "read" : "unread"}.`,
+				{ chatId: chat.id, label: chat.label, read },
+			);
+		});
+	},
+};

package/src/tools/teams-meetings.ts

@@ -13,7 +13,9 @@ import {
 	createOnlineMeeting,
 	getEvent,
 	listEvents,
+	respondToEvent,
 	updateEvent,
+	type EventResponse,
 } from "../graph/calendar.ts";
 import { auditWrite } from "../safety/audit.ts";
 import { assertAccess } from "../safety/index.ts";
@@ -302,6 +304,102 @@ export const teamsUpdateMeetingTool = {
 	},
 };
 
+export const teamsRespondInviteTool = {
+	name: "teams_respond_invite",
+	description:
+		"Answer a Microsoft Teams meeting invitation as the signed-in user: accept, decline, or mark as " +
+		"tentative. The organizer is notified unless sendResponse is false. Get the eventId from " +
+		"teams_list_meetings. Only invitations can be answered this way — a meeting the user organizes is " +
+		"changed with teams_update_meeting or cancelled with teams_cancel_meeting.",
+	parameters: Type.Object({
+		eventId: Type.String({ description: "Calendar event ID of the invitation" }),
+		response: Type.Union(
+			[Type.Literal("accept"), Type.Literal("decline"), Type.Literal("tentative")],
+			{ description: "'accept', 'decline', or 'tentative'" },
+		),
+		comment: Type.Optional(
+			Type.String({ description: "Note sent to the organizer with the answer" }),
+		),
+		sendResponse: Type.Optional(
+			Type.Boolean({
+				description: "Notify the organizer (default true). Set false to answer silently",
+			}),
+		),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Accept or decline a Teams meeting invitation",
+	promptGuidelines: [
+		"Answering an invitation notifies the organizer, so only respond to an invitation the user actually decided on.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			eventId: string;
+			response: "accept" | "decline" | "tentative";
+			comment?: string;
+			sendResponse?: boolean;
+			account?: string;
+			tenant?: string;
+		},
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const me = await currentUser(conn, signal);
+
+			const event = await getEvent(conn, params.eventId, signal);
+			if (!event) return errorResult(`Event ${params.eventId} not found. Check the ID from teams_list_meetings.`);
+
+			// Graph would answer with a bare error; the real problem is that the user
+			// is the organizer, and answering their own invitation is a no-op.
+			const organizer = [event.organizer?.mail, event.organizer?.upn].filter(Boolean) as string[];
+			const mine = [me.mail, me.upn].filter(Boolean) as string[];
+			if (
+				organizer.length > 0 &&
+				mine.some((address) => organizer.some((other) => other.toLowerCase() === address.toLowerCase()))
+			) {
+				return errorResult(
+					`You organize "${event.subject}" — there is no invitation to answer. ` +
+						`Use teams_update_meeting to change it, or teams_cancel_meeting to call it off.`,
+				);
+			}
+
+			const response: EventResponse = params.response === "tentative" ? "tentativelyAccept" : params.response;
+			await respondToEvent(conn, params.eventId, response, {
+				comment: params.comment,
+				sendResponse: params.sendResponse,
+				signal,
+			});
+
+			auditWrite(conn.audit, {
+				tool: "teams_respond_invite",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me.upn,
+				target: `event:${event.subject}`,
+				summary: `answered the invitation with "${params.response}"`,
+			});
+
+			const verb =
+				params.response === "accept"
+					? "accepted"
+					: params.response === "decline"
+						? "declined"
+						: "marked as tentative";
+			const notified = params.sendResponse === false ? " (organizer not notified)" : "";
+
+			return textResult(`✅ "${event.subject}" ${verb}${notified}.`, {
+				eventId: params.eventId,
+				response: params.response,
+			});
+		});
+	},
+};
+
 export const teamsCancelMeetingTool = {
 	name: "teams_cancel_meeting",
 	description:

package/src/tools/teams-update-message.ts

@@ -0,0 +1,88 @@
+/**
+ * teams_update_message — rewrite a message the user already sent.
+ *
+ * Editing beats delete-and-resend: the message keeps its ID and its place in
+ * the conversation, and Teams shows it as edited rather than as a gap followed
+ * by a near-duplicate. Only the sender's own messages can be edited, which is
+ * the only case that makes sense for something pi wrote in the user's name.
+ *
+ * Chats only. Editing a channel post needs the `ChannelMessage.ReadWrite`
+ * scope, which this package does not request and does not assume will be
+ * granted — so the tool does not offer a path that could not run.
+ */
+
+import { Type } from "typebox";
+import { updateMessage } from "../graph/messages.ts";
+import { auditWrite } from "../safety/audit.ts";
+import { requireChat } from "./resolve.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	currentUser,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsUpdateMessageTool = {
+	name: "teams_update_message",
+	description:
+		"Edit a message the signed-in user already sent in a Microsoft Teams chat: replaces the text and keeps " +
+		"the message in place, so Teams shows it as edited instead of as a new message. " +
+		"Use this instead of deleting a message and sending a corrected copy.",
+	parameters: Type.Object({
+		messageId: Type.String({ description: "ID of the message to edit" }),
+		body: Type.String({ description: "The new message text (lightweight markdown by default)" }),
+		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
+		html: Type.Optional(Type.Boolean({ description: "Treat 'body' as raw HTML instead of markdown" })),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Edit a message the user sent in Teams",
+	promptGuidelines: [
+		"Use teams_update_message to correct a message the user already sent, rather than deleting it and posting a replacement.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			messageId: string;
+			body: string;
+			chat: string;
+			html?: boolean;
+			account?: string;
+			tenant?: string;
+		},
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const me = await currentUser(conn, signal);
+			const chat = await requireChat(conn, params.chat, "write", signal);
+
+			await updateMessage(conn, chat.id, params.messageId, me.id, {
+				body: params.body,
+				html: params.html,
+			}, { signal });
+
+			auditWrite(conn.audit, {
+				tool: "teams_update_message",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me.upn,
+				target: `chat:${chat.label}`,
+				summary: `edited message ${params.messageId}: ${params.body.slice(0, 120)}`,
+			});
+
+			return textResult(`✅ Message ${params.messageId} edited in "${chat.label}".`, {
+				messageId: params.messageId,
+				chatId: chat.id,
+			});
+		});
+	},
+};

package/src/tools/tool-names.ts

@@ -15,14 +15,16 @@ export const MUTATION_TOOLS = new Set<string>([
 	"teams_create_chat",
 	"teams_delete_message",
 	"teams_react",
-	// Structure
-	"teams_create_channel",
+	"teams_mark_read",
+	"teams_update_message",
+	"teams_chat_members",
 	// Presence
 	"teams_set_presence",
 	"teams_set_status_message",
 	// Calendar
 	"teams_create_meeting",
 	"teams_update_meeting",
+	"teams_respond_invite",
 	"teams_cancel_meeting",
 	// Local configuration and credentials
 	"teams_setup",

package/src/types.ts

@@ -86,6 +86,17 @@ export interface ChatSummary {
 	webUrl?: string;
 }
 
+export interface ChatMemberSummary {
+	/** conversationMember id — the identifier DELETE /chats/{id}/members/{id} needs */
+	membershipId: string;
+	/** Object id of the person behind the membership */
+	userId?: string;
+	displayName: string;
+	upn?: string;
+	mail?: string;
+	roles: string[];
+}
+
 // ---------------------------------------------------------------------------
 // Messages
 // ---------------------------------------------------------------------------

package/src/utils/errors.ts

@@ -40,6 +40,7 @@ const CONSENT_HINTS: Record<string, string> = {
 	"ChannelMessage.Send": "posting in channels",
 	"Chat.ReadWrite": "reading and sending chat messages",
 	"ChatMessage.Send": "sending chat messages",
+	"ChatMember.ReadWrite": "removing someone from a chat",
 	"Presence.ReadWrite": "reading and setting your presence",
 	"Calendars.ReadWrite": "reading and creating calendar events",
 	"OnlineMeetings.ReadWrite": "creating Teams meetings",

package/src/utils/formatting.ts

@@ -114,6 +114,68 @@ export function formatRelative(iso: string | undefined): string {
 	return formatDate(iso);
 }
 
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const MONTHS = [
+	"Jan",
+	"Feb",
+	"Mar",
+	"Apr",
+	"May",
+	"Jun",
+	"Jul",
+	"Aug",
+	"Sep",
+	"Oct",
+	"Nov",
+	"Dec",
+];
+
+/**
+ * Split a naive Graph date-time into its parts, as UTC.
+ *
+ * Availability views and free/busy blocks arrive already localised to the zone
+ * the caller asked Graph for, so re-interpreting them in the machine's zone
+ * would shift every time by the offset between the two.
+ */
+function naiveParts(value: string | undefined):
+	| { weekday: string; day: number; month: string; year: number; time: string }
+	| undefined {
+	if (!value) return undefined;
+	const match = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})/.exec(value.trim());
+	if (!match) return undefined;
+	const [, year, month, day, hour, minute] = match;
+	const asUtc = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+	return {
+		weekday: WEEKDAYS[asUtc.getUTCDay()] ?? "",
+		day: Number(day),
+		month: MONTHS[Number(month) - 1] ?? "",
+		year: Number(year),
+		time: `${hour}:${minute}`,
+	};
+}
+
+/** "Mon 15 Sep 2026" — a window's day, without the clock time. */
+export function formatNaiveDay(value: string | undefined): string {
+	const parts = naiveParts(value);
+	if (!parts) return value ?? "";
+	return `${parts.weekday} ${parts.day} ${parts.month} ${parts.year}`;
+}
+
+/** "09:00–09:30" — the clock part of a free/busy block. */
+export function formatTimeRange(start: string | undefined, end: string | undefined): string {
+	const from = naiveParts(start);
+	const to = naiveParts(end);
+	if (!from || !to) return "unknown time";
+	return `${from.time}–${to.time}`;
+}
+
+/** "Mon 15 Sep, 09:00–09:30" — one proposed slot. */
+export function formatSlotRange(start: string | undefined, end: string | undefined): string {
+	const parts = naiveParts(start);
+	if (!parts) return `${start ?? "?"}–${end ?? "?"}`;
+	return `${parts.weekday} ${parts.day} ${parts.month}, ${formatTimeRange(start, end)}`;
+}
+
 /** Shorten a string for previews, without cutting mid-escape. */
 export function truncate(text: string, max: number): string {
 	const oneLine = text.replace(/\s*\n\s*/g, " ").trim();