@patimweb/pi-teams 1.5.1 → 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.5.1",
+  "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/skills/teams-collaboration/SKILL.md

@@ -131,36 +131,91 @@ instead of trying anyway.
 ## How to format a Teams message
 
 A Teams chat is a chat bubble, not a document. What arrives badly is long
-prose: the reader has to hunt for the point, and it reads as if a machine wrote
-it. The body is rendered as HTML — markdown is converted for you, so write
+prose: the answer is buried, the reader has to hunt for it, and it reads as if a
+machine wrote it. "Keep it short" does not fix that on its own — a shape does.
+The body is rendered as HTML, and markdown is converted for you, so write
 markdown and let the tool do the rest.
 
-**Reach for this shape, not for paragraphs:**
+**The shape, which is nearly always this:**
 
 ```
-Kurz: die QA-Umgebung läuft wieder.
+QA läuft wieder.
 
 - Ursache: abgelaufenes Zertifikat
 - Fix: erneuert und neu deployt
 - Offen: Monitoring für 90 Tage
 ```
 
-- **Lead with the answer.** The first line should work as the whole message for
-  someone who reads nothing else.
-- **Three short paragraphs at most.** If it needs more, it is a document — put
-  it in a file or a wiki page and link it.
+Line one is the answer. Then a blank line, then only what the reader needs in
+order to act on it. Five lines is already a long chat message.
+
+**Before and after.** Both versions say the same thing; only one is a chat:
+
+> **So nicht:** Ich habe mir die QA-Umgebung jetzt angeschaut und konnte den
+> Fehler reproduzieren. Das Problem liegt darin, dass das TLS-Zertifikat
+> abgelaufen war, wodurch alle Requests fehlgeschlagen sind. Ich habe es dann
+> erneuert und die Umgebung neu deployt, jetzt läuft wieder alles. Ich würde
+> allerdings noch empfehlen, das Monitoring einzurichten, damit das nicht
+> wieder passiert.
+
+> **So:** QA läuft wieder.
+>
+> - Ursache: abgelaufenes TLS-Zertifikat
+> - Fix: erneuert und neu deployt
+> - Empfehlung: Monitoring auf die Ablaufdaten
+
+**Three skeletons that cover most messages:**
+
+*Antwort auf eine Frage* — the answer, then at most one line of reasoning:
+
+```
+Ja, Freitag passt.
+
+Ich bin bis 14:00 im Workshop, danach jederzeit.
+```
+
+*Status* — outcome first, then what is still open:
+
+```
+Deployment ist durch, Release Notes stehen im Wiki: <Link>
+
+Offen: Smoke-Test auf Produktion, mache ich heute Nachmittag.
+```
+
+*Entscheidung nötig* — the decision, the options, the deadline:
+
+```
+Ich brauche bis morgen eine Entscheidung zum Sync-Intervall.
+
+- 5 Min: schnell, ~3× Last auf dem SAP-System
+- 15 Min: entspannt, dafür Verzögerung im Reporting
+```
+
+**Rules**
+
+- **The first line carries the message.** Someone who reads only that line
+  should know the outcome.
 - **Bullets for anything enumerable** — causes, options, next steps. Three items
-  and up belong in a list, not in a sentence with commas.
+  and up are a list; two are a sentence.
+- **One idea per line.** A line break is free; a clause chain held together by
+  commas is not.
 - **Bold the one thing that must not be missed**, and only that. Bold used
   everywhere is bold nowhere.
 - **Numbers, names and dates exactly as they are.** Do not round a figure or
   paraphrase a deadline into something friendlier.
 - **One question per message.** Two questions get one answer.
+- **No greeting and no closing.** "Hallo zusammen", "Ich habe mir das mal
+  angeschaut", "Kurz zusammengefasst:" and "Sag Bescheid, wenn du Fragen hast"
+  are all noise in a chat. The message starts with the answer and stops when it
+  is done.
+- **Over five lines, it is a document.** Put it in a wiki page or a file and send
+  the link with one sentence around it.
 
 **What Teams renders:** `**bold**`, `*italic*`, `` `code` ``, `~~struck~~`,
-`[label](url)`, `- bullets`, `1. numbered`, ``` fences. A `# heading` arrives as
-a bold line — fine for structure, not for hierarchy. **Tables are not supported
-in a chat**: convert them to bullets, or put the table in a file and link it.
+`[label](url)`, `- bullets`, `1. numbered`, and code fences. A `# heading`
+arrives as a bold line — fine for structure, not for hierarchy. **Tables are not
+supported in a chat**: convert them to bullets, or put the table in a file and
+link it.
 
 **Language and tone:** answer in the language of the conversation, in the
 register of the people in it. Short forms are normal in a chat ("passt", "ok,
@@ -323,9 +378,9 @@ teams_watch:
 2. If an answer is warranted, send it with `teams_send_chat_message` to the
    **chat ID from the prompt** — never re-resolve the chat by name. pi posts as
    the user, so the wrong chat is a wrong statement in the user's name.
-3. Keep it to the shape in *How to format a Teams message*: answer first, three
-   short paragraphs at most, bullets for lists. An unrequested message has to be
-   readable at a glance.
+3. Keep it to the shape in *How to format a Teams message*: the answer on the
+   first line, at most five short lines, bullets for anything enumerable. An
+   unrequested message has to be readable at a glance.
 4. If no answer is warranted, say so in one line and stop. Do not react, do not
    touch other chats, do not post to a channel.
 

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/tools/teams-send-channel-message.ts

@@ -10,6 +10,7 @@ import { Type } from "typebox";
 import { replyToChannelMessage, sendChannelMessage } from "../graph/messages.ts";
 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 { assertAccess } from "../safety/index.ts";
 import { truncate } from "../utils/formatting.ts";
@@ -58,10 +59,7 @@ async function resolveMentions(
 const sharedParams = {
 	channel: 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)" })),
-	body: Type.String({
-			description:
-				"Message text as lightweight markdown (bold, italics, code, bullets, numbered lists, links)",
-		}),
+	body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 	account: AccountParam,
 	tenant: TenantParam,
 	mentions: Type.Optional(
@@ -85,7 +83,7 @@ export const teamsSendChannelMessageTool = {
 	promptGuidelines: [
 		"Write in the user's voice — the post is attributed to them, not to an assistant.",
 		"Show the exact text and the target channel before posting when there is any ambiguity.",
-		"Format for a chat, not for a document: lead with the answer, three short paragraphs at most, bullets for lists. Bold, italics, code, links and bullets are rendered; headings become bold lines and tables are not supported — keep those out.",
+		CHAT_SHAPE_GUIDELINE,
 		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
 
@@ -180,6 +178,7 @@ export const teamsReplyChannelMessageTool = {
 		messageId: Type.String({ description: "ID of the thread's opening message" }),
 	}),
 	promptSnippet: "Reply in a Teams channel thread as the user",
+	promptGuidelines: [CHAT_SHAPE_GUIDELINE],
 
 	async execute(
 		_toolCallId: string,

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

@@ -21,6 +21,7 @@ import { formatGraphError } from "../utils/errors.ts";
 import { resolveUserId } from "../graph/me.ts";
 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 { truncate } from "../utils/formatting.ts";
 import { requireChat } from "./resolve.ts";
@@ -56,10 +57,7 @@ export const teamsSendChatMessageTool = {
 		"where the mention should appear.",
 	parameters: Type.Object({
 		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
-		body: Type.String({
-			description:
-				"Message text as lightweight markdown (bold, italics, code, bullets, numbered lists, links)",
-		}),
+		body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 		account: AccountParam,
 		tenant: TenantParam,
 		mentions: Type.Optional(
@@ -79,7 +77,7 @@ export const teamsSendChatMessageTool = {
 		"Write the message in the user's voice — it is sent from their account, not from an assistant.",
 		"Show the user the exact text before sending when the intent is even slightly ambiguous.",
 		"Do not add signatures, or a note that the message was written by an AI: the sending tool appends the configured AI disclosure itself (on by default), so writing one into the body duplicates it.",
-		"Format for a chat, not for a document: lead with the answer, three short paragraphs at most, bullets for lists. Bold, italics, code, links and bullets are rendered; headings become bold lines and tables are not supported — keep those out.",
+		CHAT_SHAPE_GUIDELINE,
 		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
 

package/src/tools/teams-update-message.ts

@@ -14,6 +14,7 @@
 import { Type } from "typebox";
 import { updateMessage } from "../graph/messages.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 { requireChat } from "./resolve.ts";
 import {
@@ -36,7 +37,7 @@ export const teamsUpdateMessageTool = {
 		"Use this instead of deleting a message and sending a corrected copy.",
 	parameters: Type.Object({
 		messageId: Type.String({ description: "ID of the message to edit" }),
-		body: Type.String({ description: "The new message text (lightweight markdown by default)" }),
+		body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
 		html: Type.Optional(Type.Boolean({ description: "Treat 'body' as raw HTML instead of markdown" })),
 		account: AccountParam,
@@ -45,6 +46,7 @@ export const teamsUpdateMessageTool = {
 	promptSnippet: "Edit a message the user sent in Teams",
 	promptGuidelines: [
 		"Use teams_update_message to correct a message the user already sent, rather than deleting it and posting a replacement.",
+		CHAT_SHAPE_GUIDELINE,
 	],
 
 	async execute(

package/src/utils/chat-style.ts

@@ -0,0 +1,65 @@
+/**
+ * The shape of a Teams message.
+ *
+ * A chat bubble is read at a glance, on a phone, between two other things. The
+ * failure mode is well known and it is not a lack of language skill: the model
+ * writes a *document*. It opens with context, builds up to the point, and
+ * closes with a summary — so the reader has to hunt for the answer, which is
+ * exactly the "wall of text" people complain about.
+ *
+ * Telling the model to "be brief" does not fix it. Vague length advice is the
+ * weakest kind of formatting instruction; an explicit shape and a worked
+ * example are the strongest, and they have to sit where the message is being
+ * composed rather than in a document the model may or may not have loaded.
+ *
+ * So one shape, stated the same way in every place that matters:
+ *
+ *   - the `body` parameter description — in context at the moment of writing,
+ *     which is the highest-attention placement available,
+ *   - the per-tool guideline bullet — in context for the whole session, and
+ *     flat in the Guidelines list, so it has to name its tools,
+ *   - the skill and the listen-mode prompt — which carry the worked example
+ *     (`skills/teams-collaboration/SKILL.md`).
+ *
+ * Keeping it in one module is the point. Four tools used to carry their own
+ * copy of one sentence, they had drifted, and the sentence they shared was
+ * "three short paragraphs at most" — which permits prose, and got prose.
+ */
+
+/**
+ * What a message body is, and what shape it has.
+ *
+ * Used as the `body` parameter description on every tool that sends one, so it
+ * is read at the moment the text is written. Kept short on purpose: it is in
+ * the tool schema, and every tool in this package is in context at once.
+ */
+export const CHAT_MESSAGE_BODY_DESCRIPTION =
+	"Message text as lightweight markdown, in chat shape: the answer on the first line, then at most 5 short " +
+	"lines, `- ` bullets for anything enumerable, one idea per line. No greeting, no closing, no summary. " +
+	"Rendered: **bold**, *italic*, `code`, ~~struck~~, [label](url), `- ` bullets, `1. ` numbered, ``` fences. " +
+	"A `#` heading arrives as a bold line; tables are not rendered at all.";
+
+/**
+ * The same shape as one guideline bullet.
+ *
+ * `promptGuidelines` are appended flat to the system prompt's Guidelines
+ * section with no tool-name prefix, so this names every tool it applies to —
+ * otherwise the model cannot tell which "the message body" means. It stays on
+ * one line for the same reason: it is a bullet in someone else's list.
+ */
+export const CHAT_SHAPE_GUIDELINE =
+	"teams_send_chat_message, teams_send_channel_message, teams_reply_channel_message and teams_update_message " +
+	"write chat shape, not a document: the answer on the first line, at most 5 short lines, `- ` bullets for " +
+	"enumerable items, no greeting, no closing summary, no tables.";
+
+/**
+ * The shape as prose, for the listen-mode prompt.
+ *
+ * Listen mode is the case where this matters most: an answer that arrives
+ * unrequested has to be readable at a glance, because the recipient is not
+ * waiting for it and did not ask for it.
+ */
+export const CHAT_SHAPE_FOR_LISTEN_MODE =
+	"Format it as a chat bubble, not a document: the answer on the first line, at most 5 short lines, " +
+	"`- ` bullets for anything enumerable, no greeting and no closing. The recipient is not expecting this " +
+	"message, so it has to be readable at a glance.";

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);
 }

package/src/watch/prompt.ts

@@ -16,6 +16,7 @@
  */
 
 import type { MessageSummary, SignedInUser } from "../types.ts";
+import { CHAT_SHAPE_FOR_LISTEN_MODE } from "../utils/chat-style.ts";
 import type { WatchEvent } from "./loop.ts";
 
 function senderName(message: MessageSummary): string {
@@ -114,9 +115,7 @@ export function composeWatchPrompt(event: WatchEvent, me?: SignedInUser): string
 			"the sending tool appends the configured AI disclosure itself.",
 		"- If it does not: say so in one line and stop.",
 		"",
-		"Format it for a chat bubble, not a document: the answer first, three short paragraphs at most, " +
-			"bullets for anything enumerable, no tables. The recipient is not expecting this message, so it has " +
-			"to be readable at a glance.",
+		CHAT_SHAPE_FOR_LISTEN_MODE,
 		"",
 		"Do not react, do not touch other chats, and do not send anything to a channel.",
 	].join("\n");