@patimweb/pi-teams 1.0.0

package/skills/teams-collaboration/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: teams-collaboration
+description: Microsoft Teams chats, channels, meetings and presence, acting as the signed-in user. Use when the user asks to read, search, summarize, send or reply to Teams messages; to catch up on what they missed; to post in a channel or a thread; to start a chat; to react to a message; to check or set their Teams status; to see who is available; or to schedule, change or cancel a Teams meeting. Also covers multiple Teams accounts and multiple company tenants, and the allow/deny rules that decide what pi may touch.
+---
+
+# Microsoft Teams
+
+pi acts **as the signed-in user**. A message it sends is indistinguishable from
+one the user typed: same name, same avatar, same thread. Treat every write as
+something the user is personally saying.
+
+## Before anything else
+
+Run `teams_status` if you are unsure which account is active or whether pi is
+signed in. If it reports "not signed in", run `teams_login` — it prints a short
+code and a URL that the user must open themselves.
+
+If a tool fails with an authentication, permission or configuration error, run
+`teams_doctor` and report what it says. Do not retry the failing call.
+
+## Multiple accounts and companies
+
+Every tool accepts `account` and `tenant`:
+
+- `account` — a configured Teams identity (e.g. `work`, `private`)
+- `tenant` — a tenant beneath that account: a customer, a guest tenant, a
+  subsidiary
+
+Omit both to use the default. Use `teams_accounts` to list what is configured.
+When the user says "in the customer's Teams" or names a company, pass the
+matching `tenant` rather than assuming the default is right.
+
+## What pi may do
+
+Three independent gates apply:
+
+1. **Auth mode** — an app-only account cannot post as a person at all.
+2. **Safety level** — `readonly` blocks writes, `confirm` asks the user first,
+   `open` proceeds.
+3. **Scope rules** — allow/deny lists per category (teams, channels, chats,
+   people) and per mode (read, write).
+
+When a call is refused with "Blocked by configuration", that is the user's own
+rule set. Show them the rule, do not work around it, and do not try a different
+tool to achieve the same thing. `teams_permissions` with `action: "test"`
+checks a target without touching it.
+
+## Tools
+
+### Session
+
+| Tool | Use when |
+|------|----------|
+| `teams_status` | Which account is active, who pi acts as, what it may do |
+| `teams_login` | Not signed in, or adding an account/tenant |
+| `teams_logout` | Removing a saved session |
+| `teams_accounts` | Listing accounts, switching the default, changing a safety level |
+| `teams_permissions` | Showing, testing or changing the allow/deny rules |
+| `teams_doctor` | Anything failed and you need to know why |
+| `teams_setup` | Adding a new account or tenant to the configuration |
+
+### Reading
+
+| Tool | Use when |
+|------|----------|
+| `teams_inbox` | "What did I miss?", "anything new in Teams?" |
+| `teams_list_chats` | Finding a chat, seeing recent conversations |
+| `teams_read_chat` | Reading one conversation |
+| `teams_list_teams` / `teams_list_channels` | Discovering team and channel names |
+| `teams_read_channel` | The posts in a channel (openers only) |
+| `teams_read_thread` | One thread, opener plus every reply |
+| `teams_search_messages` | Finding something said, when the location is unknown |
+| `teams_list_members` | Who is in a team or channel |
+| `teams_find_user` | Resolving a first name to a real person |
+| `teams_list_files` | Files shared in a channel |
+| `teams_get_presence` | Is someone available right now |
+| `teams_list_meetings` / `teams_get_meeting` | Calendar and meeting details |
+
+### Writing
+
+| Tool | Use when |
+|------|----------|
+| `teams_send_chat_message` | Sending a chat message |
+| `teams_create_chat` | Starting a new conversation |
+| `teams_send_channel_message` | Posting a new channel message |
+| `teams_reply_channel_message` | Answering inside an existing thread |
+| `teams_react` | Adding or removing an emoji reaction |
+| `teams_delete_message` | Taking back something the user sent |
+| `teams_create_channel` | Adding a channel to a team |
+| `teams_set_presence` / `teams_set_status_message` | Changing the user's status |
+| `teams_create_meeting` / `teams_update_meeting` / `teams_cancel_meeting` | Scheduling work |
+
+## How to write as the user
+
+- Write in **their** voice. No "As an AI…", no signature, no note that a model
+  composed it, unless they ask for one.
+- Match the register of the conversation you just read. A channel post and a
+  quick reply to a colleague are not the same thing.
+- Show the exact text and the destination before sending whenever the request
+  leaves any room for interpretation. Once it is sent, it is sent.
+- Never invent facts, commitments, dates or agreement on the user's behalf. If
+  a detail is missing, ask.
+- Prefer `teams_reply_channel_message` over a new post when answering something
+  — starting a second thread fragments the conversation.
+
+## Channel addressing
+
+Channels are addressed as `Team/Channel` or via separate `team` and `channel`
+parameters. Names are resolved case-insensitively; an ambiguous name is
+reported rather than guessed, and the answer is to pass the ID.
+
+```yaml
+teams_send_channel_message:
+  channel: "Engineering/General"
+  body: "Deployment finished, release notes are in the wiki."
+```
+
+## Mentions
+
+Pass `mentions` with names, UPNs or e-mail addresses, and write `@Display Name`
+in the body where the mention belongs:
+
+```yaml
+teams_send_chat_message:
+  chat: "Project Alpha"
+  body: "@Anna Schmidt could you take a look before the standup?"
+  mentions: ["anna@contoso.com"]
+```
+
+Resolve names with `teams_find_user` first when only a first name is known.
+
+## Threads
+
+Channel conversations are threaded. `teams_read_channel` returns the openers
+with their IDs; `teams_read_thread` returns one thread in full. To summarize a
+channel properly, read the openers, then the threads that matter — do not
+summarize from openers alone.
+
+## Reading before writing
+
+Before replying anywhere, read the recent messages first. It prevents
+answering a question that was already answered, and it is what tells you the
+tone to match.

package/src/auth/client-credentials.ts

@@ -0,0 +1,72 @@
+/**
+ * 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(),
+	};
+}

package/src/auth/device-code.ts

@@ -0,0 +1,276 @@
+/**
+ * OAuth 2.0 device authorization grant — the flow that makes pi *you*.
+ *
+ * The user opens a URL, types a short code, and signs in with their own
+ * credentials and MFA. Everything pi does afterwards is attributed to that
+ * person in Teams: messages come from them, and pi sees exactly what they see —
+ * no more.
+ *
+ * Implemented against the token endpoint directly rather than through MSAL:
+ * the extension ships with no build step, and one fetch-based module is easier
+ * to audit than a dependency tree.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import { decodeIdToken } from "./jwt.ts";
+import type { CachedToken } from "./token-store.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** What the user needs in order to complete the sign-in. */
+export interface DeviceCodeChallenge {
+	deviceCode: string;
+	userCode: string;
+	verificationUri: string;
+	/** Message Microsoft suggests showing to the user */
+	message: string;
+	/** Epoch ms after which the code is dead */
+	expiresAt: number;
+	/** Seconds between polls, as requested by the server */
+	intervalSeconds: number;
+}
+
+interface DeviceCodeResponse {
+	device_code: string;
+	user_code: string;
+	verification_uri: string;
+	expires_in: number;
+	interval: number;
+	message: string;
+}
+
+interface TokenResponse {
+	access_token: string;
+	refresh_token?: string;
+	id_token?: string;
+	expires_in: number;
+	scope?: string;
+	token_type: string;
+}
+
+interface ErrorResponse {
+	error: string;
+	error_description?: string;
+}
+
+/** A token endpoint error that callers may want to branch on. */
+export class AuthError extends Error {
+	readonly code: string;
+	constructor(code: string, message: string) {
+		super(message);
+		this.name = "AuthError";
+		this.code = code;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Endpoints
+// ---------------------------------------------------------------------------
+
+function deviceCodeUrl(conn: TeamsConnection): string {
+	return `${conn.authorityHost}/${encodeURIComponent(conn.tenantId)}/oauth2/v2.0/devicecode`;
+}
+
+export function tokenUrl(authorityHost: string, tenantId: string): string {
+	return `${authorityHost}/${encodeURIComponent(tenantId)}/oauth2/v2.0/token`;
+}
+
+// ---------------------------------------------------------------------------
+// Step 1 — request a code
+// ---------------------------------------------------------------------------
+
+/**
+ * Ask Microsoft for a device code.
+ *
+ * @throws {AuthError} when the app registration rejects the request — most
+ * often because "Allow public client flows" is still off.
+ */
+export async function requestDeviceCode(
+	conn: TeamsConnection,
+	signal?: AbortSignal,
+): Promise<DeviceCodeChallenge> {
+	const body = new URLSearchParams({
+		client_id: conn.clientId,
+		scope: conn.scopes.join(" "),
+	});
+
+	const response = await fetch(deviceCodeUrl(conn), {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: body.toString(),
+		signal,
+	});
+
+	const json = (await response.json()) as DeviceCodeResponse & Partial<ErrorResponse>;
+
+	if (!response.ok || json.error) {
+		throw new AuthError(
+			json.error ?? `http_${response.status}`,
+			json.error_description ?? `Device code request failed with HTTP ${response.status}`,
+		);
+	}
+
+	return {
+		deviceCode: json.device_code,
+		userCode: json.user_code,
+		verificationUri: json.verification_uri,
+		message: json.message,
+		expiresAt: Date.now() + json.expires_in * 1000,
+		intervalSeconds: json.interval || 5,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 — poll until the user is done
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(resolve, ms);
+		signal?.addEventListener(
+			"abort",
+			() => {
+				clearTimeout(timer);
+				reject(new AuthError("aborted", "Sign-in cancelled."));
+			},
+			{ once: true },
+		);
+	});
+}
+
+/**
+ * Poll the token endpoint until the user finishes signing in.
+ *
+ * `onPending` is called on every poll so a tool can keep the UI alive during
+ * what may be a minute or two of waiting.
+ */
+export async function pollForToken(
+	conn: TeamsConnection,
+	challenge: DeviceCodeChallenge,
+	options: { signal?: AbortSignal; onPending?: (secondsLeft: number) => void } = {},
+): Promise<CachedToken> {
+	const { signal, onPending } = options;
+	let intervalMs = challenge.intervalSeconds * 1000;
+
+	for (;;) {
+		if (Date.now() > challenge.expiresAt) {
+			throw new AuthError("expired_token", "The device code expired before sign-in completed.");
+		}
+
+		await sleep(intervalMs, signal);
+		onPending?.(Math.max(0, Math.round((challenge.expiresAt - Date.now()) / 1000)));
+
+		const body = new URLSearchParams({
+			grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+			client_id: conn.clientId,
+			device_code: challenge.deviceCode,
+		});
+
+		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 & Partial<ErrorResponse>;
+
+		if (response.ok && json.access_token) {
+			return toCachedToken(json, "device-code");
+		}
+
+		switch (json.error) {
+			case "authorization_pending":
+				continue;
+			case "slow_down":
+				// The server asks for more breathing room; honour it permanently.
+				intervalMs += 5000;
+				continue;
+			case "authorization_declined":
+				throw new AuthError("authorization_declined", "Sign-in was declined in the browser.");
+			case "expired_token":
+				throw new AuthError("expired_token", "The device code expired before sign-in completed.");
+			case "bad_verification_code":
+				throw new AuthError("bad_verification_code", "The device code was rejected. Start over.");
+			default:
+				throw new AuthError(
+					json.error ?? `http_${response.status}`,
+					json.error_description ?? `Token request failed with HTTP ${response.status}`,
+				);
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Step 3 — refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Exchange a refresh token for a fresh access token.
+ *
+ * @throws {AuthError} with code `invalid_grant` when the refresh token is dead
+ * (password change, revoked session, conditional access) — the caller should
+ * then ask the user to run `teams_login` again.
+ */
+export async function refreshAccessToken(
+	conn: TeamsConnection,
+	refreshToken: string,
+	signal?: AbortSignal,
+): Promise<CachedToken> {
+	const body = new URLSearchParams({
+		grant_type: "refresh_token",
+		client_id: conn.clientId,
+		refresh_token: refreshToken,
+		scope: conn.scopes.join(" "),
+	});
+
+	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 & Partial<ErrorResponse>;
+
+	if (!response.ok || !json.access_token) {
+		throw new AuthError(
+			json.error ?? `http_${response.status}`,
+			json.error_description ?? `Token refresh failed with HTTP ${response.status}`,
+		);
+	}
+
+	// Entra ID rotates refresh tokens; keep the old one only if none came back.
+	return { ...toCachedToken(json, "device-code"), refreshToken: json.refresh_token ?? refreshToken };
+}
+
+// ---------------------------------------------------------------------------
+// Shaping
+// ---------------------------------------------------------------------------
+
+function toCachedToken(
+	json: TokenResponse,
+	authMode: "device-code" | "client-credentials",
+): CachedToken {
+	const claims = json.id_token ? decodeIdToken(json.id_token) : undefined;
+	return {
+		accessToken: json.access_token,
+		refreshToken: json.refresh_token,
+		// Shave 60s off the stated lifetime so clock skew never hands Graph a
+		// token that expired a second ago.
+		expiresAt: Date.now() + Math.max(0, json.expires_in - 60) * 1000,
+		scopes: json.scope ? json.scope.split(" ") : [],
+		authMode,
+		user: claims
+			? {
+					id: claims.oid,
+					displayName: claims.name,
+					upn: claims.preferred_username ?? claims.upn,
+					tenantId: claims.tid,
+				}
+			: undefined,
+		updatedAt: new Date().toISOString(),
+	};
+}

package/src/auth/index.ts

@@ -0,0 +1,105 @@
+/**
+ * Auth resolver — hands the Graph layer a valid bearer token.
+ *
+ * Order of preference for a delegated connection:
+ *   1. a cached access token that is still fresh
+ *   2. a refresh of the cached refresh token
+ *   3. nothing — the caller must run `teams_login`
+ *
+ * App-only connections skip the cache-refresh dance; a new token is cheap and
+ * there is no user to interrupt.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import { AuthError, refreshAccessToken } from "./device-code.ts";
+import { acquireAppToken } from "./client-credentials.ts";
+import { getToken, saveToken, isFresh, type CachedToken } from "./token-store.ts";
+
+/** Raised when there is no usable token and only the user can fix it. */
+export class NotSignedInError extends Error {
+	readonly account: string;
+	readonly tenant: string;
+	constructor(account: string, tenant: string, detail?: string) {
+		super(
+			`Not signed in to Teams account "${account}"${tenant !== account ? ` (tenant ${tenant})` : ""}. ` +
+				`Run the teams_login tool or the /teams-login command.${detail ? ` (${detail})` : ""}`,
+		);
+		this.name = "NotSignedInError";
+		this.account = account;
+		this.tenant = tenant;
+	}
+}
+
+/** In-process cache so a burst of Graph calls does not re-read the token file. */
+const memoryCache = new Map<string, CachedToken>();
+
+function memKey(conn: TeamsConnection): string {
+	return `${conn.account.toLowerCase()}::${conn.tenantId.toLowerCase()}`;
+}
+
+/**
+ * Get a bearer token for this connection, refreshing it when needed.
+ *
+ * @throws {NotSignedInError} when a delegated sign-in is required
+ * @throws {AuthError} when the identity provider refuses
+ */
+export async function getAccessToken(
+	conn: TeamsConnection,
+	signal?: AbortSignal,
+): Promise<CachedToken> {
+	const key = memKey(conn);
+
+	const inMemory = memoryCache.get(key);
+	if (isFresh(inMemory)) return inMemory!;
+
+	if (conn.authMode === "client-credentials") {
+		const token = await acquireAppToken(conn, signal);
+		memoryCache.set(key, token);
+		saveToken(conn.account, conn.tenantId, token);
+		return token;
+	}
+
+	const cached = getToken(conn.account, conn.tenantId);
+
+	if (isFresh(cached)) {
+		memoryCache.set(key, cached!);
+		return cached!;
+	}
+
+	if (cached?.refreshToken) {
+		try {
+			const refreshed = await refreshAccessToken(conn, cached.refreshToken, signal);
+			// Keep the identity we already know; a refresh response carries no id_token
+			// unless openid was requested again.
+			const merged: CachedToken = { ...refreshed, user: refreshed.user ?? cached.user };
+			memoryCache.set(key, merged);
+			saveToken(conn.account, conn.tenantId, merged);
+			return merged;
+		} catch (err) {
+			if (err instanceof AuthError && err.code === "invalid_grant") {
+				throw new NotSignedInError(conn.account, conn.tenant, "the saved sign-in expired or was revoked");
+			}
+			throw err;
+		}
+	}
+
+	throw new NotSignedInError(conn.account, conn.tenant);
+}
+
+/** Store a freshly acquired token (used by `teams_login`). */
+export function storeToken(conn: TeamsConnection, token: CachedToken): void {
+	memoryCache.set(memKey(conn), token);
+	saveToken(conn.account, conn.tenantId, token);
+}
+
+/** Forget the in-process token — the file cache is handled by token-store. */
+export function forgetToken(conn: TeamsConnection): void {
+	memoryCache.delete(memKey(conn));
+}
+
+/** Drop every in-process token. */
+export function clearMemoryCache(): void {
+	memoryCache.clear();
+}
+
+export { AuthError };

package/src/auth/jwt.ts

@@ -0,0 +1,50 @@
+/**
+ * Minimal JWT claim reader.
+ *
+ * Used only to show *who* pi is signed in as. The token is never validated
+ * here — it came straight from the token endpoint over TLS, and Graph is the
+ * authority on whether it is accepted. Nothing security-relevant depends on
+ * these claims.
+ */
+
+export interface IdTokenClaims {
+	oid?: string;
+	tid?: string;
+	name?: string;
+	preferred_username?: string;
+	upn?: string;
+	scp?: string;
+	roles?: string[];
+	exp?: number;
+	[key: string]: unknown;
+}
+
+/** Decode the payload of a JWT, or undefined when it is not decodable. */
+export function decodeJwtPayload(token: string): IdTokenClaims | undefined {
+	try {
+		const parts = token.split(".");
+		if (parts.length < 2) return undefined;
+		const payload = parts[1]!.replace(/-/g, "+").replace(/_/g, "/");
+		const padded = payload.padEnd(payload.length + ((4 - (payload.length % 4)) % 4), "=");
+		return JSON.parse(Buffer.from(padded, "base64").toString("utf-8")) as IdTokenClaims;
+	} catch {
+		return undefined;
+	}
+}
+
+export function decodeIdToken(idToken: string): IdTokenClaims | undefined {
+	return decodeJwtPayload(idToken);
+}
+
+/**
+ * Scopes actually present in an access token (`scp`), or app roles (`roles`)
+ * for app-only tokens. `teams_doctor` uses this to tell the user which consent
+ * is still missing instead of letting them guess from a 403.
+ */
+export function tokenScopes(accessToken: string): string[] {
+	const claims = decodeJwtPayload(accessToken);
+	if (!claims) return [];
+	if (typeof claims.scp === "string" && claims.scp.length > 0) return claims.scp.split(" ");
+	if (Array.isArray(claims.roles)) return claims.roles;
+	return [];
+}