@patimweb/pi-teams 1.0.0 → 1.2.0

package/src/status.ts

@@ -6,7 +6,7 @@
  */
 
 import type { TeamsConnection } from "./config/index.ts";
-import { getToken, isFresh } from "./auth/token-store.ts";
+import { readCacheSummary } from "./auth/cache-plugin.ts";
 import { formatPermissions } from "./config/scope.ts";
 
 /** Immutable snapshot of the active Teams connection. */
@@ -27,6 +27,10 @@ export interface ConnectionCard {
 	otherAccounts: string[];
 	/** Rendered scope rules */
 	permissionSummary: string;
+	/** Listen mode is switched on */
+	watching?: boolean;
+	/** One line on what the watcher is doing, when it runs */
+	watchSummary?: string;
 }
 
 export function buildConnectionCard(
@@ -34,7 +38,7 @@ export function buildConnectionCard(
 ): ConnectionCard | undefined {
 	if (!conn) return undefined;
 
-	const token = getToken(conn.account, conn.tenantId);
+	const cache = readCacheSummary(conn.account, conn.tenantId);
 
 	return {
 		account: conn.account,
@@ -43,11 +47,26 @@ export function buildConnectionCard(
 		tenantId: conn.tenantId,
 		authMode: conn.authMode,
 		safetyLevel: conn.safetyLevel,
-		user: token?.user?.upn ?? token?.user?.displayName,
-		signedIn: isFresh(token) || !!token?.refreshToken,
-		expiresAt: token ? new Date(token.expiresAt).toISOString() : undefined,
+		user: cache.username ?? cache.name,
+		// A cached session counts as signed in even when the access token has
+		// expired: MSAL renews it silently on the next call.
+		signedIn: cache.present,
+		expiresAt: cache.expiresAt ? new Date(cache.expiresAt).toISOString() : undefined,
 		otherAccounts: conn.allAccounts.map((a) => a.name).filter((name) => name !== conn.account),
 		permissionSummary: formatPermissions(conn.permissions),
+		// What the configuration asks for; a caller that knows whether the watcher
+		// is actually running overrides this with the runtime truth.
+		watching: conn.watch.enabled,
+		watchSummary: conn.watch.enabled
+			? [
+					`every ${conn.watch.intervalSeconds} s`,
+					conn.watch.chats.length > 0 ? conn.watch.chats.join(", ") : "all recent chats",
+					conn.watch.from.length > 0 ? `from ${conn.watch.from.join(", ")}` : undefined,
+					`max ${conn.watch.maxTriggersPerHour}/h`,
+				]
+					.filter(Boolean)
+					.join(" · ")
+			: undefined,
 	};
 }
 
@@ -57,7 +76,8 @@ export function buildConnectionLabel(card: ConnectionCard | undefined): string {
 	if (!card.signedIn) return `Teams · ${card.account} · not signed in`;
 
 	const scope = card.tenant === card.account ? card.account : `${card.account}/${card.tenant}`;
-	return `✓ Teams · ${scope}${card.user ? ` · ${card.user}` : ""}`;
+	const listening = card.watching ? " · 👂 listening" : "";
+	return `✓ Teams · ${scope}${card.user ? ` · ${card.user}` : ""}${listening}`;
 }
 
 /** Rich markdown for `/teams-status` and the expanded card. */
@@ -78,12 +98,27 @@ export function formatStatusText(card: ConnectionCard | undefined): string {
 	if (card.tenant !== card.account) lines.push(`- **Tenant:** ${card.tenant}`);
 	lines.push(`- **Tenant ID:** ${card.tenantId}`);
 	lines.push(`- **Acting as:** ${card.signedIn ? (card.user ?? "(signed in)") : "not signed in — run teams_login"}`);
-	lines.push(`- **Auth mode:** ${card.authMode}${card.authMode === "client-credentials" ? " (app-only — cannot post as a person)" : ""}`);
+	lines.push(
+		`- **Auth mode:** ${card.authMode}${
+			card.authMode === "client-credentials"
+				? " (app-only — cannot post as a person)"
+				: card.authMode === "interactive"
+					? " (browser sign-in)"
+					: " (device code)"
+		}`,
+	);
 	lines.push(`- **Safety level:** ${card.safetyLevel}`);
-	if (card.expiresAt) lines.push(`- **Token expires:** ${new Date(card.expiresAt).toLocaleString()}`);
+	if (card.expiresAt) {
+		lines.push(
+			`- **Access token expires:** ${new Date(card.expiresAt).toLocaleString()} (renewed silently)`,
+		);
+	}
 	if (card.otherAccounts.length > 0) {
 		lines.push(`- **Other accounts:** ${card.otherAccounts.join(", ")}`);
 	}
+	lines.push(
+		`- **Listen mode:** ${card.watching ? `on — ${card.watchSummary ?? "running"}` : "off"}`,
+	);
 
 	lines.push("", "### What pi may do", "", card.permissionSummary);
 	return lines.join("\n");

package/src/tools/teams-accounts.ts

@@ -12,7 +12,8 @@ import {
 	setSafetyLevel,
 	validateSafetyLevel,
 } from "../config/index.ts";
-import { deleteToken, getToken, isFresh } from "../auth/token-store.ts";
+import { readCacheSummary, removeCache } from "../auth/cache-plugin.ts";
+import { resetApps } from "../auth/index.ts";
 import { clearUserCache, errorResult, run, textResult, type ToolResult } from "./shared.ts";
 
 interface AccountsParams {
@@ -69,12 +70,12 @@ export const teamsAccountsTool = {
 					const lines = ["## Configured Teams accounts", ""];
 					for (const account of config.accounts) {
 						const isDefault = config.defaultAccount === account.name;
-						const token = getToken(account.name, account.tenantId);
-						const state = isFresh(token)
-							? "signed in"
-							: token?.refreshToken
-								? "session saved"
-								: "not signed in";
+						const cache = readCacheSummary(account.name, account.tenantId);
+						const state = !cache.present
+							? "not signed in"
+							: cache.fresh
+								? "signed in"
+								: "session saved";
 
 						lines.push(
 							`### ${account.displayName ?? account.name}${isDefault ? " (default)" : ""}`,
@@ -83,16 +84,16 @@ export const teamsAccountsTool = {
 							`- tenant: ${account.tenantId}`,
 							`- auth mode: ${account.authMode ?? "device-code"}`,
 							`- safety: ${account.safetyLevel ?? config.safetyLevel ?? "confirm"}`,
-							`- status: ${state}${token?.user?.upn ? ` as ${token.user.upn}` : ""}`,
+							`- status: ${state}${cache.username ? ` as ${cache.username}` : ""}`,
 						);
 
 						for (const tenant of account.tenants ?? []) {
-							const tenantToken = getToken(account.name, tenant.tenantId);
-							const tenantState = isFresh(tenantToken)
-								? "signed in"
-								: tenantToken?.refreshToken
-									? "session saved"
-									: "not signed in";
+							const tenantCache = readCacheSummary(account.name, tenant.tenantId);
+							const tenantState = !tenantCache.present
+								? "not signed in"
+								: tenantCache.fresh
+									? "signed in"
+									: "session saved";
 							lines.push(
 								`  - tenant \`${tenant.name}\` (${tenant.tenantId}) — ${tenantState}` +
 									`${tenant.safetyLevel ? `, safety: ${tenant.safetyLevel}` : ""}`,
@@ -125,7 +126,10 @@ export const teamsAccountsTool = {
 							.find((a) => a.name === params.account)
 							?.tenants?.find((t) => t.name === params.tenant);
 						const removed = removeTenant(params.account, params.tenant);
-						if (removed && tenantConfig) deleteToken(params.account, tenantConfig.tenantId);
+						if (removed && tenantConfig) {
+							removeCache(params.account, tenantConfig.tenantId);
+							resetApps();
+						}
 						return removed
 							? textResult(`✅ Removed tenant "${params.tenant}" from account "${params.account}".`, {})
 							: errorResult(`Tenant "${params.tenant}" not found in account "${params.account}".`);
@@ -134,10 +138,11 @@ export const teamsAccountsTool = {
 					const accountConfig = config.accounts.find((a) => a.name === params.account);
 					const removed = removeAccount(params.account);
 					if (removed && accountConfig) {
-						deleteToken(params.account, accountConfig.tenantId);
+						removeCache(params.account, accountConfig.tenantId);
 						for (const tenant of accountConfig.tenants ?? []) {
-							deleteToken(params.account, tenant.tenantId);
+							removeCache(params.account, tenant.tenantId);
 						}
+						resetApps();
 					}
 					clearUserCache();
 					return removed

package/src/tools/teams-doctor.ts

@@ -13,9 +13,9 @@ import {
 	DEFAULT_SCOPES,
 	type TeamsConnection,
 } from "../config/index.ts";
-import { getToken, getTokenPath, isFresh } from "../auth/token-store.ts";
+import { getCacheDir, readCacheSummary } from "../auth/cache-plugin.ts";
 import { tokenScopes } from "../auth/jwt.ts";
-import { getAccessToken } from "../auth/index.ts";
+import { browserUnavailableReason, canOpenBrowser, getAccessToken } from "../auth/index.ts";
 import { getMe } from "../graph/me.ts";
 import { listJoinedTeams } from "../graph/teams.ts";
 import { formatGraphError, describeScope } from "../utils/errors.ts";
@@ -47,28 +47,46 @@ async function checkConnection(
 			"- ⚠️ app-only: pi cannot post messages as a person with this mode " +
 				"(Microsoft Graph restricts app-only message writes to migration scenarios)",
 		);
+	} else if (conn.authMode === "interactive" && !canOpenBrowser()) {
+		lines.push(
+			`- ⚠️ browser sign-in is configured but unavailable here (${browserUnavailableReason()}); ` +
+				"`teams_login` will use the device code flow",
+		);
 	}
 
-	const token = getToken(conn.account, conn.tenantId);
-	if (!token) {
+	const cache = readCacheSummary(conn.account, conn.tenantId);
+	if (!cache.present) {
 		lines.push("- ❌ not signed in — run `teams_login`");
 		return lines;
 	}
 
 	lines.push(
-		isFresh(token)
-			? `- ✅ token valid until ${new Date(token.expiresAt).toLocaleString()}`
-			: token.refreshToken
-				? "- ⚠️ access token expired, refresh token present (will renew on the next call)"
-				: "- ❌ token expired and no refresh token — run `teams_login`",
+		cache.fresh
+			? `- ✅ access token valid until ${new Date(cache.expiresAt!).toLocaleString()}`
+			: "- ⚠️ access token expired; MSAL renews it silently on the next call",
 	);
+	if (cache.username) lines.push(`- cached identity: ${cache.username}`);
+
+	if (offline) {
+		lines.push("- _offline check: scopes and connectivity not verified_");
+		return lines;
+	}
+
+	// Everything below needs a live token. Acquiring it also proves that silent
+	// renewal works, which is the failure users actually hit.
+	let accessToken: string;
+	try {
+		const token = await getAccessToken(conn, signal);
+		accessToken = token.accessToken;
+	} catch (err) {
+		lines.push(`- ❌ could not obtain a token: ${formatGraphError(err)}`);
+		return lines;
+	}
 
-	// Consent check works offline: the scopes are inside the token.
-	const granted = tokenScopes(token.accessToken);
+	// The granted scopes are inside the token, so this needs no extra call.
+	const granted = tokenScopes(accessToken);
 	if (granted.length > 0) {
-		const wanted = (conn.scopes.length > 0 ? conn.scopes : DEFAULT_SCOPES).filter(
-			(scope) => !["openid", "profile", "offline_access"].includes(scope),
-		);
+		const wanted = conn.scopes.length > 0 ? conn.scopes : DEFAULT_SCOPES;
 		const missing = wanted.filter(
 			(scope) => !granted.some((g) => g.toLowerCase() === scope.toLowerCase()),
 		);
@@ -86,15 +104,6 @@ async function checkConnection(
 		}
 	}
 
-	if (offline) return lines;
-
-	try {
-		await getAccessToken(conn, signal);
-	} catch (err) {
-		lines.push(`- ❌ could not obtain a token: ${formatGraphError(err)}`);
-		return lines;
-	}
-
 	try {
 		const me = await getMe(conn, signal);
 		lines.push(`- ✅ acting as **${me.displayName}** <${me.upn}>`);
@@ -146,8 +155,11 @@ export const teamsDoctorTool = {
 
 			const lines = ["## Teams doctor", ""];
 			lines.push(`- config: \`${getConfigPath()}\``);
-			lines.push(`- tokens: \`${getTokenPath()}\``);
+			lines.push(`- tokens: \`${getCacheDir()}/\``);
 			lines.push(`- audit log: \`${getAuditPath()}\``);
+			lines.push(
+				`- browser sign-in: ${canOpenBrowser() ? "available" : `unavailable — ${browserUnavailableReason()}`}`,
+			);
 			lines.push("");
 
 			if (errors.length > 0) {

package/src/tools/teams-login.ts

@@ -1,17 +1,25 @@
 /**
- * teams_login — sign in as the user via the device code flow.
+ * teams_login — sign in as the user.
+ * teams_logout — forget a saved session.
  *
- * The tool streams the code and URL through `onUpdate` as soon as Microsoft
- * issues them, then keeps polling. That ordering matters: the user has a
- * couple of minutes to act, and they cannot act on a code that only appears
- * after the tool returns.
+ * The browser flow is the default: pi opens the Microsoft sign-in page, the
+ * user signs in with their own credentials and MFA, and MSAL catches the
+ * redirect on a loopback port. Where no browser can be reached — SSH, a
+ * container, a headless box — it falls back to the device code flow and says
+ * why.
  */
 
 import { Type } from "typebox";
-import { pollForToken, requestDeviceCode } from "../auth/device-code.ts";
-import { acquireAppToken } from "../auth/client-credentials.ts";
-import { clearMemoryCache, forgetToken, storeToken } from "../auth/index.ts";
-import { clearAllTokens, deleteToken } from "../auth/token-store.ts";
+import {
+	browserUnavailableReason,
+	canOpenBrowser,
+	defaultSignInMode,
+	signIn,
+	signOut,
+	signOutAll,
+	type DeviceCodeInfo,
+	type SignInMode,
+} from "../auth/index.ts";
 import { tokenScopes } from "../auth/jwt.ts";
 import { getMe } from "../graph/me.ts";
 import { formatGraphError } from "../utils/errors.ts";
@@ -31,30 +39,64 @@ import {
 interface LoginParams {
 	account?: string;
 	tenant?: string;
+	mode?: string;
+	port?: number;
+}
+
+type Update = (update: { content: Array<{ type: "text"; text: string }> }) => void;
+
+/** What the user has to do, rendered the moment MSAL tells us. */
+function deviceCodeInstructions(label: string, info: DeviceCodeInfo, why?: string): string {
+	return [
+		`## Sign in to Teams (${label})`,
+		"",
+		why ? `_Using the device code flow because ${why}._` : "",
+		"",
+		`1. Open **${info.verificationUri}**`,
+		`2. Enter the code: **${info.userCode}**`,
+		"3. Sign in with the account pi should act as.",
+		"",
+		`The code expires in ${Math.round(info.expiresIn / 60)} minutes. Waiting…`,
+	]
+		.filter((line) => line !== "")
+		.join("\n");
 }
 
 export const teamsLoginTool = {
 	name: "teams_login",
 	description:
-		"Sign in to Microsoft Teams as yourself using the device code flow. Shows a short code and a URL; " +
-		"open the URL, enter the code, and sign in with your normal credentials. The session is saved " +
-		"(including a refresh token) so this is only needed once per account/tenant. " +
-		"Use the 'account' and 'tenant' parameters to sign in to a second company or a guest tenant.",
+		"Sign in to Microsoft Teams as yourself. By default this opens your browser at the Microsoft sign-in " +
+		"page and completes automatically — nothing to type. On a machine with no browser (SSH, a container) " +
+		"it falls back to the device code flow and shows a short code to enter on another device. " +
+		"The session is saved and renewed silently, so this is normally needed once per account. " +
+		"Use 'account' and 'tenant' to sign in to a second company or a guest tenant.",
 	parameters: Type.Object({
 		account: AccountParam,
 		tenant: TenantParam,
+		mode: Type.Optional(
+			Type.String({
+				description:
+					"Force a flow: 'interactive' (browser) or 'device-code'. Omit to let pi choose for this machine.",
+			}),
+		),
+		port: Type.Optional(
+			Type.Number({
+				description:
+					"Fixed loopback port for the browser redirect. Only needed when the app registration lists an exact redirect URI such as http://localhost:3000.",
+			}),
+		),
 	}),
 	promptSnippet: "Sign in to Microsoft Teams as the user",
 	promptGuidelines: [
-		"Use teams_login when a Teams tool reports that pi is not signed in, or when the user wants to add a second account.",
-		"Show the user code and the verification URL to the user verbatim — they cannot complete sign-in without them.",
+		"Use teams_login when a Teams tool reports that pi is not signed in, or when the user wants to add a second account or tenant.",
+		"If the device code flow is used, show the user code and URL to the user verbatim — they cannot finish signing in without them.",
 	],
 
 	async execute(
 		_toolCallId: string,
 		params: LoginParams,
 		signal: AbortSignal | undefined,
-		onUpdate: ((update: { content: Array<{ type: "text"; text: string }> }) => void) | undefined,
+		onUpdate: Update | undefined,
 		ctx: ToolContext,
 	): Promise<ToolResult> {
 		return run(async () => {
@@ -63,8 +105,7 @@ export const teamsLoginTool = {
 
 			// App-only needs no user interaction at all.
 			if (conn.authMode === "client-credentials") {
-				const token = await acquireAppToken(conn, signal);
-				storeToken(conn, token);
+				const token = await signIn(conn, { signal });
 				return textResult(
 					[
 						`✅ Acquired an app-only token for ${label}.`,
@@ -72,50 +113,60 @@ export const teamsLoginTool = {
 						`Granted app roles: ${tokenScopes(token.accessToken).join(", ") || "(none visible in the token)"}`,
 						"",
 						"Note: app-only tokens cannot post messages as a person. Switch this account to " +
-							'authMode "device-code" if pi should act as you.',
+							'authMode "interactive" if pi should act as you.',
 					].join("\n"),
 					{ account: conn.account, tenant: conn.tenant, authMode: "client-credentials" },
 				);
 			}
 
-			const challenge = await requestDeviceCode(conn, signal);
+			const requested = params.mode?.toLowerCase();
+			if (requested && requested !== "interactive" && requested !== "device-code") {
+				return errorResult(`mode must be 'interactive' or 'device-code', not "${params.mode}".`);
+			}
 
-			const instructions = [
-				`## Sign in to Teams (${label})`,
-				"",
-				`1. Open **${challenge.verificationUri}**`,
-				`2. Enter the code: **${challenge.userCode}**`,
-				"3. Sign in with the account pi should act as.",
-				"",
-				`The code expires at ${new Date(challenge.expiresAt).toLocaleTimeString()}. Waiting…`,
-			].join("\n");
+			let mode: SignInMode = (requested as SignInMode | undefined) ?? defaultSignInMode();
+			let fallbackReason: string | undefined;
 
-			onUpdate?.({ content: [{ type: "text", text: instructions }] });
+			// An explicit request for the browser on a machine that has none would
+			// hang until the timeout; say so and use the code flow instead.
+			if (mode === "interactive" && !canOpenBrowser()) {
+				fallbackReason = browserUnavailableReason();
+				mode = "device-code";
+			} else if (mode === "device-code" && !requested && !canOpenBrowser()) {
+				fallbackReason = browserUnavailableReason();
+			}
+
+			if (mode === "interactive") {
+				onUpdate?.({
+					content: [
+						{
+							type: "text",
+							text: [
+								`## Signing in to Teams (${label})`,
+								"",
+								"Opening your browser. Sign in there with the account pi should act as —",
+								"the page closes itself when you are done.",
+							].join("\n"),
+						},
+					],
+				});
+			}
 
-			let lastNotice = 0;
-			const token = await pollForToken(conn, challenge, {
+			const result = await signIn(conn, {
+				mode,
 				signal,
-				onPending: (secondsLeft) => {
-					// One nudge every 30s — enough to show progress, not enough to spam.
-					if (secondsLeft > 0 && Date.now() - lastNotice > 30_000) {
-						lastNotice = Date.now();
-						onUpdate?.({
-							content: [
-								{
-									type: "text",
-									text: `${instructions}\n\nStill waiting for sign-in… (${secondsLeft}s left)`,
-								},
-							],
-						});
-					}
+				loopbackPort: params.port ?? conn.loopbackPort,
+				onDeviceCode: (info) => {
+					onUpdate?.({
+						content: [{ type: "text", text: deviceCodeInstructions(label, info, fallbackReason) }],
+					});
 				},
 			});
 
-			storeToken(conn, token);
 			clearUserCache();
 
-			// Confirm the token actually works and report who pi now is.
-			let identity = token.user?.upn ?? token.user?.displayName ?? "(unknown)";
+			// Confirm the token actually works, and report who pi now is.
+			let identity = result.account?.username ?? result.account?.name ?? "(unknown)";
 			let jobTitle: string | undefined;
 			try {
 				const me = await getMe(conn, signal);
@@ -132,16 +183,17 @@ export const teamsLoginTool = {
 				);
 			}
 
-			const granted = tokenScopes(token.accessToken);
-			const requested = conn.scopes.filter((s) => !["openid", "profile", "offline_access"].includes(s));
-			const missing = requested.filter(
-				(scope) => !granted.some((g) => g.toLowerCase() === scope.toLowerCase()),
+			const granted = tokenScopes(result.accessToken);
+			const missing = conn.scopes.filter(
+				(scope) => !granted.some((entry) => entry.toLowerCase() === scope.toLowerCase()),
 			);
 
 			return textResult(
 				[
 					`✅ Signed in to ${label} as **${identity}**${jobTitle ? ` (${jobTitle})` : ""}.`,
 					"",
+					`Flow: ${result.mode === "interactive" ? "browser sign-in" : "device code"}` +
+						`${fallbackReason ? ` (${fallbackReason})` : ""}`,
 					`pi now acts as this user in Teams. Safety level: **${conn.safetyLevel}**.`,
 					missing.length > 0
 						? `\n⚠️ Not granted: ${missing.join(", ")}\nSome tools will fail until an admin consents to these scopes.`
@@ -151,6 +203,7 @@ export const teamsLoginTool = {
 					account: conn.account,
 					tenant: conn.tenant,
 					user: identity,
+					mode: result.mode,
 					grantedScopes: granted,
 					missingScopes: missing,
 				},
@@ -162,12 +215,12 @@ export const teamsLoginTool = {
 export const teamsLogoutTool = {
 	name: "teams_logout",
 	description:
-		"Sign out of a Teams account: removes the saved access and refresh tokens from " +
-		"~/.pi/agent/pi-teams-tokens.json. The account stays configured, so teams_login can sign in again.",
+		"Sign out of a Teams account: removes the saved session from ~/.pi/agent/pi-teams-tokens/. " +
+		"The account stays configured, so teams_login can sign in again.",
 	parameters: Type.Object({
 		account: AccountParam,
 		tenant: TenantParam,
-		all: Type.Optional(Type.Boolean({ description: "Remove the cached tokens of every account" })),
+		all: Type.Optional(Type.Boolean({ description: "Remove the saved sessions of every account" })),
 	}),
 	promptSnippet: "Sign out of a Teams account",
 
@@ -182,14 +235,12 @@ export const teamsLogoutTool = {
 			clearUserCache();
 
 			if (params.all) {
-				const count = clearAllTokens();
-				clearMemoryCache();
-				return textResult(`✅ Removed ${count} cached Teams session(s).`, { removed: count });
+				const count = signOutAll();
+				return textResult(`✅ Removed ${count} saved Teams session(s).`, { removed: count });
 			}
 
 			const conn = connectionFor(ctx, params.account, params.tenant);
-			const removed = deleteToken(conn.account, conn.tenantId);
-			forgetToken(conn);
+			const removed = await signOut(conn);
 
 			return removed
 				? textResult(`✅ Signed out of ${connectionLabel(conn)}.`, { account: conn.account })

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

@@ -57,14 +57,17 @@ 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. Plain text unless 'html' is true." }),
+	body: Type.String({
+			description:
+				"Message text as lightweight markdown (bold, italics, code, bullets, numbered lists, links)",
+		}),
 	account: AccountParam,
 	tenant: TenantParam,
 	mentions: Type.Optional(
 		Type.Array(Type.String(), { description: "People to @-mention, by name, UPN or e-mail" }),
 	),
 	importance: Type.Optional(Type.String({ description: "'normal' (default), 'high' or 'urgent'" })),
-	html: Type.Optional(Type.Boolean({ description: "Treat 'body' as raw HTML instead of plain text" })),
+	html: Type.Optional(Type.Boolean({ description: "Send 'body' as raw HTML instead of converting markdown" })),
 };
 
 export const teamsSendChannelMessageTool = {
@@ -81,6 +84,8 @@ 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.",
+		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
 
 	async execute(

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

@@ -46,7 +46,10 @@ 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. Plain text unless 'html' is true." }),
+		body: Type.String({
+			description:
+				"Message text as lightweight markdown (bold, italics, code, bullets, numbered lists, links)",
+		}),
 		account: AccountParam,
 		tenant: TenantParam,
 		mentions: Type.Optional(
@@ -58,7 +61,7 @@ export const teamsSendChatMessageTool = {
 			Type.String({ description: "'normal' (default), 'high' or 'urgent'" }),
 		),
 		html: Type.Optional(
-			Type.Boolean({ description: "Treat 'body' as raw HTML instead of plain text" }),
+			Type.Boolean({ description: "Send 'body' as raw HTML instead of converting markdown" }),
 		),
 	}),
 	promptSnippet: "Send a message in a Teams chat as the user",
@@ -66,6 +69,8 @@ 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, disclaimers, or a note that the message was written by an AI unless the user asks.",
+		"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.",
+		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
 
 	async execute(

package/src/tools/teams-setup.ts

@@ -27,6 +27,7 @@ interface SetupParams {
 	displayName?: string;
 	clientSecret?: string;
 	authMode?: string;
+	loopbackPort?: number;
 	safetyLevel?: string;
 	parentAccount?: string;
 	setDefault?: boolean;
@@ -116,7 +117,14 @@ export const teamsSetupTool = {
 		authMode: Type.Optional(
 			Type.String({
 				description:
-					"'device-code' (act as the signed-in user, default), 'client-credentials' (app-only, cannot post as a person), or 'auto'",
+					"'interactive' (browser sign-in, acts as the user — default), 'device-code' (same, but for machines with no browser), " +
+					"'client-credentials' (app-only, cannot post as a person), or 'auto' to decide per machine",
+			}),
+		),
+		loopbackPort: Type.Optional(
+			Type.Number({
+				description:
+					"Fixed port for the browser sign-in redirect. Only needed when the app registration lists an exact redirect URI such as http://localhost:3000.",
 			}),
 		),
 		safetyLevel: Type.Optional(
@@ -179,6 +187,7 @@ export const teamsSetupTool = {
 					clientSecret: params.clientSecret,
 					authMode: params.authMode as TenantConfig["authMode"],
 					scopes: params.scopes,
+					loopbackPort: params.loopbackPort,
 					safetyLevel,
 					permissions,
 				};
@@ -211,8 +220,9 @@ export const teamsSetupTool = {
 				tenantId: params.tenantId,
 				clientId: params.clientId,
 				clientSecret: params.clientSecret,
-				authMode: (params.authMode as AccountConfig["authMode"]) ?? "device-code",
+				authMode: (params.authMode as AccountConfig["authMode"]) ?? "interactive",
 				scopes: params.scopes,
+				loopbackPort: params.loopbackPort,
 				safetyLevel: safetyLevel ?? "confirm",
 				permissions,
 			};