@patimweb/pi-teams 1.9.2 → 1.11.0

package/docs/listen-mode.md

@@ -30,7 +30,11 @@ never sees.
   "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
 }
@@ -43,7 +47,7 @@ never sees.
 | `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 |
 
@@ -51,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/docs/tools.md

@@ -41,10 +41,10 @@ the default account. See [configuration.md](configuration.md).
 
 | Tool | Description |
 |------|-------------|
-| `teams_send_chat_message` | Send a chat message as you |
+| `teams_send_chat_message` | Send a chat message as you, optionally with images |
 | `teams_create_chat` | Start a 1:1 or group chat, optionally with the first message |
-| `teams_send_channel_message` | Post in a channel as you |
-| `teams_reply_channel_message` | Reply inside an existing thread |
+| `teams_send_channel_message` | Post in a channel as you, optionally with images |
+| `teams_reply_channel_message` | Reply inside an existing thread, optionally with images |
 | `teams_react` | Add or remove an emoji reaction |
 | `teams_mark_read` | Mark a chat as read (or unread again) — the natural end of a catch-up |
 | `teams_update_message` | Edit a chat message you already sent |
@@ -137,9 +137,11 @@ subset Teams renders in a chat bubble:
 | `[label](https://…)` | link |
 | `# Heading` | a bold line — Teams has no headings in a chat |
 
-Tables and images are deliberately **not** translated: Teams renders neither in
-a chat, so passing them through would look worse than plain text. Put a table in
-a file and link it instead.
+A markdown image and a table are deliberately **not** translated: Teams renders
+neither in a chat bubble, and an image URL would only work if the recipient's
+client could reach it. A picture that is already on disk goes out through the
+`images` parameter instead — see below. For a table, put it in a file and link
+to it.
 
 Pass `html: true` on a send tool to bypass the conversion and supply raw HTML
 instead. Everything else is escaped, so a message body cannot inject markup.
@@ -148,3 +150,30 @@ This is also why pi writes the way it does — short, answer-first, bullets for
 anything enumerable. The medium is a chat bubble, not a document. The rules the
 model follows are in `skills/teams-collaboration/SKILL.md`, under *How to format
 a Teams message*.
+
+## Sending images
+
+`teams_send_chat_message`, `teams_send_channel_message` and
+`teams_reply_channel_message` take `images: ["/pfad/bild.png"]` — local paths of
+pictures to attach. They appear under the text, in the order given, and a
+message may consist of images alone.
+
+Teams keeps an inline picture inside the message itself: the bytes travel in the
+same request as the text, and the body points at them (`hostedContents`).
+Nothing is uploaded to SharePoint first, which is why this works with the
+permissions the package already asks for and costs no admin consent.
+
+- Accepted: png, jpeg, gif, webp, bmp. Anything else is refused before the
+  message is built, because Teams would show it as a broken picture.
+- **4 MB per image**, the limit Graph enforces on hosted content.
+- The path must be readable from the process that sends. For a pi running in a
+  container that is a path *inside* the container.
+
+This is attachments-for-images only. A PDF, a DOCX or a ZIP cannot be sent: a
+real file attachment needs the file in SharePoint or OneDrive and a `contentUrl`
+pointing at it, which means asking for a write scope on the user's drive. The
+package deliberately does not ask for `Files.ReadWrite`, so a non-image is
+refused rather than half-supported — link to the file instead.
+
+What was sent, pictures included, is recorded in the audit entry and shown in
+the confirmation prompt at `safetyLevel: confirm`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.9.2",
+  "version": "1.11.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

@@ -97,10 +97,10 @@ instead of trying anyway.
 
 | Tool | Use when |
 |------|----------|
-| `teams_send_chat_message` | Sending a chat message |
+| `teams_send_chat_message` | Sending a chat message, with or without images |
 | `teams_create_chat` | Starting a new conversation |
-| `teams_send_channel_message` | Posting a new channel message |
-| `teams_reply_channel_message` | Answering inside an existing thread |
+| `teams_send_channel_message` | Posting a new channel message, with or without images |
+| `teams_reply_channel_message` | Answering inside an existing thread, with or without images |
 | `teams_react` | Adding or removing an emoji reaction |
 | `teams_update_message` | Fixing a message the user already sent |
 | `teams_chat_members` | Bringing someone into a group chat, or taking them out |
@@ -240,6 +240,24 @@ deliberate and must not be worked around:
 
 Ordinary SharePoint and OneDrive attachments download normally.
 
+### Sending images
+
+The three send tools take `images: ["/path/bild.png"]`: local pictures to attach
+to the message. They are shown under the text, a message may be images only, and
+nothing is uploaded anywhere — Teams keeps them inside the message.
+
+- png, jpeg, gif, webp, bmp, **at most 4 MB each**. Anything else is refused
+  before the message is built; report that instead of retrying with the same file.
+- The path is read by the process that sends. Inside a container that is a path
+  *inside* the container, not on the user's machine.
+- Only images. A PDF, DOCX or ZIP cannot be attached — give the user a link to
+  the file instead. Do not promise an attachment you cannot send.
+- The confirmation prompt and the audit entry name the images that go out, so
+  what the user approves is what is sent.
+
+For a table, the same applies as for any other non-image: put it in a file and
+link it.
+
 ## Channel addressing
 
 Channels are addressed as `Team/Channel` or via separate `team` and `channel`
@@ -365,13 +383,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",

package/src/graph/messages.ts

@@ -12,6 +12,7 @@ import type { ChannelSummary, MessageLocation, MessageSummary, PersonRef } from
 import { graphGetOptional, graphList, graphPatch, graphPost } from "./client.ts";
 import { mapMessage } from "./mappers.ts";
 import { markdownToTeamsHtml } from "../utils/richtext.ts";
+import type { HostedImage } from "../utils/hosted-content.ts";
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 type Raw = Record<string, any>;
@@ -37,6 +38,13 @@ export interface MessageInput {
 	importance?: string;
 	/** People to @-mention; each must appear in the body as @DisplayName */
 	mentions?: PersonRef[];
+	/**
+	 * Inline images, already read from disk and base64-encoded.
+	 *
+	 * They travel in the same POST as the body — Teams keeps the bytes inside the
+	 * message — so there is no second request and no file upload anywhere.
+	 */
+	images?: HostedImage[];
 }
 
 /**
@@ -77,12 +85,29 @@ export function buildMessageBody(input: MessageInput): Record<string, unknown> {
 		});
 	});
 
+	// The pictures follow the text rather than being placed inside it: the caller
+	// writes the message, and a model that also had to pick a position in the HTML
+	// would be choosing something nobody asked it to choose. The id is ours to
+	// pick — it only has to be the same in the body and in hostedContents, which is
+	// the part that quietly goes wrong.
+	const hostedContents: Record<string, unknown>[] = [];
+	(input.images ?? []).forEach((image, index) => {
+		const id = String(index + 1);
+		content += `<br><img src="../hostedContents/${id}/$value" alt="${escapeHtml(image.name)}">`;
+		hostedContents.push({
+			"@microsoft.graph.temporaryId": id,
+			contentBytes: image.contentBytes,
+			contentType: image.contentType,
+		});
+	});
+
 	const body: Record<string, unknown> = {
 		body: { contentType: "html", content },
 	};
 	if (input.subject) body.subject = input.subject;
 	if (input.importance) body.importance = input.importance;
 	if (mentionEntries.length > 0) body.mentions = mentionEntries;
+	if (hostedContents.length > 0) body.hostedContents = hostedContents;
 
 	return body;
 }

package/src/safety/index.ts

@@ -119,17 +119,29 @@ export function formatMutationSummary(
 		return str.length > max ? `${str.slice(0, max - 1)}…` : str;
 	};
 	const disclosed = (value: unknown): string => applyAiFooter(text(value, 400), footer);
+	/**
+	 * The images that travel with the message, by file name.
+	 *
+	 * Someone approving a send has to see that a picture is part of it: a
+	 * confirmation that shows only the text would be asking about half of it.
+	 */
+	const withImages = (value: unknown): string => {
+		const paths = Array.isArray(value) ? value.filter((p): p is string => typeof p === "string") : [];
+		if (paths.length === 0) return "";
+		const names = paths.map((p) => p.split(/[\\/]/).pop() ?? p).join(", ");
+		return `\n\n(with ${paths.length === 1 ? "1 image" : `${paths.length} images`}: ${text(names, 120)})`;
+	};
 
 	switch (toolName) {
 		case "teams_send_chat_message":
-			return `Send a chat message to "${text(params.chat, 60)}":\n\n${disclosed(params.body)}`;
+			return `Send a chat message to "${text(params.chat, 60)}":\n\n${disclosed(params.body)}${withImages(params.images)}`;
 		case "teams_send_channel_message": {
 			const where = params.team ? `${text(params.team, 40)}/${text(params.channel, 40)}` : text(params.channel, 60);
-			return `Post in channel ${where}:\n\n${disclosed(params.body)}`;
+			return `Post in channel ${where}:\n\n${disclosed(params.body)}${withImages(params.images)}`;
 		}
 		case "teams_reply_channel_message": {
 			const where = params.team ? `${text(params.team, 40)}/${text(params.channel, 40)}` : text(params.channel, 60);
-			return `Reply in thread ${text(params.messageId, 40)} (${where}):\n\n${disclosed(params.body)}`;
+			return `Reply in thread ${text(params.messageId, 40)} (${where}):\n\n${disclosed(params.body)}${withImages(params.images)}`;
 		}
 		case "teams_create_chat": {
 			const people = Array.isArray(params.participants) ? params.participants.join(", ") : text(params.participants);

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

@@ -12,6 +12,7 @@ import { resolveUserId } from "../graph/me.ts";
 import { auditWrite } from "../safety/audit.ts";
 import { CHAT_MESSAGE_BODY_DESCRIPTION, CHAT_SHAPE_GUIDELINE } from "../utils/chat-style.ts";
 import { applyAiFooter } from "../utils/disclosure.ts";
+import { imageNote, readHostedImage } from "../utils/hosted-content.ts";
 import { assertAccess } from "../safety/index.ts";
 import { truncate } from "../utils/formatting.ts";
 import { requireChannel } from "./resolve.ts";
@@ -67,6 +68,13 @@ const sharedParams = {
 	),
 	importance: Type.Optional(Type.String({ description: "'normal' (default), 'high' or 'urgent'" })),
 	html: Type.Optional(Type.Boolean({ description: "Send 'body' as raw HTML instead of converting markdown" })),
+	images: Type.Optional(
+		Type.Array(Type.String(), {
+			description:
+				"Local paths of images to attach (png, jpg, gif, webp, bmp; 4 MB each at most). " +
+				"They are shown inline, under the text.",
+		}),
+	),
 };
 
 export const teamsSendChannelMessageTool = {
@@ -74,7 +82,8 @@ export const teamsSendChannelMessageTool = {
 	description:
 		"Post a new message in a Microsoft Teams channel as the signed-in user. It appears exactly as if the " +
 		"user posted it. Give the channel as a 'Team/Channel' path or pass 'team' separately. " +
-		"'subject' starts a titled post; use teams_reply_channel_message to answer inside an existing thread.",
+		"'subject' starts a titled post; use teams_reply_channel_message to answer inside an existing thread. " +
+		"'images' attaches local image files to the post itself; pi cannot attach other kinds of files.",
 	parameters: Type.Object({
 		...sharedParams,
 		subject: Type.Optional(Type.String({ description: "Optional post title" })),
@@ -99,6 +108,7 @@ export const teamsSendChannelMessageTool = {
 			mentions?: string[];
 			importance?: string;
 			html?: boolean;
+			images?: string[];
 		},
 		signal: AbortSignal | undefined,
 		_onUpdate: undefined,
@@ -106,7 +116,15 @@ export const teamsSendChannelMessageTool = {
 	): Promise<ToolResult> {
 		return run(async () => {
 			const conn = connectionFor(ctx, params.account, params.tenant);
-			if (!params.body.trim()) return errorResult("Refusing to post an empty message.");
+
+			// Read before anything is posted: an image that cannot be read has to stop
+			// the post, not arrive as text promising one.
+			const images = [];
+			for (const path of params.images ?? []) images.push(await readHostedImage(path));
+
+			if (!params.body.trim() && images.length === 0) {
+				return errorResult("Refusing to post an empty message.");
+			}
 
 			const { team, channel } = await requireChannel(conn, params.team, params.channel, "write", signal);
 			const { mentions, error } = await resolveMentions(conn, params.mentions, signal);
@@ -128,6 +146,7 @@ export const teamsSendChannelMessageTool = {
 						subject: params.subject,
 						importance: params.importance,
 						mentions,
+						images,
 					},
 					signal,
 				);
@@ -138,7 +157,7 @@ export const teamsSendChannelMessageTool = {
 					tenant: conn.tenant,
 					actor: me?.upn,
 					target: `channel:${target}`,
-					summary: truncate(body, 200),
+					summary: truncate(body, 200) + imageNote(images),
 				});
 
 				return textResult(
@@ -158,7 +177,7 @@ export const teamsSendChannelMessageTool = {
 					tenant: conn.tenant,
 					actor: me?.upn,
 					target: `channel:${target}`,
-					summary: truncate(body, 200),
+					summary: truncate(body, 200) + imageNote(images),
 					error: err instanceof Error ? err.message : String(err),
 				});
 				throw err;
@@ -172,7 +191,8 @@ export const teamsReplyChannelMessageTool = {
 	description:
 		"Reply inside an existing Microsoft Teams channel thread as the signed-in user. " +
 		"Get the messageId from teams_read_channel, teams_read_thread or teams_search_messages. " +
-		"Replying keeps the conversation in one thread instead of starting a new post.",
+		"Replying keeps the conversation in one thread instead of starting a new post. " +
+		"'images' attaches local image files to the reply itself.",
 	parameters: Type.Object({
 		...sharedParams,
 		messageId: Type.String({ description: "ID of the thread's opening message" }),
@@ -192,6 +212,7 @@ export const teamsReplyChannelMessageTool = {
 			mentions?: string[];
 			importance?: string;
 			html?: boolean;
+			images?: string[];
 		},
 		signal: AbortSignal | undefined,
 		_onUpdate: undefined,
@@ -199,7 +220,15 @@ export const teamsReplyChannelMessageTool = {
 	): Promise<ToolResult> {
 		return run(async () => {
 			const conn = connectionFor(ctx, params.account, params.tenant);
-			if (!params.body.trim()) return errorResult("Refusing to post an empty reply.");
+
+			// Read before anything is posted: an image that cannot be read has to stop
+			// the reply, not arrive as text promising one.
+			const images = [];
+			for (const path of params.images ?? []) images.push(await readHostedImage(path));
+
+			if (!params.body.trim() && images.length === 0) {
+				return errorResult("Refusing to post an empty reply.");
+			}
 
 			const { team, channel } = await requireChannel(conn, params.team, params.channel, "write", signal);
 			const { mentions, error } = await resolveMentions(conn, params.mentions, signal);
@@ -221,6 +250,7 @@ export const teamsReplyChannelMessageTool = {
 						html: params.html,
 						importance: params.importance,
 						mentions,
+						images,
 					},
 					signal,
 				);
@@ -231,7 +261,7 @@ export const teamsReplyChannelMessageTool = {
 					tenant: conn.tenant,
 					actor: me?.upn,
 					target: `channel:${target}#${params.messageId}`,
-					summary: truncate(body, 200),
+					summary: truncate(body, 200) + imageNote(images),
 				});
 
 				return textResult(
@@ -251,7 +281,7 @@ export const teamsReplyChannelMessageTool = {
 					tenant: conn.tenant,
 					actor: me?.upn,
 					target: `channel:${target}#${params.messageId}`,
-					summary: truncate(body, 200),
+					summary: truncate(body, 200) + imageNote(images),
 					error: err instanceof Error ? err.message : String(err),
 				});
 				throw err;

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

@@ -23,6 +23,7 @@ import { auditWrite } from "../safety/audit.ts";
 import { assertAccess } from "../safety/index.ts";
 import { CHAT_MESSAGE_BODY_DESCRIPTION, CHAT_SHAPE_GUIDELINE } from "../utils/chat-style.ts";
 import { applyAiFooter } from "../utils/disclosure.ts";
+import { imageNote, readHostedImage } from "../utils/hosted-content.ts";
 import { truncate } from "../utils/formatting.ts";
 import { requireChat } from "./resolve.ts";
 import {
@@ -46,6 +47,7 @@ interface SendChatParams {
 	mentions?: string[];
 	importance?: string;
 	html?: boolean;
+	images?: string[];
 }
 
 export const teamsSendChatMessageTool = {
@@ -54,7 +56,8 @@ export const teamsSendChatMessageTool = {
 		"Send a message in a Microsoft Teams chat as the signed-in user. The message appears exactly as if the " +
 		"user typed it. Accepts a chat ID, group chat topic, or participant name/e-mail. " +
 		"Use 'mentions' with names or e-mail addresses to @-mention people — write '@Display Name' in the body " +
-		"where the mention should appear.",
+		"where the mention should appear. " +
+		"'images' attaches local image files to the message itself; pi cannot attach other kinds of files.",
 	parameters: Type.Object({
 		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
 		body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
@@ -71,6 +74,13 @@ export const teamsSendChatMessageTool = {
 		html: Type.Optional(
 			Type.Boolean({ description: "Send 'body' as raw HTML instead of converting markdown" }),
 		),
+		images: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"Local paths of images to attach to the message (png, jpg, gif, webp, bmp; 4 MB each at most). " +
+					"They are shown inline, under the text.",
+			}),
+		),
 	}),
 	promptSnippet: "Send a message in a Teams chat as the user",
 	promptGuidelines: [
@@ -91,7 +101,14 @@ export const teamsSendChatMessageTool = {
 		return run(async () => {
 			const conn = connectionFor(ctx, params.account, params.tenant);
 
-			if (!params.body.trim()) return errorResult("Refusing to send an empty message.");
+			// Read before anything is sent: a picture that cannot be read has to stop
+			// the message, not arrive as text promising one.
+			const images = [];
+			for (const path of params.images ?? []) images.push(await readHostedImage(path));
+
+			if (!params.body.trim() && images.length === 0) {
+				return errorResult("Refusing to send an empty message.");
+			}
 
 			const chat = await requireChat(conn, params.chat, "write", signal);
 
@@ -129,6 +146,7 @@ export const teamsSendChatMessageTool = {
 						html: params.html,
 						importance: params.importance,
 						mentions,
+						images,
 					},
 					signal,
 				);
@@ -139,7 +157,7 @@ export const teamsSendChatMessageTool = {
 					tenant: conn.tenant,
 					actor: me?.upn,
 					target: `chat:${chat.label}`,
-					summary: truncate(body, 200),
+					summary: truncate(body, 200) + imageNote(images),
 				});
 
 				// Replying is reading: clear the unread marker the answer was written for.

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/utils/hosted-content.ts

@@ -0,0 +1,105 @@
+/**
+ * Attaching a local image to a message.
+ *
+ * Teams keeps an inline image inside the message itself as a `hostedContent`:
+ * the body points at `../hostedContents/{id}/$value` and the bytes travel in the
+ * same POST. That is what makes this cheap — nothing has to be uploaded to
+ * SharePoint first, which is what a real file attachment needs, and which would
+ * mean asking for a write scope on the user's drive.
+ *
+ * Graph caps a hosted content at 4 MB, and an image of a type Teams does not
+ * render would reach the reader as a broken picture, so both are checked here,
+ * before the message that carries it is built.
+ */
+
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname } from "node:path";
+
+/** Graph rejects a hosted content larger than this. */
+export const MAX_HOSTED_CONTENT_BYTES = 4 * 1024 * 1024;
+
+/**
+ * The image types Teams shows inline, by file extension.
+ *
+ * A list rather than "anything starting with image/": a type Teams does not
+ * render arrives as a broken image, and refusing it up front is friendlier than
+ * sending it and having the reader find out.
+ */
+export const HOSTED_CONTENT_TYPES: Record<string, string> = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".bmp": "image/bmp",
+};
+
+/** The content type for a path, or undefined when Teams does not render it inline. */
+export function hostedContentType(path: string): string | undefined {
+	return HOSTED_CONTENT_TYPES[extname(path).toLowerCase()];
+}
+
+/**
+ * One image, ready to send.
+ *
+ * `contentBytes` is base64 because that is what Graph asks for: the bytes are
+ * JSON string data, not a multipart upload.
+ */
+export interface HostedImage {
+	/** The file name, as the attachment is described in audit entries */
+	name: string;
+	contentType: string;
+	contentBytes: string;
+}
+
+/** A byte count as a human reads it — the limits here are in megabytes. */
+export function formatBytes(bytes: number): string {
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Read one local image for sending.
+ *
+ * Throws with the reason instead of sending something partial: a message that
+ * quietly goes out without the picture the user asked for is worse than a tool
+ * call that says why it did not.
+ */
+export async function readHostedImage(path: string): Promise<HostedImage> {
+	const name = basename(path);
+
+	const contentType = hostedContentType(path);
+	if (!contentType) {
+		const supported = [...new Set(Object.values(HOSTED_CONTENT_TYPES))].join(", ");
+		throw new Error(`"${name}" is not an image Teams shows inline. Supported types: ${supported}.`);
+	}
+
+	let info;
+	try {
+		info = await stat(path);
+	} catch {
+		throw new Error(`"${path}" could not be read. Give a path to a file that exists locally.`);
+	}
+	if (info.isDirectory()) throw new Error(`"${path}" is a directory, not an image.`);
+	if (info.size === 0) throw new Error(`"${name}" is empty.`);
+	if (info.size > MAX_HOSTED_CONTENT_BYTES) {
+		throw new Error(
+			`"${name}" is ${formatBytes(info.size)}; Teams accepts at most ` +
+				`${formatBytes(MAX_HOSTED_CONTENT_BYTES)} per image.`,
+		);
+	}
+
+	const bytes = await readFile(path);
+	return { name, contentType, contentBytes: bytes.toString("base64") };
+}
+
+/**
+ * The images named in one phrase, for the audit entry.
+ *
+ * What went out is the thing an audit entry has to answer, and a message with a
+ * picture in it is not described by its text alone.
+ */
+export function imageNote(images: readonly HostedImage[]): string {
+	if (images.length === 0) return "";
+	const label = images.length === 1 ? "image" : "images";
+	return ` [${label}: ${images.map((image) => image.name).join(", ")}]`;
+}

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",