@patimweb/pi-teams 1.0.0 → 1.2.0

package/src/watch/index.ts

@@ -0,0 +1,224 @@
+/**
+ * Listen mode — the pure half.
+ *
+ * "Watching" Teams means answering one question over and over: *is there
+ * anything here that should wake pi up?* That question is decided entirely
+ * from data — the chat list, one message, and what we have already seen — so it
+ * lives here as pure functions. The polling, the Graph calls and the prompt
+ * injection are in ./loop.ts.
+ *
+ * Two things are deliberately not pure: the clock and the fetch. Both are
+ * injected, which is what makes the decision rules testable without a tenant.
+ */
+
+import type { ChatSummary, MessageSummary, PersonRef, SignedInUser } from "../types.ts";
+import type { ResolvedWatchConfig } from "../config/index.ts";
+import { matchesPattern } from "../config/scope.ts";
+import { chatCandidates } from "../graph/mappers.ts";
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+/**
+ * What the watcher remembers between ticks.
+ *
+ * `seen` is keyed by chat and holds the activity marker of the last message we
+ * looked at, so a tick can skip every chat that has not moved. It is a
+ * high-water mark, not a read receipt: nothing here is ever sent to Teams.
+ */
+export interface WatchState {
+	/** chatId → activity marker of the last examined message */
+	seen: Map<string, string>;
+	/** chatId → epoch ms of the last wake in that chat */
+	lastTriggered: Map<string, number>;
+	/** epoch ms of every wake, pruned to the last hour */
+	triggers: number[];
+}
+
+export function createWatchState(): WatchState {
+	return { seen: new Map(), lastTriggered: new Map(), triggers: [] };
+}
+
+/** Marker for "this is the newest state of that chat we have looked at". */
+export function activityMarker(chat: ChatSummary): string {
+	return chat.lastUpdated ?? "";
+}
+
+/** How many wakes happened within the last hour. */
+export function wakesThisHour(state: WatchState, now: number): number {
+	return state.triggers.filter((at) => now - at < 3600_000).length;
+}
+
+/**
+ * Drop bookkeeping that can no longer influence a decision.
+ *
+ * A session can run for days; without this the two maps grow with every chat
+ * the user ever touches. The hour is the longest window any rule looks at.
+ */
+export function pruneState(state: WatchState, now: number): void {
+	state.triggers = state.triggers.filter((at) => now - at < 3600_000);
+	for (const [chatId, at] of state.lastTriggered) {
+		if (now - at > 24 * 3600_000) state.lastTriggered.delete(chatId);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Which chats are worth a look
+// ---------------------------------------------------------------------------
+
+/**
+ * Chats that are both allowed by the watch filter and have moved since we last
+ * looked.
+ *
+ * @param freshnessMs How far back "new" reaches. Enabling listen mode must not
+ *   wake pi for every conversation that happened to be active this morning, so
+ *   anything older than the window is recorded as seen and then ignored.
+ */
+export function chatsToExamine(
+	state: WatchState,
+	chats: ChatSummary[],
+	watch: ResolvedWatchConfig,
+	now: number,
+	freshnessMs: number,
+): ChatSummary[] {
+	const cutoff = now - freshnessMs;
+
+	return chats.filter((chat) => {
+		if (!isWatchedChat(chat, watch)) return false;
+		if (state.seen.get(chat.id) === activityMarker(chat)) return false;
+
+		const updated = chat.lastUpdated ? new Date(chat.lastUpdated).getTime() : 0;
+		// A chat with no activity timestamp cannot be dated, so it is never new.
+		if (!updated || updated < cutoff) return false;
+
+		return true;
+	});
+}
+
+/** Does this chat fall inside the configured chat filter? */
+export function isWatchedChat(chat: ChatSummary, watch: ResolvedWatchConfig): boolean {
+	if (watch.chats.length === 0) return true;
+	const candidates = chatCandidates(chat).filter((value): value is string => !!value);
+	return watch.chats.some((pattern) => candidates.some((candidate) => matchesPattern(pattern, candidate)));
+}
+
+// ---------------------------------------------------------------------------
+// Who pi listens to
+// ---------------------------------------------------------------------------
+
+/**
+ * Does the sender fall inside the configured listen list?
+ *
+ * `chats` says where pi listens, this says to whom — the person filter is what
+ * keeps listen mode from becoming "answer the whole company". Matched against
+ * every identifier the message carries, like the scope rules do.
+ */
+export function isWatchedSender(message: MessageSummary, watch: ResolvedWatchConfig): boolean {
+	if (watch.from.length === 0) return true;
+
+	const sender = message.from;
+	if (!sender) return false;
+
+	const candidates = [sender.displayName, sender.upn, sender.mail, sender.id].filter(
+		(value): value is string => !!value,
+	);
+	return watch.from.some((pattern) => candidates.some((candidate) => matchesPattern(pattern, candidate)));
+}
+
+// ---------------------------------------------------------------------------
+// Whether a message should wake pi
+// ---------------------------------------------------------------------------
+
+export type WakeDecision = { wake: true } | { wake: false; reason: string };
+
+const WAKE: WakeDecision = { wake: true };
+const skip = (reason: string): WakeDecision => ({ wake: false, reason });
+
+/**
+ * Should this message wake pi?
+ *
+ * Ordered so the cheapest and most obvious reason to stay quiet is also the
+ * one that gets reported — a wrong wake costs a model turn, a wrong silence
+ * costs nothing but the reason in the log.
+ */
+export function shouldWake(
+	chat: ChatSummary,
+	message: MessageSummary,
+	me: SignedInUser | undefined,
+	watch: ResolvedWatchConfig,
+	state: WatchState,
+	now: number,
+): WakeDecision {
+	if (message.deletedDateTime) return skip("the message was deleted");
+	if (isFromMe(message.from, me)) return skip("the last message is my own");
+
+	if (!isWatchedChat(chat, watch)) return skip("the chat is outside the configured watch list");
+	if (!isWatchedSender(message, watch)) return skip("the sender is outside the configured listen list");
+	if (watch.mentionOnly && !mentionsMe(message, me)) return skip("the chat is set to mentions only");
+	if (watch.maxTriggersPerHour > 0 && wakesThisHour(state, now) >= watch.maxTriggersPerHour) {
+		return skip("the hourly wake limit is reached");
+	}
+
+	const last = state.lastTriggered.get(chat.id);
+	if (last !== undefined && now - last < watch.cooldownSeconds * 1000) {
+		return skip("this chat is inside its cooldown");
+	}
+
+	return WAKE;
+}
+
+/**
+ * Record that pi was woken for a chat.
+ *
+ * Split from the decision so `shouldWake` stays free of side effects and can be
+ * called speculatively.
+ */
+export function noteWake(state: WatchState, chatId: string, now: number): void {
+	state.lastTriggered.set(chatId, now);
+	state.triggers.push(now);
+}
+
+/**
+ * Was this message sent by the signed-in user?
+ *
+ * pi posts as the user, so its own replies come back as "my own message" on the
+ * next tick — which is what stops the watcher from waking on itself. Matching
+ * on the ID first and the display name second covers both a chat member entry
+ * that carries an ID and one that only carries a name.
+ */
+export function isFromMe(from: PersonRef | undefined, me: SignedInUser | undefined): boolean {
+	if (!from || !me) return false;
+	if (from.id && me.id && from.id === me.id) return true;
+	return !!from.displayName && from.displayName === me.displayName;
+}
+
+/**
+ * Does this message mention the signed-in user?
+ *
+ * Graph fills `mentions` for real @-mentions; the text fallback covers the
+ * common case of someone typing a first name, which is what "mentions only"
+ * means to a person waiting for an answer.
+ */
+export function mentionsMe(message: MessageSummary, me: SignedInUser | undefined): boolean {
+	if (!me) return false;
+
+	const mentioned = message.mentions.some(
+		(person) =>
+			(person.id && person.id === me.id) ||
+			(person.displayName && person.displayName === me.displayName),
+	);
+	if (mentioned) return true;
+
+	const text = message.text ?? "";
+	if (me.displayName && text.includes(`@${me.displayName}`)) return true;
+
+	// First name only: "Patrick, kannst du…". Word-boundary-ish, case-insensitive.
+	const firstName = me.displayName.split(/\s+/)[0];
+	if (!firstName || firstName.length < 3) return false;
+	return new RegExp(`(^|[^\\p{L}])${escapeRegExp(firstName)}($|[^\\p{L}])`, "iu").test(text);
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/watch/loop.ts

@@ -0,0 +1,304 @@
+/**
+ * Listen mode — the loop.
+ *
+ * Polls the signed-in user's chats and reports the ones that should wake pi.
+ * Deliberately knows nothing about pi: it takes a callback, so the decision
+ * rules (./index.ts) and the polling can each be tested on their own, and the
+ * extension stays the only place that touches the session.
+ *
+ * Why polling and not a webhook: Microsoft Graph change notifications for chats
+ * need a publicly reachable HTTPS endpoint plus subscription renewal, which a
+ * laptop on a home network cannot offer. Polling costs one `/me/chats` call per
+ * interval and works everywhere.
+ */
+
+import type { ChatSummary, MessageSummary, SignedInUser } from "../types.ts";
+import type { ResolvedWatchConfig, TeamsConnection } from "../config/index.ts";
+import { listChats } from "../graph/chats.ts";
+import { listChatMessages } from "../graph/messages.ts";
+import { getMe } from "../graph/me.ts";
+import { chatCandidates } from "../graph/mappers.ts";
+import { hasAccess } from "../safety/index.ts";
+import { formatGraphError } from "../utils/errors.ts";
+import {
+	activityMarker,
+	chatsToExamine,
+	createWatchState,
+	noteWake,
+	pruneState,
+	shouldWake,
+	wakesThisHour,
+	type WatchState,
+} from "./index.ts";
+
+// ---------------------------------------------------------------------------
+// Events and status
+// ---------------------------------------------------------------------------
+
+/** One message that deserves a model turn. */
+export interface WatchEvent {
+	chat: ChatSummary;
+	message: MessageSummary;
+	/** Epoch ms the wake was decided */
+	wokeAt: number;
+	/** Who pi is acting as, carried along for the prompt */
+	me?: SignedInUser;
+}
+
+/** What the footer and `teams_watch` report about a running watcher. */
+export interface WatchRuntimeStatus {
+	running: boolean;
+	enabled: boolean;
+	intervalSeconds: number;
+	lastTickAt?: number;
+	lastWakeAt?: number;
+	/** Chat label of the last wake, for the status line */
+	lastWakeChat?: string;
+	lastError?: string;
+	wakesThisHour: number;
+	/** Chats seen so far — a quick sanity signal that the loop is alive */
+	trackedChats: number;
+}
+
+// ---------------------------------------------------------------------------
+// One tick
+// ---------------------------------------------------------------------------
+
+/**
+ * Bound on how many chats one tick examines.
+ *
+ * A chat list can move a lot at once — a Monday morning, a release — and each
+ * examination is a Graph call. The cap keeps a burst from turning into a
+ * thundering herd; whatever is left over is simply picked up next tick.
+ */
+export const MAX_EXAMINATIONS_PER_TICK = 5;
+
+export interface WatchTickDeps {
+	/** Newest chats, most recent activity first */
+	listChats: () => Promise<ChatSummary[]>;
+	/** The most recent messages of one chat, newest first */
+	listMessages: (chatId: string) => Promise<MessageSummary[]>;
+	now: () => number;
+	/**
+	 * Read guard, so the watcher respects the same allow/deny rules as every
+	 * other read. Defaults to allowing everything.
+	 */
+	allowed?: (chat: ChatSummary) => boolean;
+}
+
+export interface WatchTickResult {
+	/** Chats looked at in this tick */
+	examined: number;
+	wakes: WatchEvent[];
+}
+
+/**
+ * Advance the watcher by one tick.
+ *
+ * The first tick is a **baseline**: it records what is currently there and
+ * wakes nobody. Switching listen mode on must not answer the backlog — it means
+ * "from now on", and anything older than the freshness window would be a
+ * surprise to wake for.
+ */
+export async function runWatchTick(
+	deps: WatchTickDeps,
+	state: WatchState,
+	watch: ResolvedWatchConfig,
+	me: SignedInUser | undefined,
+	options: { baseline: boolean },
+): Promise<WatchTickResult> {
+	const now = deps.now();
+	pruneState(state, now);
+
+	const chats = (await deps.listChats()).filter((chat) => deps.allowed?.(chat) ?? true);
+
+	if (options.baseline) {
+		for (const chat of chats) state.seen.set(chat.id, activityMarker(chat));
+		return { examined: 0, wakes: [] };
+	}
+
+	const freshnessMs = Math.max(5 * 60_000, watch.intervalSeconds * 2000);
+	const candidates = chatsToExamine(state, chats, watch, now, freshnessMs).slice(0, MAX_EXAMINATIONS_PER_TICK);
+
+	const wakes: WatchEvent[] = [];
+
+	for (const chat of candidates) {
+		// Mark first: a chat that fails to load must not be retried forever, and
+		// the marker is the chat list's own, so the next tick sees it as moved
+		// only if something new actually arrives.
+		state.seen.set(chat.id, activityMarker(chat));
+
+		let messages: MessageSummary[];
+		try {
+			messages = await deps.listMessages(chat.id);
+		} catch {
+			// A single unreadable chat must not end the tick — the rest of the
+			// list is still worth examining.
+			continue;
+		}
+
+		const message = messages.find((entry) => !entry.deletedDateTime) ?? messages[0];
+		if (!message) continue;
+
+		const decision = shouldWake(chat, message, me, watch, state, now);
+		if (!decision.wake) continue;
+
+		noteWake(state, chat.id, now);
+		wakes.push({ chat, message, wokeAt: now, me });
+	}
+
+	return { examined: candidates.length, wakes };
+}
+
+// ---------------------------------------------------------------------------
+// The loop
+// ---------------------------------------------------------------------------
+
+export interface WatchLoopOptions {
+	connection: TeamsConnection;
+	/** Called once per wake, in arrival order */
+	onWake: (event: WatchEvent) => void;
+	/** Called when a tick fails; the loop keeps running */
+	onError?: (message: string) => void;
+	/** Called after every tick, for the footer */
+	onTick?: (status: WatchRuntimeStatus) => void;
+}
+
+export interface WatchLoop {
+	/** Stop polling. Safe to call twice. */
+	stop(): void;
+	/** A snapshot for the status line and the tool */
+	status(): WatchRuntimeStatus;
+	/** Force a tick now, instead of waiting out the interval */
+	poll(): Promise<void>;
+}
+
+/**
+ * The loop this process is running, if any.
+ *
+ * One session runs one watcher, and the tools that report on listen mode need
+ * to see it. Keeping the slot here — rather than in the extension — means
+ * `teams_watch` can answer with live runtime facts without importing the
+ * extension, which imports the tools.
+ */
+let activeLoop: WatchLoop | undefined;
+
+export function setActiveWatchLoop(loop: WatchLoop | undefined): void {
+	activeLoop = loop;
+}
+
+export function getActiveWatchLoop(): WatchLoop | undefined {
+	return activeLoop;
+}
+
+/** Stop the running watcher, if there is one. */
+export function stopActiveWatchLoop(): void {
+	activeLoop?.stop();
+	activeLoop = undefined;
+}
+
+/**
+ * Start polling for the given connection.
+ *
+ * Each tick is scheduled after the previous one finished rather than on a fixed
+ * timer, so a slow Graph call cannot stack ticks on top of each other.
+ */
+export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
+	const { connection } = options;
+	const watch = connection.watch;
+	const state = createWatchState();
+
+	let stopped = false;
+	let baselineDone = false;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let me: SignedInUser | undefined;
+	let meResolved = false;
+	let failureCount = 0;
+
+	const status: WatchRuntimeStatus = {
+		running: true,
+		enabled: watch.enabled,
+		intervalSeconds: watch.intervalSeconds,
+		wakesThisHour: 0,
+		trackedChats: 0,
+	};
+
+	const schedule = (delayMs: number) => {
+		if (stopped) return;
+		timer = setTimeout(() => void tick(), delayMs);
+		// Do not hold the process open for a poll that can wait.
+		timer.unref?.();
+	};
+
+	async function tick(): Promise<void> {
+		if (stopped) return;
+
+		try {
+			if (!meResolved) {
+				me = await getMe(connection).catch(() => undefined);
+				meResolved = true;
+			}
+
+			const result = await runWatchTick(
+				{
+					listChats: () => listChats(connection, { max: 50, meId: me?.id }),
+					listMessages: (chatId) => listChatMessages(connection, chatId, { max: 1 }),
+					now: () => Date.now(),
+					allowed: (chat) => hasAccess(connection, "read", "chats", chatCandidates(chat)),
+				},
+				state,
+				watch,
+				me,
+				{ baseline: !baselineDone },
+			);
+
+			baselineDone = true;
+			failureCount = 0;
+			status.lastTickAt = Date.now();
+			status.lastError = undefined;
+			status.wakesThisHour = wakesThisHour(state, status.lastTickAt);
+			status.trackedChats = state.seen.size;
+
+			for (const event of result.wakes) {
+				status.lastWakeAt = event.wokeAt;
+				status.lastWakeChat = event.chat.label;
+				status.wakesThisHour = wakesThisHour(state, event.wokeAt);
+				try {
+					options.onWake(event);
+				} catch (err) {
+					options.onError?.(formatGraphError(err));
+				}
+			}
+		} catch (err) {
+			// Transient failures are normal — a sleeping laptop, an expired token,
+			// a throttled tenant. Back off instead of giving up, and report it so
+			// the user is not left wondering why nothing happens.
+			failureCount += 1;
+			status.lastTickAt = Date.now();
+			status.lastError = formatGraphError(err);
+			options.onError?.(status.lastError);
+		}
+
+		options.onTick?.(status);
+		schedule(watch.intervalSeconds * 1000 * Math.min(2 ** failureCount, 10));
+	}
+
+	// The first tick is immediate: it establishes the baseline, and a user who
+	// just switched listen mode should not wait a full interval to see it alive.
+	void tick();
+
+	return {
+		stop() {
+			stopped = true;
+			status.running = false;
+			if (timer) clearTimeout(timer);
+			timer = undefined;
+		},
+		status: () => ({ ...status, wakesThisHour: wakesThisHour(state, Date.now()) }),
+		async poll() {
+			if (timer) clearTimeout(timer);
+			timer = undefined;
+			await tick();
+		},
+	};
+}

package/src/watch/prompt.ts

@@ -0,0 +1,59 @@
+/**
+ * Listen mode — the prompt.
+ *
+ * An incoming Teams message is turned into a prompt, and this is the whole of
+ * that translation. It is a separate module because the wording is the feature:
+ * what pi does with a message it was woken for is decided here, and nothing in
+ * the polling loop should be able to change it.
+ *
+ * Two things the prompt must always carry: the chat ID — so the reply cannot
+ * land in the wrong conversation, since pi posts as a person and a name is not
+ * an identifier — and the instruction that doing nothing is a valid answer.
+ */
+
+import type { MessageSummary, SignedInUser } from "../types.ts";
+import type { WatchEvent } from "./loop.ts";
+
+function senderName(message: MessageSummary): string {
+	return message.from?.displayName ?? message.from?.upn ?? "someone";
+}
+
+/**
+ * The prompt for one wake.
+ *
+ * Written to be read by the model, not by the user: it states the facts, names
+ * the tool to use, and then gets out of the way.
+ */
+export function composeWatchPrompt(event: WatchEvent, me?: SignedInUser): string {
+	const { chat, message } = event;
+	const text = message.text?.trim() ? message.text.trim() : "(no text content — open the chat to see it)";
+	const at = message.createdDateTime ? new Date(message.createdDateTime).toLocaleString() : "just now";
+
+	return [
+		"An incoming Microsoft Teams message arrived while you were idle.",
+		"",
+		`- Chat: ${chat.label} (${chat.chatType})`,
+		`- From: ${senderName(message)}`,
+		`- At: ${at}`,
+		`- Chat ID: ${chat.id}`,
+		"",
+		"Message:",
+		text
+			.split("\n")
+			.map((line) => `> ${line}`)
+			.join("\n"),
+		"",
+		"Decide whether this needs an answer.",
+		"",
+		`- If it does: reply with teams_send_chat_message, passing chat: "${chat.id}". pi posts as ` +
+			`${me?.displayName ?? "me"}, so write in my voice, in the language of the conversation, as briefly as ` +
+			"the message allows. No greeting boilerplate, no signature.",
+		"- If it does not: say so in one line and stop.",
+		"",
+		"Format it for a chat bubble, not a document: the answer first, three short paragraphs at most, " +
+			"bullets for anything enumerable, no tables. The recipient is not expecting this message, so it has " +
+			"to be readable at a glance.",
+		"",
+		"Do not react, do not touch other chats, and do not send anything to a channel.",
+	].join("\n");
+}

package/src/auth/client-credentials.ts

@@ -1,72 +0,0 @@
-/**
- * Client credentials grant — app-only access, no user involved.
- *
- * Useful for unattended jobs (a nightly digest, a scheduled report) against
- * directory and presence data. It is deliberately *not* a way to post as
- * somebody: Microsoft Graph only accepts app-only writes to chats and channels
- * for migration scenarios (`Teamwork.Migrate.All`), so this extension refuses
- * message sends on an app-only token instead of letting them fail deep inside
- * a Graph call. See ../safety/index.ts.
- */
-
-import type { TeamsConnection } from "../config/index.ts";
-import { AuthError, tokenUrl } from "./device-code.ts";
-import type { CachedToken } from "./token-store.ts";
-
-interface TokenResponse {
-	access_token: string;
-	expires_in: number;
-	scope?: string;
-	token_type: string;
-	error?: string;
-	error_description?: string;
-}
-
-/**
- * Acquire an app-only token.
- *
- * @throws {AuthError} when the secret is missing, expired, or the app has no
- * admin-consented application permissions.
- */
-export async function acquireAppToken(
-	conn: TeamsConnection,
-	signal?: AbortSignal,
-): Promise<CachedToken> {
-	if (!conn.clientSecret) {
-		throw new AuthError(
-			"missing_client_secret",
-			`Account "${conn.account}" uses client-credentials but no clientSecret is configured.`,
-		);
-	}
-
-	const body = new URLSearchParams({
-		grant_type: "client_credentials",
-		client_id: conn.clientId,
-		client_secret: conn.clientSecret,
-		scope: conn.scopes.length === 1 ? conn.scopes[0]! : "https://graph.microsoft.com/.default",
-	});
-
-	const response = await fetch(tokenUrl(conn.authorityHost, conn.tenantId), {
-		method: "POST",
-		headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		body: body.toString(),
-		signal,
-	});
-
-	const json = (await response.json()) as TokenResponse;
-
-	if (!response.ok || !json.access_token) {
-		throw new AuthError(
-			json.error ?? `http_${response.status}`,
-			json.error_description ?? `Client credentials request failed with HTTP ${response.status}`,
-		);
-	}
-
-	return {
-		accessToken: json.access_token,
-		expiresAt: Date.now() + Math.max(0, json.expires_in - 60) * 1000,
-		scopes: json.scope ? json.scope.split(" ") : [],
-		authMode: "client-credentials",
-		updatedAt: new Date().toISOString(),
-	};
-}