@patimweb/pi-teams 1.0.0

package/src/tools/teams-permissions.ts

@@ -0,0 +1,169 @@
+/**
+ * teams_permissions — inspect, test and change the guardrails.
+ *
+ * "Test" is the interesting action: it answers "would pi be allowed to post in
+ * Engineering/Announcements?" without posting anything, which is how a user
+ * builds confidence in a rule set before turning safetyLevel to "open".
+ */
+
+import { Type } from "typebox";
+import { setPermissionBlock } from "../config/index.ts";
+import {
+	checkScope,
+	formatPermissions,
+	SCOPE_CATEGORIES,
+	type PermissionBlock,
+	type ScopeCategory,
+	type ScopeList,
+	type ScopeMode,
+} from "../config/scope.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	connectionLabel,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+interface PermissionsParams {
+	action?: string;
+	account?: string;
+	tenant?: string;
+	category?: string;
+	mode?: string;
+	target?: string;
+	allow?: string[];
+	deny?: string[];
+}
+
+const isCategory = (value: string): value is ScopeCategory =>
+	(SCOPE_CATEGORIES as string[]).includes(value);
+
+export const teamsPermissionsTool = {
+	name: "teams_permissions",
+	description:
+		"Inspect or change what pi is allowed to do in Teams. " +
+		"action 'show' (default) prints the effective allow/deny rules; " +
+		"action 'test' checks whether a specific team, channel, chat or person is in scope without touching it; " +
+		"action 'set' writes an allow/deny list for one category. " +
+		"Rules apply per category (teams, channels, chats, people) and per mode (read, write).",
+	parameters: Type.Object({
+		action: Type.Optional(Type.String({ description: "'show' (default), 'test' or 'set'" })),
+		account: AccountParam,
+		tenant: TenantParam,
+		category: Type.Optional(
+			Type.String({ description: "'teams', 'channels', 'chats' or 'people'" }),
+		),
+		mode: Type.Optional(Type.String({ description: "'read' or 'write' (default 'write')" })),
+		target: Type.Optional(
+			Type.String({
+				description: "For action 'test': what to check, e.g. 'Engineering/Announcements' or 'anna@contoso.com'",
+			}),
+		),
+		allow: Type.Optional(Type.Array(Type.String(), { description: "For action 'set': allow patterns" })),
+		deny: Type.Optional(Type.Array(Type.String(), { description: "For action 'set': deny patterns" })),
+	}),
+	promptSnippet: "Show or change what pi may do in Teams",
+	promptGuidelines: [
+		"Use teams_permissions with action 'test' before telling the user that pi can or cannot reach a channel.",
+		"When a tool fails with a scope error, show the user the matching rule instead of retrying.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: PermissionsParams,
+		_signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const action = (params.action ?? "show").toLowerCase();
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const label = connectionLabel(conn);
+
+			if (action === "show") {
+				return textResult(
+					[
+						`## What pi may do in Teams (${label})`,
+						"",
+						`Safety level: **${conn.safetyLevel}** · auth mode: **${conn.authMode}**`,
+						"",
+						formatPermissions(conn.permissions),
+						"",
+						"_Patterns are case-insensitive globs. Channels match on `Team/Channel`, their name, or their ID; " +
+							"chats match on topic, participant names and e-mail addresses._",
+					].join("\n"),
+					{ safetyLevel: conn.safetyLevel, permissions: conn.permissions },
+				);
+			}
+
+			if (action === "test") {
+				if (!params.target) return errorResult("action 'test' requires a target.");
+				const category = (params.category ?? "channels").toLowerCase();
+				if (!isCategory(category)) {
+					return errorResult(`Unknown category "${category}". Use teams, channels, chats or people.`);
+				}
+				const mode = ((params.mode ?? "write").toLowerCase() === "read" ? "read" : "write") as ScopeMode;
+
+				const decision = checkScope(conn.permissions, mode, category, [params.target]);
+				return textResult(
+					[
+						`${decision.allowed ? "✅ Allowed" : "🚫 Blocked"}: ${mode} ${category} "${params.target}" (${label})`,
+						"",
+						decision.reason,
+					].join("\n"),
+					{ allowed: decision.allowed, reason: decision.reason, pattern: decision.pattern },
+				);
+			}
+
+			if (action === "set") {
+				const category = (params.category ?? "").toLowerCase();
+				if (!isCategory(category)) {
+					return errorResult(
+						`action 'set' requires a category: teams, channels, chats or people.`,
+					);
+				}
+				if (!params.allow?.length && !params.deny?.length) {
+					return errorResult("action 'set' requires at least one allow or deny pattern.");
+				}
+
+				const list: ScopeList = {};
+				if (params.allow?.length) list.allow = params.allow;
+				if (params.deny?.length) list.deny = params.deny;
+
+				const mode = params.mode?.toLowerCase();
+				const block: PermissionBlock = {};
+				if (mode === "read" || mode === "write") {
+					block[mode] = { [category]: list };
+				} else {
+					block[category] = list;
+				}
+
+				// The block replaces the rules at this level; anything the user wants
+				// to keep must be passed again — stated plainly in the result.
+				setPermissionBlock(block, params.account, params.tenant);
+
+				return textResult(
+					[
+						`✅ Scope rules for **${category}** updated ` +
+							`${params.account ? (params.tenant ? `on ${params.account}/${params.tenant}` : `on account ${params.account}`) : "globally"}.`,
+						"",
+						params.allow?.length ? `allow: ${params.allow.join(", ")}` : "",
+						params.deny?.length ? `deny: ${params.deny.join(", ")}` : "",
+						"",
+						"_This replaces the permission block at that level. Re-run teams_permissions with action 'show' to check the result._",
+					]
+						.filter(Boolean)
+						.join("\n"),
+					{ category, allow: params.allow, deny: params.deny },
+				);
+			}
+
+			return errorResult(`Unknown action "${action}". Use 'show', 'test' or 'set'.`);
+		});
+	},
+};

package/src/tools/teams-presence.ts

@@ -0,0 +1,216 @@
+/**
+ * Presence tools — read who is around, set the user's own status.
+ */
+
+import { Type } from "typebox";
+import {
+	AVAILABILITY_VALUES,
+	clearPreferredPresence,
+	getChatPresence,
+	getMyPresence,
+	getPresenceForUser,
+	setPreferredPresence,
+	setStatusMessage,
+	type Availability,
+} from "../graph/presence.ts";
+import { resolveUserId } from "../graph/me.ts";
+import { auditWrite } from "../safety/audit.ts";
+import { assertAccess } from "../safety/index.ts";
+import { formatPresence, formatPresenceList } from "../utils/formatting.ts";
+import { requireChat } from "./resolve.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	currentUser,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsGetPresenceTool = {
+	name: "teams_get_presence",
+	description:
+		"Show Microsoft Teams presence: the signed-in user's own status by default, a colleague's when 'person' " +
+		"is given, or everyone in a chat when 'chat' is given. Use this before pinging someone — or to answer " +
+		"'is Anna available right now?'.",
+	parameters: Type.Object({
+		person: Type.Optional(Type.String({ description: "Name, e-mail or UPN of the person to check" })),
+		chat: Type.Optional(Type.String({ description: "Chat ID or name — shows presence for every member" })),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Check Teams presence",
+
+	async execute(
+		_toolCallId: string,
+		params: { person?: string; chat?: 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);
+
+			if (params.chat) {
+				const chat = await requireChat(conn, params.chat, "read", signal);
+				const entries = await getChatPresence(conn, chat.id, signal);
+				return textResult(
+					[`## Presence in ${chat.label}`, "", formatPresenceList(entries)].join("\n"),
+					{ chatId: chat.id, count: entries.length },
+				);
+			}
+
+			if (params.person) {
+				const person = await resolveUserId(conn, params.person, signal);
+				if (!person?.id) {
+					return errorResult(
+						`Could not resolve "${params.person}" to a person. Use teams_find_user to look them up.`,
+					);
+				}
+				assertAccess(conn, "read", "people", person.displayName, [
+					person.displayName,
+					person.upn,
+					person.mail,
+					person.id,
+				]);
+				const presence = await getPresenceForUser(conn, person.id, person.displayName, signal);
+				return textResult(formatPresence(presence), { userId: person.id, ...presence });
+			}
+
+			const mine = await getMyPresence(conn, signal);
+			return textResult(formatPresence(mine), { ...mine });
+		});
+	},
+};
+
+export const teamsSetPresenceTool = {
+	name: "teams_set_presence",
+	description:
+		"Set the signed-in user's own Microsoft Teams presence — the same thing as picking a status in the " +
+		`Teams app. Allowed values: ${AVAILABILITY_VALUES.join(", ")}. ` +
+		"Optionally give 'expiresIn' as an ISO 8601 duration (PT2H, PT30M) after which Teams reverts to " +
+		"automatic presence. Set reset: true to hand control back to Teams immediately.",
+	parameters: Type.Object({
+		availability: Type.Optional(
+			Type.String({ description: `One of: ${AVAILABILITY_VALUES.join(", ")}` }),
+		),
+		expiresIn: Type.Optional(
+			Type.String({ description: "ISO 8601 duration, e.g. 'PT2H' for two hours" }),
+		),
+		reset: Type.Optional(
+			Type.Boolean({ description: "Clear the preferred status and let Teams calculate it again" }),
+		),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Set the user's Teams presence",
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			availability?: string;
+			expiresIn?: string;
+			reset?: 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);
+
+			if (params.reset) {
+				await clearPreferredPresence(conn, signal);
+				auditWrite(conn.audit, {
+					tool: "teams_set_presence",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: "self",
+					summary: "cleared preferred presence",
+				});
+				return textResult("✅ Teams presence is back under Teams' own control.", { reset: true });
+			}
+
+			const value = AVAILABILITY_VALUES.find(
+				(candidate) => candidate.toLowerCase() === (params.availability ?? "").toLowerCase(),
+			);
+			if (!value) {
+				return errorResult(
+					`availability must be one of: ${AVAILABILITY_VALUES.join(", ")}.`,
+				);
+			}
+
+			await setPreferredPresence(conn, value as Availability, {
+				expirationDuration: params.expiresIn,
+				signal,
+			});
+
+			auditWrite(conn.audit, {
+				tool: "teams_set_presence",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me?.upn,
+				target: "self",
+				summary: `presence → ${value}${params.expiresIn ? ` for ${params.expiresIn}` : ""}`,
+			});
+
+			return textResult(
+				`✅ Your Teams presence is now **${value}**${params.expiresIn ? ` (until ${params.expiresIn} from now)` : ""}.`,
+				{ availability: value, expiresIn: params.expiresIn },
+			);
+		});
+	},
+};
+
+export const teamsSetStatusMessageTool = {
+	name: "teams_set_status_message",
+	description:
+		"Set the status message shown under the signed-in user's name in Microsoft Teams " +
+		"(e.g. 'In a workshop until Thursday'). Pass an empty message to clear it.",
+	parameters: Type.Object({
+		message: Type.String({ description: "Status text; empty string clears it" }),
+		expiresAt: Type.Optional(
+			Type.String({ description: "ISO 8601 UTC timestamp when the message should expire" }),
+		),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Set the user's Teams status message",
+
+	async execute(
+		_toolCallId: string,
+		params: { message: string; expiresAt?: 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 setStatusMessage(conn, params.message, { expiresAt: params.expiresAt, signal });
+
+			const me = await currentUser(conn, signal).catch(() => undefined);
+			auditWrite(conn.audit, {
+				tool: "teams_set_status_message",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me?.upn,
+				target: "self",
+				summary: params.message ? `status message → "${params.message}"` : "cleared status message",
+			});
+
+			return textResult(
+				params.message
+					? `✅ Status message set to: "${params.message}"${params.expiresAt ? ` (until ${params.expiresAt})` : ""}`
+					: "✅ Status message cleared.",
+				{ message: params.message },
+			);
+		});
+	},
+};

package/src/tools/teams-react.ts

@@ -0,0 +1,109 @@
+/**
+ * teams_react — add or remove an emoji reaction on a message.
+ */
+
+import { Type } from "typebox";
+import { setReaction, unsetReaction } from "../graph/messages.ts";
+import { auditWrite } from "../safety/audit.ts";
+import { requireChannel, requireChat } from "./resolve.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	currentUser,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+import type { MessageLocation } from "../types.ts";
+
+interface ReactParams {
+	messageId: string;
+	reaction: string;
+	chat?: string;
+	channel?: string;
+	team?: string;
+	replyId?: string;
+	remove?: boolean;
+	account?: string;
+	tenant?: string;
+}
+
+export const teamsReactTool = {
+	name: "teams_react",
+	description:
+		"Add or remove an emoji reaction on a Microsoft Teams message, as the signed-in user. " +
+		"Specify either 'chat' or 'channel' (plus 'team') to say where the message lives. " +
+		"For a reply inside a channel thread, pass the thread's messageId and the reply's ID as 'replyId'. " +
+		"The reaction is a Unicode emoji such as 👍 or ✅.",
+	parameters: Type.Object({
+		messageId: Type.String({ description: "ID of the message to react to" }),
+		reaction: Type.String({ description: "Unicode emoji, e.g. 👍, ❤️, ✅" }),
+		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 reacting to a reply in a thread" })),
+		remove: Type.Optional(Type.Boolean({ description: "Remove the reaction instead of adding it" })),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "React to a Teams message",
+
+	async execute(
+		_toolCallId: string,
+		params: ReactParams,
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): 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.");
+			}
+
+			const action = params.remove ? unsetReaction : setReaction;
+			await action(conn, location, params.messageId, params.reaction, {
+				replyId: params.replyId,
+				signal,
+			});
+
+			const me = await currentUser(conn, signal).catch(() => undefined);
+			auditWrite(conn.audit, {
+				tool: "teams_react",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me?.upn,
+				target,
+				summary: `${params.remove ? "removed" : "added"} reaction ${params.reaction} on ${params.messageId}`,
+			});
+
+			return textResult(
+				`✅ ${params.remove ? "Removed" : "Added"} ${params.reaction} on message ${params.messageId} (${target}).`,
+				{ messageId: params.messageId, reaction: params.reaction, removed: !!params.remove },
+			);
+		});
+	},
+};

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

@@ -0,0 +1,75 @@
+/**
+ * teams_read_channel — read the top-level posts of a channel.
+ */
+
+import { Type } from "typebox";
+import { listChannelMessages } from "../graph/messages.ts";
+import { formatMessageList } from "../utils/formatting.ts";
+import { requireChannel } from "./resolve.ts";
+import {
+	AccountParam,
+	LimitParam,
+	TenantParam,
+	connectionFor,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsReadChannelTool = {
+	name: "teams_read_channel",
+	description:
+		"Read the posts of a Microsoft Teams channel (top-level messages, not the replies inside each thread). " +
+		"Pass team and channel by name or ID, or a single 'Team/Channel' path as 'channel'. " +
+		"Set withReplyCounts to also show how many replies each thread has — use teams_read_thread for the replies themselves.",
+	parameters: Type.Object({
+		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)" })),
+		account: AccountParam,
+		tenant: TenantParam,
+		limit: LimitParam,
+		withReplyCounts: Type.Optional(
+			Type.Boolean({ description: "Resolve reply counts for each post (slower, one call per post)" }),
+		),
+	}),
+	promptSnippet: "Read posts from a Teams channel",
+	promptGuidelines: [
+		"Channel conversations are threaded: teams_read_channel returns the openers, teams_read_thread the replies.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			channel: string;
+			team?: string;
+			account?: string;
+			tenant?: string;
+			limit?: number;
+			withReplyCounts?: boolean;
+		},
+		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 messages = await listChannelMessages(conn, channel, {
+				max: params.limit ?? conn.maxMessages,
+				withReplies: params.withReplyCounts,
+				signal,
+			});
+
+			return textResult(
+				formatMessageList(messages, `${team.displayName}/${channel.displayName}`),
+				{
+					teamId: team.id,
+					channelId: channel.id,
+					count: messages.length,
+				},
+			);
+		});
+	},
+};

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

@@ -0,0 +1,73 @@
+/**
+ * teams_read_chat — read the messages of one chat.
+ */
+
+import { Type } from "typebox";
+import { listChatMessages } from "../graph/messages.ts";
+import { formatChatDetail, formatMessageList } from "../utils/formatting.ts";
+import { requireChat } from "./resolve.ts";
+import {
+	AccountParam,
+	LimitParam,
+	TenantParam,
+	connectionFor,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsReadChatTool = {
+	name: "teams_read_chat",
+	description:
+		"Read messages from a Microsoft Teams chat. Accepts a chat ID, a group chat topic, or a participant's " +
+		"name or e-mail — ambiguous matches are reported rather than guessed. Returns messages oldest first " +
+		"with sender, timestamp, reactions and message IDs.",
+	parameters: Type.Object({
+		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
+		account: AccountParam,
+		tenant: TenantParam,
+		limit: LimitParam,
+		includeDetails: Type.Optional(
+			Type.Boolean({ description: "Also show chat metadata (members, type, link)" }),
+		),
+	}),
+	promptSnippet: "Read messages from a Teams chat",
+	promptGuidelines: [
+		"Use teams_read_chat to catch up on a conversation before replying.",
+		"Quote the messageId when the user wants to react to or delete a specific message.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			chat: string;
+			account?: string;
+			tenant?: string;
+			limit?: number;
+			includeDetails?: boolean;
+		},
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const chat = await requireChat(conn, params.chat, "read", signal);
+
+			const messages = await listChatMessages(conn, chat.id, {
+				max: params.limit ?? conn.maxMessages,
+				signal,
+			});
+
+			const body = formatMessageList(messages, chat.label);
+			const detail = params.includeDetails ? `${formatChatDetail(chat)}\n\n` : "";
+
+			return textResult(`${detail}${body}`, {
+				chatId: chat.id,
+				label: chat.label,
+				count: messages.length,
+			});
+		});
+	},
+};