@patimweb/pi-teams 1.3.1 → 1.4.0

package/src/tools/teams-update-message.ts

@@ -14,6 +14,7 @@
 import { Type } from "typebox";
 import { updateMessage } from "../graph/messages.ts";
 import { auditWrite } from "../safety/audit.ts";
+import { applyAiFooter } from "../utils/disclosure.ts";
 import { requireChat } from "./resolve.ts";
 import {
 	AccountParam,
@@ -65,8 +66,12 @@ export const teamsUpdateMessageTool = {
 			const me = await currentUser(conn, signal);
 			const chat = await requireChat(conn, params.chat, "write", signal);
 
+			// An edit replaces the whole body, so the disclosure has to survive it —
+			// idempotently, so a body that already ends with it is not doubled.
+			const body = applyAiFooter(params.body, conn.aiFooter, { html: params.html });
+
 			await updateMessage(conn, chat.id, params.messageId, me.id, {
-				body: params.body,
+				body,
 				html: params.html,
 			}, { signal });
 
@@ -76,7 +81,7 @@ export const teamsUpdateMessageTool = {
 				tenant: conn.tenant,
 				actor: me.upn,
 				target: `chat:${chat.label}`,
-				summary: `edited message ${params.messageId}: ${params.body.slice(0, 120)}`,
+				summary: `edited message ${params.messageId}: ${body.slice(0, 120)}`,
 			});
 
 			return textResult(`✅ Message ${params.messageId} edited in "${chat.label}".`, {

package/src/tools/teams-watch.ts

@@ -12,9 +12,11 @@ import {
 	getConfigPath,
 	resolveConnection,
 	setWatchConfig,
+	type TeamsConnection,
 	type WatchConfig,
 } from "../config/index.ts";
 import { getActiveWatchLoop, type WatchRuntimeStatus } from "../watch/loop.ts";
+import { getWatchCursorPath } from "../watch/cursor.ts";
 import { errorResult, run, textResult, type ToolContext, type ToolResult } from "./shared.ts";
 
 interface WatchParams {
@@ -29,6 +31,24 @@ interface WatchParams {
 	maxTriggersPerHour?: number;
 }
 
+/**
+ * What the cursor means, in the status output.
+ *
+ * The single most surprising thing about listen mode is what happens when it is
+ * switched on again, so the answer is part of the status rather than only in
+ * the docs.
+ */
+const CURSOR_NOTES = [
+	"### What wakes pi",
+	"",
+	"A chat wakes pi when both are true: it has moved since pi last looked (a cursor per account, kept "
+		+ "on disk), and its newest message is still unread for you in Teams. Switching listen mode back "
+		+ "on therefore answers what you missed, and a chat you have already read in Teams stays quiet.",
+	"",
+	"A backlog is drained over several ticks and capped by the hourly wake limit, so a long absence does "
+		+ "not produce a burst of answers.",
+].join("\n");
+
 /** Renders the effective settings the same way the config file would. */
 function describe(watch: {
 	enabled: boolean;
@@ -56,7 +76,7 @@ function describe(watch: {
  * 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[] {
+function runtimeLines(runtime: WatchRuntimeStatus | undefined, conn: TeamsConnection): string[] {
 	if (!runtime) {
 		return [
 			"Nothing is polling in this session.",
@@ -79,9 +99,15 @@ function runtimeLines(runtime: WatchRuntimeStatus | undefined): string[] {
 	if (runtime.lastWakeChat) {
 		lines.push(`- last wake: ${runtime.lastWakeChat}`);
 	}
+	if (runtime.catchUp !== undefined) {
+		const read = runtime.catchUpRead ? `, ${runtime.catchUpRead} of them already read` : "";
+		lines.push(`- catch-up on start: ${runtime.catchUp} chat(s) had moved${read}`);
+	}
 	if (runtime.lastError) {
 		lines.push(`- ⚠️ last error: ${runtime.lastError}`);
 	}
+
+	lines.push(`- cursor: \`${getWatchCursorPath(conn.account, conn.tenantId)}\``);
 	return lines;
 }
 
@@ -89,6 +115,9 @@ 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. " +
+		"A chat wakes it when it has moved since pi last looked, so switching listen mode on also answers " +
+		"what arrived while pi was not running; only the very first run on an account records history " +
+		"without answering it. " +
 		"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.",
@@ -135,6 +164,7 @@ export const teamsWatchTool = {
 		"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.",
+		"Enabling listen mode answers what arrived since the last run, so say how much is waiting rather than implying only new messages count.",
 	],
 
 	async execute(
@@ -149,9 +179,9 @@ export const teamsWatchTool = {
 
 			// 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 = () => {
+			const inspect = (): TeamsConnection | undefined => {
 				try {
-					return resolveConnection(params.account, params.tenant).watch;
+					return resolveConnection(params.account, params.tenant);
 				} catch {
 					return undefined;
 				}
@@ -169,12 +199,13 @@ export const teamsWatchTool = {
 
 			switch (action) {
 				case "status": {
-					const watch = inspect();
-					if (!watch) {
+					const conn = inspect();
+					if (!conn) {
 						return errorResult(
 							`No usable Teams account for these settings. Check ${getConfigPath()}.`,
 						);
 					}
+					const watch = conn.watch;
 					const loop = getActiveWatchLoop();
 					const runtime = loop?.status();
 					return textResult(
@@ -183,7 +214,9 @@ export const teamsWatchTool = {
 							"",
 							describe(watch),
 							"",
-							...runtimeLines(runtime),
+							...runtimeLines(runtime, conn),
+							"",
+							...CURSOR_NOTES,
 						].join("\n"),
 						{ watch, runtime },
 					);
@@ -197,9 +230,10 @@ export const teamsWatchTool = {
 							"",
 							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.",
+							"pi now polls these chats and treats anything that has moved since its last look as a prompt — " +
+								"including what arrived while it was not running, so the first tick may answer several messages. " +
+								"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"),

package/src/utils/disclosure.ts

@@ -0,0 +1,55 @@
+/**
+ * The AI disclosure footer.
+ *
+ * When `aiFooter` is on, every message pi sends in the user's name ends with a
+ * note saying so. It is applied here rather than asked for in a prompt because
+ * a disclosure that depends on the model remembering is not a disclosure: this
+ * is the one piece of an outgoing message that must not be negotiable.
+ *
+ * Two properties matter more than the wording:
+ *
+ *  - **Idempotent.** The same body run through this twice carries one footer,
+ *    so an edit of an already-footered message does not stack them — and a
+ *    model that copied the footer from the chat it is answering does not
+ *    produce two.
+ *  - **Body-shaped.** The body may be markdown or raw HTML depending on the
+ *    tool call, and the footer has to arrive as text in both. HTML output
+ *    escapes it and wraps it in its own paragraph.
+ */
+
+import type { ResolvedAiFooter } from "../config/index.ts";
+
+/**
+ * Append the disclosure, or return the body untouched.
+ *
+ * A disabled footer, an empty body, and a body that already ends with the note
+ * all come back unchanged — the caller never has to ask whether it should.
+ */
+export function applyAiFooter(
+	body: string,
+	footer: ResolvedAiFooter | undefined,
+	options: { html?: boolean } = {},
+): string {
+	if (!footer?.enabled) return body;
+
+	const text = footer.text.trim();
+	// An empty message is refused before it is sent, and a disclosure on its own
+	// is not a message.
+	if (!text || !body.trim()) return body;
+	if (hasAiFooter(body, text)) return body;
+
+	const trimmed = body.trimEnd();
+	return options.html
+		? `${trimmed}\n<p>${escapeHtml(text)}</p>`
+		: `${trimmed}\n\n${text}`;
+}
+
+/** Does this body already carry the disclosure? */
+export function hasAiFooter(body: string, text: string): boolean {
+	const trimmed = body.trimEnd();
+	return trimmed.endsWith(text) || trimmed.endsWith(`<p>${escapeHtml(text)}</p>`);
+}
+
+function escapeHtml(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/src/watch/cursor.ts

@@ -0,0 +1,112 @@
+/**
+ * Listen mode — the durable cursor.
+ *
+ * The watcher's memory of what it has already answered used to die with the
+ * session, which made "switch listen mode on" mean "from now on": whatever
+ * arrived while pi was not running was silently dropped. The Telegram bridge
+ * solves the same problem with the Bot API's `offset` cursor — Telegram
+ * re-delivers every update that has not been acknowledged yet, and the bridge
+ * persists that offset, so a restart answers exactly the messages that came in
+ * while it was down, and never the same one twice.
+ *
+ * Graph has no such cursor for chats, so this module keeps one: `chatId → the
+ * activity marker of the newest message pi has already looked at`. A chat has
+ * moved (and is therefore worth answering) when its current marker differs from
+ * the stored one. Written after every tick, so a crash costs nothing but the
+ * tick it died in.
+ *
+ * One file per account **and** tenant, next to the token cache: two accounts in
+ * one process must not share a cursor, and neither must a guest tenant beneath
+ * the same account.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "../config/index.ts";
+
+/** Shape of the file on disk. Kept small — it is read on every session start. */
+interface WatchCursorFile {
+	version: 1;
+	/** ISO timestamp of the last write, for humans reading the file */
+	updatedAt: string;
+	/** chatId → activity marker of the newest message already examined */
+	chats: Record<string, string>;
+}
+
+export function getWatchCursorDir(): string {
+	return join(getAgentDir(), "pi-teams-watch");
+}
+
+/**
+ * Path of one account+tenant cursor.
+ *
+ * Sanitised the same way the token cache is, so a hand-written account name
+ * cannot escape the directory.
+ */
+export function getWatchCursorPath(account: string, tenantId: string): string {
+	const clean = (value: string) => value.toLowerCase().replace(/[^a-z0-9._-]/g, "_");
+	return join(getWatchCursorDir(), `${clean(account)}__${clean(tenantId)}.json`);
+}
+
+/**
+ * The cursor for an account+tenant, or `undefined` when there is none yet.
+ *
+ * `undefined` is meaningful, not just "missing": it means listen mode has never
+ * run for this account, which is the one case where history is deliberately
+ * skipped instead of answered. A corrupt file is reported the same way — the
+ * alternative is a watcher that refuses to start — and the next tick writes a
+ * fresh one.
+ */
+export function readWatchCursor(account: string, tenantId: string): Map<string, string> | undefined {
+	const path = getWatchCursorPath(account, tenantId);
+	if (!existsSync(path)) return undefined;
+
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<WatchCursorFile>;
+		const chats = parsed?.chats;
+		if (parsed?.version !== 1 || !chats || typeof chats !== "object") return undefined;
+
+		return new Map(
+			Object.entries(chats).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+		);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Persist the cursor. Never throws.
+ *
+ * Written to a temporary file and renamed, so a crash mid-write leaves the
+ * previous cursor intact rather than a half-file that would be read as
+ * "no cursor" and replay a whole history.
+ */
+export function writeWatchCursor(
+	account: string,
+	tenantId: string,
+	chats: ReadonlyMap<string, string>,
+): void {
+	const path = getWatchCursorPath(account, tenantId);
+	const file: WatchCursorFile = {
+		version: 1,
+		updatedAt: new Date().toISOString(),
+		chats: Object.fromEntries(chats),
+	};
+
+	try {
+		const dir = getWatchCursorDir();
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+		const tmpPath = `${path}.${process.pid}.tmp`;
+		writeFileSync(tmpPath, `${JSON.stringify(file)}\n`, { encoding: "utf-8", mode: 0o600 });
+		chmodSync(tmpPath, 0o600);
+		renameSync(tmpPath, path);
+	} catch {
+		/* A cursor that cannot be written costs a repeated examination, not an operation. */
+		try {
+			unlinkSync(`${path}.${process.pid}.tmp`);
+		} catch {
+			/* ignore */
+		}
+	}
+}

package/src/watch/index.ts

@@ -9,6 +9,12 @@
  *
  * 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.
+ *
+ * `seen` is the durable cursor (see ./cursor.ts): a chat whose marker differs
+ * from the stored one has moved since pi last looked, and `isUnread` then says
+ * whether the user has already opened it in Teams. That pair is what makes
+ * switching listen mode back on answer exactly the messages that are still open
+ * — including the ones that arrived while pi was not running.
  */
 
 import type { ChatSummary, MessageSummary, PersonRef, SignedInUser } from "../types.ts";
@@ -24,20 +30,56 @@ import { chatCandidates } from "../graph/mappers.ts";
  * 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.
+ * looked at, so a tick can skip every chat that has not moved. It survives the
+ * session on disk, which is what turns "new since the last poll" into "new
+ * since pi last looked". 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 */
+	/** chatId → activity marker of the last examined message, restored from disk */
 	seen: Map<string, string>;
+	/**
+	 * chatId → how often examining it has failed in a row.
+	 *
+	 * The cursor is written before the chat is examined, which is what keeps a
+	 * broken chat from being retried forever — but on its own it would also turn
+	 * a token renewal or a throttle into a message that is never answered. So a
+	 * failure un-marks the chat again, up to MAX_CHAT_ATTEMPTS.
+	 */
+	attempts: Map<string, number>;
 	/** 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: [] };
+/**
+ * How often one chat may fail before pi stops trying and moves on.
+ *
+ * Three is enough to ride out a token renewal and a throttling window, and few
+ * enough that a chat Graph will never serve does not occupy a batch slot on
+ * every tick.
+ */
+export const MAX_CHAT_ATTEMPTS = 3;
+
+/**
+ * @param seen The persisted cursor, when this account has been watched before.
+ *   Omitted means the very first run, which is the only run that skips history.
+ */
+export function createWatchState(seen?: Iterable<[string, string]>): WatchState {
+	return { seen: new Map(seen), attempts: new Map(), lastTriggered: new Map(), triggers: [] };
+}
+
+/** Record a failed examination; true while the chat is still worth retrying. */
+export function noteFailure(state: WatchState, chatId: string): boolean {
+	const attempts = (state.attempts.get(chatId) ?? 0) + 1;
+	state.attempts.set(chatId, attempts);
+	return attempts < MAX_CHAT_ATTEMPTS;
+}
+
+/** Forget the failure count of a chat that was examined successfully. */
+export function noteSuccess(state: WatchState, chatId: string): void {
+	state.attempts.delete(chatId);
 }
 
 /** Marker for "this is the newest state of that chat we have looked at". */
@@ -45,6 +87,15 @@ export function activityMarker(chat: ChatSummary): string {
 	return chat.lastUpdated ?? "";
 }
 
+/**
+ * Upper bound on cursor entries.
+ *
+ * A user can accumulate chats for years, and the file is read on every session
+ * start; a thousand is two orders of magnitude more than the window the watcher
+ * polls, so the bound is only ever felt by chats that are long out of sight.
+ */
+const MAX_CURSOR_ENTRIES = 1000;
+
 /** 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;
@@ -53,14 +104,31 @@ export function wakesThisHour(state: WatchState, now: number): number {
 /**
  * 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.
+ * A session can run for days; without this the 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);
 	}
+
+	// The cursor is pruned by size, never by age. Dropping the entry of a chat
+	// that has simply been quiet for a long time would make it a candidate again
+	// and answer an old message; the count bound only ever touches chats far
+	// outside the window the chat list is read in.
+	if (state.seen.size > MAX_CURSOR_ENTRIES) {
+		const byMarker = [...state.seen.entries()].sort((a, b) => (b[1] ?? "").localeCompare(a[1] ?? ""));
+		state.seen = new Map(byMarker.slice(0, MAX_CURSOR_ENTRIES));
+	}
+
+	// Counters are bounded by size rather than by the cursor: a chat that keeps
+	// failing is deliberately *not* in the cursor, and its counter is what stops
+	// it from being retried forever.
+	if (state.attempts.size > MAX_CURSOR_ENTRIES) {
+		const overflow = state.attempts.size - MAX_CURSOR_ENTRIES;
+		for (const chatId of [...state.attempts.keys()].slice(0, overflow)) state.attempts.delete(chatId);
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -71,28 +139,26 @@ export function pruneState(state: WatchState, now: number): void {
  * 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.
+ * Two questions are asked in sequence and they are deliberately different:
+ * "has this chat moved since pi last examined it?" is this function, and "does
+ * the user still need to see it?" is `isUnread`, which needs one Graph call per
+ * chat and therefore lives in the loop. Age is part of neither: a message that
+ * is still unread is still open, whether it arrived a minute or a week ago.
  */
 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;
+		const marker = activityMarker(chat);
+		// A chat the chat list cannot date has nothing to compare, so it is never
+		// "new" — and never marked, which costs no Graph call at all.
+		if (!marker) return false;
 
-		return true;
+		return state.seen.get(chat.id) !== marker;
 	});
 }
 
@@ -135,6 +201,28 @@ export type WakeDecision = { wake: true } | { wake: false; reason: string };
 const WAKE: WakeDecision = { wake: true };
 const skip = (reason: string): WakeDecision => ({ wake: false, reason });
 
+/**
+ * Is the newest message in this chat still unread for the user?
+ *
+ * This is the Teams read cursor talking, not pi's own memory: a message the
+ * user already opened in Teams does not need an answer from pi, and a message
+ * that is still unread does — even if it arrived days ago while pi was not
+ * running. Graph withholds the read time for some chat shapes, and a chat we
+ * cannot date is not "new" at all; both fall back to answering, because a read
+ * state we cannot read must not silently switch listen mode off.
+ */
+export function isUnread(chat: ChatSummary, lastMessageReadAt?: string): boolean {
+	const marker = activityMarker(chat);
+	if (!marker) return false;
+	if (!lastMessageReadAt) return true;
+
+	const read = new Date(lastMessageReadAt).getTime();
+	const moved = new Date(marker).getTime();
+	if (!Number.isFinite(read) || !Number.isFinite(moved)) return true;
+
+	return read < moved;
+}
+
 /**
  * Should this message wake pi?
  *