@patimweb/pi-teams 1.11.0 → 1.13.0

package/docs/listen-mode.md

@@ -173,3 +173,24 @@ Polling works anywhere.
 whether listen mode is enabled and actually running, how many chats it tracks,
 how many are waiting out a cooldown, when the last poll was, and what the last
 error said. See [troubleshooting.md](troubleshooting.md) for the specific cases.
+
+## Presence while listening
+
+Teams shows a user as **Offline** unless at least one presence session exists
+for them — a running Teams client is one, pi calling Graph is not. Even a
+status set with `teams_set_presence` stays invisible without a session.
+
+While listen mode runs, pi therefore holds its own application presence
+session (`setPresence`, session ID = the app's client ID, `Presence.ReadWrite`)
+and renews it every 5 minutes for 15 minutes at a time. You show as
+**Available**, or as whatever you picked with `teams_set_presence`. When the
+watcher stops, pi clears the session and you drop back to Offline straight away
+(at the latest 15 minutes after pi was killed).
+
+## "Seen" as soon as pi picks a message up
+
+When a message wakes pi, the chat is marked read right away — before the answer
+is written. With read receipts on in the tenant, the sender sees the "seen" eye
+under their message and knows a reply is coming. A real typing indicator
+("…") is not possible: Microsoft Graph has no typing API for user accounts,
+only the Bot Framework has one for bots.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "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/extension/index.ts

@@ -37,6 +37,7 @@ import {
 	type WatchLoop,
 } from "../watch/loop.ts";
 import { composeWatchPrompt } from "../watch/prompt.ts";
+import { setChatReadState } from "../graph/chats.ts";
 import { clearWakeTarget, pinViolation, pinWakeTarget } from "../watch/pin.ts";
 import { readWatchCursor, writeWatchCursor } from "../watch/cursor.ts";
 
@@ -225,6 +226,13 @@ export default function (pi: ExtensionAPI) {
 				// answer the chat that woke pi, and the message it is about to read
 				// was written by somebody else.
 				pinWakeTarget(event.chat.id, event.chat.label);
+				// Mark the chat read the moment pi picks it up: with read receipts on,
+				// the sender sees the "seen" eye right away — the closest thing to a
+				// typing indicator Graph offers (there is no typing API for users).
+				// Fire-and-forget: a failed receipt must not hold up the answer.
+				if (event.me?.id) {
+					void setChatReadState(conn, event.chat.id, event.me, true).catch(() => undefined);
+				}
 				pi.sendUserMessage(composeWatchPrompt(event, event.me), { deliverAs: "followUp" });
 			},
 			onTick: (status) => {

package/src/graph/presence.ts

@@ -1,10 +1,14 @@
 /**
  * Presence — reading who is available and setting the user's own status.
  *
- * Setting presence uses `setUserPreferredPresence`, not `setPresence`: the
- * latter is tied to an application session and gets overwritten by the Teams
- * client within seconds. Preferred presence is what the user themselves sets
- * in the app, so it behaves the way they expect — including the expiry.
+ * What the user picks (`teams_set_presence`) is the *preferred* presence
+ * (`setUserPreferredPresence`) — the same thing as choosing a status in the
+ * Teams app, including the expiry.
+ *
+ * Preferred presence only shows while at least one presence *session* exists
+ * for the user; without one, Teams shows Offline no matter what was picked.
+ * pi opens its own application session (`setPresence`, sessionId = client ID)
+ * while listen mode runs — see ../watch/presence-keeper.ts.
  */
 
 import type { TeamsConnection } from "../config/index.ts";
@@ -114,6 +118,44 @@ export async function setPreferredPresence(
 	await graphPost(conn, "/me/presence/setUserPreferredPresence", body, { signal: options.signal });
 }
 
+/**
+ * Create or refresh pi's own application presence session for a user.
+ *
+ * `sessionId` must be the app's client ID. The session lasts
+ * `expirationDuration` (PT5M … PT4H) and has to be renewed to stay alive.
+ * Uses `/users/{id}` so it works for delegated and app-only tokens alike.
+ */
+export async function setSessionPresence(
+	conn: TeamsConnection,
+	userId: string,
+	availability: "Available" | "Busy" | "Away",
+	options: { expirationDuration?: string; signal?: AbortSignal } = {},
+): Promise<void> {
+	const body: Record<string, unknown> = {
+		sessionId: conn.clientId,
+		availability,
+		activity: availability,
+	};
+	if (options.expirationDuration) body.expirationDuration = options.expirationDuration;
+	await graphPost(conn, `/users/${encodeURIComponent(userId)}/presence/setPresence`, body, {
+		signal: options.signal,
+	});
+}
+
+/** End pi's application presence session right away. */
+export async function clearSessionPresence(
+	conn: TeamsConnection,
+	userId: string,
+	signal?: AbortSignal,
+): Promise<void> {
+	await graphPost(
+		conn,
+		`/users/${encodeURIComponent(userId)}/presence/clearPresence`,
+		{ sessionId: conn.clientId },
+		{ signal },
+	);
+}
+
 /** Hand presence back to Teams' automatic calculation. */
 export async function clearPreferredPresence(
 	conn: TeamsConnection,

package/src/utils/chat-style.ts

@@ -37,7 +37,9 @@ export const CHAT_MESSAGE_BODY_DESCRIPTION =
 	"Message text as lightweight markdown, in chat shape: the answer on the first line, then at most 5 short " +
 	"lines, `- ` bullets for anything enumerable, one idea per line. No greeting, no closing, no summary. " +
 	"Rendered: **bold**, *italic*, `code`, ~~struck~~, [label](url), `- ` bullets, `1. ` numbered, ``` fences. " +
-	"A `#` heading arrives as a bold line; tables are not rendered at all.";
+	"A `#` heading arrives as a bold line; tables are not rendered at all. Longer posts the user asked for " +
+	"(digest, summary, list of news): an intro line, a blank line, then one `- ` bullet per item, a blank line " +
+	"before any closing note.";
 
 /**
  * The same shape as one guideline bullet.
@@ -50,7 +52,8 @@ export const CHAT_MESSAGE_BODY_DESCRIPTION =
 export const CHAT_SHAPE_GUIDELINE =
 	"teams_send_chat_message, teams_send_channel_message, teams_reply_channel_message and teams_update_message " +
 	"write chat shape, not a document: the answer on the first line, at most 5 short lines, `- ` bullets for " +
-	"enumerable items, no greeting, no closing summary, no tables.";
+	"enumerable items, no greeting, no closing summary, no tables; a longer post (digest) is one `- ` bullet per " +
+	"item with blank lines between intro, list and closing note.";
 
 /**
  * The shape as prose, for the listen-mode prompt.

package/src/utils/richtext.ts

@@ -63,6 +63,11 @@ const HEADING = /^\s{0,3}#{1,6}\s+(.*)$/;
  * 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.
+ *
+ * Teams renders `<p>` (and lists) in a chat bubble with no margin at all, so
+ * `<p>a</p><p>b</p>` looks exactly like `a<br>b` — every blank line the model
+ * wrote disappears and a digest arrives as one block. The Teams client itself
+ * writes an empty paragraph for a blank line, so blocks are joined with one.
  */
 export function markdownToTeamsHtml(text: string): string {
 	const lines = text.replace(/\r\n?/g, "\n").split("\n");
@@ -146,5 +151,8 @@ export function markdownToTeamsHtml(text: string): string {
 	if (code) blocks.push(`<pre>${escapeHtml(code.join("\n"))}</pre>`);
 	flushBlock();
 
-	return blocks.join("");
+	return blocks.join(BLOCK_SPACER);
 }
+
+/** What the Teams client writes for an empty line between two blocks. */
+export const BLOCK_SPACER = "<p>&nbsp;</p>";

package/src/watch/loop.ts

@@ -25,6 +25,7 @@ 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 { presenceKeeperFor, type PresenceKeeper } from "./presence-keeper.ts";
 import {
 	activityMarker,
 	chatsToExamine,
@@ -298,6 +299,11 @@ export interface WatchLoopOptions {
 	onError?: (message: string) => void;
 	/** Called after every tick, for the footer */
 	onTick?: (status: WatchRuntimeStatus) => void;
+	/**
+	 * Holds the user's Teams presence online while the watcher runs.
+	 * Defaults to a Graph-backed keeper; pass `null` to leave presence alone.
+	 */
+	presence?: PresenceKeeper | null;
 }
 
 export interface WatchLoop {
@@ -365,6 +371,10 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 	 */
 	let me: SignedInUser | undefined;
 	let failureCount = 0;
+	const presence =
+		options.presence === undefined
+			? presenceKeeperFor(connection, options.onError)
+			: options.presence ?? undefined;
 
 	const status: WatchRuntimeStatus = {
 		running: true,
@@ -393,6 +403,9 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 					throw new WatchIdentityError(err);
 				}
 			}
+			// Teams shows Offline without a presence session; pi holds one while
+			// it listens (see ./presence-keeper.ts).
+			if (me.id && !stopped) presence?.start(me.id);
 
 			const result = await runWatchTick(
 				{
@@ -475,6 +488,7 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 			status.running = false;
 			if (timer) clearTimeout(timer);
 			timer = undefined;
+			void presence?.stop();
 		},
 		status: () => ({ ...status, wakesThisHour: wakesThisHour(state, Date.now()) }),
 		async poll() {

package/src/watch/presence-keeper.ts

@@ -0,0 +1,100 @@
+/**
+ * Listen mode — keeping the user online while pi listens.
+ *
+ * Teams shows a user as Offline unless at least one *presence session* exists
+ * for them. A running Teams client is such a session; pi talking to Graph is
+ * not. Even a preferred presence set with `setUserPreferredPresence` only takes
+ * effect "when at least one presence session exists for the user. Otherwise, the
+ * user's presence shows as Offline" (Microsoft Graph docs). A user who only
+ * works through pi therefore always looked Offline, including while pi was
+ * answering their chats.
+ *
+ * While listen mode runs, pi now holds its own application presence session
+ * (`setPresence`, sessionId = the app's client ID) and renews it before it
+ * expires. When the watcher stops, the session is cleared so the user drops to
+ * Offline right away instead of lingering as Available. A preferred presence
+ * the user picked (`teams_set_presence`, e.g. DoNotDisturb) still wins over the
+ * session — which is the point: it now actually shows.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import { clearSessionPresence, setSessionPresence } from "../graph/presence.ts";
+import { formatGraphError } from "../utils/errors.ts";
+
+/** How long each session write lasts. Graph accepts PT5M … PT4H. */
+export const PRESENCE_SESSION_MINUTES = 15;
+/** Renew well before expiry so one slow or failed call does not drop the user. */
+export const PRESENCE_RENEW_MINUTES = 5;
+
+export interface PresenceKeeperDeps {
+	set: (userId: string, expirationDuration: string) => Promise<void>;
+	clear: (userId: string) => Promise<void>;
+	onError?: (message: string) => void;
+}
+
+export interface PresenceKeeper {
+	/** Start (or keep) holding the session for this user. Idempotent. */
+	start(userId: string): void;
+	/** Stop renewing and clear the session. Safe to call twice. */
+	stop(): Promise<void>;
+	/** Whether a renewal timer is running */
+	readonly active: boolean;
+}
+
+export function createPresenceKeeper(deps: PresenceKeeperDeps): PresenceKeeper {
+	let userId: string | undefined;
+	let timer: ReturnType<typeof setInterval> | undefined;
+	/** Report a failure once, not every renewal, until a renewal succeeds again. */
+	let failing = false;
+	const duration = `PT${PRESENCE_SESSION_MINUTES}M`;
+
+	const renew = async () => {
+		if (!userId) return;
+		try {
+			await deps.set(userId, duration);
+			failing = false;
+		} catch (err) {
+			if (!failing) deps.onError?.(`Could not keep Teams presence online: ${formatGraphError(err)}`);
+			failing = true;
+		}
+	};
+
+	return {
+		start(id: string) {
+			if (timer && userId === id) return;
+			if (timer) clearInterval(timer);
+			userId = id;
+			void renew();
+			timer = setInterval(() => void renew(), PRESENCE_RENEW_MINUTES * 60_000);
+			timer.unref?.();
+		},
+		async stop() {
+			if (timer) clearInterval(timer);
+			timer = undefined;
+			const id = userId;
+			userId = undefined;
+			if (!id) return;
+			try {
+				await deps.clear(id);
+			} catch {
+				/* the session expires on its own within PRESENCE_SESSION_MINUTES */
+			}
+		},
+		get active() {
+			return timer !== undefined;
+		},
+	};
+}
+
+/** The keeper wired to Graph for one connection. */
+export function presenceKeeperFor(
+	conn: TeamsConnection,
+	onError?: (message: string) => void,
+): PresenceKeeper {
+	return createPresenceKeeper({
+		set: (userId, expirationDuration) =>
+			setSessionPresence(conn, userId, "Available", { expirationDuration }),
+		clear: (userId) => clearSessionPresence(conn, userId),
+		onError,
+	});
+}