@patimweb/pi-teams 1.2.0 → 1.3.0

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();

package/src/utils/slots.ts

@@ -0,0 +1,171 @@
+/**
+ * Finding a slot everyone is free in.
+ *
+ * Graph returns availability as a *string*, one character per time slot since
+ * the window start — so the one thing that can go silently wrong is the mapping
+ * from character index back to a clock time. That mapping lives here, pure and
+ * testable, instead of inside a tool where the only test would be a live
+ * calendar.
+ *
+ * Naive date-times ("2026-09-15T09:00:00", no offset) are parsed as UTC on
+ * purpose: they already carry the zone the caller asked Graph for, and reading
+ * them as UTC keeps the arithmetic independent of the machine's own zone.
+ */
+
+/** One person's availability, as Graph's availability view expresses it. */
+export interface BusyView {
+	/** Name to report the person by */
+	name: string;
+	/** One character per slot: `0` free, `1` tentative, `2` busy, `3` out of office, `4` working elsewhere */
+	view: string;
+}
+
+export interface SlotWindow {
+	/** First slot, naive ISO, aligned with index 0 of every view */
+	start: string;
+	/** Slot width in minutes — the same value the Graph call used */
+	intervalMinutes: number;
+	/** Ignore slots that begin before this naive ISO (used to skip the past) */
+	notBefore?: string;
+	/** Also ignore slots outside Mon–Fri, 09:00–17:00 */
+	workingHoursOnly?: boolean;
+}
+
+export interface FreeSlot {
+	start: string;
+	end: string;
+}
+
+const FREE = "0";
+const WORKDAY_START = 9 * 60;
+const WORKDAY_END = 17 * 60;
+const MINUTE_MS = 60_000;
+
+/**
+ * Parse a naive Graph date-time into a UTC timestamp.
+ *
+ * Returns undefined for anything without a date and time rather than guessing:
+ * a missing value must not become "1 January 1970, which looks free".
+ */
+export function parseNaive(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const match = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?/.exec(value.trim());
+	if (!match) return undefined;
+	const [, year, month, day, hour, minute, second] = match;
+	return Date.UTC(
+		Number(year),
+		Number(month) - 1,
+		Number(day),
+		Number(hour),
+		Number(minute),
+		Number(second ?? 0),
+	);
+}
+
+/** UTC timestamp → naive ISO without milliseconds. */
+export function formatNaive(timestamp: number): string {
+	return new Date(timestamp).toISOString().slice(0, 19);
+}
+
+/** Shift a naive date-time by whole minutes. */
+export function addMinutes(naive: string, minutes: number): string | undefined {
+	const parsed = parseNaive(naive);
+	return parsed === undefined ? undefined : formatNaive(parsed + minutes * MINUTE_MS);
+}
+
+/** `YYYY-MM-DDT00:00:00` for today + offset, in the machine's time zone. */
+export function localDayStart(offsetDays = 0): string {
+	const date = new Date();
+	date.setDate(date.getDate() + offsetDays);
+	return `${localDate(date)}T00:00:00`;
+}
+
+/** The current time as a naive date-time, in the machine's time zone. */
+export function localNow(): string {
+	return `${localDate(new Date())}T${localTime(new Date())}`;
+}
+
+/** The machine's time zone, for calls that would otherwise default to UTC. */
+export function localTimeZone(): string {
+	try {
+		return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+	} catch {
+		return "UTC";
+	}
+}
+
+function localDate(date: Date): string {
+	const pad = (n: number) => String(n).padStart(2, "0");
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+function localTime(date: Date): string {
+	const pad = (n: number) => String(n).padStart(2, "0");
+	return `${pad(date.getHours())}:${pad(date.getMinutes())}:00`;
+}
+
+function insideWorkingHours(start: number, end: number): boolean {
+	const from = new Date(start);
+	const to = new Date(end);
+	const weekday = from.getUTCDay();
+	if (weekday === 0 || weekday === 6) return false;
+	// A slot has to fit inside one working day; a window across midnight is not
+	// a 30-minute meeting anyway.
+	if (from.toISOString().slice(0, 10) !== to.toISOString().slice(0, 10)) return false;
+	const startMinutes = from.getUTCHours() * 60 + from.getUTCMinutes();
+	const endMinutes = to.getUTCHours() * 60 + to.getUTCMinutes();
+	return startMinutes >= WORKDAY_START && endMinutes <= WORKDAY_END;
+}
+
+/** The first slots in which nobody has anything. */
+export function findCommonFreeSlots(
+	views: readonly BusyView[],
+	window: SlotWindow,
+	limit = 5,
+): FreeSlot[] {
+	const base = parseNaive(window.start);
+	if (base === undefined || views.length === 0) return [];
+
+	// The shortest view decides how far the search goes: where Graph truncated
+	// a person's availability the tail is unknown, and unknown is not free.
+	const horizon = Math.min(...views.map((entry) => entry.view.length));
+	const earliest = parseNaive(window.notBefore);
+	const step = window.intervalMinutes * MINUTE_MS;
+
+	const slots: FreeSlot[] = [];
+	for (let index = 0; index < horizon && slots.length < limit; index += 1) {
+		if (views.some((entry) => entry.view[index] !== FREE)) continue;
+
+		const start = base + index * step;
+		const end = start + step;
+		if (earliest !== undefined && start < earliest) continue;
+		if (window.workingHoursOnly && !insideWorkingHours(start, end)) continue;
+
+		slots.push({ start: formatNaive(start), end: formatNaive(end) });
+	}
+
+	return slots;
+}
+
+/**
+ * The statuses keeping everyone apart, for when no slot is free.
+ *
+ * Turns "nothing works" into something a person can act on, and reports only
+ * times and statuses — never what the appointment is.
+ */
+export function describeBusy(
+	busy: readonly {
+		scheduleId: string;
+		busy: Array<{ status: string; start: string; end: string }>;
+	}[],
+	names: Map<string, string>,
+): string[] {
+	return busy.map((entry) => {
+		const name = names.get(entry.scheduleId.toLowerCase()) ?? entry.scheduleId;
+		const blocks = entry.busy
+			.slice(0, 6)
+			.map((block) => `${block.start.slice(11, 16)}–${block.end.slice(11, 16)} (${block.status})`)
+			.join(", ");
+		return `- ${name}: ${blocks || "no busy blocks reported"}`;
+	});
+}

package/src/tools/teams-create-channel.ts

@@ -1,89 +0,0 @@
-/**
- * teams_create_channel — add a channel to a team.
- */
-
-import { Type } from "typebox";
-import { createChannel } from "../graph/teams.ts";
-import { auditWrite } from "../safety/audit.ts";
-import { requireTeam } from "./resolve.ts";
-import {
-	AccountParam,
-	TenantParam,
-	connectionFor,
-	currentUser,
-	run,
-	textResult,
-	type ToolContext,
-	type ToolResult,
-} from "./shared.ts";
-
-export const teamsCreateChannelTool = {
-	name: "teams_create_channel",
-	description:
-		"Create a new channel in a Microsoft Teams team. membershipType 'standard' (default) is visible to the " +
-		"whole team, 'private' only to the members you add afterwards.",
-	parameters: Type.Object({
-		team: Type.String({ description: "Team name or ID" }),
-		name: Type.String({ description: "Channel display name" }),
-		description: Type.Optional(Type.String({ description: "Channel description" })),
-		membershipType: Type.Optional(
-			Type.String({ description: "'standard' (default) or 'private'" }),
-		),
-		account: AccountParam,
-		tenant: TenantParam,
-	}),
-	promptSnippet: "Create a channel in a Teams team",
-
-	async execute(
-		_toolCallId: string,
-		params: {
-			team: string;
-			name: string;
-			description?: string;
-			membershipType?: string;
-			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 team = await requireTeam(conn, params.team, "write", signal);
-
-			const channel = await createChannel(
-				conn,
-				team,
-				{
-					displayName: params.name,
-					description: params.description,
-					membershipType: params.membershipType,
-				},
-				signal,
-			);
-
-			const me = await currentUser(conn, signal).catch(() => undefined);
-			auditWrite(conn.audit, {
-				tool: "teams_create_channel",
-				account: conn.account,
-				tenant: conn.tenant,
-				actor: me?.upn,
-				target: `team:${team.displayName}`,
-				summary: `created channel "${params.name}" (${params.membershipType ?? "standard"})`,
-			});
-
-			return textResult(
-				[
-					`✅ Channel **${team.displayName}/${channel.displayName}** created.`,
-					"",
-					`channelId: ${channel.id}`,
-					channel.webUrl ? `Open in Teams: ${channel.webUrl}` : "",
-				]
-					.filter(Boolean)
-					.join("\n"),
-				{ teamId: team.id, channelId: channel.id },
-			);
-		});
-	},
-};