@patimweb/pi-teams 1.6.0 → 1.6.1

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,12 @@ 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 `/mnt/c` is not mounted, set `PI_TEAMS_NO_BROWSER=1` and use the device code flow — see `AADSTS53003` if Conditional Access blocks that |
 
 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.6.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/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,139 @@ 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 } = {},
+): { command: string; args: string[] } {
+	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] };
+}
+
+/**
+ * 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);
+		if (isWsl()) {
+			throw new Error(
+				`${cause}. From WSL the URL is handed to Windows PowerShell at ` +
+					`${WSL_POWERSHELL}; if the Windows drive is not mounted there, set ` +
+					"PI_TEAMS_NO_BROWSER=1 to use the device code flow instead.",
+			);
+		}
+		throw err instanceof Error ? err : new Error(cause);
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Browser response pages
 // ---------------------------------------------------------------------------

package/src/utils/environment.ts

@@ -12,10 +12,16 @@
  * 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.
  */
+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;
 
@@ -24,6 +30,11 @@ export function canOpenBrowser(): boolean {
 
 	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);
 }