@patimweb/pi-teams 1.0.0

package/src/config/scope.ts

@@ -0,0 +1,272 @@
+/**
+ * Scope rules — which teams, channels, chats and people pi may touch.
+ *
+ * Pure functions only. No I/O, no Graph calls — everything here is testable
+ * with plain objects, which matters because these rules are the last line of
+ * defence before pi speaks as the user.
+ *
+ * Semantics
+ * ---------
+ * - Rules exist per category (teams / channels / chats / people) and per mode
+ *   (read / write).
+ * - `deny` accumulates across all levels (global → account → tenant) and always
+ *   wins. A deny anywhere blocks the target.
+ * - `allow` narrows: the most specific level that defines a non-empty allow
+ *   list wins. If no level defines one, everything the signed-in user can
+ *   reach is allowed (`*`).
+ * - A target is matched against several candidate strings (id, display name,
+ *   "Team/Channel" path, e-mail, UPN). A match on any candidate counts.
+ * - Patterns are case-insensitive globs: `*` matches any run of characters
+ *   (including `/`), `?` matches exactly one. An `id:` prefix is stripped so
+ *   `id:19:abc@thread.tacv2` reads naturally in a config file.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Categories a rule can apply to. */
+export type ScopeCategory = "teams" | "channels" | "chats" | "people";
+
+/** Read or write access. */
+export type ScopeMode = "read" | "write";
+
+/** Allow/deny lists for a single category. */
+export interface ScopeList {
+	allow?: string[];
+	deny?: string[];
+}
+
+/** Per-category rules. */
+export interface ScopeRules {
+	teams?: ScopeList;
+	channels?: ScopeList;
+	chats?: ScopeList;
+	people?: ScopeList;
+}
+
+/**
+ * A permission block as written in pi-teams.json.
+ *
+ * Category keys at the top level apply to both modes; `read` and `write`
+ * blocks refine one mode. A `write` allow list overrides the shorthand allow
+ * list at the same level; deny lists from both are unioned.
+ */
+export interface PermissionBlock extends ScopeRules {
+	read?: ScopeRules;
+	write?: ScopeRules;
+}
+
+/** Fully resolved rules for every category and mode. */
+export type ResolvedPermissions = {
+	[M in ScopeMode]: { [C in ScopeCategory]: Required<ScopeList> };
+};
+
+/** The outcome of a scope check. */
+export interface ScopeDecision {
+	allowed: boolean;
+	/** Which rule produced the decision, for error messages and `/teams-permissions`. */
+	reason: string;
+	/** The pattern that matched, when one did. */
+	pattern?: string;
+}
+
+export const SCOPE_CATEGORIES: ScopeCategory[] = ["teams", "channels", "chats", "people"];
+export const SCOPE_MODES: ScopeMode[] = ["read", "write"];
+
+// ---------------------------------------------------------------------------
+// Glob matching
+// ---------------------------------------------------------------------------
+
+/** Escape regex metacharacters except `*` and `?`, which become wildcards. */
+function globToRegExp(pattern: string): RegExp {
+	const escaped = pattern
+		.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+		.replace(/\*/g, "[\\s\\S]*")
+		.replace(/\?/g, "[\\s\\S]");
+	return new RegExp(`^${escaped}$`, "i");
+}
+
+/** Normalize a pattern or candidate: trim, drop an `id:` prefix, lowercase. */
+function normalize(value: string): string {
+	return value.trim().replace(/^id:/i, "").toLowerCase();
+}
+
+/**
+ * Match a single pattern against a single candidate string.
+ * Exported for tests and for `teams_permissions` explanations.
+ */
+export function matchesPattern(pattern: string, candidate: string): boolean {
+	const p = normalize(pattern);
+	const c = normalize(candidate);
+	if (!p || !c) return false;
+	if (p === "*") return true;
+	if (p === c) return true;
+	return globToRegExp(p).test(c);
+}
+
+/** Find the first pattern in `patterns` that matches any of `candidates`. */
+export function findMatch(
+	patterns: readonly string[],
+	candidates: readonly string[],
+): string | undefined {
+	for (const pattern of patterns) {
+		for (const candidate of candidates) {
+			if (matchesPattern(pattern, candidate)) return pattern;
+		}
+	}
+	return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+function emptyList(): Required<ScopeList> {
+	return { allow: [], deny: [] };
+}
+
+/** Rules that allow everything — the default when nothing is configured. */
+export function defaultPermissions(): ResolvedPermissions {
+	const forMode = () => ({
+		teams: { allow: ["*"], deny: [] as string[] },
+		channels: { allow: ["*"], deny: [] as string[] },
+		chats: { allow: ["*"], deny: [] as string[] },
+		people: { allow: ["*"], deny: [] as string[] },
+	});
+	return { read: forMode(), write: forMode() };
+}
+
+/**
+ * Collapse a list of permission blocks (least specific first) into resolved
+ * rules. Later blocks are more specific and win on `allow`; `deny` is unioned.
+ */
+export function resolvePermissions(
+	blocks: readonly (PermissionBlock | undefined)[],
+): ResolvedPermissions {
+	const resolved: ResolvedPermissions = {
+		read: { teams: emptyList(), channels: emptyList(), chats: emptyList(), people: emptyList() },
+		write: { teams: emptyList(), channels: emptyList(), chats: emptyList(), people: emptyList() },
+	};
+
+	for (const block of blocks) {
+		if (!block) continue;
+
+		for (const mode of SCOPE_MODES) {
+			const modeRules = block[mode];
+
+			for (const category of SCOPE_CATEGORIES) {
+				const shorthand = block[category];
+				const specific = modeRules?.[category];
+				const target = resolved[mode][category];
+
+				// deny accumulates from every level and both shapes
+				for (const pattern of shorthand?.deny ?? []) {
+					if (!target.deny.includes(pattern)) target.deny.push(pattern);
+				}
+				for (const pattern of specific?.deny ?? []) {
+					if (!target.deny.includes(pattern)) target.deny.push(pattern);
+				}
+
+				// allow: the most specific non-empty list wins
+				if (specific?.allow && specific.allow.length > 0) {
+					target.allow = [...specific.allow];
+				} else if (shorthand?.allow && shorthand.allow.length > 0) {
+					target.allow = [...shorthand.allow];
+				}
+			}
+		}
+	}
+
+	// Nothing configured for a slot means "everything the user can reach"
+	for (const mode of SCOPE_MODES) {
+		for (const category of SCOPE_CATEGORIES) {
+			if (resolved[mode][category].allow.length === 0) {
+				resolved[mode][category].allow = ["*"];
+			}
+		}
+	}
+
+	return resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Checking
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether a target may be read or written.
+ *
+ * @param permissions - resolved rules
+ * @param mode - read or write
+ * @param category - which rule set applies
+ * @param candidates - identifiers for the target (id, name, path, e-mail…);
+ *                     empty or blank entries are ignored
+ */
+export function checkScope(
+	permissions: ResolvedPermissions,
+	mode: ScopeMode,
+	category: ScopeCategory,
+	candidates: readonly (string | undefined)[],
+): ScopeDecision {
+	const list = permissions[mode][category];
+	const values = candidates.filter((c): c is string => !!c && c.trim().length > 0);
+
+	if (values.length === 0) {
+		return { allowed: false, reason: `no identifier available to check against the ${category} rules` };
+	}
+
+	const denied = findMatch(list.deny, values);
+	if (denied) {
+		return {
+			allowed: false,
+			reason: `blocked by ${mode}.${category}.deny rule "${denied}"`,
+			pattern: denied,
+		};
+	}
+
+	const allowed = findMatch(list.allow, values);
+	if (allowed) {
+		return {
+			allowed: true,
+			reason: allowed === "*"
+				? `allowed by ${mode}.${category} default (*)`
+				: `allowed by ${mode}.${category}.allow rule "${allowed}"`,
+			pattern: allowed,
+		};
+	}
+
+	return {
+		allowed: false,
+		reason:
+			`not covered by any ${mode}.${category}.allow rule ` +
+			`(configured: ${list.allow.join(", ") || "none"})`,
+	};
+}
+
+/** Convenience: keep only the entries a check lets through. */
+export function filterAllowed<T>(
+	permissions: ResolvedPermissions,
+	mode: ScopeMode,
+	category: ScopeCategory,
+	items: readonly T[],
+	candidatesOf: (item: T) => (string | undefined)[],
+): T[] {
+	return items.filter((item) => checkScope(permissions, mode, category, candidatesOf(item)).allowed);
+}
+
+/** Render resolved rules as markdown — used by `teams_permissions` and the doctor. */
+export function formatPermissions(permissions: ResolvedPermissions): string {
+	const lines: string[] = [];
+	for (const mode of SCOPE_MODES) {
+		lines.push(`**${mode === "read" ? "Read" : "Write"}**`);
+		for (const category of SCOPE_CATEGORIES) {
+			const list = permissions[mode][category];
+			const allow = list.allow.join(", ") || "none";
+			const deny = list.deny.length > 0 ? ` · deny: ${list.deny.join(", ")}` : "";
+			lines.push(`- ${category}: allow: ${allow}${deny}`);
+		}
+		lines.push("");
+	}
+	return lines.join("\n").trimEnd();
+}

package/src/extension/index.ts

@@ -0,0 +1,336 @@
+/**
+ * pi-teams extension entry point.
+ *
+ * Registers the tools, the status surfaces, the slash commands, and — most
+ * importantly — the `tool_call` interceptor that enforces the safety level
+ * before anything is said in the user's name.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+
+import {
+	ensureConfigTemplate,
+	getConfigPath,
+	tryResolveConnection,
+	type TeamsConnection,
+} from "../config/index.ts";
+import { buildConnectionCard, buildConnectionLabel, formatStatusText, type ConnectionCard } from "../status.ts";
+import {
+	blockReason,
+	formatMutationSummary,
+	isMutationTool,
+	LOCAL_CONFIG_TOOLS,
+} from "../safety/index.ts";
+
+import { teamsSetupTool } from "../tools/teams-setup.ts";
+import { teamsLoginTool, teamsLogoutTool } from "../tools/teams-login.ts";
+import { teamsAccountsTool } from "../tools/teams-accounts.ts";
+import { teamsStatusTool } from "../tools/teams-status.ts";
+import { teamsDoctorTool } from "../tools/teams-doctor.ts";
+import { teamsPermissionsTool } from "../tools/teams-permissions.ts";
+import { teamsListTeamsTool } from "../tools/teams-list-teams.ts";
+import { teamsListChannelsTool } from "../tools/teams-list-channels.ts";
+import { teamsListMembersTool } from "../tools/teams-list-members.ts";
+import { teamsFindUserTool } from "../tools/teams-find-user.ts";
+import { teamsListChatsTool } from "../tools/teams-list-chats.ts";
+import { teamsReadChatTool } from "../tools/teams-read-chat.ts";
+import { teamsSendChatMessageTool } from "../tools/teams-send-chat-message.ts";
+import { teamsCreateChatTool } from "../tools/teams-create-chat.ts";
+import { teamsReadChannelTool } from "../tools/teams-read-channel.ts";
+import { teamsReadThreadTool } from "../tools/teams-read-thread.ts";
+import {
+	teamsReplyChannelMessageTool,
+	teamsSendChannelMessageTool,
+} from "../tools/teams-send-channel-message.ts";
+import { teamsCreateChannelTool } from "../tools/teams-create-channel.ts";
+import { teamsListFilesTool } from "../tools/teams-list-files.ts";
+import { teamsSearchMessagesTool } from "../tools/teams-search-messages.ts";
+import { teamsReactTool } from "../tools/teams-react.ts";
+import { teamsDeleteMessageTool } from "../tools/teams-delete-message.ts";
+import { teamsInboxTool } from "../tools/teams-inbox.ts";
+import {
+	teamsGetPresenceTool,
+	teamsSetPresenceTool,
+	teamsSetStatusMessageTool,
+} from "../tools/teams-presence.ts";
+import {
+	teamsCancelMeetingTool,
+	teamsCreateMeetingTool,
+	teamsGetMeetingTool,
+	teamsListMeetingsTool,
+	teamsUpdateMeetingTool,
+} from "../tools/teams-meetings.ts";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** Every tool, in the order they appear in the documentation. */
+const tools = [
+	// Setup & session
+	teamsSetupTool,
+	teamsLoginTool,
+	teamsLogoutTool,
+	teamsAccountsTool,
+	teamsStatusTool,
+	teamsPermissionsTool,
+	teamsDoctorTool,
+	// Discovery
+	teamsListTeamsTool,
+	teamsListChannelsTool,
+	teamsListMembersTool,
+	teamsFindUserTool,
+	// Chats
+	teamsListChatsTool,
+	teamsReadChatTool,
+	teamsSendChatMessageTool,
+	teamsCreateChatTool,
+	// Channels
+	teamsReadChannelTool,
+	teamsReadThreadTool,
+	teamsSendChannelMessageTool,
+	teamsReplyChannelMessageTool,
+	teamsCreateChannelTool,
+	teamsListFilesTool,
+	// Cross-cutting
+	teamsSearchMessagesTool,
+	teamsReactTool,
+	teamsDeleteMessageTool,
+	teamsInboxTool,
+	// Presence
+	teamsGetPresenceTool,
+	teamsSetPresenceTool,
+	teamsSetStatusMessageTool,
+	// Calendar
+	teamsListMeetingsTool,
+	teamsGetMeetingTool,
+	teamsCreateMeetingTool,
+	teamsUpdateMeetingTool,
+	teamsCancelMeetingTool,
+];
+
+export default function (pi: ExtensionAPI) {
+	// The session's default connection. Re-resolved when the config changes, so
+	// teams_setup takes effect without a restart.
+	let connection: TeamsConnection | undefined;
+
+	const refresh = (): TeamsConnection | undefined => {
+		connection = tryResolveConnection();
+		return connection;
+	};
+
+	// -----------------------------------------------------------------------
+	// Status card — rendered in the transcript, never sent to the model
+	// -----------------------------------------------------------------------
+
+	pi.registerEntryRenderer<ConnectionCard>("teams-connection", (entry, { expanded }, theme) => {
+		const card = entry.data;
+		const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+		box.addChild(new Text(theme.fg("accent", theme.bold("Microsoft Teams")), 0, 0));
+
+		if (!card) {
+			box.addChild(new Text(theme.fg("warning", "not configured"), 0, 0));
+			return box;
+		}
+
+		const scope = card.tenant === card.account ? card.account : `${card.account}/${card.tenant}`;
+		box.addChild(new Text(theme.fg("dim", `${scope}${card.user ? ` · ${card.user}` : ""}`), 0, 0));
+		box.addChild(
+			new Text(
+				card.signedIn
+					? theme.fg("muted", `safety: ${card.safetyLevel}`)
+					: theme.fg("warning", "not signed in — run /teams-login"),
+				0,
+				0,
+			),
+		);
+		if (expanded) {
+			box.addChild(new Text(theme.fg("muted", formatStatusText(card)), 0, 0));
+		}
+		return box;
+	});
+
+	// -----------------------------------------------------------------------
+	// Commands
+	// -----------------------------------------------------------------------
+
+	pi.registerCommand("teams-status", {
+		description: "Show the current Microsoft Teams connection and permissions",
+		handler: async (_args, ctx) => {
+			const card = buildConnectionCard(refresh());
+			if (!card) {
+				ctx.ui.notify(`Teams: no configuration found. See ${getConfigPath()}`, "warning");
+				return;
+			}
+			pi.appendEntry<ConnectionCard>("teams-connection", card);
+			ctx.ui.setStatus("teams", ctx.ui.theme.fg("success", buildConnectionLabel(card)));
+			ctx.ui.notify(buildConnectionLabel(card), "info");
+		},
+	});
+
+	pi.registerCommand("teams-login", {
+		description: "Sign in to Microsoft Teams as yourself (device code flow)",
+		handler: async (args, ctx) => {
+			const account = args.trim();
+			if (!refresh()) {
+				ctx.ui.notify(
+					`Teams: no account configured yet. Use the teams_setup tool, or edit ${getConfigPath()}.`,
+					"warning",
+				);
+				return;
+			}
+			pi.sendUserMessage(
+				account
+					? `Please use the teams_login tool to sign in to the Teams account "${account}".`
+					: "Please use the teams_login tool to sign me in to Microsoft Teams.",
+				{ deliverAs: "steer" },
+			);
+			ctx.ui.notify("Starting Teams sign-in…", "info");
+		},
+	});
+
+	pi.registerCommand("teams-inbox", {
+		description: "Show what needs your attention in Microsoft Teams",
+		handler: async (_args, ctx) => {
+			if (!refresh()) {
+				ctx.ui.notify("Teams is not configured. Use the teams_setup tool first.", "error");
+				return;
+			}
+			pi.sendUserMessage(
+				"Please use teams_inbox to show me what needs my attention in Teams right now, and summarize it.",
+				{ deliverAs: "steer" },
+			);
+			ctx.ui.notify("Checking Teams…", "info");
+		},
+	});
+
+	pi.registerCommand("teams-doctor", {
+		description: "Diagnose the Microsoft Teams configuration and sign-in",
+		handler: async (_args, ctx) => {
+			pi.sendUserMessage(
+				"Please run the teams_doctor tool and summarize what is wrong and how to fix it.",
+				{ deliverAs: "steer" },
+			);
+			ctx.ui.notify("Running Teams doctor…", "info");
+		},
+	});
+
+	pi.registerCommand("teams-permissions", {
+		description: "Show what pi is allowed to do in Microsoft Teams",
+		handler: async (_args, ctx) => {
+			pi.sendUserMessage(
+				"Please run teams_permissions with action 'show' and explain in plain language what you may and may not do in Teams.",
+				{ deliverAs: "steer" },
+			);
+			ctx.ui.notify("Reading Teams guardrails…", "info");
+		},
+	});
+
+	// -----------------------------------------------------------------------
+	// Session start
+	// -----------------------------------------------------------------------
+
+	pi.on("session_start", async (_event, ctx) => {
+		const created = ensureConfigTemplate();
+		refresh();
+
+		if (!connection) {
+			ctx.ui.notify(
+				created
+					? `@patimweb/pi-teams: a config template was created at ${getConfigPath()} — add your Entra ID tenantId and clientId, or run the teams_setup tool.`
+					: `@patimweb/pi-teams: no usable Teams account configured. See ${getConfigPath()} or run the teams_setup tool.`,
+				"warning",
+			);
+			return;
+		}
+
+		const card = buildConnectionCard(connection);
+		if (!card) return;
+
+		ctx.ui.setStatus("teams", ctx.ui.theme.fg(card.signedIn ? "success" : "warning", buildConnectionLabel(card)));
+
+		if (!card.signedIn) {
+			ctx.ui.notify(
+				`@patimweb/pi-teams: account "${card.account}" is configured but not signed in. Run /teams-login.`,
+				"warning",
+			);
+		} else {
+			ctx.ui.notify(
+				`@patimweb/pi-teams loaded (${card.account}${card.user ? ` as ${card.user}` : ""}, safety: ${card.safetyLevel})`,
+				"info",
+			);
+		}
+
+		// Survives /reload, so the transcript keeps saying who pi is acting as.
+		const existing = ctx.sessionManager
+			.getEntries()
+			.some((entry: any) => entry.type === "custom" && entry.customType === "teams-connection");
+		if (!existing) pi.appendEntry<ConnectionCard>("teams-connection", card);
+	});
+
+	// -----------------------------------------------------------------------
+	// Tools
+	// -----------------------------------------------------------------------
+
+	for (const tool of tools) {
+		pi.registerTool({
+			name: tool.name,
+			label: tool.name.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+			description: tool.description,
+			parameters: tool.parameters as any,
+			promptSnippet: "promptSnippet" in tool ? (tool as any).promptSnippet : undefined,
+			promptGuidelines: "promptGuidelines" in tool ? (tool as any).promptGuidelines : undefined,
+			async execute(
+				toolCallId: string,
+				params: any,
+				signal: AbortSignal | undefined,
+				onUpdate: any,
+				ctx: any,
+			) {
+				return (tool as any).execute(toolCallId, params, signal, onUpdate, {
+					cwd: ctx.cwd,
+					connection,
+				});
+			},
+		});
+	}
+
+	// -----------------------------------------------------------------------
+	// Safety interceptor
+	// -----------------------------------------------------------------------
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (!isMutationTool(event.toolName)) return;
+
+		// A tool may target a different account than the session default, so the
+		// rules are resolved against the connection that will actually be used.
+		const params = (event.input ?? {}) as Record<string, unknown>;
+		const target =
+			tryResolveConnection(
+				typeof params.account === "string" ? params.account : undefined,
+				typeof params.tenant === "string" ? params.tenant : undefined,
+			) ?? connection;
+
+		if (!target) {
+			// teams_setup has to work before anything is configured — that is what
+			// it is for.
+			if (LOCAL_CONFIG_TOOLS.has(event.toolName)) return;
+			return {
+				block: true,
+				reason: `Microsoft Teams is not configured. Run the teams_setup tool, or edit ${getConfigPath()}.`,
+			};
+		}
+
+		const blocked = blockReason(target.safetyLevel, target.authMode, event.toolName);
+		if (blocked) return { block: true, reason: blocked };
+
+		if (target.safetyLevel === "confirm") {
+			const scope = target.tenant === target.account ? target.account : `${target.account}/${target.tenant}`;
+			const summary = formatMutationSummary(event.toolName, params);
+			const approved = await ctx.ui.confirm(
+				"Microsoft Teams — acting as you",
+				`${summary}\n\nAccount: ${scope}\n\nAllow this?`,
+			);
+			if (!approved) return { block: true, reason: `User declined: ${summary}` };
+		}
+	});
+}