@patimweb/pi-teams 1.0.0

package/src/tools/teams-setup.ts

@@ -0,0 +1,245 @@
+/**
+ * teams_setup — write an account (or a tenant beneath one) to pi-teams.json.
+ *
+ * Exists so the extension can be configured by talking to pi, instead of
+ * hand-editing JSON. Everything it writes can equally be written by hand; this
+ * is a convenience, not a separate source of truth.
+ */
+
+import { Type } from "typebox";
+import {
+	getConfigPath,
+	upsertAccount,
+	upsertTenant,
+	setDefaultAccount,
+	validateSafetyLevel,
+	type AccountConfig,
+	type TenantConfig,
+} from "../config/index.ts";
+import type { PermissionBlock, ScopeList } from "../config/scope.ts";
+import { formatPermissions, resolvePermissions } from "../config/scope.ts";
+import { errorResult, run, textResult, type ToolResult } from "./shared.ts";
+
+interface SetupParams {
+	name: string;
+	tenantId: string;
+	clientId?: string;
+	displayName?: string;
+	clientSecret?: string;
+	authMode?: string;
+	safetyLevel?: string;
+	parentAccount?: string;
+	setDefault?: boolean;
+	scopes?: string[];
+	allowTeams?: string[];
+	denyTeams?: string[];
+	allowChannels?: string[];
+	denyChannels?: string[];
+	allowChats?: string[];
+	denyChats?: string[];
+	allowPeople?: string[];
+	denyPeople?: string[];
+	writeAllowChannels?: string[];
+	writeDenyChannels?: string[];
+	writeAllowChats?: string[];
+	writeDenyChats?: string[];
+	writeDenyPeople?: string[];
+}
+
+const StringList = (description: string) =>
+	Type.Optional(Type.Array(Type.String(), { description }));
+
+function list(allow?: string[], deny?: string[]): ScopeList | undefined {
+	if (!allow?.length && !deny?.length) return undefined;
+	const result: ScopeList = {};
+	if (allow?.length) result.allow = allow;
+	if (deny?.length) result.deny = deny;
+	return result;
+}
+
+/** Turn the flat parameters into the nested permission block stored in JSON. */
+export function buildPermissionBlock(params: SetupParams): PermissionBlock | undefined {
+	const block: PermissionBlock = {};
+
+	const teams = list(params.allowTeams, params.denyTeams);
+	const channels = list(params.allowChannels, params.denyChannels);
+	const chats = list(params.allowChats, params.denyChats);
+	const people = list(params.allowPeople, params.denyPeople);
+
+	if (teams) block.teams = teams;
+	if (channels) block.channels = channels;
+	if (chats) block.chats = chats;
+	if (people) block.people = people;
+
+	const writeChannels = list(params.writeAllowChannels, params.writeDenyChannels);
+	const writeChats = list(params.writeAllowChats, params.writeDenyChats);
+	const writePeople = list(undefined, params.writeDenyPeople);
+
+	if (writeChannels || writeChats || writePeople) {
+		block.write = {};
+		if (writeChannels) block.write.channels = writeChannels;
+		if (writeChats) block.write.chats = writeChats;
+		if (writePeople) block.write.people = writePeople;
+	}
+
+	return Object.keys(block).length > 0 ? block : undefined;
+}
+
+export const teamsSetupTool = {
+	name: "teams_setup",
+	description:
+		"Configure a Microsoft Teams account (or an additional tenant beneath an existing account) and write it to " +
+		"~/.pi/agent/pi-teams.json. Set clientId and tenantId from your Entra ID app registration. " +
+		"Use parentAccount to add a guest/customer tenant to an account that already exists. " +
+		"Allow/deny lists restrict which teams, channels, chats and people pi may touch. " +
+		"After setup, run teams_login to sign in.",
+	parameters: Type.Object({
+		name: Type.String({
+			description: "Short account (or tenant) name used in every other tool, e.g. 'work', 'customer-alpha'",
+		}),
+		tenantId: Type.String({
+			description: "Entra ID tenant ID or domain, e.g. 'contoso.onmicrosoft.com' or a GUID",
+		}),
+		clientId: Type.Optional(
+			Type.String({
+				description:
+					"Application (client) ID of the Entra ID app registration. Required for a new account; a tenant inherits the account's.",
+			}),
+		),
+		displayName: Type.Optional(Type.String({ description: "Friendly name shown in status output" })),
+		clientSecret: Type.Optional(
+			Type.String({
+				description:
+					"Client secret — only for app-only (client-credentials) access. Not needed, and not recommended, for acting as the user.",
+			}),
+		),
+		authMode: Type.Optional(
+			Type.String({
+				description:
+					"'device-code' (act as the signed-in user, default), 'client-credentials' (app-only, cannot post as a person), or 'auto'",
+			}),
+		),
+		safetyLevel: Type.Optional(
+			Type.String({
+				description: "'open' (no prompts), 'confirm' (ask before every write, default), or 'readonly' (never write)",
+			}),
+		),
+		parentAccount: Type.Optional(
+			Type.String({
+				description: "Add this as a tenant beneath an existing account instead of creating a new account",
+			}),
+		),
+		setDefault: Type.Optional(
+			Type.Boolean({ description: "Make this the default account for tools that omit 'account'" }),
+		),
+		scopes: StringList("Override the requested Microsoft Graph scopes (advanced)"),
+		allowTeams: StringList("Teams pi may see at all. Glob patterns, e.g. ['Engineering', 'Project *']"),
+		denyTeams: StringList("Teams pi must never touch"),
+		allowChannels: StringList("Channels pi may see. Use 'Team/Channel' paths, e.g. ['Engineering/*']"),
+		denyChannels: StringList("Channels pi must never touch, e.g. ['*/Announcements']"),
+		allowChats: StringList("Chats pi may see — match on chat topic or participant name/e-mail"),
+		denyChats: StringList("Chats pi must never touch"),
+		allowPeople: StringList("People pi may interact with (name, UPN or e-mail patterns)"),
+		denyPeople: StringList("People pi must never message, e.g. ['ceo@contoso.com']"),
+		writeAllowChannels: StringList("Channels pi may POST in (narrower than allowChannels)"),
+		writeDenyChannels: StringList("Channels pi may read but never post in"),
+		writeAllowChats: StringList("Chats pi may send messages to"),
+		writeDenyChats: StringList("Chats pi may read but never send to"),
+		writeDenyPeople: StringList("People pi may read about but never message"),
+	}),
+	promptSnippet: "Configure a Microsoft Teams account for pi",
+	promptGuidelines: [
+		"Use teams_setup when the user wants to connect a Teams account, add a second company/tenant, or change which channels pi may use.",
+		"Ask for the clientId and tenantId of their Entra ID app registration if they have not provided them.",
+		"After teams_setup, tell the user to run teams_login (or /teams-login) to sign in as themselves.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: SetupParams,
+		_signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		_ctx: unknown,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const safetyLevel = params.safetyLevel ? validateSafetyLevel(params.safetyLevel) : undefined;
+			if (params.safetyLevel && !safetyLevel) {
+				return errorResult(
+					`Invalid safetyLevel "${params.safetyLevel}". Use "open", "confirm" or "readonly".`,
+				);
+			}
+
+			const permissions = buildPermissionBlock(params);
+
+			if (params.parentAccount) {
+				const tenant: TenantConfig = {
+					name: params.name,
+					tenantId: params.tenantId,
+					clientId: params.clientId,
+					clientSecret: params.clientSecret,
+					authMode: params.authMode as TenantConfig["authMode"],
+					scopes: params.scopes,
+					safetyLevel,
+					permissions,
+				};
+				upsertTenant(params.parentAccount, tenant);
+
+				return textResult(
+					[
+						`✅ Tenant "${params.name}" added to account "${params.parentAccount}".`,
+						"",
+						`Config: ${getConfigPath()}`,
+						"",
+						permissions ? formatPermissions(resolvePermissions([permissions])) : "No scope restrictions configured — pi may use everything this identity can reach.",
+						"",
+						`Next: run teams_login with account "${params.parentAccount}" and tenant "${params.name}".`,
+					].join("\n"),
+					{ account: params.parentAccount, tenant: params.name },
+				);
+			}
+
+			if (!params.clientId) {
+				return errorResult(
+					"clientId is required for a new account. Create an Entra ID app registration " +
+						"(public client, 'Allow public client flows' enabled) and pass its Application (client) ID.",
+				);
+			}
+
+			const account: AccountConfig = {
+				name: params.name,
+				displayName: params.displayName,
+				tenantId: params.tenantId,
+				clientId: params.clientId,
+				clientSecret: params.clientSecret,
+				authMode: (params.authMode as AccountConfig["authMode"]) ?? "device-code",
+				scopes: params.scopes,
+				safetyLevel: safetyLevel ?? "confirm",
+				permissions,
+			};
+
+			upsertAccount(account);
+			if (params.setDefault) setDefaultAccount(params.name);
+
+			return textResult(
+				[
+					`✅ Teams account "${params.name}" saved.`,
+					"",
+					`- Tenant: ${params.tenantId}`,
+					`- Client: ${params.clientId}`,
+					`- Auth mode: ${account.authMode}`,
+					`- Safety level: ${account.safetyLevel}`,
+					`- Config file: ${getConfigPath()} (mode 0600)`,
+					"",
+					"### Effective scope rules",
+					"",
+					permissions
+						? formatPermissions(resolvePermissions([permissions]))
+						: "No restrictions configured — pi may use everything this identity can reach.",
+					"",
+					`Next: run teams_login${params.setDefault ? "" : ` with account "${params.name}"`} to sign in as yourself.`,
+				].join("\n"),
+				{ account: params.name, configPath: getConfigPath() },
+			);
+		});
+	},
+};

package/src/tools/teams-status.ts

@@ -0,0 +1,73 @@
+/**
+ * teams_status — who pi is acting as, and what it is allowed to do.
+ */
+
+import { Type } from "typebox";
+import { buildConnectionCard, formatStatusText } from "../status.ts";
+import { getToken, isFresh } from "../auth/token-store.ts";
+import { readRootConfig } from "../config/index.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsStatusTool = {
+	name: "teams_status",
+	description:
+		"Show the current Microsoft Teams connection: which account and tenant pi is acting as, whether it is " +
+		"signed in, the safety level, and the allow/deny rules in force. Call this when the user asks what pi " +
+		"can do in Teams, or to check a connection before a write.",
+	parameters: Type.Object({
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Show the Teams connection and permissions",
+
+	async execute(
+		_toolCallId: string,
+		params: { 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 card = buildConnectionCard(conn);
+			const root = readRootConfig();
+
+			const others: string[] = [];
+			for (const account of root.accounts) {
+				const tenants = [
+					{ name: account.name, tenantId: account.tenantId },
+					...(account.tenants ?? []).map((t) => ({ name: `${account.name}/${t.name}`, tenantId: t.tenantId })),
+				];
+				for (const entry of tenants) {
+					const token = getToken(account.name, entry.tenantId);
+					const state = isFresh(token)
+						? "signed in"
+						: token?.refreshToken
+							? "session saved (will refresh)"
+							: "not signed in";
+					const who = token?.user?.upn ? ` — ${token.user.upn}` : "";
+					others.push(`- ${entry.name}: ${state}${who}`);
+				}
+			}
+
+			return textResult(
+				[
+					formatStatusText(card),
+					"",
+					"### All configured accounts",
+					"",
+					others.join("\n") || "(none)",
+				].join("\n"),
+				{ account: conn.account, tenant: conn.tenant, signedIn: card?.signedIn ?? false },
+			);
+		});
+	},
+};

package/src/tools/tool-names.ts

@@ -0,0 +1,30 @@
+/**
+ * Tool names in one place.
+ *
+ * The safety interceptor and the tool modules both need to agree on what
+ * counts as a mutation; keeping the set here (instead of in shared.ts) avoids
+ * an import cycle between safety/ and tools/.
+ */
+
+/** Every tool that changes something in Teams, Outlook, or the local config. */
+export const MUTATION_TOOLS = new Set<string>([
+	// Messaging
+	"teams_send_chat_message",
+	"teams_send_channel_message",
+	"teams_reply_channel_message",
+	"teams_create_chat",
+	"teams_delete_message",
+	"teams_react",
+	// Structure
+	"teams_create_channel",
+	// Presence
+	"teams_set_presence",
+	"teams_set_status_message",
+	// Calendar
+	"teams_create_meeting",
+	"teams_update_meeting",
+	"teams_cancel_meeting",
+	// Local configuration and credentials
+	"teams_setup",
+	"teams_logout",
+]);

package/src/types.ts

@@ -0,0 +1,192 @@
+/**
+ * Domain data types.
+ *
+ * Plain, immutable interfaces. No behavior, no classes, no inheritance.
+ * Everything the Graph layer returns is normalized into these shapes before
+ * it reaches a formatter or a tool.
+ */
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/** The signed-in user behind an access token. */
+export interface SignedInUser {
+	/** Object ID (oid claim) */
+	id: string;
+	/** Display name */
+	displayName: string;
+	/** User principal name / login */
+	upn: string;
+	/** Primary SMTP address, when known */
+	mail?: string;
+	/** Tenant ID (tid claim) */
+	tenantId: string;
+	/** Job title, when known */
+	jobTitle?: string;
+}
+
+/** A person referenced in a message, member list, or search result. */
+export interface PersonRef {
+	id?: string;
+	displayName: string;
+	upn?: string;
+	mail?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Teams & channels
+// ---------------------------------------------------------------------------
+
+export interface TeamSummary {
+	id: string;
+	displayName: string;
+	description?: string;
+	visibility?: string;
+	isArchived?: boolean;
+	webUrl?: string;
+}
+
+export interface ChannelSummary {
+	id: string;
+	displayName: string;
+	description?: string;
+	/** "standard" | "private" | "shared" */
+	membershipType?: string;
+	webUrl?: string;
+	/** Owning team, filled in by the caller for display + scope checks */
+	teamId?: string;
+	teamName?: string;
+}
+
+export interface MemberSummary {
+	id: string;
+	displayName: string;
+	upn?: string;
+	mail?: string;
+	roles: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Chats
+// ---------------------------------------------------------------------------
+
+export interface ChatSummary {
+	id: string;
+	/** "oneOnOne" | "group" | "meeting" */
+	chatType: string;
+	/** Explicit topic for group chats, otherwise derived from members */
+	topic?: string;
+	/** Human label used for display and scope matching */
+	label: string;
+	members: PersonRef[];
+	lastUpdated?: string;
+	lastMessagePreview?: string;
+	lastMessageFrom?: string;
+	webUrl?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+
+export interface MessageSummary {
+	id: string;
+	/** Plain-text rendering of the message body */
+	text: string;
+	/** Original content type: "text" | "html" */
+	contentType: string;
+	from?: PersonRef;
+	createdDateTime?: string;
+	lastModifiedDateTime?: string;
+	/** Set when the message was soft-deleted */
+	deletedDateTime?: string;
+	subject?: string;
+	importance?: string;
+	/** Parent message id for channel replies */
+	replyToId?: string;
+	/** Number of replies, when the caller resolved them */
+	replyCount?: number;
+	mentions: PersonRef[];
+	reactions: MessageReaction[];
+	attachments: MessageAttachment[];
+	webUrl?: string;
+	/** Where the message lives — used for follow-up calls and scope checks */
+	location?: MessageLocation;
+}
+
+export interface MessageReaction {
+	type: string;
+	user?: string;
+	createdDateTime?: string;
+}
+
+export interface MessageAttachment {
+	id?: string;
+	name?: string;
+	contentType?: string;
+	contentUrl?: string;
+}
+
+export interface MessageLocation {
+	kind: "chat" | "channel";
+	chatId?: string;
+	teamId?: string;
+	teamName?: string;
+	channelId?: string;
+	channelName?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Presence
+// ---------------------------------------------------------------------------
+
+export interface PresenceInfo {
+	id: string;
+	displayName?: string;
+	availability: string;
+	activity: string;
+	statusMessage?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Calendar & meetings
+// ---------------------------------------------------------------------------
+
+export interface EventSummary {
+	id: string;
+	subject: string;
+	start?: string;
+	end?: string;
+	timeZone?: string;
+	isAllDay?: boolean;
+	isOnlineMeeting?: boolean;
+	joinUrl?: string;
+	organizer?: PersonRef;
+	attendees: PersonRef[];
+	location?: string;
+	bodyPreview?: string;
+	webLink?: string;
+}
+
+export interface OnlineMeetingSummary {
+	id: string;
+	subject?: string;
+	joinUrl: string;
+	start?: string;
+	end?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Files
+// ---------------------------------------------------------------------------
+
+export interface DriveItemSummary {
+	id: string;
+	name: string;
+	size?: number;
+	lastModifiedDateTime?: string;
+	lastModifiedBy?: string;
+	webUrl?: string;
+	isFolder: boolean;
+}

package/src/utils/errors.ts

@@ -0,0 +1,133 @@
+/**
+ * Microsoft Graph errors → messages a person can act on.
+ *
+ * Graph is unusually good at returning precise error codes and unusually bad
+ * at explaining what to do about them. The mapping below turns the common ones
+ * into the next step ("consent to X", "run teams_login", "ask an admin").
+ */
+
+/** An error returned by the Graph API, with its code preserved. */
+export class GraphError extends Error {
+	readonly status: number;
+	readonly code: string;
+	readonly requestId?: string;
+	readonly raw?: unknown;
+
+	constructor(status: number, code: string, message: string, requestId?: string, raw?: unknown) {
+		super(message);
+		this.name = "GraphError";
+		this.status = status;
+		this.code = code;
+		this.requestId = requestId;
+		this.raw = raw;
+	}
+}
+
+/** Raised when a scope rule blocks an operation. */
+export class ScopeDeniedError extends Error {
+	readonly target: string;
+	readonly reason: string;
+	constructor(target: string, reason: string) {
+		super(`Blocked by configuration: ${target} — ${reason}.`);
+		this.name = "ScopeDeniedError";
+		this.target = target;
+		this.reason = reason;
+	}
+}
+
+const CONSENT_HINTS: Record<string, string> = {
+	"ChannelMessage.Read.All": "reading channel messages",
+	"ChannelMessage.Send": "posting in channels",
+	"Chat.ReadWrite": "reading and sending chat messages",
+	"ChatMessage.Send": "sending chat messages",
+	"Presence.ReadWrite": "reading and setting your presence",
+	"Calendars.ReadWrite": "reading and creating calendar events",
+	"OnlineMeetings.ReadWrite": "creating Teams meetings",
+};
+
+/** Normalize any thrown value into a readable, actionable message. */
+export function formatGraphError(error: unknown): string {
+	if (error instanceof ScopeDeniedError) return error.message;
+
+	if (error instanceof GraphError) {
+		switch (error.code) {
+			case "InvalidAuthenticationToken":
+				return "The access token was rejected. Run teams_login to sign in again.";
+			case "Unauthorized":
+				return "Authentication failed. Run teams_login to sign in again.";
+			case "Forbidden":
+			case "AccessDenied":
+			case "Authorization_RequestDenied":
+				return (
+					"Permission denied. The signed-in user (or the app registration) lacks access to this " +
+					"resource. Run teams_doctor to see which Graph scopes were actually granted."
+				);
+			case "NotFound":
+			case "itemNotFound":
+			case "ResourceNotFound":
+				return "Not found. Check the team, channel, chat or message ID.";
+			case "ErrorItemNotFound":
+				return "Not found — the item may have been deleted or you no longer have access.";
+			case "activityLimitReached":
+			case "TooManyRequests":
+				return "Throttled by Microsoft Graph. Wait a moment and try again.";
+			case "BadRequest":
+				return `Graph rejected the request: ${error.message}`;
+			case "UnknownError":
+				return `Graph returned an unspecified error: ${error.message}`;
+			default:
+				return `${error.code}: ${error.message}`;
+		}
+	}
+
+	if (error instanceof Error) {
+		const msg = error.message;
+		if (msg.includes("ENOTFOUND")) return "DNS error: could not resolve the Graph endpoint.";
+		if (msg.includes("ECONNREFUSED") || msg.includes("ETIMEDOUT")) {
+			return "Network error: could not reach Microsoft Graph. Check your connection or proxy.";
+		}
+		if (msg.includes("AADSTS7000218")) {
+			return (
+				"The app registration rejected the device code flow. Enable 'Allow public client flows' " +
+				"in Entra ID → App registrations → Authentication."
+			);
+		}
+		if (msg.includes("AADSTS65001")) {
+			return "Consent is missing for one or more scopes. Sign in again, or ask an admin to grant consent.";
+		}
+		if (msg.includes("AADSTS50076") || msg.includes("AADSTS50079")) {
+			return "Multi-factor authentication is required. Complete the sign-in in the browser and retry.";
+		}
+		if (msg.includes("AADSTS50020")) {
+			return (
+				"The signed-in user does not exist in that tenant. For a guest/customer tenant, make sure the " +
+				"account is invited there and the app registration is multi-tenant."
+			);
+		}
+		return msg.split("\n")[0] ?? "Unknown error";
+	}
+
+	return String(error);
+}
+
+export function isAuthError(error: unknown): boolean {
+	if (error instanceof GraphError) {
+		return error.status === 401 || error.code === "InvalidAuthenticationToken";
+	}
+	return false;
+}
+
+export function isNotFoundError(error: unknown): boolean {
+	if (error instanceof GraphError) return error.status === 404;
+	return false;
+}
+
+export function isThrottled(error: unknown): boolean {
+	if (error instanceof GraphError) return error.status === 429 || error.status === 503;
+	return false;
+}
+
+/** Human-readable purpose of a Graph scope, for doctor output. */
+export function describeScope(scope: string): string | undefined {
+	return CONSENT_HINTS[scope];
+}