@patimweb/pi-teams 1.0.0

package/src/tools/teams-list-members.ts

@@ -0,0 +1,72 @@
+/**
+ * teams_list_members — members of a team or a channel.
+ */
+
+import { Type } from "typebox";
+import { listChannelMembers, listTeamMembers } from "../graph/teams.ts";
+import { hasAccess } from "../safety/index.ts";
+import { formatMemberList } from "../utils/formatting.ts";
+import { requireChannel, requireTeam } from "./resolve.ts";
+import {
+	AccountParam,
+	LimitParam,
+	TenantParam,
+	connectionFor,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsListMembersTool = {
+	name: "teams_list_members",
+	description:
+		"List the members of a Microsoft Teams team, or of one channel when 'channel' is given. " +
+		"Returns display names, e-mail addresses and roles — useful before @-mentioning someone or " +
+		"starting a chat with the right person.",
+	parameters: Type.Object({
+		team: Type.String({ description: "Team display name or ID" }),
+		channel: Type.Optional(
+			Type.String({ description: "Channel name or ID; omit to list the whole team" }),
+		),
+		account: AccountParam,
+		tenant: TenantParam,
+		limit: LimitParam,
+	}),
+	promptSnippet: "List members of a Teams team or channel",
+
+	async execute(
+		_toolCallId: string,
+		params: { team: string; channel?: 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);
+
+			if (params.channel) {
+				const { team, channel } = await requireChannel(conn, params.team, params.channel, "read", signal);
+				const members = await listChannelMembers(conn, team.id, channel.id, params.limit ?? 200, signal);
+				const visible = members.filter((member) =>
+					hasAccess(conn, "read", "people", [member.displayName, member.upn, member.mail, member.id]),
+				);
+				return textResult(
+					formatMemberList(visible, `${team.displayName}/${channel.displayName}`),
+					{ team: team.displayName, channel: channel.displayName, count: visible.length },
+				);
+			}
+
+			const team = await requireTeam(conn, params.team, "read", signal);
+			const members = await listTeamMembers(conn, team.id, params.limit ?? 200, signal);
+			const visible = members.filter((member) =>
+				hasAccess(conn, "read", "people", [member.displayName, member.upn, member.mail, member.id]),
+			);
+
+			return textResult(formatMemberList(visible, team.displayName), {
+				team: team.displayName,
+				count: visible.length,
+			});
+		});
+	},
+};

package/src/tools/teams-list-teams.ts

@@ -0,0 +1,65 @@
+/**
+ * teams_list_teams — the teams the signed-in user belongs to, filtered by the
+ * read rules.
+ */
+
+import { Type } from "typebox";
+import { listJoinedTeams } from "../graph/teams.ts";
+import { teamCandidates } from "../graph/mappers.ts";
+import { hasAccess } from "../safety/index.ts";
+import { formatTeamList } from "../utils/formatting.ts";
+import {
+	AccountParam,
+	LimitParam,
+	TenantParam,
+	connectionFor,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsListTeamsTool = {
+	name: "teams_list_teams",
+	description:
+		"List the Microsoft Teams teams the signed-in user is a member of. Teams excluded by the configured " +
+		"read rules are not shown. Use this to discover team names and IDs before reading or posting in a channel.",
+	parameters: Type.Object({
+		account: AccountParam,
+		tenant: TenantParam,
+		limit: LimitParam,
+		filter: Type.Optional(
+			Type.String({ description: "Only show teams whose name contains this text" }),
+		),
+	}),
+	promptSnippet: "List the user's Microsoft Teams teams",
+
+	async execute(
+		_toolCallId: string,
+		params: { account?: string; tenant?: string; limit?: number; filter?: string },
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const all = await listJoinedTeams(conn, params.limit ?? 100, signal);
+
+			const visible = all.filter((team) => hasAccess(conn, "read", "teams", teamCandidates(team)));
+			const filtered = params.filter
+				? visible.filter((team) =>
+						team.displayName.toLowerCase().includes(params.filter!.toLowerCase()),
+					)
+				: visible;
+
+			const hidden = all.length - visible.length;
+			const note = hidden > 0 ? `\n\n_${hidden} team(s) hidden by your scope rules._` : "";
+
+			return textResult(`${formatTeamList(filtered)}${note}`, {
+				count: filtered.length,
+				hidden,
+				account: conn.account,
+			});
+		});
+	},
+};

package/src/tools/teams-login.ts

@@ -0,0 +1,199 @@
+/**
+ * teams_login — sign in as the user via the device code flow.
+ *
+ * The tool streams the code and URL through `onUpdate` as soon as Microsoft
+ * issues them, then keeps polling. That ordering matters: the user has a
+ * couple of minutes to act, and they cannot act on a code that only appears
+ * after the tool returns.
+ */
+
+import { Type } from "typebox";
+import { pollForToken, requestDeviceCode } from "../auth/device-code.ts";
+import { acquireAppToken } from "../auth/client-credentials.ts";
+import { clearMemoryCache, forgetToken, storeToken } from "../auth/index.ts";
+import { clearAllTokens, deleteToken } from "../auth/token-store.ts";
+import { tokenScopes } from "../auth/jwt.ts";
+import { getMe } from "../graph/me.ts";
+import { formatGraphError } from "../utils/errors.ts";
+import {
+	AccountParam,
+	TenantParam,
+	clearUserCache,
+	connectionFor,
+	connectionLabel,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+interface LoginParams {
+	account?: string;
+	tenant?: string;
+}
+
+export const teamsLoginTool = {
+	name: "teams_login",
+	description:
+		"Sign in to Microsoft Teams as yourself using the device code flow. Shows a short code and a URL; " +
+		"open the URL, enter the code, and sign in with your normal credentials. The session is saved " +
+		"(including a refresh token) so this is only needed once per account/tenant. " +
+		"Use the 'account' and 'tenant' parameters to sign in to a second company or a guest tenant.",
+	parameters: Type.Object({
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Sign in to Microsoft Teams as the user",
+	promptGuidelines: [
+		"Use teams_login when a Teams tool reports that pi is not signed in, or when the user wants to add a second account.",
+		"Show the user code and the verification URL to the user verbatim — they cannot complete sign-in without them.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: LoginParams,
+		signal: AbortSignal | undefined,
+		onUpdate: ((update: { content: Array<{ type: "text"; text: string }> }) => void) | undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const label = connectionLabel(conn);
+
+			// App-only needs no user interaction at all.
+			if (conn.authMode === "client-credentials") {
+				const token = await acquireAppToken(conn, signal);
+				storeToken(conn, token);
+				return textResult(
+					[
+						`✅ Acquired an app-only token for ${label}.`,
+						"",
+						`Granted app roles: ${tokenScopes(token.accessToken).join(", ") || "(none visible in the token)"}`,
+						"",
+						"Note: app-only tokens cannot post messages as a person. Switch this account to " +
+							'authMode "device-code" if pi should act as you.',
+					].join("\n"),
+					{ account: conn.account, tenant: conn.tenant, authMode: "client-credentials" },
+				);
+			}
+
+			const challenge = await requestDeviceCode(conn, signal);
+
+			const instructions = [
+				`## Sign in to Teams (${label})`,
+				"",
+				`1. Open **${challenge.verificationUri}**`,
+				`2. Enter the code: **${challenge.userCode}**`,
+				"3. Sign in with the account pi should act as.",
+				"",
+				`The code expires at ${new Date(challenge.expiresAt).toLocaleTimeString()}. Waiting…`,
+			].join("\n");
+
+			onUpdate?.({ content: [{ type: "text", text: instructions }] });
+
+			let lastNotice = 0;
+			const token = await pollForToken(conn, challenge, {
+				signal,
+				onPending: (secondsLeft) => {
+					// One nudge every 30s — enough to show progress, not enough to spam.
+					if (secondsLeft > 0 && Date.now() - lastNotice > 30_000) {
+						lastNotice = Date.now();
+						onUpdate?.({
+							content: [
+								{
+									type: "text",
+									text: `${instructions}\n\nStill waiting for sign-in… (${secondsLeft}s left)`,
+								},
+							],
+						});
+					}
+				},
+			});
+
+			storeToken(conn, token);
+			clearUserCache();
+
+			// Confirm the token actually works and report who pi now is.
+			let identity = token.user?.upn ?? token.user?.displayName ?? "(unknown)";
+			let jobTitle: string | undefined;
+			try {
+				const me = await getMe(conn, signal);
+				identity = `${me.displayName} <${me.upn}>`;
+				jobTitle = me.jobTitle;
+			} catch (err) {
+				return textResult(
+					[
+						`✅ Signed in to ${label}, but the first Graph call failed: ${formatGraphError(err)}`,
+						"",
+						"Run teams_doctor to see which permissions are missing.",
+					].join("\n"),
+					{ account: conn.account, tenant: conn.tenant, warning: true },
+				);
+			}
+
+			const granted = tokenScopes(token.accessToken);
+			const requested = conn.scopes.filter((s) => !["openid", "profile", "offline_access"].includes(s));
+			const missing = requested.filter(
+				(scope) => !granted.some((g) => g.toLowerCase() === scope.toLowerCase()),
+			);
+
+			return textResult(
+				[
+					`✅ Signed in to ${label} as **${identity}**${jobTitle ? ` (${jobTitle})` : ""}.`,
+					"",
+					`pi now acts as this user in Teams. Safety level: **${conn.safetyLevel}**.`,
+					missing.length > 0
+						? `\n⚠️ Not granted: ${missing.join(", ")}\nSome tools will fail until an admin consents to these scopes.`
+						: "\nAll requested scopes were granted.",
+				].join("\n"),
+				{
+					account: conn.account,
+					tenant: conn.tenant,
+					user: identity,
+					grantedScopes: granted,
+					missingScopes: missing,
+				},
+			);
+		});
+	},
+};
+
+export const teamsLogoutTool = {
+	name: "teams_logout",
+	description:
+		"Sign out of a Teams account: removes the saved access and refresh tokens from " +
+		"~/.pi/agent/pi-teams-tokens.json. The account stays configured, so teams_login can sign in again.",
+	parameters: Type.Object({
+		account: AccountParam,
+		tenant: TenantParam,
+		all: Type.Optional(Type.Boolean({ description: "Remove the cached tokens of every account" })),
+	}),
+	promptSnippet: "Sign out of a Teams account",
+
+	async execute(
+		_toolCallId: string,
+		params: { account?: string; tenant?: string; all?: boolean },
+		_signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			clearUserCache();
+
+			if (params.all) {
+				const count = clearAllTokens();
+				clearMemoryCache();
+				return textResult(`✅ Removed ${count} cached Teams session(s).`, { removed: count });
+			}
+
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const removed = deleteToken(conn.account, conn.tenantId);
+			forgetToken(conn);
+
+			return removed
+				? textResult(`✅ Signed out of ${connectionLabel(conn)}.`, { account: conn.account })
+				: errorResult(`No saved session for ${connectionLabel(conn)}.`);
+		});
+	},
+};

package/src/tools/teams-meetings.ts

@@ -0,0 +1,342 @@
+/**
+ * Calendar and meeting tools.
+ *
+ * "Create a Teams meeting" means a calendar event with a join link and real
+ * invitations, so that is what `teams_create_meeting` does by default; passing
+ * no attendees and `calendarEvent: false` gives the bare join link instead.
+ */
+
+import { Type } from "typebox";
+import {
+	cancelEvent,
+	createEvent,
+	createOnlineMeeting,
+	getEvent,
+	listEvents,
+	updateEvent,
+} from "../graph/calendar.ts";
+import { auditWrite } from "../safety/audit.ts";
+import { assertAccess } from "../safety/index.ts";
+import { formatEventDetail, formatEventList } from "../utils/formatting.ts";
+import {
+	AccountParam,
+	LimitParam,
+	TenantParam,
+	connectionFor,
+	currentUser,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsListMeetingsTool = {
+	name: "teams_list_meetings",
+	description:
+		"List the signed-in user's calendar events and Teams meetings in a time range (default: the next 7 days). " +
+		"Recurring series are expanded into actual occurrences. Use this for 'what's on my calendar', " +
+		"'when is my next meeting', or to find an event ID.",
+	parameters: Type.Object({
+		start: Type.Optional(
+			Type.String({ description: "ISO 8601 start of the range; defaults to now" }),
+		),
+		end: Type.Optional(
+			Type.String({ description: "ISO 8601 end of the range; defaults to 7 days from now" }),
+		),
+		account: AccountParam,
+		tenant: TenantParam,
+		limit: LimitParam,
+	}),
+	promptSnippet: "List the user's Teams meetings and calendar events",
+
+	async execute(
+		_toolCallId: string,
+		params: { start?: string; end?: 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 events = await listEvents(conn, {
+				start: params.start,
+				end: params.end,
+				max: params.limit ?? 25,
+				signal,
+			});
+			return textResult(formatEventList(events), { count: events.length });
+		});
+	},
+};
+
+export const teamsGetMeetingTool = {
+	name: "teams_get_meeting",
+	description:
+		"Show one calendar event or Teams meeting in full: time, organizer, attendees, join link and notes. " +
+		"Get the eventId from teams_list_meetings.",
+	parameters: Type.Object({
+		eventId: Type.String({ description: "Calendar event ID" }),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Show details of a Teams meeting",
+
+	async execute(
+		_toolCallId: string,
+		params: { eventId: 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 event = await getEvent(conn, params.eventId, signal);
+			if (!event) return errorResult(`Event ${params.eventId} not found.`);
+			return textResult(formatEventDetail(event), { eventId: event.id });
+		});
+	},
+};
+
+export const teamsCreateMeetingTool = {
+	name: "teams_create_meeting",
+	description:
+		"Schedule a Microsoft Teams meeting as the signed-in user: creates a calendar event with a join link " +
+		"and sends invitations to the attendees. Times are ISO 8601 local date-times " +
+		"(e.g. '2026-09-15T10:00:00') interpreted in 'timeZone'. " +
+		"Set calendarEvent: false for a bare join link with no calendar entry or invitations.",
+	parameters: Type.Object({
+		subject: Type.String({ description: "Meeting title" }),
+		start: Type.String({ description: "Start, ISO 8601 local date-time, e.g. '2026-09-15T10:00:00'" }),
+		end: Type.String({ description: "End, ISO 8601 local date-time" }),
+		attendees: Type.Optional(
+			Type.Array(Type.String(), { description: "Required attendees, by e-mail address" }),
+		),
+		optionalAttendees: Type.Optional(
+			Type.Array(Type.String(), { description: "Optional attendees, by e-mail address" }),
+		),
+		timeZone: Type.Optional(
+			Type.String({ description: "IANA or Windows time zone, e.g. 'Europe/Berlin'. Default UTC." }),
+		),
+		body: Type.Optional(Type.String({ description: "Agenda or invitation text" })),
+		location: Type.Optional(Type.String({ description: "Physical location, if any" })),
+		calendarEvent: Type.Optional(
+			Type.Boolean({ description: "Create a calendar event (default true). False = join link only." }),
+		),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Schedule a Teams meeting",
+	promptGuidelines: [
+		"Confirm date, time, time zone and attendee list with the user before creating a meeting — invitations cannot be un-sent.",
+		"Pass attendees as e-mail addresses; use teams_find_user to resolve names first.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			subject: string;
+			start: string;
+			end: string;
+			attendees?: string[];
+			optionalAttendees?: string[];
+			timeZone?: string;
+			body?: string;
+			location?: string;
+			calendarEvent?: 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).catch(() => undefined);
+
+			// Inviting someone is contacting them, so the people rules apply.
+			for (const address of [...(params.attendees ?? []), ...(params.optionalAttendees ?? [])]) {
+				assertAccess(conn, "write", "people", address, [address]);
+			}
+
+			if (params.calendarEvent === false) {
+				const meeting = await createOnlineMeeting(
+					conn,
+					{ subject: params.subject, start: params.start, end: params.end },
+					signal,
+				);
+				auditWrite(conn.audit, {
+					tool: "teams_create_meeting",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: "calendar",
+					summary: `created ad-hoc meeting "${params.subject}"`,
+				});
+				return textResult(
+					[`✅ Meeting link created for "${params.subject}".`, "", `Join: ${meeting.joinUrl}`].join("\n"),
+					{ meetingId: meeting.id, joinUrl: meeting.joinUrl },
+				);
+			}
+
+			const event = await createEvent(
+				conn,
+				{
+					subject: params.subject,
+					start: params.start,
+					end: params.end,
+					timeZone: params.timeZone,
+					attendees: params.attendees,
+					optionalAttendees: params.optionalAttendees,
+					body: params.body,
+					location: params.location,
+					onlineMeeting: true,
+				},
+				signal,
+			);
+
+			auditWrite(conn.audit, {
+				tool: "teams_create_meeting",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me?.upn,
+				target: "calendar",
+				summary:
+					`created "${params.subject}" ${params.start}–${params.end} ` +
+					`with ${(params.attendees ?? []).join(", ") || "no attendees"}`,
+			});
+
+			return textResult(
+				[
+					`✅ Meeting **${event.subject}** scheduled as ${me?.displayName ?? "you"}.`,
+					"",
+					formatEventDetail(event),
+				].join("\n"),
+				{ eventId: event.id, joinUrl: event.joinUrl },
+			);
+		});
+	},
+};
+
+export const teamsUpdateMeetingTool = {
+	name: "teams_update_meeting",
+	description:
+		"Change an existing calendar event the signed-in user organizes: time, subject, attendees, location or " +
+		"agenda. Attendees receive an update. Only the fields you pass are changed.",
+	parameters: Type.Object({
+		eventId: Type.String({ description: "Calendar event ID" }),
+		subject: Type.Optional(Type.String({ description: "New title" })),
+		start: Type.Optional(Type.String({ description: "New start, ISO 8601 local date-time" })),
+		end: Type.Optional(Type.String({ description: "New end, ISO 8601 local date-time" })),
+		timeZone: Type.Optional(Type.String({ description: "Time zone for the new times" })),
+		attendees: Type.Optional(
+			Type.Array(Type.String(), { description: "Replacement list of required attendees (e-mail)" }),
+		),
+		optionalAttendees: Type.Optional(
+			Type.Array(Type.String(), { description: "Replacement list of optional attendees (e-mail)" }),
+		),
+		body: Type.Optional(Type.String({ description: "New agenda text" })),
+		location: Type.Optional(Type.String({ description: "New location" })),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Update a Teams meeting",
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			eventId: string;
+			subject?: string;
+			start?: string;
+			end?: string;
+			timeZone?: string;
+			attendees?: string[];
+			optionalAttendees?: string[];
+			body?: string;
+			location?: 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);
+
+			for (const address of [...(params.attendees ?? []), ...(params.optionalAttendees ?? [])]) {
+				assertAccess(conn, "write", "people", address, [address]);
+			}
+
+			const event = await updateEvent(
+				conn,
+				params.eventId,
+				{
+					subject: params.subject,
+					start: params.start,
+					end: params.end,
+					timeZone: params.timeZone,
+					attendees: params.attendees,
+					optionalAttendees: params.optionalAttendees,
+					body: params.body,
+					location: params.location,
+				},
+				signal,
+			);
+
+			const me = await currentUser(conn, signal).catch(() => undefined);
+			auditWrite(conn.audit, {
+				tool: "teams_update_meeting",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me?.upn,
+				target: "calendar",
+				summary: `updated event ${params.eventId}`,
+			});
+
+			return textResult([`✅ Meeting updated.`, "", formatEventDetail(event)].join("\n"), {
+				eventId: event.id,
+			});
+		});
+	},
+};
+
+export const teamsCancelMeetingTool = {
+	name: "teams_cancel_meeting",
+	description:
+		"Cancel a meeting the signed-in user organizes — attendees receive a cancellation notice. " +
+		"For a meeting organized by somebody else, the event is removed from the user's own calendar instead.",
+	parameters: Type.Object({
+		eventId: Type.String({ description: "Calendar event ID" }),
+		comment: Type.Optional(Type.String({ description: "Note sent with the cancellation" })),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Cancel a Teams meeting",
+
+	async execute(
+		_toolCallId: string,
+		params: { eventId: string; comment?: 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);
+			await cancelEvent(conn, params.eventId, params.comment, signal);
+
+			const me = await currentUser(conn, signal).catch(() => undefined);
+			auditWrite(conn.audit, {
+				tool: "teams_cancel_meeting",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me?.upn,
+				target: "calendar",
+				summary: `cancelled event ${params.eventId}`,
+			});
+
+			return textResult(`✅ Meeting ${params.eventId} cancelled.`, { eventId: params.eventId });
+		});
+	},
+};