@patimweb/pi-teams 1.1.0 → 1.3.0

package/src/extension/index.ts

@@ -12,6 +12,7 @@ import { Box, Text } from "@earendil-works/pi-tui";
 import {
 	ensureConfigTemplate,
 	getConfigPath,
+	setWatchConfig,
 	tryResolveConnection,
 	type TeamsConnection,
 } from "../config/index.ts";
@@ -22,6 +23,13 @@ import {
 	isMutationTool,
 	LOCAL_CONFIG_TOOLS,
 } from "../safety/index.ts";
+import {
+	setActiveWatchLoop,
+	startWatchLoop,
+	stopActiveWatchLoop,
+	type WatchLoop,
+} from "../watch/loop.ts";
+import { composeWatchPrompt } from "../watch/prompt.ts";
 
 import { teamsSetupTool } from "../tools/teams-setup.ts";
 import { teamsLoginTool, teamsLogoutTool } from "../tools/teams-login.ts";
@@ -43,12 +51,16 @@ 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 { teamsMarkReadTool } from "../tools/teams-mark-read.ts";
+import { teamsUpdateMessageTool } from "../tools/teams-update-message.ts";
+import { teamsChatMembersTool } from "../tools/teams-chat-members.ts";
+import { teamsAvailabilityTool } from "../tools/teams-availability.ts";
 import { teamsDeleteMessageTool } from "../tools/teams-delete-message.ts";
 import { teamsInboxTool } from "../tools/teams-inbox.ts";
+import { teamsWatchTool } from "../tools/teams-watch.ts";
 import {
 	teamsGetPresenceTool,
 	teamsSetPresenceTool,
@@ -59,6 +71,7 @@ import {
 	teamsCreateMeetingTool,
 	teamsGetMeetingTool,
 	teamsListMeetingsTool,
+	teamsRespondInviteTool,
 	teamsUpdateMeetingTool,
 } from "../tools/teams-meetings.ts";
 
@@ -73,6 +86,7 @@ const tools = [
 	teamsAccountsTool,
 	teamsStatusTool,
 	teamsPermissionsTool,
+	teamsWatchTool,
 	teamsDoctorTool,
 	// Discovery
 	teamsListTeamsTool,
@@ -84,16 +98,18 @@ const tools = [
 	teamsReadChatTool,
 	teamsSendChatMessageTool,
 	teamsCreateChatTool,
+	teamsMarkReadTool,
+	teamsChatMembersTool,
 	// Channels
 	teamsReadChannelTool,
 	teamsReadThreadTool,
 	teamsSendChannelMessageTool,
 	teamsReplyChannelMessageTool,
-	teamsCreateChannelTool,
 	teamsListFilesTool,
 	// Cross-cutting
 	teamsSearchMessagesTool,
 	teamsReactTool,
+	teamsUpdateMessageTool,
 	teamsDeleteMessageTool,
 	teamsInboxTool,
 	// Presence
@@ -103,8 +119,10 @@ const tools = [
 	// Calendar
 	teamsListMeetingsTool,
 	teamsGetMeetingTool,
+	teamsAvailabilityTool,
 	teamsCreateMeetingTool,
 	teamsUpdateMeetingTool,
+	teamsRespondInviteTool,
 	teamsCancelMeetingTool,
 ];
 
@@ -118,6 +136,74 @@ export default function (pi: ExtensionAPI) {
 		return connection;
 	};
 
+	// -----------------------------------------------------------------------
+	// Listen mode
+	// -----------------------------------------------------------------------
+
+	/** The watcher running in this session, when listen mode is on. */
+	let watchLoop: WatchLoop | undefined;
+
+	/** The last polling error the user was told about, so it is said once. */
+	let reportedWatchError: string | undefined;
+
+	const stopWatch = () => {
+		watchLoop?.stop();
+		watchLoop = undefined;
+		setActiveWatchLoop(undefined);
+	};
+
+	/**
+	 * Start the watcher for the session's account, if the config asks for it.
+	 *
+	 * Restarting is the same call: the old loop is stopped first, so a config
+	 * change cannot leave two pollers running.
+	 */
+	const startWatch = (ctx: any) => {
+		stopWatch();
+
+		const conn = refresh();
+		if (!conn?.watch.enabled) return;
+
+		reportedWatchError = undefined;
+		const loop = startWatchLoop({
+			connection: conn,
+			onWake: (event) => {
+				pi.sendUserMessage(composeWatchPrompt(event, event.me), { deliverAs: "followUp" });
+			},
+			onTick: (status) => {
+				if (!status.lastError) reportedWatchError = undefined;
+			},
+			onError: (message) => {
+				// A watcher that fails every tick would otherwise say so every minute.
+				if (message === reportedWatchError) return;
+				reportedWatchError = message;
+				ctx.ui.notify(`Teams listen mode: ${message}`, "warning");
+			},
+		});
+
+		watchLoop = loop;
+		setActiveWatchLoop(loop);
+	};
+
+	/**
+	 * Paint the footer status line from the current connection.
+	 *
+	 * The only place the status line is written, so the three surfaces —
+	 * session start, `/teams-status`, and a tool result — cannot drift apart.
+	 */
+	const paintStatus = (ctx: any) => {
+		const card = buildConnectionCard(refresh());
+		if (!card) return;
+		const watching = !!watchLoop?.status().running;
+		ctx.ui.setStatus(
+			"teams",
+			ctx.ui.theme.fg(
+				card.signedIn ? "success" : "warning",
+				buildConnectionLabel({ ...card, watching }),
+			),
+		);
+	};
+
 	// -----------------------------------------------------------------------
 	// Status card — rendered in the transcript, never sent to the model
 	// -----------------------------------------------------------------------
@@ -162,7 +248,7 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 			pi.appendEntry<ConnectionCard>("teams-connection", card);
-			ctx.ui.setStatus("teams", ctx.ui.theme.fg("success", buildConnectionLabel(card)));
+			paintStatus(ctx);
 			ctx.ui.notify(buildConnectionLabel(card), "info");
 		},
 	});
@@ -188,6 +274,56 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("teams-listen", {
+		description: "Let pi listen to Teams: on, off, or status (default)",
+		handler: async (args, ctx) => {
+			const conn = refresh();
+			if (!conn) {
+				ctx.ui.notify(
+					`Teams: no account configured yet. Use the teams_setup tool, or edit ${getConfigPath()}.`,
+					"warning",
+				);
+				return;
+			}
+
+			const action = args.trim().toLowerCase() || "status";
+
+			if (action === "on" || action === "off") {
+				// Written to the account, not globally: the watcher listens as one
+				// identity, and "which account" must not be a guess.
+				const watch = setWatchConfig({ enabled: action === "on" }, conn.account);
+				startWatch(ctx);
+				paintStatus(ctx);
+				ctx.ui.notify(
+					watch.enabled
+						? `Teams listen mode on — polling every ${watch.intervalSeconds} s, max ${watch.maxTriggersPerHour} wakes/hour.`
+						: "Teams listen mode off.",
+					"info",
+				);
+				return;
+			}
+
+			if (action !== "status") {
+				ctx.ui.notify(`Unknown argument "${action}". Use on, off, or status.`, "warning");
+				return;
+			}
+
+			const runtime = watchLoop?.status();
+			pi.appendEntry<ConnectionCard>("teams-connection", { ...buildConnectionCard(conn)!, watching: !!runtime?.running });
+			ctx.ui.notify(
+				[
+					`Listen mode: ${conn.watch.enabled ? "on" : "off"}`,
+					`every ${conn.watch.intervalSeconds} s`,
+					conn.watch.chats.length > 0 ? `chats: ${conn.watch.chats.join(", ")}` : "all recent chats",
+					conn.watch.from.length > 0 ? `people: ${conn.watch.from.join(", ")}` : "any sender",
+					conn.watch.mentionOnly ? "mentions only" : "every message",
+					runtime ? `${runtime.wakesThisHour} wake(s) this hour` : "not running in this session",
+				].join(" · "),
+				"info",
+			);
+		},
+	});
+
 	pi.registerCommand("teams-inbox", {
 		description: "Show what needs your attention in Microsoft Teams",
 		handler: async (_args, ctx) => {
@@ -246,7 +382,8 @@ export default function (pi: ExtensionAPI) {
 		const card = buildConnectionCard(connection);
 		if (!card) return;
 
-		ctx.ui.setStatus("teams", ctx.ui.theme.fg(card.signedIn ? "success" : "warning", buildConnectionLabel(card)));
+		paintStatus(ctx);
+		startWatch(ctx);
 
 		if (!card.signedIn) {
 			ctx.ui.notify(
@@ -294,6 +431,16 @@ export default function (pi: ExtensionAPI) {
 		});
 	}
 
+	// -----------------------------------------------------------------------
+	// Listen mode lifecycle
+	// -----------------------------------------------------------------------
+
+	pi.on("session_shutdown", () => {
+		// The timer would be unref'd anyway, but a poll in flight during shutdown
+		// would still be a Graph call for a session that is gone.
+		stopWatch();
+	});
+
 	// -----------------------------------------------------------------------
 	// Safety interceptor
 	// -----------------------------------------------------------------------
@@ -333,4 +480,39 @@ export default function (pi: ExtensionAPI) {
 			if (!approved) return { block: true, reason: `User declined: ${summary}` };
 		}
 	});
+
+	// -----------------------------------------------------------------------
+	// Status after a tool ran
+	// -----------------------------------------------------------------------
+
+	/**
+	 * The status line is a snapshot of session start — but every change to the
+	 * connection happens afterwards, in a tool, and tools have no UI context of
+	 * their own. Without this the footer would still read "not signed in" after a
+	 * successful login, and "listening" after listen mode was switched off.
+	 */
+	const STATUS_TOOLS = new Set([
+		"teams_login",
+		"teams_logout",
+		"teams_setup",
+		"teams_accounts",
+		"teams_watch",
+	]);
+
+	/** Tools after which the watcher has to be re-read from the config. */
+	const WATCH_CONFIG_TOOLS = new Set(["teams_watch", "teams_setup", "teams_accounts"]);
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (!STATUS_TOOLS.has(event.toolName) || event.isError) return;
+
+		if (event.toolName === "teams_logout") {
+			// A watcher polling a session that was just removed only produces
+			// errors; leaving it running would be noise, not service.
+			stopWatch();
+		} else if (WATCH_CONFIG_TOOLS.has(event.toolName)) {
+			startWatch(ctx);
+		}
+
+		paintStatus(ctx);
+	});
 }

package/src/graph/calendar.ts

@@ -143,6 +143,93 @@ export async function cancelEvent(
 	}
 }
 
+/** RSVP responses Graph accepts on an invitation. */
+export type EventResponse = "accept" | "decline" | "tentativelyAccept";
+
+/**
+ * Answer a meeting invitation.
+ *
+ * This is the calendar's equivalent of saying yes out loud: with
+ * `sendResponse` the organizer is notified, which is why the tool asks for
+ * confirmation rather than doing it quietly.
+ */
+export async function respondToEvent(
+	conn: TeamsConnection,
+	eventId: string,
+	response: EventResponse,
+	options: { comment?: string; sendResponse?: boolean; signal?: AbortSignal } = {},
+): Promise<void> {
+	await graphPost(
+		conn,
+		`/me/events/${encodeURIComponent(eventId)}/${response}`,
+		{ comment: options.comment, sendResponse: options.sendResponse !== false },
+		{ signal: options.signal },
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Free / busy
+// ---------------------------------------------------------------------------
+
+/** One person's availability over the requested window. */
+export interface FreeBusyWindow {
+	/** The address Graph matched the schedule to */
+	scheduleId: string;
+	/**
+	 * One character per slot, starting at the window start:
+	 * `0` free, `1` tentative, `2` busy, `3` out of office, `4` working elsewhere.
+	 */
+	availabilityView: string;
+	/** Everything that was not free, with subject omitted on purpose */
+	busy: Array<{ status: string; start: string; end: string }>;
+}
+
+/**
+ * Free/busy for several people in one call.
+ *
+ * `getSchedule` is what a delegated token may read about another person's
+ * calendar — free/busy, not the appointments — and it is the reason
+ * availability works without the `.Shared` scopes that `findMeetingTimes`
+ * insists on. Subjects are reported by Graph but dropped here: knowing that
+ * somebody is busy is the point, knowing why is their business.
+ */
+export async function getSchedule(
+	conn: TeamsConnection,
+	input: {
+		schedules: string[];
+		start: string;
+		end: string;
+		timeZone: string;
+		/** Slot width in minutes; Graph allows 5–1440 */
+		intervalMinutes?: number;
+		signal?: AbortSignal;
+	},
+): Promise<FreeBusyWindow[]> {
+	const raw = await graphPost<Raw>(conn, "/me/calendar/getSchedule", {
+		schedules: input.schedules,
+		startTime: { dateTime: input.start, timeZone: input.timeZone },
+		endTime: { dateTime: input.end, timeZone: input.timeZone },
+		availabilityViewInterval: Math.min(Math.max(input.intervalMinutes ?? 30, 5), 1440),
+	}, {
+		signal: input.signal,
+		// Without this the busy blocks come back in UTC while the view is indexed
+		// in the requested zone, and the two would not line up.
+		headers: { Prefer: `outlook.timezone="${input.timeZone}"` },
+	});
+
+	return (raw?.value ?? []).map((entry: Raw) => ({
+		scheduleId: entry.scheduleId ?? "",
+		availabilityView: entry.availabilityView ?? "",
+		busy: (entry.scheduleItems ?? [])
+			.filter((item: Raw) => item.status && item.status !== "free")
+			.map((item: Raw) => ({
+				status: item.status,
+				start: item.start?.dateTime ?? "",
+				end: item.end?.dateTime ?? "",
+			})),
+	}));
+}
+
 /** Ad-hoc meeting link with no calendar entry. */
 export async function createOnlineMeeting(
 	conn: TeamsConnection,

package/src/graph/chats.ts

@@ -3,10 +3,10 @@
  */
 
 import type { TeamsConnection } from "../config/index.ts";
-import type { ChatSummary, PersonRef } from "../types.ts";
-import { graphGetOptional, graphList, graphPost } from "./client.ts";
+import type { ChatMemberSummary, ChatSummary, PersonRef } from "../types.ts";
+import { graphDelete, graphGetOptional, graphList, graphPost } from "./client.ts";
 import { GraphError } from "../utils/errors.ts";
-import { mapChat } from "./mappers.ts";
+import { mapChat, mapChatMember } from "./mappers.ts";
 import { resolveUserId } from "./me.ts";
 
 /**
@@ -140,6 +140,137 @@ export async function createChat(
 	return mapChat((raw ?? {}) as Record<string, never>);
 }
 
+// ---------------------------------------------------------------------------
+// Read state
+// ---------------------------------------------------------------------------
+
+/**
+ * Endpoint and body for the two read-cursor actions.
+ *
+ * Graph takes the user in the **body**, not in the URL: the delegated token
+ * says who is allowed to act, the body says whose read state changes. Kept as
+ * a pure function (like `deletePath`) because this is the part worth testing.
+ */
+export function readStateRequest(
+	chatId: string,
+	user: { id: string; tenantId?: string },
+	read: boolean,
+): { path: string; body: Record<string, unknown> } {
+	return {
+		path: `/chats/${encodeURIComponent(chatId)}/${
+			read ? "markChatReadForUser" : "markChatUnreadForUser"
+		}`,
+		// `tenantId` may be undefined; JSON.stringify drops it, and Graph accepts
+		// the id alone.
+		body: { user: { id: user.id, tenantId: user.tenantId } },
+	};
+}
+
+/**
+ * Mark a chat as read — or unread again — for the signed-in user.
+ *
+ * This is the only read-state a delegated token may move, and it moves the
+ * same cursor the app moves when you open a chat: it does not touch what
+ * anyone else sees, but read receipts (where the tenant has them on) do make
+ * the chat look seen. Channel messages have no equivalent action.
+ */
+export async function setChatReadState(
+	conn: TeamsConnection,
+	chatId: string,
+	user: { id: string; tenantId?: string },
+	read: boolean,
+	options: { signal?: AbortSignal } = {},
+): Promise<void> {
+	const { path, body } = readStateRequest(chatId, user, read);
+	await graphPost(conn, path, body, { signal: options.signal });
+}
+
+// ---------------------------------------------------------------------------
+// Membership
+// ---------------------------------------------------------------------------
+
+/**
+ * The members of a chat, with the membership id each one is removed by.
+ *
+ * Read raw rather than through `mapChat`, because a `ChatSummary` keeps only
+ * the people (what a label and the scope rules need) and drops the membership
+ * id that removing someone requires.
+ */
+export async function listChatMembers(
+	conn: TeamsConnection,
+	chatId: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<ChatMemberSummary[]> {
+	const raw = await graphList<Record<string, never>>(
+		conn,
+		`/chats/${encodeURIComponent(chatId)}/members`,
+		{ max: 100, signal: options.signal },
+	);
+	return raw.map((entry) => mapChatMember(entry));
+}
+
+/**
+ * Add a person to an existing chat.
+ *
+ * Graph binds the member by user id or UPN; a 1:1 chat cannot be extended (the
+ * Teams client converts it to a group chat, Graph refuses), so callers should
+ * check the chat type first.
+ */
+export async function addChatMember(
+	conn: TeamsConnection,
+	chatId: string,
+	person: PersonRef,
+	options: { signal?: AbortSignal } = {},
+): Promise<void> {
+	const bind = person.id ?? person.upn ?? person.mail;
+	if (!bind) throw new Error(`Cannot add ${person.displayName}: no user id, UPN or e-mail address.`);
+
+	await graphPost(
+		conn,
+		`/chats/${encodeURIComponent(chatId)}/members`,
+		{
+			"@odata.type": "#microsoft.graph.aadUserConversationMember",
+			"user@odata.bind": `https://graph.microsoft.com/v1.0/users/${encodeURIComponent(bind)}`,
+			roles: [],
+		},
+		{ signal: options.signal },
+	);
+}
+
+/** Remove one membership. Graph takes the membership id, not the user id. */
+export async function removeChatMember(
+	conn: TeamsConnection,
+	chatId: string,
+	membershipId: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<void> {
+	await graphDelete(
+		conn,
+		`/chats/${encodeURIComponent(chatId)}/members/${encodeURIComponent(membershipId)}`,
+		{ signal: options.signal },
+	);
+}
+
+/**
+ * Find the membership of one person in a chat.
+ *
+ * Matching goes through the identifiers a caller can actually have: object id,
+ * UPN, e-mail, display name.
+ */
+export function matchChatMember(
+	members: readonly ChatMemberSummary[],
+	reference: string,
+): ChatMemberSummary | undefined {
+	const needle = reference.trim().toLowerCase();
+	if (!needle) return undefined;
+
+	return members.find((member) =>
+		[member.userId, member.upn, member.mail, member.displayName]
+			.filter((value): value is string => !!value)
+			.some((value) => value.toLowerCase() === needle),
+	);
+}
+
 /** Resolve people references (UPN, e-mail, name) to PersonRefs. */
 export async function resolveParticipants(
 	conn: TeamsConnection,

package/src/graph/mappers.ts

@@ -9,6 +9,7 @@
 
 import type {
 	ChannelSummary,
+	ChatMemberSummary,
 	ChatSummary,
 	DriveItemSummary,
 	EventSummary,
@@ -67,6 +68,25 @@ export function mapMember(raw: Raw): MemberSummary {
 	};
 }
 
+/**
+ * A chat member.
+ *
+ * Graph exposes two identifiers per member and they are not interchangeable:
+ * the membership id is what removes someone, the user id is what says who they
+ * are. Keeping both here is cheaper than looking them up again later.
+ */
+export function mapChatMember(raw: Raw): ChatMemberSummary {
+	const user = raw.user ?? raw;
+	return {
+		membershipId: raw.id ?? "",
+		userId: user?.id ?? undefined,
+		displayName: raw.displayName ?? user?.displayName ?? "(unknown)",
+		upn: user?.userPrincipalName ?? raw.userPrincipalName ?? undefined,
+		mail: user?.email ?? raw.email ?? undefined,
+		roles: Array.isArray(raw.roles) ? raw.roles : [],
+	};
+}
+
 /** Identifiers a person can be matched against by the scope rules. */
 export function personCandidates(person: PersonRef | MemberSummary | undefined): (string | undefined)[] {
 	if (!person) return [];