@patimweb/pi-teams 1.1.0 → 1.2.0

package/src/tools/teams-watch.ts

@@ -0,0 +1,229 @@
+/**
+ * teams_watch — switch listen mode on and off, and report what it is doing.
+ *
+ * The actual polling lives in the extension, because only it can inject a
+ * message into the session and update the status line. This tool owns the
+ * configuration and the explanation; the extension restarts the loop when the
+ * config changes.
+ */
+
+import { Type } from "typebox";
+import {
+	getConfigPath,
+	resolveConnection,
+	setWatchConfig,
+	type WatchConfig,
+} from "../config/index.ts";
+import { getActiveWatchLoop, type WatchRuntimeStatus } from "../watch/loop.ts";
+import { errorResult, run, textResult, type ToolContext, type ToolResult } from "./shared.ts";
+
+interface WatchParams {
+	action?: string;
+	account?: string;
+	tenant?: string;
+	intervalSeconds?: number;
+	chats?: string[];
+	from?: string[];
+	mentionOnly?: boolean;
+	cooldownSeconds?: number;
+	maxTriggersPerHour?: number;
+}
+
+/** Renders the effective settings the same way the config file would. */
+function describe(watch: {
+	enabled: boolean;
+	intervalSeconds: number;
+	chats: string[];
+	from: string[];
+	mentionOnly: boolean;
+	cooldownSeconds: number;
+	maxTriggersPerHour: number;
+}): string {
+	return [
+		`- enabled: ${watch.enabled}`,
+		`- poll every: ${watch.intervalSeconds} s`,
+		`- chats: ${watch.chats.length > 0 ? watch.chats.map((c) => `\`${c}\``).join(", ") : "every chat with recent activity"}`,
+		`- people: ${watch.from.length > 0 ? watch.from.map((p) => `\`${p}\``).join(", ") : "any sender"}`,
+		`- mentions only: ${watch.mentionOnly}`,
+		`- cooldown per chat: ${watch.cooldownSeconds} s`,
+		`- wake limit: ${watch.maxTriggersPerHour} per hour`,
+	].join("\n");
+}
+
+/**
+ * The live facts about a running watcher, for the status action.
+ *
+ * Distinguishes "configured on" from "actually polling": after an edit to the
+ * config file the two can differ until the extension picks it up.
+ */
+function runtimeLines(runtime: WatchRuntimeStatus | undefined): string[] {
+	if (!runtime) {
+		return [
+			"Nothing is polling in this session.",
+			"",
+			"Listen mode is read when a pi session starts. If the config says `enabled: true` and this "
+				+ "says otherwise, start a new session — or switch it with the `/teams-listen` command.",
+		];
+	}
+
+	const lines = [
+		"### Running in this session",
+		"",
+		`- running: ${runtime.running}`,
+		`- chats tracked: ${runtime.trackedChats}`,
+		`- woken this hour: ${runtime.wakesThisHour}`,
+	];
+	if (runtime.lastTickAt) {
+		lines.push(`- last poll: ${new Date(runtime.lastTickAt).toLocaleTimeString()}`);
+	}
+	if (runtime.lastWakeChat) {
+		lines.push(`- last wake: ${runtime.lastWakeChat}`);
+	}
+	if (runtime.lastError) {
+		lines.push(`- ⚠️ last error: ${runtime.lastError}`);
+	}
+	return lines;
+}
+
+export const teamsWatchTool = {
+	name: "teams_watch",
+	description:
+		"Control listen mode: pi polls your Teams chats and turns an incoming message into a prompt it answers. " +
+		"Use action 'status' to see the current settings, 'enable' or 'disable' to switch it, and the optional " +
+		"fields to narrow what may wake pi (chat patterns, mentions only, interval, cooldown, hourly limit). " +
+		"The watcher runs in the extension session; this tool changes the configuration it reads.",
+	parameters: Type.Object({
+		action: Type.Optional(
+			Type.String({ description: "'status' (default), 'enable' or 'disable'" }),
+		),
+		account: Type.Optional(
+			Type.String({ description: "Account the settings apply to; omit to set them globally" }),
+		),
+		tenant: Type.Optional(
+			Type.String({
+				description:
+					"Tenant beneath that account. Used by action 'status' to report the settings in force for it — listen mode itself is configured per account, not per tenant.",
+			}),
+		),
+		intervalSeconds: Type.Optional(
+			Type.Number({ description: "Seconds between polls (minimum 15, default 60)" }),
+		),
+		chats: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"Glob patterns for the chats to watch — matched against topic, label, chat ID and participant names",
+			}),
+		),
+		from: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"Glob patterns for the people pi listens to — matched against display name, UPN and e-mail. Omit for any sender.",
+			}),
+		),
+		mentionOnly: Type.Optional(
+			Type.Boolean({ description: "Only wake pi where the signed-in user is mentioned" }),
+		),
+		cooldownSeconds: Type.Optional(
+			Type.Number({ description: "Seconds to stay quiet in a chat after waking pi for it (default 300)" }),
+		),
+		maxTriggersPerHour: Type.Optional(
+			Type.Number({ description: "Hard cap on wakes per hour (default 10)" }),
+		),
+	}),
+	promptSnippet: "Turn Teams listen mode on or off",
+	promptGuidelines: [
+		"Use teams_watch when the user wants pi to notice incoming Teams messages on its own.",
+		"Tell the user plainly that listen mode spends a model turn per incoming message, and that pi answers in their name.",
+		"Enabling listen mode takes effect immediately; the settings survive a restart.",
+	],
+
+	async execute(
+		_toolCallId: string,
+		params: WatchParams,
+		_signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		_ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const action = (params.action ?? "status").toLowerCase();
+
+			// Reported from the resolved connection, so the answer shows what is in
+			// force for that account and tenant — not just what the file says.
+			const inspect = () => {
+				try {
+					return resolveConnection(params.account, params.tenant).watch;
+				} catch {
+					return undefined;
+				}
+			};
+
+			const patch: WatchConfig = {};
+			if (params.intervalSeconds !== undefined) patch.intervalSeconds = params.intervalSeconds;
+			if (params.chats !== undefined) patch.chats = params.chats;
+		if (params.from !== undefined) patch.from = params.from;
+			if (params.mentionOnly !== undefined) patch.mentionOnly = params.mentionOnly;
+			if (params.cooldownSeconds !== undefined) patch.cooldownSeconds = params.cooldownSeconds;
+			if (params.maxTriggersPerHour !== undefined) {
+				patch.maxTriggersPerHour = params.maxTriggersPerHour;
+			}
+
+			switch (action) {
+				case "status": {
+					const watch = inspect();
+					if (!watch) {
+						return errorResult(
+							`No usable Teams account for these settings. Check ${getConfigPath()}.`,
+						);
+					}
+					const loop = getActiveWatchLoop();
+					const runtime = loop?.status();
+					return textResult(
+						[
+							`## Listen mode — ${watch.enabled ? "on" : "off"}`,
+							"",
+							describe(watch),
+							"",
+							...runtimeLines(runtime),
+						].join("\n"),
+						{ watch, runtime },
+					);
+				}
+
+				case "enable": {
+					const watch = setWatchConfig({ ...patch, enabled: true }, params.account);
+					return textResult(
+						[
+							"## Listen mode — on",
+							"",
+							describe(watch),
+							"",
+							"pi now polls these chats and treats a new message as a prompt. It answers in your name " +
+								"and under the safety level in force, so anything it decides to send still follows the " +
+								"usual confirmation rules.",
+							"",
+							`Written to ${getConfigPath()}.`,
+						].join("\n"),
+						{ watch },
+					);
+				}
+
+				case "disable": {
+					const watch = setWatchConfig({ ...patch, enabled: false }, params.account);
+					return textResult(
+						[
+							"## Listen mode — off",
+							"",
+							describe(watch),
+							"",
+							"Polling stops now; the settings stay in the file for the next time.",
+						].join("\n"),
+						{ watch },
+					);
+				}
+
+				default:
+					return errorResult(`Unknown action "${action}". Use 'status', 'enable' or 'disable'.`);
+			}
+		});
+	},
+};

package/src/tools/tool-names.ts

@@ -27,4 +27,5 @@ export const MUTATION_TOOLS = new Set<string>([
 	// Local configuration and credentials
 	"teams_setup",
 	"teams_logout",
+	"teams_watch",
 ]);

package/src/utils/formatting.ts

@@ -82,18 +82,6 @@ export function htmlToText(content: string, contentType = "html"): string {
 		.trim();
 }
 
-/** Convert plain text to the minimal HTML Teams expects for a message body. */
-export function textToHtml(text: string): string {
-	const escaped = text
-		.replace(/&/g, "&")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;");
-	return escaped
-		.split(/\n{2,}/)
-		.map((para) => `<p>${para.replace(/\n/g, "<br>")}</p>`)
-		.join("");
-}
-
 // ---------------------------------------------------------------------------
 // Dates
 // ---------------------------------------------------------------------------

package/src/utils/richtext.ts

@@ -0,0 +1,150 @@
+/**
+ * Markdown-ish text → the HTML subset Microsoft Teams renders in a message.
+ *
+ * Why this exists: a message body is HTML, but the model writes markdown. Sent
+ * raw, `**wichtig**` arrives as literal asterisks and `- Punkt` as literal
+ * dashes — which is exactly the "wall of text" a person sees in a chat when
+ * nothing was formatted for the medium.
+ *
+ * Teams supports far less HTML than a browser. This translates only what
+ * survives in a chat bubble:
+ *
+ *   `**bold**` → `<b>`            `- item` → `<ul><li>`
+ *   `*italic*` / `_italic_` → `<i>`   `1. item` → `<ol><li>`
+ *   `` `code` `` → `<code>`        ``` fences → `<pre>`
+ *   `~~struck~~` → `<s>`          `# Heading` → a bold line
+ *   `[label](url)` → `<a href>`
+ *
+ * Tables and images are deliberately unsupported: Teams renders neither in a
+ * chat, so pretending otherwise would produce worse output than plain text.
+ * Everything else is escaped and kept as written.
+ */
+
+const HTML_ESCAPES: Record<string, string> = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+};
+
+function escapeHtml(text: string): string {
+	return text.replace(/[&<>]/g, (char) => HTML_ESCAPES[char] ?? char);
+}
+
+/**
+ * Inline markup of a single line.
+ *
+ * Order matters: code spans are protected first (so `**` inside them stays
+ * literal), then links, then emphasis. The underscore rule requires a boundary
+ * on both sides so `snake_case_name` survives untouched.
+ */
+function inline(raw: string): string {
+	let text = escapeHtml(raw);
+
+	text = text.replace(/`([^`]+)`/g, "<code>$1</code>");
+	text = text.replace(
+		/\[([^\]]+)\]\((https?:\/\/[^\s)]+|mailto:[^\s)]+)\)/g,
+		'<a href="$2">$1</a>',
+	);
+	text = text.replace(/\*\*([^*]+)\*\*/g, "<b>$1</b>");
+	text = text.replace(/(^|[^*\w])\*([^*\n]+)\*/g, "$1<i>$2</i>");
+	text = text.replace(/(^|[\s(])_([^_\n]+)_(?=$|[\s).,;:!?])/g, "$1<i>$2</i>");
+	text = text.replace(/~~([^~]+)~~/g, "<s>$1</s>");
+
+	return text;
+}
+
+const BULLET = /^\s*[-*+]\s+(.*)$/;
+const NUMBERED = /^\s*\d+[.)]\s+(.*)$/;
+const HEADING = /^\s{0,3}#{1,6}\s+(.*)$/;
+
+/**
+ * Convert a message body to Teams HTML.
+ *
+ * Blank lines separate paragraphs, single newlines become `<br>` inside one —
+ * which is what a person typing into the chat box gets, and the safest
+ * assumption for text that was generated, not composed.
+ */
+export function markdownToTeamsHtml(text: string): string {
+	const lines = text.replace(/\r\n?/g, "\n").split("\n");
+	const blocks: string[] = [];
+
+	let paragraph: string[] = [];
+	let list: { ordered: boolean; items: string[] } | undefined;
+	let code: string[] | undefined;
+
+	const flushParagraph = () => {
+		if (paragraph.length === 0) return;
+		blocks.push(`<p>${paragraph.map(inline).join("<br>")}</p>`);
+		paragraph = [];
+	};
+
+	const flushList = () => {
+		if (!list) return;
+		const tag = list.ordered ? "ol" : "ul";
+		const items = list.items.map((item) => `<li>${inline(item)}</li>`).join("");
+		blocks.push(`<${tag}>${items}</${tag}>`);
+		list = undefined;
+	};
+
+	const flushBlock = () => {
+		flushParagraph();
+		flushList();
+	};
+
+	for (const line of lines) {
+		// A fence swallows everything until the next one, verbatim.
+		if (/^\s*```/.test(line)) {
+			if (code) {
+				blocks.push(`<pre>${escapeHtml(code.join("\n"))}</pre>`);
+				code = undefined;
+			} else {
+				flushBlock();
+				code = [];
+			}
+			continue;
+		}
+		if (code) {
+			code.push(line);
+			continue;
+		}
+
+		if (line.trim() === "") {
+			flushBlock();
+			continue;
+		}
+
+		const heading = HEADING.exec(line);
+		if (heading) {
+			flushBlock();
+			blocks.push(`<p><b>${inline(heading[1])}</b></p>`);
+			continue;
+		}
+
+		const bullet = BULLET.exec(line);
+		if (bullet) {
+			flushParagraph();
+			if (list && list.ordered) flushList();
+			list ??= { ordered: false, items: [] };
+			list.items.push(bullet[1]);
+			continue;
+		}
+
+		const numbered = NUMBERED.exec(line);
+		if (numbered) {
+			flushParagraph();
+			if (list && !list.ordered) flushList();
+			list ??= { ordered: true, items: [] };
+			list.items.push(numbered[1]);
+			continue;
+		}
+
+		flushList();
+		paragraph.push(line);
+	}
+
+	// An unterminated fence is still code, not lost text.
+	if (code) blocks.push(`<pre>${escapeHtml(code.join("\n"))}</pre>`);
+	flushBlock();
+
+	return blocks.join("");
+}

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, "\\$&");
+}