@patimweb/pi-teams 1.6.0 → 1.7.0-next.1

package/README.md

@@ -267,6 +267,14 @@ account with `"authMode": "device-code"`, or per call with
 Either way the session is cached on disk and renewed silently, so signing in is
 a once-per-account affair.
 
+In **WSL** the URL is handed to Windows PowerShell, so the browser on the
+Windows side opens: no X server, no `DISPLAY`, and the authorize URL survives
+whole — including its `&`, which a `cmd.exe` handoff would cut at the first one.
+If the built-in launchers do not fit the machine, set `PI_TEAMS_BROWSER` to a
+command line that opens a URL: `{}` is replaced by the URL, otherwise the URL is
+appended. Every failure carries the URL in its message, so it can be pasted
+into a browser by hand — the one route that needs nothing installed.
+
 Microsoft Graph only permits app-only writes to chats and channels for
 migration scenarios (`Teamwork.Migrate.All`), so pi-teams refuses those calls
 up front instead of letting them fail deep inside a Graph request. Use
@@ -467,6 +475,7 @@ teams_permissions:
 | `teams_list_members` | Members of a team or channel |
 | `teams_find_user` | Directory lookup by name, e-mail or UPN |
 | `teams_list_files` | Files in a channel's SharePoint folder |
+| `teams_download_files` | Download the images and files of messages to a local directory |
 | `teams_get_presence` | Your status, a colleague's, or a whole chat's |
 | `teams_availability` | When several people are all free, from calendar free/busy |
 | `teams_list_meetings` | Calendar events and meetings in a range |
@@ -590,6 +599,7 @@ teams_send_channel_message:
 | `~/.pi/agent/pi-teams-tokens/` | one MSAL token cache per account+tenant | `0600` |
 | `~/.pi/agent/pi-teams-audit.jsonl` | one line per write: when, who, where, what | `0600` |
 | `~/.pi/agent/pi-teams-watch/` | listen mode's cursor: the newest message it has looked at per chat | `0600` |
+| `~/.pi/agent/pi-teams-files/` | images and files downloaded from messages, one folder per chat or channel | — |
 
 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
@@ -648,8 +658,9 @@ network connection.
 | `AADSTS50011` (redirect URI mismatch) | Add `http://localhost` under *Mobile and desktop applications*, or pin `loopbackPort` |
 | `AADSTS50020` | The account is not a member/guest of that tenant, or the app is single-tenant |
 | Signed out after about an hour | The tenant grants no `offline_access`, so there is no refresh token. `teams_doctor` names the missing scope; otherwise sign in again when it expires |
-| Browser never opens | No browser is reachable here; `teams_doctor` says why. `teams_login mode: device-code` always works |
-| Browser opens, page never returns | A firewall is blocking the loopback port. Pin `loopbackPort` and allow it, or use the device code flow |
+| Browser never opens | The launcher failed: the error names it, and carries the URL to open by hand. `teams_doctor` says whether a browser counts as reachable here, and `PI_TEAMS_BROWSER` points pi at your own command |
+| Browser opens, page never returns | Read what the browser showed before suspecting a firewall: a pending admin consent (`AADSTS65004`), a Conditional Access policy (`AADSTS53003`), or a redirect URI that does not match the port (`AADSTS50011`). The timeout message names all three. A blocked loopback port is the fourth possibility — pin `loopbackPort` and allow it |
+| A screenshot in a message is missing from the output | The text of a message cannot carry a picture. `teams_read_chat` says how many images a message has; `teams_download_files` fetches them so they can be opened |
 | "Not signed in" | Run `teams_login`; the saved session may have been revoked |
 | Status line says "not signed in" although sign-in worked | The line is written at session start and after every auth tool; if it lags, `/teams-status` repaints it |
 | "Blocked by configuration" | Your own scope rules. `teams_permissions action: test` shows which rule |

package/docs/entra-app-registration.md

@@ -81,8 +81,23 @@ AADSTS7000218: The request body must contain the following parameter:
 
 ## 3. API permissions
 
-**App registrations** → your app → **API permissions** → **Add a permission** →
-**Microsoft Graph** → **Delegated permissions**:
+**Entra admin center** → **Entra ID** → **App registrations** → your app →
+**API permissions**. Four clicks, and the third one is the one people get
+wrong:
+
+1. **Add a permission** — the button above the permission list.
+2. **Microsoft Graph** — the first tile under *Commonly used Microsoft APIs*.
+   Not *Azure DevOps*, not *Azure Storage*: those are different APIs and their
+   permissions will not help.
+3. **Delegated permissions**, *not* **Application permissions**. pi acts as you.
+   An application permission would give the app its own identity and a
+   completely different consent model — and the two tiles sit directly under
+   each other, which is why this is the usual mistake.
+4. Type each name into **Start typing a permission to filter these results**,
+   tick the box, and press **Add permissions** once at the end. Nothing is
+   saved until that button is pressed, so a half-filled list can be closed.
+
+What you should end up ticking:
 
 | Permission | Needed for |
 |---|---|
@@ -99,7 +114,25 @@ AADSTS7000218: The request body must contain the following parameter:
 | `Files.Read.All`, `Sites.Read.All` | channel files |
 
 `openid`, `profile` and `offline_access` are deliberately absent: MSAL always
-requests them and rejects them in an explicit scope list.
+requests them and rejects them in an explicit scope list. (You will still see
+them in the picker, under **OpenId permissions**. Leave them alone.)
+
+### The Admin consent required column
+
+After adding them, the list has a column that decides whether step 4 is a
+five-second job or a ticket to your administrator:
+
+| Permission | Admin consent required |
+|---|---|
+| `ChannelMessage.Read.All` | **Yes** — reading channels and threads |
+| `ChannelMember.Read.All` | **Yes** — channel member lists |
+| `ChatMember.ReadWrite` | **Yes** — only if you added it, see below |
+| everything else in the list above | No |
+
+The column shows the *default* for an organization, and a tenant can relax it
+per permission, per user or per app — read it as "expect to need an admin", not
+as a property of the permission itself. The scopes showing **Yes** are the ones
+step 4 is about.
 
 **What is not needed:** no client secret, no certificate, no redirect URI beyond
 step 2, no application (as opposed to delegated) permissions.
@@ -112,7 +145,7 @@ again:
 
 | Permission | Unlocks | Consent |
 |---|---|---|
-| `ChatMember.ReadWrite` | removing someone from a chat (`teams_chat_members`) | user |
+| `ChatMember.ReadWrite` | removing someone from a chat (`teams_chat_members`) | **admin** — the portal shows it as *Admin consent required: Yes*, and the tool says which scope is missing until it is granted |
 
 Without it the tool answers with the exact scope it is missing instead of
 failing at Graph with a consent error. Editing and deleting chat messages,
@@ -183,6 +216,12 @@ Or edit `~/.pi/agent/pi-teams.json` directly — the same file, mode `0600`:
    with your own credentials and MFA, and the page closes itself. Nothing to
    copy or type. Over SSH or in a container, pi falls back to the device code
    flow and shows a short code to enter on any device.
+
+   In **WSL** the URL is handed to Windows PowerShell, so the browser on the
+   Windows side opens — no X server and no `DISPLAY` needed. A launcher that
+   cannot be started is reported as an error; if you are upgrading from a
+   version that hung here instead, see the last row of the troubleshooting
+   table.
 2. `teams_status` — who pi acts as, which token is cached, what it may do.
 3. `teams_doctor` — checks configuration, sign-in, granted scopes and
    connectivity in one go. It reports a missing consent as a **named
@@ -223,9 +262,13 @@ that tenant on its own.
 | `AADSTS50011` — *redirect URI mismatch* | an exact URI is registered that does not match the chosen port | register the port-less `http://localhost`, or pin the port in the same file |
 | `AADSTS7000218` — *client_assertion or client_secret* | **Allow public client flows** is off | step 2b |
 | `AADSTS65001` — *consent required* | permissions added but never consented | sign in again; for the two admin scopes, step 4 |
+| `AADSTS65004` — *request pending* | an **admin consent request** is waiting for approval, or consent was declined once | step 4: an administrator presses **Grant admin consent**. A pending request is under **Enterprise applications** → your app → **Permissions**. Until it is approved the browser comes back with this code instead of a token |
+| `AADSTS53003` — *blocked by Conditional Access* | a policy requires a managed or compliant device, which the **device code** flow cannot satisfy | this is why the browser sign-in has to work rather than quietly fall back: on such a tenant the device code route is a dead end, not a fallback. Use a machine that satisfies the policy, or add pi's loopback redirect to it |
 | `AADSTS50020` — *not a member of the tenant* | wrong tenant, no guest account, or the app is single-tenant | steps 1 and 7 |
 | `AADSTS700016` — *application not found in directory* | wrong tenant ID or client ID | recheck `<DIRECTORY_TENANT_ID>` and `<APPLICATION_CLIENT_ID>` |
 | signed out after about an hour | the tenant grants no `offline_access` | the app needs a refresh token to renew silently; without it, run `teams_login` when the session expires. `teams_doctor` names the missing scope |
+| browser never opens from WSL | older versions called `xdg-open`, which a plain WSL distro does not have — and the failure was swallowed | update pi-teams: current versions hand the URL to Windows PowerShell. If the Windows drive is not mounted where the handoff expects it, set `PI_TEAMS_BROWSER` to your own command |
+| browser opens, no callback, five-minute timeout | three unrelated causes look identical from inside pi | read what the browser showed: a consent still pending (`AADSTS65004`), Conditional Access (`AADSTS53003`), or a redirect URI that does not match the port (`AADSTS50011`). The timeout text says the same. An exit code of 0 proves nothing — a launcher can exit 0 without having opened anything |
 
 Run `teams_doctor` first for anything in this table: it validates the
 configuration, the cached session, the granted scopes and the connection to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.6.0",
+  "version": "1.7.0-next.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/auth/index.ts

@@ -235,10 +235,15 @@ export function defaultSignInMode(): SignInMode {
 
 export { browserUnavailableReason, canOpenBrowser };
 
-function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string, hint?: string): Promise<T> {
 	return new Promise<T>((resolve, reject) => {
 		const timer = setTimeout(() => {
-			reject(new AuthError("timeout", `${label} timed out after ${Math.round(ms / 1000)}s.`));
+			reject(
+				new AuthError(
+					"timeout",
+					`${label} timed out after ${Math.round(ms / 1000)}s.${hint ? ` ${hint}` : ""}`,
+				),
+			);
 		}, ms);
 		promise.then(
 			(value) => {
@@ -253,6 +258,23 @@ function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise
 	});
 }
 
+/**
+ * What it means when a browser sign-in never comes back.
+ *
+ * Three unrelated causes look identical from here: the browser opens and no
+ * callback ever arrives. Naming all of them in the timeout text is the
+ * difference between a five-second fix and hunting the launcher, which is
+ * usually innocent — so the text asks the one question that separates them.
+ */
+const BROWSER_TIMEOUT_HINT =
+	"The browser opened but nothing came back. Check what the browser showed: " +
+	"a consent that is still pending (AADSTS65004 — an admin request waiting under " +
+	"Enterprise applications), a Conditional Access policy that blocks the sign-in " +
+	"(AADSTS53003), or a redirect URI on the app registration that does not match " +
+	"this port (AADSTS50011). If no browser opened at all, the launcher is the " +
+	"problem: set PI_TEAMS_BROWSER to your own command, or open the URL that came " +
+	"with the error by hand.";
+
 /**
  * Sign in as the user.
  *
@@ -289,6 +311,7 @@ export async function signIn(
 				}),
 				timeoutMs,
 				"Browser sign-in",
+				BROWSER_TIMEOUT_HINT,
 			);
 			if (!result) throw new AuthError("no_token", "Microsoft returned no token.");
 			return { ...toTokenInfo(result), mode: "interactive" };

package/src/auth/msal.ts

@@ -7,7 +7,7 @@
  * whether a browser is actually reachable, and open it.
  */
 
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import {
 	ConfidentialClientApplication,
 	LogLevel,
@@ -15,7 +15,7 @@ import {
 	type Configuration,
 } from "@azure/msal-node";
 import type { TeamsConnection } from "../config/index.ts";
-import { browserUnavailableReason, canOpenBrowser } from "../utils/environment.ts";
+import { browserUnavailableReason, canOpenBrowser, isWsl } from "../utils/environment.ts";
 import { createCachePlugin } from "./cache-plugin.ts";
 
 export { browserUnavailableReason, canOpenBrowser };
@@ -101,32 +101,192 @@ export function resetApps(): void {
 // Browser
 // ---------------------------------------------------------------------------
 
-/** Open a URL in the user's default browser, detached from this process. */
-export function openBrowser(url: string): Promise<void> {
-	return new Promise((resolve, reject) => {
-		const [command, args] =
-			process.platform === "darwin"
-				? ["open", [url]]
-				: process.platform === "win32"
-					? // `start` is a shell builtin, and the empty string is the window
-						// title cmd.exe would otherwise take the URL for.
-						["cmd.exe", ["/c", "start", "", url]]
-					: ["xdg-open", [url]];
+/**
+ * The Windows-side shell a WSL session hands its URL to.
+ *
+ * Windows PowerShell rather than `cmd.exe`: the authorize URL carries several
+ * `&`, and `cmd /c start` reads the first of them as a command separator and
+ * opens a truncated URL. Single quotes survive them.
+ */
+const WSL_POWERSHELL = "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe";
+
+/** How long to wait for a launcher that neither exits nor errors. */
+const LAUNCH_EXIT_GRACE_MS = 2000;
+
+/**
+ * The command that puts `url` in front of the user in a browser.
+ *
+ * Split out of `openBrowser` so the shapes stay testable: the Windows and WSL
+ * forms are easy to get subtly wrong, and all of them fail quietly when they
+ * are.
+ */
+export function browserLaunch(
+	url: string,
+	target: { platform?: NodeJS.Platform; wsl?: boolean; browser?: string } = {},
+): { command: string; args: string[] } {
+	const override = (target.browser ?? process.env.PI_TEAMS_BROWSER)?.trim();
+	if (override) return overrideLaunch(url, override);
+
+	const platform = target.platform ?? process.platform;
+
+	if (target.wsl ?? isWsl()) {
+		// Escaping a quote inside a PowerShell single-quoted string means doubling
+		// it. Nothing else in the URL needs attention.
+		const quoted = url.replace(/'/g, "''");
+		return {
+			command: WSL_POWERSHELL,
+			args: ["-NoProfile", "-NonInteractive", "-Command", `Start-Process '${quoted}'`],
+		};
+	}
 
+	if (platform === "darwin") return { command: "open", args: [url] };
+
+	if (platform === "win32") {
+		// `start` is a shell builtin, and the empty string is the window title
+		// cmd.exe would otherwise take the URL for.
+		return { command: "cmd.exe", args: ["/c", "start", "", url] };
+	}
+
+	return { command: "xdg-open", args: [url] };
+}
+
+/**
+ * A launcher the user supplied through `PI_TEAMS_BROWSER`.
+ *
+ * Takes a complete command line. `{}` in any argument is replaced by the URL;
+ * without it the URL is appended. This is the escape hatch for a WSL distro
+ * with no `xdg-open`: point it at a script, or at a Windows binary, instead of
+ * installing a shim for every program on the machine.
+ */
+function overrideLaunch(url: string, override: string): { command: string; args: string[] } {
+	const [command, ...rest] = splitCommandLine(override);
+	if (!command) throw new Error("PI_TEAMS_BROWSER is set but names no command.");
+
+	if (rest.some((part) => part.includes("{}"))) {
+		return { command, args: rest.map((part) => part.replaceAll("{}", url)) };
+	}
+	return { command, args: [...rest, url] };
+}
+
+/** Split on whitespace, honouring simple quoting. No expansion, no escaping. */
+function splitCommandLine(input: string): string[] {
+	const parts: string[] = [];
+	let current = "";
+	let quote: string | undefined;
+
+	for (const char of input) {
+		if (quote) {
+			if (char === quote) quote = undefined;
+			else current += char;
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			quote = char;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			if (current) parts.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+
+	if (current) parts.push(current);
+	return parts;
+}
+
+/**
+ * Run a launcher and wait until it is clear whether it worked.
+ *
+ * Two things have to be caught, and both were lost when this resolved on spawn.
+ * A missing launcher — `xdg-open` on a fresh WSL distro — reports ENOENT on
+ * `error` and never exits. A launcher that is present but finds no browser
+ * exits non-zero, which is how `xdg-open` says so.
+ *
+ * Resolving on spawn made both look like success, so the sign-in sat waiting
+ * for a redirect from a browser that had never opened, until the five minute
+ * timeout replaced the real cause with "Browser sign-in timed out".
+ */
+export function launchBrowser(
+	command: string,
+	args: string[],
+	graceMs = LAUNCH_EXIT_GRACE_MS,
+): Promise<void> {
+	return new Promise((resolve, reject) => {
+		let child: ChildProcess;
 		try {
-			const child = spawn(command as string, args as string[], {
-				detached: true,
-				stdio: "ignore",
-			});
-			child.on("error", reject);
-			child.unref();
-			resolve();
+			child = spawn(command, args, { detached: true, stdio: ["ignore", "ignore", "pipe"] });
 		} catch (err) {
 			reject(err instanceof Error ? err : new Error(String(err)));
+			return;
 		}
+
+		let settled = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let stderr = "";
+
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderr += String(chunk);
+		});
+
+		const settle = (err?: Error) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			child.unref();
+			if (err) reject(err);
+			else resolve();
+		};
+
+		// A launcher that stays alive is waiting on the browser, not failing.
+		timer = setTimeout(() => settle(), graceMs);
+
+		child.once("error", (err: NodeJS.ErrnoException) => {
+			const detail = err.code === "ENOENT" ? `${command} was not found` : err.message;
+			settle(new Error(`could not open a browser: ${detail}`));
+		});
+
+		child.once("close", (code, signal) => {
+			if (code === 0) settle();
+			else {
+				// `close`, not `exit`: the exit event can fire before the stderr pipe has
+				// drained, and the reason xdg-open gives is on stderr.
+				const why = stderr.trim() ? `: ${stderr.trim()}` : "";
+				settle(
+					new Error(
+						`could not open a browser: ${command} exited with ` +
+							`${code === null ? `signal ${signal ?? "unknown"}` : `code ${code}`}${why}`,
+					),
+				);
+			}
+		});
 	});
 }
 
+/** Open a URL in the user's default browser, detached from this process. */
+export async function openBrowser(url: string): Promise<void> {
+	const { command, args } = browserLaunch(url);
+
+	try {
+		await launchBrowser(command, args);
+	} catch (err) {
+		const cause = err instanceof Error ? err.message : String(err);
+		// The URL goes in every failure message. An exact exit code is only ever a
+		// hint — a shim and some real xdg-open implementations exit 0 without
+		// showing anything — so the one thing that always works is the address
+		// itself, pasted into a browser by hand.
+		const fallback = `Open it by hand instead: ${url}`;
+		if (isWsl()) {
+			throw new Error(
+				`${cause}. ${fallback} — from WSL the handoff expects Windows PowerShell at ` +
+					`${WSL_POWERSHELL}; set PI_TEAMS_BROWSER to use your own command instead.`,
+			);
+		}
+		throw new Error(`${cause}. ${fallback}`);
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Browser response pages
 // ---------------------------------------------------------------------------

package/src/extension/index.ts

@@ -53,6 +53,7 @@ import {
 	teamsSendChannelMessageTool,
 } from "../tools/teams-send-channel-message.ts";
 import { teamsListFilesTool } from "../tools/teams-list-files.ts";
+import { teamsDownloadFilesTool } from "../tools/teams-download-files.ts";
 import { teamsSearchMessagesTool } from "../tools/teams-search-messages.ts";
 import { teamsReactTool } from "../tools/teams-react.ts";
 import { teamsMarkReadTool } from "../tools/teams-mark-read.ts";
@@ -107,6 +108,7 @@ const tools = [
 	teamsSendChannelMessageTool,
 	teamsReplyChannelMessageTool,
 	teamsListFilesTool,
+	teamsDownloadFilesTool,
 	// Cross-cutting
 	teamsSearchMessagesTool,
 	teamsReactTool,

package/src/graph/client.ts

@@ -131,6 +131,53 @@ export async function graphRequest<T = unknown>(
 	}
 }
 
+/**
+ * Download a Graph resource as bytes.
+ *
+ * `graphRequest` parses JSON, so the two things that are not JSON — the images
+ * embedded in a message and the files attached to it — come through here. Same
+ * token handling and throttling back-off; the body is returned as it arrived,
+ * because its content type is the only hint at what the file is.
+ */
+export async function graphDownload(
+	conn: TeamsConnection,
+	path: string,
+	options: RequestOptions = {},
+): Promise<{ data: Buffer; contentType?: string }> {
+	const maxRetries = options.maxRetries ?? 3;
+	// An absolute URL is allowed here too: Graph answers a hostedContent with a
+	// redirect to a pre-authenticated location, and `fetch` follows it.
+	const url = buildUrl(conn, path, options);
+
+	let attempt = 0;
+	for (;;) {
+		const token = await getAccessToken(conn, options.signal);
+
+		const response = await fetch(url, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${token.accessToken}`, ...options.headers },
+			signal: options.signal,
+		});
+
+		if (response.ok) {
+			return {
+				data: Buffer.from(await response.arrayBuffer()),
+				contentType: response.headers.get("content-type") ?? undefined,
+			};
+		}
+
+		if ((response.status === 429 || response.status === 503) && attempt < maxRetries) {
+			const retryAfter = Number(response.headers.get("Retry-After") ?? "0");
+			const waitMs = retryAfter > 0 ? retryAfter * 1000 : Math.min(2 ** attempt * 1000, 8000);
+			attempt += 1;
+			await sleep(waitMs);
+			continue;
+		}
+
+		throw await toGraphError(response);
+	}
+}
+
 async function toGraphError(response: Response): Promise<GraphError> {
 	let code = `HTTP${response.status}`;
 	let message = response.statusText || `Request failed with status ${response.status}`;

package/src/graph/mappers.ts

@@ -23,6 +23,7 @@ import type {
 	SignedInUser,
 	TeamSummary,
 } from "../types.ts";
+import { imageUrlsInHtml } from "../utils/attachments.ts";
 import { htmlToText } from "../utils/formatting.ts";
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -216,9 +217,21 @@ function mapAttachments(raw: Raw): MessageAttachment[] {
 		name: a.name ?? undefined,
 		contentType: a.contentType ?? undefined,
 		contentUrl: a.contentUrl ?? undefined,
+		contentBytes: a.contentBytes ?? undefined,
 	}));
 }
 
+/**
+ * Inline images, pulled out of the body before it is flattened to text.
+ *
+ * `htmlToText` turns every `<img>` into `[image: alt]`, which is right for a
+ * reader that only wants prose and wrong for one that could fetch the image:
+ * the URL it drops points at Graph.
+ */
+function mapImageUrls(raw: Raw): string[] {
+	return imageUrlsInHtml(raw.body?.content ?? "");
+}
+
 function mapMentions(raw: Raw): PersonRef[] {
 	return (raw.mentions ?? [])
 		.map((m: Raw) => mapPerson(m.mentioned) ?? { displayName: m.mentionText ?? "(mention)" })
@@ -241,6 +254,7 @@ export function mapMessage(raw: Raw, location?: MessageLocation): MessageSummary
 		mentions: mapMentions(raw),
 		reactions: mapReactions(raw),
 		attachments: mapAttachments(raw),
+		imageUrls: mapImageUrls(raw),
 		webUrl: raw.webUrl ?? undefined,
 		location,
 	};

package/src/graph/media.ts

@@ -0,0 +1,174 @@
+/**
+ * Downloading what a message carries.
+ *
+ * A tool result is text, so bytes have to reach the disk before an agent can
+ * look at them — that is the whole job here. Both sources are Graph: inline
+ * images live in `hostedContents`, files are `attachments`, and a small
+ * attachment arrives inline as base64 instead of a URL.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { TeamsConnection } from "../config/index.ts";
+import type { MessageAttachment, MessageSummary } from "../types.ts";
+import { extensionForContentType, safeFileName } from "../utils/attachments.ts";
+import { formatGraphError } from "../utils/errors.ts";
+import { graphDownload } from "./client.ts";
+
+/**
+ * Refuse anything larger.
+ *
+ * A message can carry a two gigabyte video, and a tool call that quietly fills
+ * the disk is worse than one that says no.
+ */
+export const MAX_FILE_BYTES = 25 * 1024 * 1024;
+
+export interface SavedFile {
+	path: string;
+	name: string;
+	bytes: number;
+	kind: "image" | "attachment";
+	contentType?: string;
+}
+
+export interface SkippedFile {
+	name: string;
+	reason: string;
+	/** The URL to fetch by hand, when there is one. */
+	url?: string;
+}
+
+export interface SaveResult {
+	saved: SavedFile[];
+	skipped: SkippedFile[];
+}
+
+function tooBig(bytes: number): string {
+	const mb = Math.round((bytes / (1024 * 1024)) * 10) / 10;
+	return `larger than ${Math.round(MAX_FILE_BYTES / (1024 * 1024))} MB (${mb} MB)`;
+}
+
+/** Append the extension the content type implies, when the name has none. */
+function nameWithExtension(name: string | undefined, contentType: string | undefined, fallback: string): string {
+	const safe = safeFileName(name, fallback);
+	if (/\.[a-z0-9]{1,5}$/i.test(safe)) return safe;
+	return safe + extensionForContentType(contentType);
+}
+
+/** Keep two attachments with the same name from overwriting each other. */
+function uniqueName(used: Set<string>, name: string): string {
+	if (!used.has(name)) {
+		used.add(name);
+		return name;
+	}
+	const dot = name.lastIndexOf(".");
+	const stem = dot > 0 ? name.slice(0, dot) : name;
+	const suffix = dot > 0 ? name.slice(dot) : "";
+	for (let n = 2; ; n += 1) {
+		const candidate = `${stem}-${n}${suffix}`;
+		if (!used.has(candidate)) {
+			used.add(candidate);
+			return candidate;
+		}
+	}
+}
+
+/**
+ * Save every image and attachment of one message into `dir`.
+ *
+ * Never throws for a single failed file: a message with three images and one
+ * broken link should still leave the three on disk, with the failure reported
+ * next to them.
+ */
+export async function saveMessageFiles(
+	conn: TeamsConnection,
+	message: MessageSummary,
+	dir: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<SaveResult> {
+	const saved: SavedFile[] = [];
+	const skipped: SkippedFile[] = [];
+	const used = new Set<string>();
+
+	await mkdir(dir, { recursive: true });
+
+	const write = async (
+		baseName: string,
+		contentType: string | undefined,
+		data: Buffer,
+		kind: SavedFile["kind"],
+	): Promise<void> => {
+		const name = uniqueName(used, baseName);
+		const path = join(dir, name);
+		await writeFile(path, data);
+		saved.push({ path, name, bytes: data.byteLength, kind, contentType });
+	};
+
+	// Inline images carry no name, so they are numbered the way they appear.
+	let imageIndex = 0;
+	for (const url of message.imageUrls) {
+		imageIndex += 1;
+		const label = `image ${imageIndex}`;
+		try {
+			const { data, contentType } = await graphDownload(conn, url, { signal: options.signal });
+			if (data.byteLength > MAX_FILE_BYTES) {
+				skipped.push({ name: label, reason: tooBig(data.byteLength), url });
+				continue;
+			}
+			const extension = extensionForContentType(contentType) || ".bin";
+			await write(`${message.id}-${imageIndex}${extension}`, contentType, data, "image");
+		} catch (err) {
+			skipped.push({ name: label, reason: formatGraphError(err), url });
+		}
+	}
+
+	for (const attachment of message.attachments) {
+		const label = attachment.name ?? "attachment";
+
+		if (attachment.contentBytes) {
+			// Small attachments arrive with the message itself.
+			const data = Buffer.from(attachment.contentBytes, "base64");
+			if (data.byteLength > MAX_FILE_BYTES) {
+				skipped.push({ name: label, reason: tooBig(data.byteLength), url: attachment.contentUrl });
+				continue;
+			}
+			await write(
+				nameWithExtension(attachment.name, attachment.contentType, `attachment-${message.id}`),
+				attachment.contentType,
+				data,
+				"attachment",
+			);
+			continue;
+		}
+
+		if (!attachment.contentUrl) {
+			skipped.push({ name: label, reason: describeMissing(attachment) });
+			continue;
+		}
+
+		try {
+			const { data, contentType } = await graphDownload(conn, attachment.contentUrl, {
+				signal: options.signal,
+			});
+			if (data.byteLength > MAX_FILE_BYTES) {
+				skipped.push({ name: label, reason: tooBig(data.byteLength), url: attachment.contentUrl });
+				continue;
+			}
+			await write(
+				nameWithExtension(attachment.name, contentType ?? attachment.contentType, `attachment-${message.id}`),
+				contentType ?? attachment.contentType,
+				data,
+				"attachment",
+			);
+		} catch (err) {
+			skipped.push({ name: label, reason: formatGraphError(err), url: attachment.contentUrl });
+		}
+	}
+
+	return { saved, skipped };
+}
+
+function describeMissing(attachment: MessageAttachment): string {
+	const type = attachment.contentType ? ` (${attachment.contentType})` : "";
+	return `no content URL and no inline bytes${type} — likely a card or a code snippet, not a file`;
+}

package/src/tools/teams-download-files.ts

@@ -0,0 +1,145 @@
+/**
+ * teams_download_files — save the files and images a message carries.
+ *
+ * The read tools flatten a message to text, which is right for prose and wrong
+ * for anything with bytes in it. This is the counterpart: it fetches the images
+ * embedded in messages and the files attached to them into a directory, and
+ * returns the paths, so a reader can open them.
+ */
+
+import { join } from "node:path";
+import { Type } from "typebox";
+import { getAgentDir } from "../config/index.ts";
+import { saveMessageFiles, type SavedFile, type SkippedFile } from "../graph/media.ts";
+import {
+	getChannelMessage,
+	getChatMessage,
+	listChannelMessages,
+	listChatMessages,
+} from "../graph/messages.ts";
+import type { MessageSummary } from "../types.ts";
+import { safeFileName } from "../utils/attachments.ts";
+import { formatDownloadResult } from "../utils/formatting.ts";
+import { requireChannel, requireChat, TargetError } from "./resolve.ts";
+import {
+	AccountParam,
+	TenantParam,
+	connectionFor,
+	run,
+	textResult,
+	type ToolContext,
+	type ToolResult,
+} from "./shared.ts";
+
+export const teamsDownloadFilesTool = {
+	name: "teams_download_files",
+	description:
+		"Download the images embedded in Teams messages and the files attached to them to a local " +
+		"directory, and return the paths so they can be opened. Covers files attached to a message, not " +
+		"a channel's SharePoint folder (see teams_list_files).",
+	parameters: Type.Object({
+		chat: Type.Optional(Type.String({ description: "Chat ID, topic, or a participant's name/e-mail" })),
+		channel: Type.Optional(Type.String({ description: "Channel name or ID, or a 'Team/Channel' path" })),
+		team: Type.Optional(Type.String({ description: "Team name or ID (omit when using a path)" })),
+		messageId: Type.Optional(
+			Type.String({ description: "Download only this message instead of scanning recent ones" }),
+		),
+		limit: Type.Optional(
+			Type.Number({ description: "How many recent messages to scan (default 10, max 50)" }),
+		),
+		dir: Type.Optional(Type.String({ description: "Directory to save into (default: pi-teams-files)" })),
+		account: AccountParam,
+		tenant: TenantParam,
+	}),
+	promptSnippet: "Download files and images from Teams messages",
+
+	async execute(
+		_toolCallId: string,
+		params: {
+			chat?: string;
+			channel?: string;
+			team?: string;
+			messageId?: string;
+			limit?: number;
+			dir?: string;
+			account?: string;
+			tenant?: string;
+		},
+		signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			if (params.chat && params.channel) {
+				throw new TargetError("Pass either 'chat' or 'channel', not both.");
+			}
+			if (!params.chat && !params.channel) {
+				throw new TargetError("Pass a 'chat' or a 'channel' to download from.");
+			}
+
+			const conn = connectionFor(ctx, params.account, params.tenant);
+			const scanLimit = Math.min(Math.max(params.limit ?? 10, 1), 50);
+
+			let label: string;
+			let slug: string;
+			let messages: MessageSummary[];
+
+			if (params.chat) {
+				const chat = await requireChat(conn, params.chat, "read", signal);
+				label = chat.label;
+				slug = safeFileName(chat.label, chat.id);
+				messages = params.messageId
+					? await one(await getChatMessage(conn, chat.id, params.messageId, signal), params.messageId)
+					: await listChatMessages(conn, chat.id, { max: scanLimit, signal });
+			} else {
+				const { team, channel } = await requireChannel(
+					conn,
+					params.team,
+					params.channel as string,
+					"read",
+					signal,
+				);
+				label = `${team.displayName}/${channel.displayName}`;
+				slug = safeFileName(`${team.displayName}-${channel.displayName}`, channel.id);
+				messages = params.messageId
+					? await one(await getChannelMessage(conn, channel, params.messageId, signal), params.messageId)
+					: await listChannelMessages(conn, channel, { max: scanLimit, signal });
+			}
+
+			const dir = params.dir ?? join(getAgentDir(), "pi-teams-files", slug);
+
+			const saved: SavedFile[] = [];
+			const skipped: SkippedFile[] = [];
+			for (const message of messages) {
+				const result = await saveMessageFiles(conn, message, dir, { signal });
+				saved.push(...result.saved);
+				skipped.push(...result.skipped);
+			}
+
+			const withFiles = messages.filter(
+				(m) => m.imageUrls.length > 0 || m.attachments.length > 0,
+			).length;
+
+			return textResult(
+				[
+					formatDownloadResult(label, dir, saved, skipped),
+					"",
+					`Scanned ${messages.length} message${messages.length === 1 ? "" : "s"}` +
+						`${withFiles === 0 ? ", none with files" : ""}.`,
+				].join("\n"),
+				{
+					dir,
+					saved: saved.map((file) => file.path),
+					skipped: skipped.length,
+					scanned: messages.length,
+				},
+			);
+		});
+	},
+};
+
+/** A single message, or a clear error — rather than silently downloading nothing. */
+async function one(message: MessageSummary | undefined, messageId: string): Promise<MessageSummary[]> {
+	if (!message) throw new TargetError(`No message ${messageId} in this conversation.`);
+	return [message];
+}

package/src/types.ts

@@ -121,6 +121,13 @@ export interface MessageSummary {
 	mentions: PersonRef[];
 	reactions: MessageReaction[];
 	attachments: MessageAttachment[];
+	/**
+	 * URLs of the images embedded in the message body.
+	 *
+	 * Graph URLs, absolute and ready to fetch — Teams writes them into the HTML
+	 * as the `src` of each `<img>`. Empty for a text-only message.
+	 */
+	imageUrls: string[];
 	webUrl?: string;
 	/** Where the message lives — used for follow-up calls and scope checks */
 	location?: MessageLocation;
@@ -137,6 +144,8 @@ export interface MessageAttachment {
 	name?: string;
 	contentType?: string;
 	contentUrl?: string;
+	/** Small attachments arrive inline as base64 instead of a URL. */
+	contentBytes?: string;
 }
 
 export interface MessageLocation {

package/src/utils/attachments.ts

@@ -0,0 +1,76 @@
+/**
+ * What a message carries besides text.
+ *
+ * Two different mechanisms hide behind "there was a picture in that message":
+ * an inline image is a `hostedContent` referenced from the message HTML, and a
+ * file is an `attachment` on the message. For a long time only the second one
+ * reached the mapper, so a reader saw `[image: Bild]` and nothing else — the
+ * URL was in the body all along, pointing straight at Graph.
+ *
+ * The helpers here are pure, because the shapes are the part that quietly goes
+ * wrong and they can be tested without a Graph call.
+ */
+
+/** Absolute URLs of the inline images in a message body, in the order shown. */
+export function imageUrlsInHtml(html: string): string[] {
+	const urls: string[] = [];
+	for (const match of html.matchAll(/<img\b[^>]*\bsrc=["']([^"']+)["']/gi)) {
+		const src = decodeEntities(match[1] ?? "");
+		// An <img> can also point at an outside host. Only content that lives in
+		// the message itself is ours to fetch.
+		if (/\/hostedContents\//i.test(src) && !urls.includes(src)) urls.push(src);
+	}
+	return urls;
+}
+
+function decodeEntities(input: string): string {
+	return input
+		.replace(/&amp;/g, "&")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&#(\d+);/g, (_match, code: string) => String.fromCharCode(Number(code)));
+}
+
+const CONTENT_TYPE_EXTENSIONS: Record<string, string> = {
+	"image/png": ".png",
+	"image/jpeg": ".jpg",
+	"image/jpg": ".jpg",
+	"image/gif": ".gif",
+	"image/webp": ".webp",
+	"image/bmp": ".bmp",
+	"image/svg+xml": ".svg",
+	"application/pdf": ".pdf",
+	"text/plain": ".txt",
+	"text/csv": ".csv",
+	"application/json": ".json",
+	"application/zip": ".zip",
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+	"application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+};
+
+/** Extension for a response content type, including the dot. Empty when unknown. */
+export function extensionForContentType(contentType: string | undefined): string {
+	const type = (contentType ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+	return CONTENT_TYPE_EXTENSIONS[type] ?? "";
+}
+
+/**
+ * A name that can be written on any platform, and is never empty.
+ *
+ * Keeps the extension when shortening: `slice` from the front would turn
+ * `quarterly-report.pdf` into a name ending in `-report.pdf` at best and into
+ * an unnamed blob at worst.
+ */
+export function safeFileName(name: string | undefined, fallback: string): string {
+	const base = (name ?? "").split(/[\\/]/).pop() ?? "";
+	const cleaned = base
+		// Reserved on Windows, plus control characters.
+		.replace(/[\u0000-\u001f<>:"|?*]/g, "_")
+		// A leading dot would make the file invisible in most file managers.
+		.replace(/^[.\s]+/, "")
+		.trim();
+	if (!cleaned) return fallback;
+	return cleaned.length > 120 ? cleaned.slice(-120) : cleaned;
+}

package/src/utils/environment.ts

@@ -12,26 +12,43 @@
  * The interactive sign-in needs two things: a browser to open, and a loopback
  * listener that browser can reach. Over SSH both assumptions break — `open`
  * would launch a browser on the *remote* machine, where nobody is looking — so
- * those sessions get the device code flow instead.
+ * those sessions get the device code flow instead. In WSL the browser is on
+ * the Windows side of the same machine, which is what `isWsl` accounts for.
  *
- * Set `PI_TEAMS_NO_BROWSER=1` to force that fallback anywhere.
+ * Set `PI_TEAMS_NO_BROWSER=1` to force that fallback anywhere, or
+ * `PI_TEAMS_BROWSER` to a command line that opens a URL where the built-in
+ * launchers cannot.
  */
+export function isWsl(): boolean {
+	if (process.platform !== "linux") return false;
+	return !!(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+}
+
 export function canOpenBrowser(): boolean {
 	if (process.env.PI_TEAMS_NO_BROWSER) return false;
 
+	// An explicit launcher is a statement that a browser is reachable, even where
+	// the heuristics below would not find one — a WSL setup, or a machine whose
+	// browser is reached through something custom.
+	if (process.env.PI_TEAMS_BROWSER?.trim()) return true;
+
 	// A remote shell: the browser would appear on the wrong machine.
 	if (process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.SSH_CLIENT) return false;
 
 	if (process.platform === "darwin" || process.platform === "win32") return true;
 
+	// WSL is not a headless Linux: the browser lives on Windows and `openBrowser`
+	// hands the URL over to it. DISPLAY says nothing either way — WSLg sets it on
+	// Windows 11 and not on Windows 10, while the handoff works on both.
+	if (isWsl()) return true;
+
 	// Linux and the BSDs need a display server for a browser to appear at all.
 	return !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
 }
 
 /** Why the interactive flow is unavailable, phrased for a user-facing message. */
 export function browserUnavailableReason(): string {
-	if (process.env.PI_TEAMS_NO_BROWSER) return "PI_TEAMS_NO_BROWSER is set";
-	if (process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.SSH_CLIENT) {
+	if (process.env.PI_TEAMS_NO_BROWSER) return "PI_TEAMS_NO_BROWSER is set";	if (process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.SSH_CLIENT) {
 		return "this is an SSH session, so the browser would open on the wrong machine";
 	}
 	if (process.platform !== "darwin" && process.platform !== "win32") {

package/src/utils/formatting.ts

@@ -298,6 +298,12 @@ export function formatMessage(message: MessageSummary, options: { showId?: boole
 	if (message.attachments.length > 0) {
 		meta.push(`attachments: ${message.attachments.map((a) => a.name ?? "file").join(", ")}`);
 	}
+	if (message.imageUrls.length > 0) {
+		// The images themselves are not in the text. Saying how many there are is
+		// what tells a reader that something is missing and where to get it.
+		const count = message.imageUrls.length;
+		meta.push(`${count} image${count === 1 ? "" : "s"} — use teams_download_files`);
+	}
 	if (message.replyCount !== undefined && message.replyCount > 0) {
 		meta.push(`${message.replyCount} repl${message.replyCount === 1 ? "y" : "ies"}`);
 	}
@@ -404,3 +410,40 @@ export function formatFileList(items: readonly DriveItemSummary[], title: string
 	}
 	return lines.join("\n");
 }
+
+/**
+ * The result of saving a message's files.
+ *
+ * Typed structurally on purpose: this module is a leaf and knows nothing about
+ * Graph, so the caller passes the shape it already has.
+ */
+export function formatDownloadResult(
+	label: string,
+	dir: string,
+	saved: readonly { path: string; name: string; bytes: number; kind: string }[],
+	skipped: readonly { name: string; reason: string; url?: string }[],
+): string {
+	const lines = [`## Files from ${label}`, ""];
+
+	if (saved.length === 0) {
+		lines.push("Nothing to download.");
+	} else {
+		lines.push(`${saved.length} file${saved.length === 1 ? "" : "s"} saved to \`${dir}\`:`, "");
+		for (const file of saved) {
+			const icon = file.kind === "image" ? "🖼" : "📄";
+			lines.push(`- ${icon} \`${file.path}\` (${formatBytes(file.bytes)})`);
+		}
+		lines.push("", "Open them with the file-reading tool.");
+	}
+
+	if (skipped.length > 0) {
+		lines.push("", "Not saved:");
+		for (const file of skipped) {
+			// The URL is the fallback: it can be opened by hand where the download
+			// was refused.
+			lines.push(`- **${file.name}** — ${file.reason}${file.url ? `\n  ${file.url}` : ""}`);
+		}
+	}
+
+	return lines.join("\n");
+}