@patimweb/pi-teams 1.0.0 → 1.1.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-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,
 			};

package/src/tools/teams-status.ts

@@ -4,7 +4,7 @@
 
 import { Type } from "typebox";
 import { buildConnectionCard, formatStatusText } from "../status.ts";
-import { getToken, isFresh } from "../auth/token-store.ts";
+import { readCacheSummary } from "../auth/cache-plugin.ts";
 import { readRootConfig } from "../config/index.ts";
 import {
 	AccountParam,
@@ -47,13 +47,13 @@ export const teamsStatusTool = {
 					...(account.tenants ?? []).map((t) => ({ name: `${account.name}/${t.name}`, tenantId: t.tenantId })),
 				];
 				for (const entry of tenants) {
-					const token = getToken(account.name, entry.tenantId);
-					const state = isFresh(token)
-						? "signed in"
-						: token?.refreshToken
-							? "session saved (will refresh)"
-							: "not signed in";
-					const who = token?.user?.upn ? ` — ${token.user.upn}` : "";
+					const cache = readCacheSummary(account.name, entry.tenantId);
+					const state = !cache.present
+						? "not signed in"
+						: cache.fresh
+							? "signed in"
+							: "session saved (renews on next use)";
+					const who = cache.username ? ` — ${cache.username}` : "";
 					others.push(`- ${entry.name}: ${state}${who}`);
 				}
 			}

package/src/utils/environment.ts

@@ -0,0 +1,41 @@
+/**
+ * Environment detection.
+ *
+ * Deliberately dependency-free: both the config layer and the auth layer need
+ * to know whether a browser is reachable, and neither should have to import
+ * the other to find out.
+ */
+
+/**
+ * Can we realistically put a browser in front of this user?
+ *
+ * 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.
+ *
+ * Set `PI_TEAMS_NO_BROWSER=1` to force that fallback anywhere.
+ */
+export function canOpenBrowser(): boolean {
+	if (process.env.PI_TEAMS_NO_BROWSER) return false;
+
+	// 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;
+
+	// 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) {
+		return "this is an SSH session, so the browser would open on the wrong machine";
+	}
+	if (process.platform !== "darwin" && process.platform !== "win32") {
+		return "no display server is available (DISPLAY and WAYLAND_DISPLAY are unset)";
+	}
+	return "no browser is available";
+}

package/src/auth/client-credentials.ts

@@ -1,72 +0,0 @@
-/**
- * Client credentials grant — app-only access, no user involved.
- *
- * Useful for unattended jobs (a nightly digest, a scheduled report) against
- * directory and presence data. It is deliberately *not* a way to post as
- * somebody: Microsoft Graph only accepts app-only writes to chats and channels
- * for migration scenarios (`Teamwork.Migrate.All`), so this extension refuses
- * message sends on an app-only token instead of letting them fail deep inside
- * a Graph call. See ../safety/index.ts.
- */
-
-import type { TeamsConnection } from "../config/index.ts";
-import { AuthError, tokenUrl } from "./device-code.ts";
-import type { CachedToken } from "./token-store.ts";
-
-interface TokenResponse {
-	access_token: string;
-	expires_in: number;
-	scope?: string;
-	token_type: string;
-	error?: string;
-	error_description?: string;
-}
-
-/**
- * Acquire an app-only token.
- *
- * @throws {AuthError} when the secret is missing, expired, or the app has no
- * admin-consented application permissions.
- */
-export async function acquireAppToken(
-	conn: TeamsConnection,
-	signal?: AbortSignal,
-): Promise<CachedToken> {
-	if (!conn.clientSecret) {
-		throw new AuthError(
-			"missing_client_secret",
-			`Account "${conn.account}" uses client-credentials but no clientSecret is configured.`,
-		);
-	}
-
-	const body = new URLSearchParams({
-		grant_type: "client_credentials",
-		client_id: conn.clientId,
-		client_secret: conn.clientSecret,
-		scope: conn.scopes.length === 1 ? conn.scopes[0]! : "https://graph.microsoft.com/.default",
-	});
-
-	const response = await fetch(tokenUrl(conn.authorityHost, conn.tenantId), {
-		method: "POST",
-		headers: { "Content-Type": "application/x-www-form-urlencoded" },
-		body: body.toString(),
-		signal,
-	});
-
-	const json = (await response.json()) as TokenResponse;
-
-	if (!response.ok || !json.access_token) {
-		throw new AuthError(
-			json.error ?? `http_${response.status}`,
-			json.error_description ?? `Client credentials request failed with HTTP ${response.status}`,
-		);
-	}
-
-	return {
-		accessToken: json.access_token,
-		expiresAt: Date.now() + Math.max(0, json.expires_in - 60) * 1000,
-		scopes: json.scope ? json.scope.split(" ") : [],
-		authMode: "client-credentials",
-		updatedAt: new Date().toISOString(),
-	};
-}