@patimweb/pi-teams 1.9.1 → 1.10.0

package/docs/listen-mode.md

@@ -15,8 +15,11 @@ understanding before switching on.
 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
-`autoStart` if a session is meant to start listening by itself, which is only
-sensible for an unattended one.
+`autoStart` if a session is meant to start listening by itself. Only a session
+with a UI does: a pi started headless by another pi loads the same extensions
+and the same configuration, and a watcher there would answer chats inside a
+throwaway process and move the shared cursor past messages the real session
+never sees.
 
 ## Settings
 
@@ -27,7 +30,11 @@ sensible for an unattended one.
   "intervalSeconds": 60,
   "chats": ["Anna*", "Vertrieb*"],
   "from": ["anna.schmidt@contoso.com"],
-  "mentionOnly": false,
+  "mentionOnly": {
+    "default": true,
+    "chats": { "*Holodeck*": true },
+    "people": { "anna.schmidt@contoso.com": false }
+  },
   "cooldownSeconds": 300,
   "maxTriggersPerHour": 10
 }
@@ -36,11 +43,11 @@ sensible for an unattended one.
 | Key | Default | Meaning |
 |-----|---------|---------|
 | `enabled` | `false` | whether listen mode is switched on |
-| `autoStart` | `false` | whether a pi session may start the watcher without being asked |
+| `autoStart` | `false` | whether a session with a UI 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. |
-| `mentionOnly` | `false` | only wake where you are mentioned |
+| `mentionOnly` | `false` | whether a message has to address you: `true`/`false`, or `{ default, chats, people }` for overrides. See [below](#who-has-to-address-pi). |
 | `cooldownSeconds` | `300` | stay quiet in a chat after waking pi for it |
 | `maxTriggersPerHour` | `10` | hard cap on wakes per hour |
 
@@ -48,6 +55,51 @@ Set it globally, or per account — the account level wins field by field.
 `teams_watch` writes the same keys; `/teams-listen` writes to the session's
 account.
 
+### Who has to address pi
+
+`mentionOnly` answers one question: does a message have to name you before it
+may wake pi? It is easy to get wrong in both directions — too strict and pi goes
+silent in chats that wanted an answer, too loose and it answers conversations it
+was never part of.
+
+A message counts as an address when it **@-mentions you** (or names you in the
+text: `Patrick, kannst du…`), or when it arrives in a **1:1 chat**. A chat with
+one other person is addressed to you by definition — there is nobody else it
+could be meant for — so demanding a mention there would only buy silence. Group
+and meeting chats have no such shortcut.
+
+The switch takes a boolean for "everywhere", or an object when one answer is not
+enough:
+
+```json
+"mentionOnly": {
+  "default": true,
+  "chats": { "*Holodeck*": true, "chat-1": false },
+  "people": { "anna.schmidt@contoso.com": false, "bernd@contoso.com": true }
+}
+```
+
+Rules are matched like the scope rules — chats against topic, label, chat ID and
+participants, people against display name, UPN, e-mail and id — and the **first**
+matching pattern wins, so put the specific rule above the general one. Both
+values are settable, which is what makes the switch usable: a global `true` with
+one person set to `false` means everyone has to address you except that person.
+
+The order, most specific first:
+
+1. a `chats` rule for this conversation,
+2. the 1:1 exemption,
+3. a `people` rule for the sender,
+4. `default`.
+
+The 1:1 exemption sits **above** the people rules deliberately: it is about the
+conversation rather than about somebody in it, so a rule meant for group chats
+cannot silence the direct messages that need no ceremony. To require a mention
+in a 1:1, name that chat in `chats`.
+
+An account that sets `mentionOnly` replaces the whole switch, exactly as it
+does for `chats` and `from` — the object does not merge with the global one.
+
 ## How a wake is decided
 
 A chat wakes pi when two things are true:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.9.1",
+  "version": "1.10.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/skills/teams-collaboration/SKILL.md

@@ -365,13 +365,21 @@ teams_watch:
   action: enable
   chats: ["Anna*", "Vertrieb*"]     # where to listen
   from: ["anna.schmidt@contoso.com"] # who to listen to
-  mentionOnly: false
+  mentionOnly:
+    default: true
+    people: {"anna.schmidt@contoso.com": false}
   intervalSeconds: 60
 ```
 
 - `chats` decides **where** pi listens (topic, label, chat ID, participants),
   `from` decides **to whom** (name, UPN, e-mail). Narrow both: a watcher that
   watches everything answers everything.
+- `mentionOnly` decides whether a message has to address the user at all: a
+  boolean for everywhere, or `{ default, chats, people }` for overrides, matched
+  first-pattern-wins. A message in a **1:1 chat** counts as an address, so the
+  overrides are about group and meeting chats — the usual shape is a global
+  `true` with one person set to `false`, so that person never has to mention the
+  user.
 - `/teams-listen on|off|status` switches it in the session; `teams_watch
   action: status` reports what is configured and what is actually running.
 - pi answers what is still **unread**: a chat wakes it when it has moved since

package/src/config/index.ts

@@ -123,14 +123,62 @@ export interface WatchConfig {
 	 * listens, `from` decides *to whom*.
 	 */
 	from?: string[];
-	/** Only wake pi where the signed-in user is mentioned (default: false) */
-	mentionOnly?: boolean;
+	/**
+	 * Whether a message has to address pi before it wakes it.
+	 *
+	 * A plain `true`/`false` is the all-or-nothing form and needs no further
+	 * explanation; the object form adds per-scope overrides. See
+	 * `MentionOnlyConfig`.
+	 */
+	mentionOnly?: boolean | MentionOnlyConfig;
 	/** Seconds to stay quiet in a chat after waking pi for it (default: 300) */
 	cooldownSeconds?: number;
 	/** Hard cap on wakes per hour, across all chats (default: 10) */
 	maxTriggersPerHour?: number;
 }
 
+/**
+ * Where a mention is required, and where it is not.
+ *
+ * `mentionOnly: true` on its own is all-or-nothing: in a group or a meeting
+ * chat nobody has to say the user's name, and everyone must. This is the same
+ * switch with per-scope overrides, and a rule may turn the requirement **off**
+ * as well as on.
+ *
+ * One-to-one chats need no override — a direct message is an address — so a
+ * person rule is about that person in the chats that have other people in them.
+ * `mentionRequired` holds the exact order the rules are applied in.
+ *
+ * Patterns are matched like every other scope rule: chats against topic,
+ * label, chat ID and participant names; people against display name, UPN,
+ * e-mail and id. The **first** matching entry wins, so write the specific rule
+ * above the general one.
+ */
+export interface MentionOnlyConfig {
+	/** Baseline when no override matches (default: false) */
+	default?: boolean;
+	/** `{ "pattern": true|false }` — whether a mention is required in that chat */
+	chats?: Record<string, boolean>;
+	/** `{ "pattern": true|false }` — whether that person has to mention pi */
+	people?: Record<string, boolean>;
+}
+
+/** One resolved mention-only rule. Order is preserved: first match wins. */
+export interface MentionOnlyRule {
+	pattern: string;
+	value: boolean;
+}
+
+/** The mention-only switch after resolution. */
+export interface ResolvedMentionOnly {
+	/** Used when neither a chat nor a person rule matches */
+	default: boolean;
+	/** Per-chat overrides, in config order */
+	chats: MentionOnlyRule[];
+	/** Per-person overrides, in config order */
+	people: MentionOnlyRule[];
+}
+
 /** A watch config after every default and clamp has been applied. */
 export interface ResolvedWatchConfig {
 	enabled: boolean;
@@ -138,7 +186,7 @@ export interface ResolvedWatchConfig {
 	intervalSeconds: number;
 	chats: string[];
 	from: string[];
-	mentionOnly: boolean;
+	mentionOnly: ResolvedMentionOnly;
 	cooldownSeconds: number;
 	maxTriggersPerHour: number;
 }
@@ -333,7 +381,7 @@ export const WATCH_DEFAULTS: ResolvedWatchConfig = {
 	intervalSeconds: 60,
 	chats: [],
 	from: [],
-	mentionOnly: false,
+	mentionOnly: { default: false, chats: [], people: [] },
 	cooldownSeconds: 300,
 	maxTriggersPerHour: 10,
 };
@@ -747,7 +795,7 @@ export function resolveWatchConfig(
 		intervalSeconds: clamp(pick("intervalSeconds"), WATCH_BOUNDS.intervalSeconds, WATCH_DEFAULTS.intervalSeconds),
 		chats: normalizePatterns(pick("chats")),
 		from: normalizePatterns(pick("from")),
-		mentionOnly: pick("mentionOnly") ?? WATCH_DEFAULTS.mentionOnly,
+		mentionOnly: resolveMentionOnly(pick("mentionOnly")),
 		cooldownSeconds: clamp(pick("cooldownSeconds"), WATCH_BOUNDS.cooldownSeconds, WATCH_DEFAULTS.cooldownSeconds),
 		maxTriggersPerHour: clamp(
 			pick("maxTriggersPerHour"),
@@ -757,6 +805,51 @@ export function resolveWatchConfig(
 	};
 }
 
+/**
+ * Normalise the mention-only switch.
+ *
+ * Exported for tests. A plain boolean keeps working — `true` is
+ * `{ default: true }` with no overrides — so an existing config file needs no
+ * change, and the older key still reads the way it always did.
+ */
+export function resolveMentionOnly(
+	value: boolean | MentionOnlyConfig | undefined,
+): ResolvedMentionOnly {
+	if (typeof value === "boolean") {
+		return { default: value, chats: [], people: [] };
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return { default: false, chats: [], people: [] };
+	}
+
+	return {
+		default: typeof value.default === "boolean" ? value.default : false,
+		chats: normalizeMentionRules(value.chats),
+		people: normalizeMentionRules(value.people),
+	};
+}
+
+/**
+ * Keep only `pattern → boolean` pairs.
+ *
+ * A hand-edited config file can carry anything, and a rule that is neither a
+ * usable pattern nor a boolean is not worth failing the whole config over: it
+ * is dropped, and the default decides instead.
+ */
+function normalizeMentionRules(
+	rules: Record<string, boolean> | undefined,
+): MentionOnlyRule[] {
+	if (!rules || typeof rules !== "object" || Array.isArray(rules)) return [];
+
+	const normalized: MentionOnlyRule[] = [];
+	for (const [pattern, value] of Object.entries(rules)) {
+		const trimmed = typeof pattern === "string" ? pattern.trim() : "";
+		if (!trimmed || typeof value !== "boolean") continue;
+		normalized.push({ pattern: trimmed, value });
+	}
+	return normalized;
+}
+
 /**
  * Effective AI-footer settings: account > global > default.
  *

package/src/extension/index.ts

@@ -13,6 +13,7 @@ import {
 	ensureConfigTemplate,
 	getConfigPath,
 	setWatchConfig,
+	type ResolvedMentionOnly,
 	tryResolveConnection,
 	type TeamsConnection,
 } from "../config/index.ts";
@@ -86,6 +87,19 @@ import {
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+/**
+ * The mention-only switch in one phrase, for the status line.
+ *
+ * The override count is part of it on purpose: "mentions only" and "mentions
+ * only, with two exemptions" behave differently enough that the difference
+ * should not be invisible in the place people check the setting.
+ */
+function mentionSummary(mentionOnly: ResolvedMentionOnly): string {
+	const overrides = mentionOnly.chats.length + mentionOnly.people.length;
+	const base = mentionOnly.default ? "mentions only" : "every message";
+	return overrides > 0 ? `${base} (${overrides} override${overrides === 1 ? "" : "s"})` : base;
+}
+
 /** Every tool, in the order they appear in the documentation. */
 const tools = [
 	// Setup & session
@@ -360,7 +374,7 @@ export default function (pi: ExtensionAPI) {
 					`every ${conn.watch.intervalSeconds} s`,
 					conn.watch.chats.length > 0 ? `chats: ${conn.watch.chats.join(", ")}` : "all recent chats",
 					conn.watch.from.length > 0 ? `people: ${conn.watch.from.join(", ")}` : "any sender",
-					conn.watch.mentionOnly ? "mentions only" : "every message",
+					mentionSummary(conn.watch.mentionOnly),
 					runtime ? `${runtime.wakesThisHour} wake(s) this hour` : "not running in this session",
 				].join(" · "),
 				"info",
@@ -429,7 +443,12 @@ export default function (pi: ExtensionAPI) {
 		// 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 });
+		// Only an interactive session listens on its own. A pi started headless by
+		// another pi (`--mode json -p`, e.g. a subagent) loads the same extensions
+		// and the same config: autoStart there would run a second watcher that
+		// answers chats inside a throwaway process and advances the shared cursor,
+		// so the real session never sees those messages.
+		if (connection.watch.autoStart && ctx.hasUI) startWatch(ctx, { explicit: true });
 
 		paintStatus(ctx);
 

package/src/tools/teams-watch.ts

@@ -12,6 +12,8 @@ import {
 	getConfigPath,
 	resolveConnection,
 	setWatchConfig,
+	type MentionOnlyConfig,
+	type ResolvedMentionOnly,
 	type TeamsConnection,
 	type WatchConfig,
 } from "../config/index.ts";
@@ -26,7 +28,7 @@ interface WatchParams {
 	intervalSeconds?: number;
 	chats?: string[];
 	from?: string[];
-	mentionOnly?: boolean;
+	mentionOnly?: boolean | MentionOnlyConfig;
 	cooldownSeconds?: number;
 	maxTriggersPerHour?: number;
 }
@@ -50,6 +52,16 @@ const CURSOR_NOTES = [
 		+ "never dropped: it stays open and is answered as soon as the wait is over.",
 ].join("\n");
 
+/** Renders the mention-only switch, which is a default plus optional overrides. */
+function describeMentionOnly(mentionOnly: ResolvedMentionOnly): string {
+	const rules = [
+		...mentionOnly.chats.map((rule) => `chat \`${rule.pattern}\` → ${rule.value}`),
+		...mentionOnly.people.map((rule) => `person \`${rule.pattern}\` → ${rule.value}`),
+	];
+	const overrides = rules.length > 0 ? ` (${rules.join(", ")})` : "";
+	return `- mentions only: ${mentionOnly.default}${overrides}`;
+}
+
 /** Renders the effective settings the same way the config file would. */
 function describe(watch: {
 	enabled: boolean;
@@ -57,7 +69,7 @@ function describe(watch: {
 	intervalSeconds: number;
 	chats: string[];
 	from: string[];
-	mentionOnly: boolean;
+	mentionOnly: ResolvedMentionOnly;
 	cooldownSeconds: number;
 	maxTriggersPerHour: number;
 }): string {
@@ -67,7 +79,7 @@ function describe(watch: {
 		`- 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}`,
+		describeMentionOnly(watch.mentionOnly),
 		`- cooldown per chat: ${watch.cooldownSeconds} s`,
 		`- wake limit: ${watch.maxTriggersPerHour} per hour`,
 	].join("\n");
@@ -159,7 +171,23 @@ export const teamsWatchTool = {
 			}),
 		),
 		mentionOnly: Type.Optional(
-			Type.Boolean({ description: "Only wake pi where the signed-in user is mentioned" }),
+			Type.Union(
+				[
+					Type.Boolean(),
+					Type.Object({
+						default: Type.Optional(Type.Boolean()),
+						chats: Type.Optional(Type.Record(Type.String(), Type.Boolean())),
+						people: Type.Optional(Type.Record(Type.String(), Type.Boolean())),
+					}),
+				],
+				{
+					description:
+						"Whether a message must address you before it wakes pi. `true`/`false` applies everywhere; "
+						+ "`{ default, chats, people }` adds per-chat and per-person overrides, and a rule may be false "
+						+ "to exempt someone who then does not have to mention you. 1:1 chats always count as addressed. "
+						+ "First matching pattern wins.",
+				},
+			),
 		),
 		cooldownSeconds: Type.Optional(
 			Type.Number({ description: "Seconds to stay quiet in a chat after waking pi for it (default 300)" }),
@@ -174,6 +202,7 @@ export const teamsWatchTool = {
 		"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.",
+		"`mentionOnly` takes a boolean or `{ default, chats, people }`. A 1:1 chat already counts as a direct address, so the overrides are for group and meeting chats — for example a global `true` with one person set to `false`, so that person never has to mention you.",
 	],
 
 	async execute(

package/src/watch/index.ts

@@ -18,7 +18,7 @@
  */
 
 import type { ChatSummary, MessageSummary, PersonRef, SignedInUser } from "../types.ts";
-import type { ResolvedWatchConfig } from "../config/index.ts";
+import type { MentionOnlyRule, ResolvedWatchConfig } from "../config/index.ts";
 import { matchesPattern } from "../config/scope.ts";
 import { chatCandidates } from "../graph/mappers.ts";
 
@@ -256,6 +256,85 @@ export function isWatchedSender(message: MessageSummary, watch: ResolvedWatchCon
 	return watch.from.some((pattern) => candidates.some((candidate) => matchesPattern(pattern, candidate)));
 }
 
+// ---------------------------------------------------------------------------
+// Whether a message has to address pi at all
+// ---------------------------------------------------------------------------
+
+/**
+ * Does this message have to mention the user before it may wake pi?
+ *
+ * The ladder, most specific first:
+ *
+ * 1. an explicit chat rule — a statement about this one conversation;
+ * 2. a one-to-one chat — a direct message is an address by definition;
+ * 3. an explicit person rule;
+ * 4. the configured default.
+ *
+ * Either value can be set at every step, so a global `true` with one person set
+ * to `false` means that person does not have to mention the user first. A 1:1
+ * chat sits above the person rules deliberately: it is about the conversation
+ * rather than about somebody in it, and a rule meant for group chats must not
+ * silence the direct messages that need no ceremony. To require a mention even
+ * there, name the chat.
+ */
+export function mentionRequired(
+	chat: ChatSummary,
+	message: MessageSummary,
+	me: SignedInUser | undefined,
+	watch: ResolvedWatchConfig,
+): boolean {
+	const chatRule = firstMentionRule(
+		watch.mentionOnly.chats,
+		chatCandidates(chat).filter((value): value is string => !!value),
+	);
+	if (chatRule !== undefined) return chatRule;
+
+	if (isDirectChat(chat, me)) return false;
+
+	const sender = message.from;
+	const candidates = sender
+		? [sender.displayName, sender.upn, sender.mail, sender.id].filter(
+				(value): value is string => !!value,
+			)
+		: [];
+
+	return firstMentionRule(watch.mentionOnly.people, candidates) ?? watch.mentionOnly.default;
+}
+
+/**
+ * Is this conversation a one-to-one?
+ *
+ * A message in a chat with a single other person *is* a direct address: there
+ * is nobody else it could be meant for, and Teams 1:1 messages carry no
+ * @-mention. Counting them as "not addressed" would silence exactly the
+ * conversations that need no ceremony.
+ *
+ * `chatType` is authoritative when Graph sends one. It can come back as
+ * "unknown" — the mapper's fallback — and then the member list is the only
+ * evidence, so the people other than the signed-in user are counted. Whether
+ * the signed-in user appears in that list is up to Graph, which is why the
+ * comparison runs per member rather than a plain length check.
+ */
+export function isDirectChat(chat: ChatSummary, me: SignedInUser | undefined): boolean {
+	if (chat.chatType === "oneOnOne") return true;
+	if (chat.chatType && chat.chatType !== "unknown") return false;
+
+	return chat.members.filter((member) => !isFromMe(member, me)).length === 1;
+}
+
+/** The value of the first rule that matches any candidate, in config order. */
+function firstMentionRule(
+	rules: readonly MentionOnlyRule[],
+	candidates: readonly string[],
+): boolean | undefined {
+	for (const rule of rules) {
+		for (const candidate of candidates) {
+			if (matchesPattern(rule.pattern, candidate)) return rule.value;
+		}
+	}
+	return undefined;
+}
+
 // ---------------------------------------------------------------------------
 // What the answer has to cover
 // ---------------------------------------------------------------------------
@@ -388,7 +467,9 @@ export function shouldWake(
 
 	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 (mentionRequired(chat, message, me, watch) && !mentionsMe(message, me)) {
+		return skip("a mention is required here and the message has none");
+	}
 	if (watch.maxTriggersPerHour > 0 && wakesThisHour(state, now) >= watch.maxTriggersPerHour) {
 		return defer(
 			"the hourly wake limit is reached",