@patimweb/pi-teams 1.0.0

package/src/graph/teams.ts

@@ -0,0 +1,271 @@
+/**
+ * Teams, channels, members and channel files.
+ *
+ * Every lookup accepts a name *or* an ID, because that is how people refer to
+ * their own teams ("post this in Engineering/General"). Name resolution is
+ * case-insensitive and reports ambiguity rather than guessing — posting in the
+ * wrong channel is not a recoverable mistake.
+ */
+
+import type { TeamsConnection } from "../config/index.ts";
+import type { ChannelSummary, DriveItemSummary, MemberSummary, TeamSummary } from "../types.ts";
+import { graphGetOptional, graphList, graphPost, graphRequest } from "./client.ts";
+import { mapChannel, mapDriveItem, mapMember, mapTeam } from "./mappers.ts";
+
+/** Raised when a name matches more than one team or channel. */
+export class AmbiguousNameError extends Error {
+	readonly candidates: string[];
+	constructor(kind: string, name: string, candidates: string[]) {
+		super(
+			`${kind} "${name}" is ambiguous — ${candidates.length} matches: ${candidates.join(", ")}. ` +
+				`Use the ID instead.`,
+		);
+		this.name = "AmbiguousNameError";
+		this.candidates = candidates;
+	}
+}
+
+const isGuid = (value: string): boolean => /^[0-9a-f-]{36}$/i.test(value);
+const isChannelId = (value: string): boolean => value.startsWith("19:");
+
+// ---------------------------------------------------------------------------
+// Teams
+// ---------------------------------------------------------------------------
+
+/** Teams the signed-in user is a member of. */
+export async function listJoinedTeams(
+	conn: TeamsConnection,
+	max = 100,
+	signal?: AbortSignal,
+): Promise<TeamSummary[]> {
+	const raw = await graphList<Record<string, unknown>>(conn, "/me/joinedTeams", { max, signal });
+	return raw.map((entry) => mapTeam(entry as Record<string, never>));
+}
+
+export async function getTeam(
+	conn: TeamsConnection,
+	teamId: string,
+	signal?: AbortSignal,
+): Promise<TeamSummary | undefined> {
+	const raw = await graphGetOptional<Record<string, unknown>>(
+		conn,
+		`/teams/${encodeURIComponent(teamId)}`,
+		{ signal },
+	);
+	return raw ? mapTeam(raw as Record<string, never>) : undefined;
+}
+
+/**
+ * Resolve a team by ID or display name.
+ *
+ * @throws {AmbiguousNameError} when a name matches several teams
+ */
+export async function resolveTeam(
+	conn: TeamsConnection,
+	reference: string,
+	signal?: AbortSignal,
+): Promise<TeamSummary | undefined> {
+	if (isGuid(reference)) {
+		const direct = await getTeam(conn, reference, signal);
+		if (direct) return direct;
+	}
+
+	const teams = await listJoinedTeams(conn, 200, signal);
+	const lower = reference.toLowerCase();
+
+	const exact = teams.filter((t) => t.displayName.toLowerCase() === lower || t.id === reference);
+	if (exact.length === 1) return exact[0];
+	if (exact.length > 1) {
+		throw new AmbiguousNameError("Team", reference, exact.map((t) => `${t.displayName} (${t.id})`));
+	}
+
+	const partial = teams.filter((t) => t.displayName.toLowerCase().includes(lower));
+	if (partial.length === 1) return partial[0];
+	if (partial.length > 1) {
+		throw new AmbiguousNameError("Team", reference, partial.map((t) => t.displayName));
+	}
+
+	return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Channels
+// ---------------------------------------------------------------------------
+
+export async function listChannels(
+	conn: TeamsConnection,
+	team: TeamSummary,
+	max = 100,
+	signal?: AbortSignal,
+): Promise<ChannelSummary[]> {
+	const raw = await graphList<Record<string, unknown>>(
+		conn,
+		`/teams/${encodeURIComponent(team.id)}/channels`,
+		{ max, signal },
+	);
+	return raw.map((entry) =>
+		mapChannel(entry as Record<string, never>, { id: team.id, name: team.displayName }),
+	);
+}
+
+export async function getChannel(
+	conn: TeamsConnection,
+	team: TeamSummary,
+	channelId: string,
+	signal?: AbortSignal,
+): Promise<ChannelSummary | undefined> {
+	const raw = await graphGetOptional<Record<string, unknown>>(
+		conn,
+		`/teams/${encodeURIComponent(team.id)}/channels/${encodeURIComponent(channelId)}`,
+		{ signal },
+	);
+	return raw
+		? mapChannel(raw as Record<string, never>, { id: team.id, name: team.displayName })
+		: undefined;
+}
+
+/**
+ * Resolve a channel by ID or display name inside a team.
+ *
+ * @throws {AmbiguousNameError} when a name matches several channels
+ */
+export async function resolveChannel(
+	conn: TeamsConnection,
+	team: TeamSummary,
+	reference: string,
+	signal?: AbortSignal,
+): Promise<ChannelSummary | undefined> {
+	if (isChannelId(reference)) {
+		const direct = await getChannel(conn, team, reference, signal);
+		if (direct) return direct;
+	}
+
+	const channels = await listChannels(conn, team, 200, signal);
+	const lower = reference.toLowerCase();
+
+	const exact = channels.filter((c) => c.displayName.toLowerCase() === lower || c.id === reference);
+	if (exact.length === 1) return exact[0];
+	if (exact.length > 1) {
+		throw new AmbiguousNameError("Channel", reference, exact.map((c) => `${c.displayName} (${c.id})`));
+	}
+
+	const partial = channels.filter((c) => c.displayName.toLowerCase().includes(lower));
+	if (partial.length === 1) return partial[0];
+	if (partial.length > 1) {
+		throw new AmbiguousNameError("Channel", reference, partial.map((c) => c.displayName));
+	}
+
+	return undefined;
+}
+
+/**
+ * Resolve "Team/Channel", or a team plus channel reference, in one step.
+ * Returns whatever it could resolve so callers can produce a precise error.
+ */
+export async function resolveTeamAndChannel(
+	conn: TeamsConnection,
+	teamRef: string | undefined,
+	channelRef: string,
+	signal?: AbortSignal,
+): Promise<{ team?: TeamSummary; channel?: ChannelSummary }> {
+	let teamReference = teamRef;
+	let channelReference = channelRef;
+
+	if (!teamReference && channelRef.includes("/")) {
+		const [first, ...rest] = channelRef.split("/");
+		teamReference = first;
+		channelReference = rest.join("/");
+	}
+
+	if (!teamReference) return {};
+
+	const team = await resolveTeam(conn, teamReference, signal);
+	if (!team) return {};
+
+	const channel = await resolveChannel(conn, team, channelReference, signal);
+	return { team, channel };
+}
+
+export async function createChannel(
+	conn: TeamsConnection,
+	team: TeamSummary,
+	input: { displayName: string; description?: string; membershipType?: string },
+	signal?: AbortSignal,
+): Promise<ChannelSummary> {
+	const raw = await graphPost<Record<string, unknown>>(
+		conn,
+		`/teams/${encodeURIComponent(team.id)}/channels`,
+		{
+			displayName: input.displayName,
+			description: input.description,
+			membershipType: input.membershipType ?? "standard",
+		},
+		{ signal },
+	);
+	return mapChannel((raw ?? {}) as Record<string, never>, { id: team.id, name: team.displayName });
+}
+
+// ---------------------------------------------------------------------------
+// Members
+// ---------------------------------------------------------------------------
+
+export async function listTeamMembers(
+	conn: TeamsConnection,
+	teamId: string,
+	max = 200,
+	signal?: AbortSignal,
+): Promise<MemberSummary[]> {
+	const raw = await graphList<Record<string, unknown>>(
+		conn,
+		`/teams/${encodeURIComponent(teamId)}/members`,
+		{ max, signal },
+	);
+	return raw.map((entry) => mapMember(entry as Record<string, never>));
+}
+
+export async function listChannelMembers(
+	conn: TeamsConnection,
+	teamId: string,
+	channelId: string,
+	max = 200,
+	signal?: AbortSignal,
+): Promise<MemberSummary[]> {
+	const raw = await graphList<Record<string, unknown>>(
+		conn,
+		`/teams/${encodeURIComponent(teamId)}/channels/${encodeURIComponent(channelId)}/members`,
+		{ max, signal },
+	);
+	return raw.map((entry) => mapMember(entry as Record<string, never>));
+}
+
+// ---------------------------------------------------------------------------
+// Files
+// ---------------------------------------------------------------------------
+
+/** Files in a channel's SharePoint folder. */
+export async function listChannelFiles(
+	conn: TeamsConnection,
+	teamId: string,
+	channelId: string,
+	max = 50,
+	signal?: AbortSignal,
+): Promise<DriveItemSummary[]> {
+	const folder = await graphRequest<Record<string, unknown>>(
+		conn,
+		"GET",
+		`/teams/${encodeURIComponent(teamId)}/channels/${encodeURIComponent(channelId)}/filesFolder`,
+		{ signal },
+	);
+
+	const parentReference = folder?.["parentReference"] as { driveId?: string } | undefined;
+	const driveId = parentReference?.driveId;
+	const itemId = folder?.["id"] as string | undefined;
+	if (!driveId || !itemId) return [];
+
+	const raw = await graphList<Record<string, unknown>>(
+		conn,
+		`/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(itemId)}/children`,
+		{ max, signal },
+	);
+	return raw.map((entry) => mapDriveItem(entry as Record<string, never>));
+}

package/src/safety/audit.ts

@@ -0,0 +1,57 @@
+/**
+ * Append-only audit log of everything pi wrote in the user's name.
+ *
+ * One JSON object per line in `~/.pi/agent/pi-teams-audit.jsonl`, mode 0600.
+ * The point is answerability: when a colleague asks "did you really send that
+ * at 23:40?", the user can look it up instead of guessing. Logging never
+ * blocks or fails an operation — a broken log is a smaller problem than a
+ * refused message.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "../config/index.ts";
+
+export interface AuditEntry {
+	/** ISO timestamp */
+	at: string;
+	/** Tool that performed the write */
+	tool: string;
+	account: string;
+	tenant: string;
+	/** Who pi acted as, when known */
+	actor?: string;
+	/** Human-readable target, e.g. "Engineering/General" */
+	target: string;
+	/** One-line description of what happened */
+	summary: string;
+	/** Present when the operation failed */
+	error?: string;
+}
+
+export function getAuditPath(): string {
+	return join(getAgentDir(), "pi-teams-audit.jsonl");
+}
+
+/** Append an entry. Never throws. */
+export function recordAudit(entry: AuditEntry): void {
+	try {
+		const path = getAuditPath();
+		const dir = dirname(path);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+		const isNew = !existsSync(path);
+		appendFileSync(path, `${JSON.stringify(entry)}\n`, { encoding: "utf-8", mode: 0o600 });
+		if (isNew) chmodSync(path, 0o600);
+	} catch {
+		/* auditing must never break the operation it describes */
+	}
+}
+
+/** Convenience wrapper used by the tools. */
+export function auditWrite(
+	enabled: boolean,
+	fields: Omit<AuditEntry, "at">,
+): void {
+	if (!enabled) return;
+	recordAudit({ at: new Date().toISOString(), ...fields });
+}

package/src/safety/index.ts

@@ -0,0 +1,186 @@
+/**
+ * The safety model — three independent gates, all of which must pass before
+ * pi says or changes anything as the user.
+ *
+ *  1. **Auth mode.** An app-only (client-credentials) token cannot post as a
+ *     person; Microsoft Graph only allows that for migration. Rather than
+ *     letting the call fail at Graph, writes are refused here with an
+ *     explanation.
+ *  2. **Safety level.** `readonly` blocks every mutation, `confirm` asks the
+ *     user first, `open` lets them through. Configurable globally, per account
+ *     and per tenant, most specific winning.
+ *  3. **Scope rules.** Allow/deny lists decide *which* teams, channels, chats
+ *     and people are in play at all — for reading as well as writing. See
+ *     ../config/scope.ts.
+ *
+ * Gates 1 and 2 live in the extension's `tool_call` interceptor because they
+ * need only the tool name. Gate 3 lives in the tools, because only they know
+ * which channel a message is actually headed for.
+ */
+
+import type { SafetyLevel, TeamsConnection } from "../config/index.ts";
+import { checkScope, type ScopeCategory, type ScopeMode } from "../config/scope.ts";
+import { ScopeDeniedError } from "../utils/errors.ts";
+import { MUTATION_TOOLS } from "../tools/tool-names.ts";
+
+// ---------------------------------------------------------------------------
+// Gate 1 + 2 — tool-level
+// ---------------------------------------------------------------------------
+
+export function isMutationTool(toolName: string): boolean {
+	return MUTATION_TOOLS.has(toolName);
+}
+
+/**
+ * Tools that only change local files — the config and the token cache.
+ *
+ * They still ask for confirmation, but `readonly` must not block them: that
+ * level means "do not change anything in Teams", and a user who set it still
+ * needs a way to add an account or sign out. They also work before anything is
+ * configured at all, which is the whole point of `teams_setup`.
+ */
+export const LOCAL_CONFIG_TOOLS = new Set<string>(["teams_setup", "teams_logout"]);
+
+/**
+ * Why a mutation must be refused outright, or undefined when it may proceed
+ * (possibly after confirmation).
+ */
+export function blockReason(
+	safetyLevel: SafetyLevel,
+	authMode: "device-code" | "client-credentials",
+	toolName: string,
+): string | undefined {
+	if (!isMutationTool(toolName)) return undefined;
+	if (LOCAL_CONFIG_TOOLS.has(toolName)) return undefined;
+
+	if (safetyLevel === "readonly") {
+		return (
+			`"${toolName}" is blocked: safetyLevel is "readonly". ` +
+			`Set safetyLevel to "confirm" or "open" in pi-teams.json (globally, on the account, or on the tenant).`
+		);
+	}
+
+	if (authMode === "client-credentials" && APP_ONLY_FORBIDDEN.has(toolName)) {
+		return (
+			`"${toolName}" cannot run on an app-only token. Microsoft Graph only permits app-only writes to ` +
+			`chats and channels for migration scenarios, so pi cannot post as a person this way. ` +
+			`Set authMode to "device-code" for this account and run teams_login.`
+		);
+	}
+
+	return undefined;
+}
+
+/**
+ * Tools that need a real user behind them.
+ * Directory reads and calendar work still function app-only.
+ */
+const APP_ONLY_FORBIDDEN = new Set<string>([
+	"teams_send_chat_message",
+	"teams_send_channel_message",
+	"teams_reply_channel_message",
+	"teams_create_chat",
+	"teams_delete_message",
+	"teams_react",
+	"teams_set_presence",
+	"teams_set_status_message",
+]);
+
+// ---------------------------------------------------------------------------
+// Confirmation summaries
+// ---------------------------------------------------------------------------
+
+/**
+ * One line describing what is about to happen, shown in the confirm dialog.
+ *
+ * This is the last thing a user reads before pi speaks for them, so it shows
+ * the destination and the actual text — never just the tool name.
+ */
+export function formatMutationSummary(
+	toolName: string,
+	params: Record<string, unknown>,
+): string {
+	const text = (value: unknown, max = 160): string => {
+		const str = String(value ?? "").replace(/\s*\n\s*/g, " ").trim();
+		return str.length > max ? `${str.slice(0, max - 1)}…` : str;
+	};
+
+	switch (toolName) {
+		case "teams_send_chat_message":
+			return `Send a chat message to "${text(params.chat, 60)}":\n\n${text(params.body, 400)}`;
+		case "teams_send_channel_message": {
+			const where = params.team ? `${text(params.team, 40)}/${text(params.channel, 40)}` : text(params.channel, 60);
+			return `Post in channel ${where}:\n\n${text(params.body, 400)}`;
+		}
+		case "teams_reply_channel_message": {
+			const where = params.team ? `${text(params.team, 40)}/${text(params.channel, 40)}` : text(params.channel, 60);
+			return `Reply in thread ${text(params.messageId, 40)} (${where}):\n\n${text(params.body, 400)}`;
+		}
+		case "teams_create_chat": {
+			const people = Array.isArray(params.participants) ? params.participants.join(", ") : text(params.participants);
+			return `Create a new chat with: ${text(people, 200)}`;
+		}
+		case "teams_create_channel":
+			return `Create channel "${text(params.name, 60)}" in team "${text(params.team, 60)}"`;
+		case "teams_delete_message":
+			return `Delete your message ${text(params.messageId, 60)}`;
+		case "teams_react":
+			return `${params.remove ? "Remove" : "Add"} reaction ${text(params.reaction, 10)} on message ${text(params.messageId, 50)}`;
+		case "teams_set_presence":
+			return `Set your Teams presence to ${text(params.availability, 30)}${params.expiresIn ? ` for ${text(params.expiresIn, 20)}` : ""}`;
+		case "teams_set_status_message":
+			return `Set your Teams status message to: "${text(params.message, 200)}"`;
+		case "teams_create_meeting":
+			return `Create meeting "${text(params.subject, 60)}" (${text(params.start, 30)} – ${text(params.end, 30)}) with ${text(Array.isArray(params.attendees) ? params.attendees.join(", ") : params.attendees, 160)}`;
+		case "teams_update_meeting":
+			return `Update meeting ${text(params.eventId, 50)}`;
+		case "teams_cancel_meeting":
+			return `Cancel meeting ${text(params.eventId, 50)}`;
+		case "teams_setup":
+			return `Write Teams account "${text(params.name, 40)}" to pi-teams.json`;
+		case "teams_logout":
+			return `Sign out of Teams account "${text(params.account, 40) || "(default)"}"`;
+		default:
+			return `${toolName}: ${text(JSON.stringify(params), 200)}`;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Gate 3 — scope enforcement
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert that a target is in scope, or throw.
+ *
+ * @param conn - the resolved connection carrying the rules
+ * @param mode - read or write
+ * @param category - which rule set applies
+ * @param label - how the target is named in the error message
+ * @param candidates - identifiers to match (id, name, path, e-mail, …)
+ *
+ * @throws {ScopeDeniedError}
+ */
+export function assertAccess(
+	conn: TeamsConnection,
+	mode: ScopeMode,
+	category: ScopeCategory,
+	label: string,
+	candidates: (string | undefined)[],
+): void {
+	const decision = checkScope(conn.permissions, mode, category, candidates);
+	if (!decision.allowed) {
+		throw new ScopeDeniedError(`${mode} ${category.replace(/s$/, "")} "${label}"`, decision.reason);
+	}
+}
+
+/** Non-throwing variant, for filtering lists. */
+export function hasAccess(
+	conn: TeamsConnection,
+	mode: ScopeMode,
+	category: ScopeCategory,
+	candidates: (string | undefined)[],
+): boolean {
+	return checkScope(conn.permissions, mode, category, candidates).allowed;
+}
+
+export { ScopeDeniedError };

package/src/status.ts

@@ -0,0 +1,90 @@
+/**
+ * Connection status helpers — pure, testable, TUI-free.
+ *
+ * Consumed by three surfaces: the footer status line, the persistent
+ * connection card in the transcript, and the `/teams-status` command.
+ */
+
+import type { TeamsConnection } from "./config/index.ts";
+import { getToken, isFresh } from "./auth/token-store.ts";
+import { formatPermissions } from "./config/scope.ts";
+
+/** Immutable snapshot of the active Teams connection. */
+export interface ConnectionCard {
+	account: string;
+	accountDisplayName: string;
+	tenant: string;
+	tenantId: string;
+	authMode: string;
+	safetyLevel: string;
+	/** Signed-in user, when a token is cached */
+	user?: string;
+	/** Whether a usable token exists right now */
+	signedIn: boolean;
+	/** ISO timestamp of token expiry, when known */
+	expiresAt?: string;
+	/** Other configured account names */
+	otherAccounts: string[];
+	/** Rendered scope rules */
+	permissionSummary: string;
+}
+
+export function buildConnectionCard(
+	conn: TeamsConnection | undefined,
+): ConnectionCard | undefined {
+	if (!conn) return undefined;
+
+	const token = getToken(conn.account, conn.tenantId);
+
+	return {
+		account: conn.account,
+		accountDisplayName: conn.accountDisplayName,
+		tenant: conn.tenant,
+		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,
+		otherAccounts: conn.allAccounts.map((a) => a.name).filter((name) => name !== conn.account),
+		permissionSummary: formatPermissions(conn.permissions),
+	};
+}
+
+/** Short footer label, e.g. "✓ Teams · work · anna@contoso.com". */
+export function buildConnectionLabel(card: ConnectionCard | undefined): string {
+	if (!card) return "Teams · not configured";
+	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}` : ""}`;
+}
+
+/** Rich markdown for `/teams-status` and the expanded card. */
+export function formatStatusText(card: ConnectionCard | undefined): string {
+	if (!card) {
+		return [
+			"## Microsoft Teams",
+			"",
+			"⚠️ **Not configured.**",
+			"",
+			"A template was created at `~/.pi/agent/pi-teams.json`. Fill in your Entra ID " +
+				"`tenantId` and `clientId` — or run the `teams_setup` tool — then run `teams_login`.",
+		].join("\n");
+	}
+
+	const lines: string[] = ["## Microsoft Teams", ""];
+	lines.push(`- **Account:** ${card.accountDisplayName}${card.accountDisplayName !== card.account ? ` (${card.account})` : ""}`);
+	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(`- **Safety level:** ${card.safetyLevel}`);
+	if (card.expiresAt) lines.push(`- **Token expires:** ${new Date(card.expiresAt).toLocaleString()}`);
+	if (card.otherAccounts.length > 0) {
+		lines.push(`- **Other accounts:** ${card.otherAccounts.join(", ")}`);
+	}
+
+	lines.push("", "### What pi may do", "", card.permissionSummary);
+	return lines.join("\n");
+}