@patimweb/pi-teams 1.5.0 → 1.5.1

package/README.md

@@ -87,7 +87,10 @@ What it does, and what it deliberately does not:
   message is still unread for you in Teams. So switching listen mode back on
   answers what you missed while pi was not running — and a chat you already read
   in Teams stays quiet. A backlog is drained a few chats per tick and capped by
-  `maxTriggersPerHour`, so a long absence does not produce a burst.
+  `maxTriggersPerHour`, so a long absence does not produce a burst. A chat held
+  back by its `cooldownSeconds`, or by that hourly cap, is *delayed, never
+  dropped*: it keeps its place in line and is answered as soon as the wait is
+  over. `teams_watch action: status` shows how many are waiting right now.
 - **Never wakes for its own messages.** pi posts as you, so its own reply comes
   back as "my own message" and stops the loop.
 - **Respects the read rules.** A chat excluded by `permissions.read.chats` is
@@ -652,7 +655,8 @@ network connection.
 | "Blocked by configuration" | Your own scope rules. `teams_permissions action: test` shows which rule |
 | "cannot run on an app-only token" | Set `authMode: "interactive"` and run `teams_login` |
 | 403 reading channel messages | `ChannelMessage.Read.All` needs **admin** consent — see "Who has to approve what" |
-| Listen mode does nothing | `teams_watch action: status` says whether it is enabled and running. Only messages arriving *after* it was switched on wake pi |
+| Listen mode does nothing | `teams_watch action: status` says whether it is enabled and running, how many chats it tracks, and where the cursor lives. A chat you have already read in Teams stays quiet by design, and one held back by its cooldown or the hourly cap shows up as *waiting* |
+| Listen mode never answers one specific chat | `waiting` in `teams_watch action: status` says whether it is sitting out a `cooldownSeconds` window; chats it has already decided about are in the cursor under `~/.pi/agent/pi-teams-watch/` |
 | Listen mode answers too much | Narrow `watch.chats` and `watch.from`, raise `cooldownSeconds`, lower `maxTriggersPerHour` |
 | Listen mode stopped by itself | `teams_watch action: status` shows the last polling error; a revoked session or a sleeping laptop is the usual cause, and it resumes on its own |
 | Throttled | Graph rate limit; the client retries with back-off, then reports it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Microsoft Teams integration for pi coding agent — acts fully as the signed-in user across multiple accounts and tenants: chats, channels, meetings, presence, with configurable guardrails",
   "keywords": [
     "pi-package",

package/src/status.ts

@@ -81,7 +81,12 @@ export function buildConnectionLabel(card: ConnectionCard | undefined): string {
 	if (!card.signedIn) return `Teams · ${card.account} · not signed in`;
 
 	const scope = card.tenant === card.account ? card.account : `${card.account}/${card.tenant}`;
-	const listening = card.watching ? " · 👂 listening" : "";
+	// A monochrome mark, not an emoji: the rest of the label is drawn in the
+	// terminal's own font (the ✓ included), and a colour glyph next to it looks
+	// like a different interface. ◉ reads as "live", which is what the label is
+	// saying — and it survives a terminal without emoji fonts, where 👂 would
+	// come out as tofu.
+	const listening = card.watching ? " · ◉ listening" : "";
 	return `✓ Teams · ${scope}${card.user ? ` · ${card.user}` : ""}${listening}`;
 }
 

package/src/tools/teams-send-chat-message.ts

@@ -5,10 +5,19 @@
  * from the user typing it. Hence the order of operations — resolve the chat,
  * check the chat rules, check every participant against the people rules,
  * resolve the mentions, send, then record the audit entry.
+ *
+ * The last step is the read cursor. Sending from Graph does not move it — only
+ * the user opening the chat, or teams_mark_read, does — so without this a chat
+ * pi has just answered keeps its unread marker in Teams, which is the one thing
+ * that looks like nobody dealt with it. Replying is reading, so the message
+ * would arrive with the chat still bold; the mark is best effort and comes last,
+ * because a send that went out must not be reported as failed.
  */
 
 import { Type } from "typebox";
+import { setChatReadState } from "../graph/chats.ts";
 import { sendChatMessage } from "../graph/messages.ts";
+import { formatGraphError } from "../utils/errors.ts";
 import { resolveUserId } from "../graph/me.ts";
 import { auditWrite } from "../safety/audit.ts";
 import { assertAccess } from "../safety/index.ts";
@@ -135,6 +144,18 @@ export const teamsSendChatMessageTool = {
 					summary: truncate(body, 200),
 				});
 
+				// Replying is reading: clear the unread marker the answer was written for.
+				// Deliberately after the audit entry, so the message that went out is
+				// recorded even when the read-mark cannot be moved.
+				let readNote = "";
+				if (me) {
+					try {
+						await setChatReadState(conn, chat.id, me, true, { signal });
+					} catch (err) {
+						readNote = `\n\n⚠️ The chat could not be marked as read: ${formatGraphError(err)}`;
+					}
+				}
+
 				return textResult(
 					[
 						`✅ Message sent to **${chat.label}** as ${me?.displayName ?? "you"} (${connectionLabel(conn)}).`,
@@ -142,7 +163,7 @@ export const teamsSendChatMessageTool = {
 						`> ${truncate(body, 300)}`,
 						"",
 						`messageId: ${sent.id}`,
-					].join("\n"),
+					].join("\n") + readNote,
 					{ chatId: chat.id, messageId: sent.id },
 				);
 			} catch (err) {

package/src/tools/teams-watch.ts

@@ -46,7 +46,8 @@ const CURSOR_NOTES = [
 		+ "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.",
+		+ "not produce a burst of answers. A chat held back by its cooldown or by that limit is delayed, "
+		+ "never dropped: it stays open and is answered as soon as the wait is over.",
 ].join("\n");
 
 /** Renders the effective settings the same way the config file would. */
@@ -93,6 +94,12 @@ function runtimeLines(runtime: WatchRuntimeStatus | undefined, conn: TeamsConnec
 		`- chats tracked: ${runtime.trackedChats}`,
 		`- woken this hour: ${runtime.wakesThisHour}`,
 	];
+	if (runtime.waiting > 0) {
+		lines.push(
+			`- waiting: ${runtime.waiting} chat(s) — held back by their cooldown or by the wake limit, "
+				+ "and answered once that clears`,
+		);
+	}
 	if (runtime.lastTickAt) {
 		lines.push(`- last poll: ${new Date(runtime.lastTickAt).toLocaleTimeString()}`);
 	}
@@ -115,9 +122,8 @@ 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. " +
+		"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. " +
 		"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.",
@@ -216,7 +222,7 @@ export const teamsWatchTool = {
 							"",
 							...runtimeLines(runtime, conn),
 							"",
-							...CURSOR_NOTES,
+							CURSOR_NOTES,
 						].join("\n"),
 						{ watch, runtime },
 					);

package/src/watch/cursor.ts

@@ -15,6 +15,11 @@
  * the stored one. Written after every tick, so a crash costs nothing but the
  * tick it died in.
  *
+ * What lands here is a *decision*, not a sighting: a chat whose wake was only
+ * postponed — inside its cooldown, or over the hourly limit — is deliberately
+ * kept out of the file (see `noteDeferral` in ./index.ts), because an entry here
+ * means the watcher will never look at that chat again.
+ *
  * 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.

package/src/watch/index.ts

@@ -51,6 +51,20 @@ export interface WatchState {
 	lastTriggered: Map<string, number>;
 	/** epoch ms of every wake, pruned to the last hour */
 	triggers: number[];
+	/**
+	 * chatId → epoch ms before which this chat must not be looked at again.
+	 *
+	 * The counterpart of `seen`, and the whole point of the pair: a chat whose
+	 * decision was only *postponed* — inside its cooldown, or held back by the
+	 * hourly wake limit — is deliberately **not** written to the cursor, because
+	 * the cursor means "pi has looked at this and will not look again". A message
+	 * written down there is a message nobody ever answers.
+	 *
+	 * In memory on purpose: it only saves the Graph calls of re-examining the chat
+	 * every tick until the wait is over, so losing it on a restart costs one extra
+	 * examination — never a message.
+	 */
+	retryAfter: Map<string, number>;
 }
 
 /**
@@ -67,7 +81,42 @@ export const MAX_CHAT_ATTEMPTS = 3;
  *   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: [] };
+	return {
+		seen: new Map(seen),
+		attempts: new Map(),
+		lastTriggered: new Map(),
+		triggers: [],
+		retryAfter: new Map(),
+	};
+}
+
+/**
+ * Record that a chat has been looked at and decided.
+ *
+ * "Decided" is the operative word: only a final decision may write the cursor,
+ * since the cursor is what stops the watcher from ever looking at that chat
+ * again. A postponed chat goes to `noteDeferral` instead.
+ */
+export function settleChat(state: WatchState, chatId: string, marker: string): void {
+	state.seen.set(chatId, marker);
+	state.retryAfter.delete(chatId);
+}
+
+/**
+ * Keep a chat open — and out of the batch — until `until`.
+ *
+ * Not writing the cursor is what keeps the message; this is only the throttle
+ * on how often the chat is re-read while it waits.
+ */
+export function noteDeferral(state: WatchState, chatId: string, until: number): void {
+	state.retryAfter.set(chatId, until);
+}
+
+/** How many chats are waiting out a cooldown or the wake limit right now. */
+export function waitingCount(state: WatchState, now: number): number {
+	let waiting = 0;
+	for (const until of state.retryAfter.values()) if (until > now) waiting += 1;
+	return waiting;
 }
 
 /** Record a failed examination; true while the chat is still worth retrying. */
@@ -122,6 +171,12 @@ export function pruneState(state: WatchState, now: number): void {
 		state.seen = new Map(byMarker.slice(0, MAX_CURSOR_ENTRIES));
 	}
 
+	// Waiting chats expire by themselves — a deferral can never outlive the hour
+	// the wake limit looks at, so there is nothing to bound here.
+	for (const [chatId, until] of state.retryAfter) {
+		if (until <= now) state.retryAfter.delete(chatId);
+	}
+
 	// 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.
@@ -149,6 +204,7 @@ export function chatsToExamine(
 	state: WatchState,
 	chats: ChatSummary[],
 	watch: ResolvedWatchConfig,
+	now: number,
 ): ChatSummary[] {
 	return chats.filter((chat) => {
 		if (!isWatchedChat(chat, watch)) return false;
@@ -158,7 +214,15 @@ export function chatsToExamine(
 		// "new" — and never marked, which costs no Graph call at all.
 		if (!marker) return false;
 
-		return state.seen.get(chat.id) !== marker;
+		if (state.seen.get(chat.id) === marker) return false;
+
+		// Moved, but the decision on it is only postponed: the chat is still open
+		// (it is not in the cursor), but looking at it again right now would only
+		// re-read the same message. Deliberately after the cursor check, and
+		// deliberately out of the batch rather than in it — a chat waiting out its
+		// cooldown must not cost another chat its slot in the tick.
+		const until = state.retryAfter.get(chat.id);
+		return until === undefined || until <= now;
 	});
 }
 
@@ -244,11 +308,39 @@ export function openMessages(
 // Whether a message should wake pi
 // ---------------------------------------------------------------------------
 
-export type WakeDecision = { wake: true } | { wake: false; reason: string };
+export type WakeDecision =
+	| { wake: true }
+	| {
+			wake: false;
+			reason: string;
+			/**
+			 * Set when the skip is only for now: ms to wait before looking again.
+			 * Absent means the decision is final — this message is not for pi.
+			 */
+			retryAfterMs?: number;
+		};
 
 const WAKE: WakeDecision = { wake: true };
+
+/** Final: this message will never be one of pi's. */
 const skip = (reason: string): WakeDecision => ({ wake: false, reason });
 
+/** Only for now: the message stays open and is looked at again after the wait. */
+const defer = (reason: string, retryAfterMs: number): WakeDecision => ({
+	wake: false,
+	reason,
+	retryAfterMs: Math.max(MIN_RETRY_MS, Math.round(retryAfterMs)),
+});
+
+/**
+ * Floor on a retry delay.
+ *
+ * A cooldown that is a second away, or a wake limit about to slide, would
+ * otherwise turn the deferral into "examine this chat again on every tick" —
+ * the point of waiting is to not pay for the same Graph calls until it matters.
+ */
+const MIN_RETRY_MS = 5_000;
+
 /**
  * Is the newest message in this chat still unread for the user?
  *
@@ -275,8 +367,13 @@ export function isUnread(chat: ChatSummary, lastMessageReadAt?: string): boolean
  * 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.
+ * one that gets reported.
+ *
+ * The two kinds of "no" are told apart here, and it matters: a message from
+ * somebody pi does not listen to will never become an answer, while a chat in
+ * its cooldown or a burst over the hourly limit is only waiting. Those two are
+ * returned with a `retryAfterMs`, and the loop uses it to keep the chat open
+ * instead of writing it off in the cursor.
  */
 export function shouldWake(
 	chat: ChatSummary,
@@ -293,17 +390,34 @@ export function shouldWake(
 	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");
+		return defer(
+			"the hourly wake limit is reached",
+			nextWakeSlot(state, now, watch.maxTriggersPerHour) - now,
+		);
 	}
 
 	const last = state.lastTriggered.get(chat.id);
 	if (last !== undefined && now - last < watch.cooldownSeconds * 1000) {
-		return skip("this chat is inside its cooldown");
+		return defer("this chat is inside its cooldown", last + watch.cooldownSeconds * 1000 - now);
 	}
 
 	return WAKE;
 }
 
+/**
+ * When the next wake fits under the hourly limit.
+ *
+ * The limit is a sliding window, not a bucket that empties on the hour, so the
+ * answer is "when the oldest wake of the last hour falls out of it". That is
+ * what keeps a burst — a Monday morning, a release — from silencing a chat for
+ * the rest of the hour.
+ */
+export function nextWakeSlot(state: WatchState, now: number, maxPerHour: number): number {
+	const recent = state.triggers.filter((at) => now - at < 3600_000).sort((a, b) => a - b);
+	if (maxPerHour < 1 || recent.length < maxPerHour) return now;
+	return recent[recent.length - maxPerHour] + 3600_000;
+}
+
 /**
  * Record that pi was woken for a chat.
  *

package/src/watch/loop.ts

@@ -30,12 +30,15 @@ import {
 	chatsToExamine,
 	createWatchState,
 	isUnread,
+	noteDeferral,
 	noteFailure,
 	noteSuccess,
 	noteWake,
 	openMessages,
 	pruneState,
+	settleChat,
 	shouldWake,
+	waitingCount,
 	wakesThisHour,
 	WATCH_MESSAGE_WINDOW,
 	type WatchState,
@@ -78,6 +81,12 @@ export interface WatchRuntimeStatus {
 	wakesThisHour: number;
 	/** Chats seen so far — a quick sanity signal that the loop is alive */
 	trackedChats: number;
+	/**
+	 * Chats still open but held back right now — inside their cooldown, or waiting
+	 * for a slot under the hourly limit. The visible form of "not lost, not yet
+	 * answered": without it, a burst that hits the limit looks like silence.
+	 */
+	waiting: number;
 	/** How many chats had moved when the watcher came up, before the per-tick cap */
 	catchUp?: number;
 	/** Of those, how many the user had already read in Teams */
@@ -132,6 +141,8 @@ export interface WatchTickResult {
 	pending: number;
 	/** Of the examined ones, how many the user had already read */
 	alreadyRead: number;
+	/** Of the examined ones, how many were only postponed */
+	deferred: number;
 	wakes: WatchEvent[];
 }
 
@@ -143,6 +154,12 @@ export interface WatchTickResult {
  * without one every chat is compared against the user's own read state on the
  * very first tick. What keeps that from becoming a flood is the per-tick cap
  * and the hourly wake limit, not a window that quietly drops messages.
+ *
+ * The one rule the whole function hangs on: **the cursor is written only for a
+ * decision that is final.** It is the record of what pi has looked at, so what
+ * lands in it is never looked at again — which is right for a message from
+ * somebody pi does not listen to, and wrong for a message that was merely too
+ * early. Those go to `noteDeferral` instead and keep their place in line.
  */
 export async function runWatchTick(
 	deps: WatchTickDeps,
@@ -155,17 +172,22 @@ export async function runWatchTick(
 
 	const chats = (await deps.listChats()).filter((chat) => deps.allowed?.(chat) ?? true);
 
-	const candidates = chatsToExamine(state, chats, watch);
+	const candidates = chatsToExamine(state, chats, watch, now);
 	const batch = candidates.slice(0, MAX_EXAMINATIONS_PER_TICK);
 
 	const wakes: WatchEvent[] = [];
 	let alreadyRead = 0;
+	let deferred = 0;
 
 	for (const chat of batch) {
-		// Mark first, then undo the mark if this chat cannot be examined: a chat
-		// that fails must not be retried forever, but a token renewal must not turn
-		// into a message nobody ever answers.
-		state.seen.set(chat.id, activityMarker(chat));
+		const marker = activityMarker(chat);
+
+		// A chat that cannot be read must not occupy a batch slot on every tick, and
+		// a token renewal must not turn into a message nobody ever answers: it is
+		// written off only once it has used up its attempts.
+		const failed = () => {
+			if (!noteFailure(state, chat.id)) settleChat(state, chat.id, marker);
+		};
 
 		// The read cursor first: a chat the user has already opened in Teams ends
 		// here, one Graph call in, before the message is even fetched.
@@ -173,12 +195,13 @@ export async function runWatchTick(
 		try {
 			readAt = await deps.readState(chat.id);
 		} catch {
-			if (noteFailure(state, chat.id)) state.seen.delete(chat.id);
+			failed();
 			continue;
 		}
 
 		if (!isUnread(chat, readAt)) {
 			noteSuccess(state, chat.id);
+			settleChat(state, chat.id, marker);
 			alreadyRead += 1;
 			continue;
 		}
@@ -189,19 +212,33 @@ export async function runWatchTick(
 		} catch {
 			// A single unreadable chat must not end the tick — the rest of the
 			// list is still worth examining.
-			if (noteFailure(state, chat.id)) state.seen.delete(chat.id);
+			failed();
 			continue;
 		}
 
 		noteSuccess(state, chat.id);
 
 		const message = messages.find((entry) => !entry.deletedDateTime) ?? messages[0];
-		if (!message) continue;
+		if (!message) {
+			settleChat(state, chat.id, marker);
+			continue;
+		}
 
 		const decision = shouldWake(chat, message, me, watch, state, now);
-		if (!decision.wake) continue;
+		if (!decision.wake) {
+			if (decision.retryAfterMs !== undefined) {
+				// Postponed, not answered and not written off: the chat keeps its
+				// message and waits out the cooldown or the wake limit.
+				noteDeferral(state, chat.id, now + decision.retryAfterMs);
+				deferred += 1;
+			} else {
+				settleChat(state, chat.id, marker);
+			}
+			continue;
+		}
 
 		noteWake(state, chat.id, now);
+		settleChat(state, chat.id, marker);
 
 		// The answer has to cover the whole open thread, not just its newest line:
 		// the trigger message is the reason for the wake, the backlog is the reason
@@ -217,10 +254,10 @@ export async function runWatchTick(
 	}
 
 	// Written even when nothing woke: marking a chat examined is the progress
-	// that must survive a restart.
+	// that must survive a restart. Postponed chats are absent from it on purpose.
 	if (batch.length > 0) deps.persistCursor?.(state.seen);
 
-	return { examined: batch.length, pending: candidates.length, alreadyRead, wakes };
+	return { examined: batch.length, pending: candidates.length, alreadyRead, deferred, wakes };
 }
 
 // ---------------------------------------------------------------------------
@@ -301,6 +338,7 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 		intervalSeconds: watch.intervalSeconds,
 		wakesThisHour: 0,
 		trackedChats: 0,
+		waiting: 0,
 	};
 
 	const schedule = (delayMs: number) => {
@@ -346,6 +384,7 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 			status.lastError = undefined;
 			status.wakesThisHour = wakesThisHour(state, status.lastTickAt);
 			status.trackedChats = state.seen.size;
+			status.waiting = waitingCount(state, status.lastTickAt);
 
 			for (const event of result.wakes) {
 				status.lastWakeAt = event.wokeAt;