@patimweb/pi-teams 1.0.0

package/src/tools/resolve.ts

@@ -0,0 +1,138 @@
+/**
+ * Target resolution with scope enforcement.
+ *
+ * Every tool that touches a specific channel or chat goes through here, so the
+ * "resolve the name, then check the rules" pair can never be half-done: the
+ * functions below either return an in-scope target or throw.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import type { ChannelSummary, ChatSummary, TeamSummary } from "../types.ts";
+import { chatCandidates, channelCandidates, teamCandidates } from "../graph/mappers.ts";
+import { findChats } from "../graph/chats.ts";
+import { resolveTeam, resolveTeamAndChannel } from "../graph/teams.ts";
+import { assertAccess } from "../safety/index.ts";
+import type { ScopeMode } from "../config/scope.ts";
+import { currentUser } from "./shared.ts";
+
+/** Raised when a name matches nothing, or too much to be safe. */
+export class TargetError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "TargetError";
+	}
+}
+
+/**
+ * Resolve a team by name or ID and check it against the rules.
+ *
+ * @throws {TargetError} when it does not exist
+ * @throws {ScopeDeniedError} when the rules forbid it
+ */
+export async function requireTeam(
+	conn: TeamsConnection,
+	reference: string,
+	mode: ScopeMode,
+	signal?: AbortSignal,
+): Promise<TeamSummary> {
+	const team = await resolveTeam(conn, reference, signal);
+	if (!team) {
+		throw new TargetError(
+			`Team "${reference}" not found among the teams you are a member of. ` +
+				`Use teams_list_teams to see the available names.`,
+		);
+	}
+	assertAccess(conn, mode, "teams", team.displayName, teamCandidates(team));
+	return team;
+}
+
+/**
+ * Resolve a channel (optionally via "Team/Channel") and check both the team
+ * and the channel against the rules.
+ */
+export async function requireChannel(
+	conn: TeamsConnection,
+	teamRef: string | undefined,
+	channelRef: string,
+	mode: ScopeMode,
+	signal?: AbortSignal,
+): Promise<{ team: TeamSummary; channel: ChannelSummary }> {
+	if (!teamRef && !channelRef.includes("/")) {
+		throw new TargetError(
+			`Specify the team as well: pass 'team' explicitly, or use a "Team/Channel" path for 'channel'.`,
+		);
+	}
+
+	const { team, channel } = await resolveTeamAndChannel(conn, teamRef, channelRef, signal);
+
+	if (!team) {
+		throw new TargetError(
+			`Team "${teamRef ?? channelRef.split("/")[0]}" not found. Use teams_list_teams to see the available names.`,
+		);
+	}
+	assertAccess(conn, mode, "teams", team.displayName, teamCandidates(team));
+
+	if (!channel) {
+		throw new TargetError(
+			`Channel "${channelRef}" not found in team "${team.displayName}". ` +
+				`Use teams_list_channels to see the available names.`,
+		);
+	}
+	assertAccess(
+		conn,
+		mode,
+		"channels",
+		`${team.displayName}/${channel.displayName}`,
+		channelCandidates(channel),
+	);
+
+	return { team, channel };
+}
+
+/**
+ * Resolve a chat by ID, topic or participant and check it against the rules.
+ *
+ * Refuses ambiguous matches: sending "the usual update" to the wrong Anna is
+ * not something a confirmation dialog can undo.
+ */
+export async function requireChat(
+	conn: TeamsConnection,
+	reference: string,
+	mode: ScopeMode,
+	signal?: AbortSignal,
+): Promise<ChatSummary> {
+	const me = await currentUser(conn, signal).catch(() => undefined);
+	const matches = await findChats(conn, reference, { meId: me?.id, signal });
+
+	if (matches.length === 0) {
+		throw new TargetError(
+			`No chat matching "${reference}". Use teams_list_chats to see recent chats, ` +
+				`or teams_create_chat to start a new one.`,
+		);
+	}
+
+	if (matches.length > 1) {
+		const options = matches.slice(0, 8).map((chat) => `"${chat.label}" (${chat.id})`);
+		throw new TargetError(
+			`"${reference}" matches ${matches.length} chats: ${options.join(", ")}. ` +
+				`Pass the chat ID to be unambiguous.`,
+		);
+	}
+
+	const chat = matches[0]!;
+	assertAccess(conn, mode, "chats", chat.label, chatCandidates(chat));
+
+	// A chat is also the people in it: a deny rule on a person must stop a
+	// message to any chat they are part of, not just their 1:1.
+	for (const member of chat.members) {
+		if (me && member.id === me.id) continue;
+		assertAccess(conn, mode, "people", member.displayName, [
+			member.displayName,
+			member.upn,
+			member.mail,
+			member.id,
+		]);
+	}
+
+	return chat;
+}

package/src/tools/shared.ts

@@ -0,0 +1,124 @@
+/**
+ * Shared tool plumbing — parameter schemas, result helpers, connection
+ * resolution and the guards every tool runs before touching Graph.
+ */
+
+import { Type } from "typebox";
+import {
+	resolveConnection,
+	type TeamsConnection,
+} from "../config/index.ts";
+import { getMe } from "../graph/me.ts";
+import { formatGraphError } from "../utils/errors.ts";
+import type { SignedInUser } from "../types.ts";
+
+// ---------------------------------------------------------------------------
+// Common parameters
+// ---------------------------------------------------------------------------
+
+/** Which configured account to act as. */
+export const AccountParam = Type.Optional(
+	Type.String({
+		description:
+			"Configured account name to act as (see teams_accounts). Uses the default account if omitted.",
+	}),
+);
+
+/** Which tenant beneath that account — for guest access and customer tenants. */
+export const TenantParam = Type.Optional(
+	Type.String({
+		description:
+			"Tenant name configured beneath the account (guest or customer tenant). Uses the account's home tenant if omitted.",
+	}),
+);
+
+export const LimitParam = Type.Optional(
+	Type.Number({ description: "Maximum number of items to return" }),
+);
+
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+
+export interface ToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: Record<string, unknown>;
+}
+
+export function textResult(text: string, details: Record<string, unknown> = {}): ToolResult {
+	return { content: [{ type: "text", text }], details };
+}
+
+export function errorResult(message: string): ToolResult {
+	return { content: [{ type: "text", text: `❌ ${message}` }], details: { error: true } };
+}
+
+/** Wrap a tool body so every failure comes back as a readable message. */
+export async function run(fn: () => Promise<ToolResult>): Promise<ToolResult> {
+	try {
+		return await fn();
+	} catch (err) {
+		return errorResult(formatGraphError(err));
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Connection
+// ---------------------------------------------------------------------------
+
+/** The context every tool receives from the extension. */
+export interface ToolContext {
+	cwd: string;
+	connection?: TeamsConnection;
+}
+
+/**
+ * Resolve the connection for this call.
+ *
+ * The session-level connection is reused when no override is given, so the
+ * common case costs nothing; naming an account or tenant re-resolves against
+ * the config file, which also picks up edits made during the session.
+ */
+export function connectionFor(
+	ctx: ToolContext,
+	account?: string,
+	tenant?: string,
+): TeamsConnection {
+	if (!account && !tenant && ctx.connection) return ctx.connection;
+	return resolveConnection(account, tenant);
+}
+
+// ---------------------------------------------------------------------------
+// Identity cache
+// ---------------------------------------------------------------------------
+
+const meCache = new Map<string, SignedInUser>();
+
+/**
+ * The signed-in user for a connection, cached for the session.
+ *
+ * Several tools need the user's own ID — to label chats from their point of
+ * view, to check "is this my message" — and none of them should pay for a
+ * `/me` round-trip each time.
+ */
+export async function currentUser(
+	conn: TeamsConnection,
+	signal?: AbortSignal,
+): Promise<SignedInUser> {
+	const key = `${conn.account}::${conn.tenantId}`;
+	const cached = meCache.get(key);
+	if (cached) return cached;
+	const me = await getMe(conn, signal);
+	meCache.set(key, me);
+	return me;
+}
+
+/** Forget cached identities (after a logout or account switch). */
+export function clearUserCache(): void {
+	meCache.clear();
+}
+
+/** Short label for a connection, e.g. "work" or "work/customer-alpha". */
+export function connectionLabel(conn: TeamsConnection): string {
+	return conn.tenant === conn.account ? conn.account : `${conn.account}/${conn.tenant}`;
+}

package/src/tools/teams-accounts.ts

@@ -0,0 +1,169 @@
+/**
+ * teams_accounts — list, switch between, and remove accounts and tenants.
+ */
+
+import { Type } from "typebox";
+import {
+	getConfigPath,
+	readRootConfig,
+	removeAccount,
+	removeTenant,
+	setDefaultAccount,
+	setSafetyLevel,
+	validateSafetyLevel,
+} from "../config/index.ts";
+import { deleteToken, getToken, isFresh } from "../auth/token-store.ts";
+import { clearUserCache, errorResult, run, textResult, type ToolResult } from "./shared.ts";
+
+interface AccountsParams {
+	action?: string;
+	account?: string;
+	tenant?: string;
+	safetyLevel?: string;
+}
+
+export const teamsAccountsTool = {
+	name: "teams_accounts",
+	description:
+		"Manage configured Teams accounts and their tenants: list them, switch the default, change a safety level, " +
+		"or delete one. Use this for multi-account and multi-company setups. " +
+		"Actions: 'list' (default), 'use', 'delete', 'safety'.",
+	parameters: Type.Object({
+		action: Type.Optional(
+			Type.String({ description: "'list' (default), 'use', 'delete', or 'safety'" }),
+		),
+		account: Type.Optional(Type.String({ description: "Account name the action applies to" })),
+		tenant: Type.Optional(
+			Type.String({ description: "Tenant beneath that account; omit to target the account itself" }),
+		),
+		safetyLevel: Type.Optional(
+			Type.String({ description: "For action 'safety': 'open', 'confirm' or 'readonly'" }),
+		),
+	}),
+	promptSnippet: "List or switch Microsoft Teams accounts",
+	promptGuidelines: [
+		"Use teams_accounts when the user mentions a different company, tenant, or Teams identity.",
+		"Prefer passing account/tenant directly to the tool you need instead of switching the default.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: AccountsParams,
+		_signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		_ctx: unknown,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const action = (params.action ?? "list").toLowerCase();
+			const config = readRootConfig();
+
+			if (config.accounts.length === 0) {
+				return textResult(
+					`No Teams accounts configured yet. Run teams_setup, or edit ${getConfigPath()}.`,
+					{ accounts: [] },
+				);
+			}
+
+			switch (action) {
+				case "list": {
+					const lines = ["## Configured Teams accounts", ""];
+					for (const account of config.accounts) {
+						const isDefault = config.defaultAccount === account.name;
+						const token = getToken(account.name, account.tenantId);
+						const state = isFresh(token)
+							? "signed in"
+							: token?.refreshToken
+								? "session saved"
+								: "not signed in";
+
+						lines.push(
+							`### ${account.displayName ?? account.name}${isDefault ? " (default)" : ""}`,
+							"",
+							`- name: \`${account.name}\``,
+							`- tenant: ${account.tenantId}`,
+							`- auth mode: ${account.authMode ?? "device-code"}`,
+							`- safety: ${account.safetyLevel ?? config.safetyLevel ?? "confirm"}`,
+							`- status: ${state}${token?.user?.upn ? ` as ${token.user.upn}` : ""}`,
+						);
+
+						for (const tenant of account.tenants ?? []) {
+							const tenantToken = getToken(account.name, tenant.tenantId);
+							const tenantState = isFresh(tenantToken)
+								? "signed in"
+								: tenantToken?.refreshToken
+									? "session saved"
+									: "not signed in";
+							lines.push(
+								`  - tenant \`${tenant.name}\` (${tenant.tenantId}) — ${tenantState}` +
+									`${tenant.safetyLevel ? `, safety: ${tenant.safetyLevel}` : ""}`,
+							);
+						}
+						lines.push("");
+					}
+					lines.push(`Config: ${getConfigPath()}`);
+					return textResult(lines.join("\n"), {
+						accounts: config.accounts.map((a) => a.name),
+						defaultAccount: config.defaultAccount,
+					});
+				}
+
+				case "use": {
+					if (!params.account) return errorResult("action 'use' requires an account name.");
+					setDefaultAccount(params.account, params.tenant);
+					clearUserCache();
+					return textResult(
+						`✅ Default Teams account is now "${params.account}"${params.tenant ? ` (tenant ${params.tenant})` : ""}.`,
+						{ defaultAccount: params.account, defaultTenant: params.tenant },
+					);
+				}
+
+				case "delete": {
+					if (!params.account) return errorResult("action 'delete' requires an account name.");
+
+					if (params.tenant) {
+						const tenantConfig = config.accounts
+							.find((a) => a.name === params.account)
+							?.tenants?.find((t) => t.name === params.tenant);
+						const removed = removeTenant(params.account, params.tenant);
+						if (removed && tenantConfig) deleteToken(params.account, tenantConfig.tenantId);
+						return removed
+							? textResult(`✅ Removed tenant "${params.tenant}" from account "${params.account}".`, {})
+							: errorResult(`Tenant "${params.tenant}" not found in account "${params.account}".`);
+					}
+
+					const accountConfig = config.accounts.find((a) => a.name === params.account);
+					const removed = removeAccount(params.account);
+					if (removed && accountConfig) {
+						deleteToken(params.account, accountConfig.tenantId);
+						for (const tenant of accountConfig.tenants ?? []) {
+							deleteToken(params.account, tenant.tenantId);
+						}
+					}
+					clearUserCache();
+					return removed
+						? textResult(`✅ Removed account "${params.account}" and its cached sessions.`, {})
+						: errorResult(`Account "${params.account}" not found.`);
+				}
+
+				case "safety": {
+					const level = validateSafetyLevel(params.safetyLevel);
+					if (!level) {
+						return errorResult(
+							`action 'safety' requires safetyLevel to be "open", "confirm" or "readonly".`,
+						);
+					}
+					setSafetyLevel(level, params.account, params.tenant);
+					const target = params.account
+						? params.tenant
+							? `${params.account}/${params.tenant}`
+							: params.account
+						: "globally";
+					return textResult(`✅ Safety level set to "${level}" ${target}.`, { safetyLevel: level });
+				}
+
+				default:
+					return errorResult(`Unknown action "${action}". Use 'list', 'use', 'delete' or 'safety'.`);
+			}
+		});
+	},
+};

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

@@ -0,0 +1,89 @@
+/**
+ * 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 },
+			);
+		});
+	},
+};

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

@@ -0,0 +1,112 @@
+/**
+ * teams_create_chat — start a new 1:1 or group chat.
+ *
+ * Teams reuses an existing 1:1 conversation, so calling this for "message
+ * Anna" does not litter the user's chat list with duplicates.
+ */
+
+import { Type } from "typebox";
+import { createChat, resolveParticipants } from "../graph/chats.ts";
+import { sendChatMessage } from "../graph/messages.ts";
+import { auditWrite } from "../safety/audit.ts";
+import { assertAccess } from "../safety/index.ts";
+import { truncate } from "../utils/formatting.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	currentUser,
+	errorResult,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+interface CreateChatParams {
+	participants: string[];
+	topic?: string;
+	message?: string;
+	account?: string;
+	tenant?: string;
+}
+
+export const teamsCreateChatTool = {
+	name: "teams_create_chat",
+	description:
+		"Start a new Microsoft Teams chat with one or more people, optionally sending the first message right " +
+		"away. Participants are given as names, e-mail addresses or user principal names. " +
+		"For one participant, Teams reuses the existing 1:1 chat if there is one.",
+	parameters: Type.Object({
+		participants: Type.Array(Type.String(), {
+			description: "People to include, by name, e-mail or UPN",
+		}),
+		topic: Type.Optional(Type.String({ description: "Group chat topic (group chats only)" })),
+		message: Type.Optional(Type.String({ description: "First message to send into the new chat" })),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Start a new Teams chat",
+
+	async execute(
+		_toolCallId: string,
+		params: CreateChatParams,
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const conn = connectionFor(ctx, params.account, params.tenant);
+
+			if (!params.participants?.length) {
+				return errorResult("At least one participant is required.");
+			}
+
+			const { resolved, unresolved } = await resolveParticipants(conn, params.participants, signal);
+			if (unresolved.length > 0) {
+				return errorResult(
+					`Could not resolve: ${unresolved.join(", ")}. Use teams_find_user to look them up.`,
+				);
+			}
+
+			for (const person of resolved) {
+				assertAccess(conn, "write", "people", person.displayName, [
+					person.displayName,
+					person.upn,
+					person.mail,
+					person.id,
+				]);
+			}
+
+			const chat = await createChat(conn, resolved, { topic: params.topic, signal });
+			const me = await currentUser(conn, signal).catch(() => undefined);
+			const label = params.topic ?? resolved.map((p) => p.displayName).join(", ");
+
+			auditWrite(conn.audit, {
+				tool: "teams_create_chat",
+				account: conn.account,
+				tenant: conn.tenant,
+				actor: me?.upn,
+				target: `chat:${label}`,
+				summary: `created chat with ${resolved.map((p) => p.upn ?? p.displayName).join(", ")}`,
+			});
+
+			const lines = [`✅ Chat with **${label}** ready.`, "", `chatId: ${chat.id}`];
+
+			if (params.message?.trim()) {
+				const sent = await sendChatMessage(conn, chat.id, { body: params.message }, signal);
+				auditWrite(conn.audit, {
+					tool: "teams_create_chat",
+					account: conn.account,
+					tenant: conn.tenant,
+					actor: me?.upn,
+					target: `chat:${label}`,
+					summary: truncate(params.message, 200),
+				});
+				lines.push("", `Sent as ${me?.displayName ?? "you"}:`, "", `> ${truncate(params.message, 300)}`, "", `messageId: ${sent.id}`);
+			}
+
+			return textResult(lines.join("\n"), { chatId: chat.id, participants: resolved.length });
+		});
+	},
+};