@patimweb/pi-teams 1.7.2 → 1.8.0

package/README.md

@@ -51,9 +51,16 @@ into a prompt it answers — as you, in the chat it arrived in.
 /teams-listen off
 ```
 
+Listen mode never starts on its own. It belongs to the session it was switched
+on in and ends with it: quitting pi closes the watcher, and `/new` or `/resume`
+stops it too. A stored `enabled: true` is a setting, not an instruction — set
+`watch.autoStart` if a session is meant to start listening by itself, which is
+only sensible for an unattended one.
+
 ```json
 "watch": {
-  "enabled": true,
+  "enabled": false,
+  "autoStart": false,
   "intervalSeconds": 60,
   "chats": ["Anna*", "Vertrieb*"],
   "from": ["anna.schmidt@contoso.com"],
@@ -65,7 +72,8 @@ into a prompt it answers — as you, in the chat it arrived in.
 
 | Key | Default | Meaning |
 |-----|---------|---------|
-| `enabled` | `false` | whether the watcher runs |
+| `enabled` | `false` | whether listen mode is switched on |
+| `autoStart` | `false` | whether a pi session may start the watcher without being asked |
 | `intervalSeconds` | `60` | seconds between polls (minimum 15) |
 | `chats` | `[]` | **where** pi listens: glob patterns matched against topic, label, chat ID and participant names. Empty means every recent chat. |
 | `from` | `[]` | **who** pi listens to: glob patterns matched against display name, UPN and e-mail. Empty means any sender. |
@@ -603,8 +611,9 @@ teams_send_channel_message:
 
 Both the config and the token cache are written through a private temp file and
 an atomic rename, so an interrupted write cannot truncate them. The watch
-cursor is what makes listen mode survive a restart, and deleting it only costs
-one re-examination of the chats in the list — it is not silently re-answering
+cursor is what keeps listen mode from re-answering what it has already seen, and
+deleting it only costs one re-examination of the chats in the list — it is not
+silently re-answering
 anything, because the decision also asks Teams whether the message is still
 unread. To revoke pi's access entirely, run `teams_logout` with `all: true` and
 remove the app's consent in Entra ID.

package/package.json

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

@@ -99,6 +99,14 @@ export interface TenantConfig {
 export interface WatchConfig {
 	/** Whether the watcher runs at all (default: false) */
 	enabled?: boolean;
+	/**
+	 * Whether a pi session may start the watcher by itself (default: false).
+	 *
+	 * Off means listen mode only ever starts when it is switched on in that
+	 * session. A stored setting is not a decision: an agent that answers in your
+	 * name should not begin doing so because a file says it may.
+	 */
+	autoStart?: boolean;
 	/** Seconds between polls (default: 60, minimum: 15) */
 	intervalSeconds?: number;
 	/**
@@ -126,6 +134,7 @@ export interface WatchConfig {
 /** A watch config after every default and clamp has been applied. */
 export interface ResolvedWatchConfig {
 	enabled: boolean;
+	autoStart: boolean;
 	intervalSeconds: number;
 	chats: string[];
 	from: string[];
@@ -309,6 +318,7 @@ const DEFAULTS = {
  */
 export const WATCH_DEFAULTS: ResolvedWatchConfig = {
 	enabled: false,
+	autoStart: false,
 	intervalSeconds: 60,
 	chats: [],
 	from: [],
@@ -721,6 +731,7 @@ export function resolveWatchConfig(
 
 	return {
 		enabled: pick("enabled") ?? WATCH_DEFAULTS.enabled,
+		autoStart: pick("autoStart") ?? WATCH_DEFAULTS.autoStart,
 		intervalSeconds: clamp(pick("intervalSeconds"), WATCH_BOUNDS.intervalSeconds, WATCH_DEFAULTS.intervalSeconds),
 		chats: normalizePatterns(pick("chats")),
 		from: normalizePatterns(pick("from")),

package/src/extension/index.ts

@@ -16,7 +16,13 @@ import {
 	tryResolveConnection,
 	type TeamsConnection,
 } from "../config/index.ts";
-import { buildConnectionCard, buildConnectionLabel, formatStatusText, type ConnectionCard } from "../status.ts";
+import {
+	buildConnectionCard,
+	buildConnectionLabel,
+	buildStartupNotice,
+	formatStatusText,
+	type ConnectionCard,
+} from "../status.ts";
 import {
 	blockReason,
 	formatMutationSummary,
@@ -167,12 +173,19 @@ export default function (pi: ExtensionAPI) {
 	};
 
 	/**
-	 * Start the watcher for the session's account, if the config asks for it.
+	 * Start the watcher for the session's account — but only when it was asked for.
+	 *
+	 * `explicit` is the whole safety property. Switching listen mode on is a
+	 * decision, so only the two places the user makes it — `/teams-listen on` and
+	 * `teams_watch action: enable` — pass `explicit: true`. Everything else may
+	 * only stop the loop. Without that split, "re-read the config" would be a way
+	 * for a stored setting to switch itself back on, which is precisely how a
+	 * listener nobody started turns up, polling and answering in your name.
 	 *
 	 * Restarting is the same call: the old loop is stopped first, so a config
 	 * change cannot leave two pollers running.
 	 */
-	const startWatch = (ctx: any) => {
+	const startWatch = (ctx: any, options: { explicit?: boolean } = {}) => {
 		const conn = refresh();
 
 		// Already watching this exact configuration: leave the loop alone, so its
@@ -183,6 +196,7 @@ export default function (pi: ExtensionAPI) {
 		stopWatch();
 
 		if (!conn?.watch.enabled) return;
+		if (!options.explicit) return;
 
 		reportedWatchError = undefined;
 		const loop = startWatchLoop({
@@ -317,7 +331,7 @@ export default function (pi: ExtensionAPI) {
 				// Written to the account, not globally: the watcher listens as one
 				// identity, and "which account" must not be a guess.
 				const watch = setWatchConfig({ enabled: action === "on" }, conn.account);
-				startWatch(ctx);
+				startWatch(ctx, { explicit: true });
 				paintStatus(ctx);
 				ctx.ui.notify(
 					watch.enabled
@@ -407,8 +421,12 @@ export default function (pi: ExtensionAPI) {
 		const card = buildConnectionCard(connection);
 		if (!card) return;
 
+		// A stored setting is not a decision. A session starts the watcher only when
+		// the configuration opts into it; otherwise listen mode waits until it is
+		// switched on in this session with `/teams-listen on`.
+		if (connection.watch.autoStart) startWatch(ctx, { explicit: true });
+
 		paintStatus(ctx);
-		startWatch(ctx);
 
 		if (!card.signedIn) {
 			ctx.ui.notify(
@@ -416,10 +434,11 @@ export default function (pi: ExtensionAPI) {
 				"warning",
 			);
 		} else {
-			ctx.ui.notify(
-				`@patimweb/pi-teams loaded (${card.account}${card.user ? ` as ${card.user}` : ""}, safety: ${card.safetyLevel})`,
-				"info",
-			);
+			const notice = buildStartupNotice(card, {
+				listening: !!watchLoop?.status().running,
+				intervalSeconds: connection.watch.intervalSeconds,
+			});
+			ctx.ui.notify(notice.message, notice.level);
 		}
 
 		// Survives /reload, so the transcript keeps saying who pi is acting as.
@@ -535,7 +554,10 @@ export default function (pi: ExtensionAPI) {
 			// errors; leaving it running would be noise, not service.
 			stopWatch();
 		} else if (WATCH_CONFIG_TOOLS.has(event.toolName)) {
-			startWatch(ctx);
+			// Only `enable` is a decision. A status call, or a re-read after
+			// teams_setup, may stop the loop but never start it.
+			const action = (event.input as { action?: string } | undefined)?.action;
+			startWatch(ctx, { explicit: action === "enable" });
 		}
 
 		paintStatus(ctx);

package/src/status.ts

@@ -90,6 +90,34 @@ export function buildConnectionLabel(card: ConnectionCard | undefined): string {
 	return `✓ Teams · ${scope}${card.user ? ` · ${card.user}` : ""}${listening}`;
 }
 
+/**
+ * The line a session starts with.
+ *
+ * It names listen mode on purpose. A session can be listening — polling, and
+ * answering in your name — so the transcript should never be silent about it.
+ *
+ * The level is part of the answer: being listened to is the state worth a louder
+ * notice, not the ordinary one of it being off.
+ */
+export function buildStartupNotice(
+	card: ConnectionCard,
+	watch: { listening: boolean; intervalSeconds: number },
+): { message: string; level: "info" | "warning" } {
+	const identity = `@patimweb/pi-teams loaded (${card.account}${card.user ? ` as ${card.user}` : ""}, safety: ${card.safetyLevel})`;
+
+	// Reported from what is actually running, not from the stored setting: those
+	// two are no longer the same thing, and a notice that reported the file
+	// instead of the loop would be the very confusion it exists to prevent.
+	if (!watch.listening) {
+		return { message: `${identity} · listen mode off — /teams-listen on to start`, level: "info" };
+	}
+
+	return {
+		message: `${identity} · listen mode ON — every ${watch.intervalSeconds} s, /teams-listen off to stop`,
+		level: "warning",
+	};
+}
+
 /** Rich markdown for `/teams-status` and the expanded card. */
 export function formatStatusText(card: ConnectionCard | undefined): string {
 	if (!card) {

package/src/tools/teams-watch.ts

@@ -53,6 +53,7 @@ const CURSOR_NOTES = [
 /** Renders the effective settings the same way the config file would. */
 function describe(watch: {
 	enabled: boolean;
+	autoStart: boolean;
 	intervalSeconds: number;
 	chats: string[];
 	from: string[];
@@ -62,6 +63,7 @@ function describe(watch: {
 }): string {
 	return [
 		`- enabled: ${watch.enabled}`,
+		`- starts with a session: ${watch.autoStart}`,
 		`- 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"}`,
@@ -82,8 +84,9 @@ function runtimeLines(runtime: WatchRuntimeStatus | undefined, conn: TeamsConnec
 		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.",
+			"Listen mode starts only when it is switched on here — `/teams-listen on`, or "
+				+ "`teams_watch action: enable`. A stored `enabled: true` does not start it by itself: "
+				+ "set `watch.autoStart` if a session is meant to start listening on its own.",
 		];
 	}