@patimweb/pi-teams 1.0.0 → 1.2.0

package/skills/teams-collaboration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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; to schedule, change or cancel a Teams meeting; or to make pi notice incoming Teams messages on its own (listen mode). Also covers how to format a message for a chat rather than a document, multiple Teams accounts and multiple company tenants, and the allow/deny rules that decide what pi may touch.
 ---
 
 # Microsoft Teams
@@ -12,8 +12,10 @@ 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.
+signed in. If it reports "not signed in", run `teams_login`: it opens the
+user's browser and completes on its own. On a machine with no browser it falls
+back to a device code — then show the code and the URL to the user verbatim,
+because they cannot finish signing in without them.
 
 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.
@@ -89,6 +91,7 @@ checks a target without touching it.
 | `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 |
+| `teams_watch` | Letting pi notice incoming messages on its own |
 
 ## How to write as the user
 
@@ -103,6 +106,48 @@ checks a target without touching it.
 - Prefer `teams_reply_channel_message` over a new post when answering something
   — starting a second thread fragments the conversation.
 
+## 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
+markdown and let the tool do the rest.
+
+**Reach for this shape, not for paragraphs:**
+
+```
+Kurz: die QA-Umgebung 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.
+- **Bullets for anything enumerable** — causes, options, next steps. Three items
+  and up belong in a list, not in a sentence with commas.
+- **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.
+
+**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.
+
+**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,
+5 min") — but never shorten a fact into ambiguity.
+
+When pi listens on its own (see *Listen mode*), this matters most: an answer
+that arrives unrequested must be readable at a glance, because the recipient is
+not expecting it.
+
 ## Channel addressing
 
 Channels are addressed as `Team/Channel` or via separate `team` and `channel`
@@ -141,3 +186,46 @@ summarize from openers alone.
 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.
+
+## Listen mode
+
+Listen mode is the only case where pi acts without being asked: it polls the
+user's chats, and an incoming message is turned into a prompt. Off by default,
+and it costs one model turn per message that wakes it.
+
+```yaml
+teams_watch:
+  action: enable
+  chats: ["Anna*", "Vertrieb*"]     # where to listen
+  from: ["anna.schmidt@contoso.com"] # who to listen to
+  mentionOnly: false
+  intervalSeconds: 60
+```
+
+- `chats` decides **where** pi listens (topic, label, chat ID, participants),
+  `from` decides **to whom** (name, UPN, e-mail). Narrow both: a watcher that
+  watches everything answers everything.
+- `/teams-listen on|off|status` switches it in the session; `teams_watch
+  action: status` reports what is configured and what is actually running.
+- The first poll only records what is there — switching it on never answers the
+  backlog, only what arrives afterwards.
+- pi never wakes for its own messages, so it cannot answer itself.
+- Listen mode does **not** bypass anything: a reply it decides to send is
+  subject to the same safety level and scope rules as a reply you asked for. At
+  `safetyLevel: confirm` every one of them is confirmed with the user first.
+
+**When a listen prompt arrives**, do this:
+
+1. Judge the message before answering. "Danke, passt" needs no reply; a
+   question, a blocker or a decision does.
+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.
+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.
+
+Never let listen mode turn into a conversation with itself: if the incoming
+message is already an answer to something pi sent, the loop ends there.

package/src/auth/cache-plugin.ts

@@ -0,0 +1,215 @@
+/**
+ * MSAL token cache, persisted to disk.
+ *
+ * MSAL keeps its cache in memory and hands us a serialized blob through the
+ * `ICachePlugin` hooks; without persisting it, every pi session would start
+ * with a fresh sign-in. One file per account+tenant under
+ * `~/.pi/agent/pi-teams-tokens/`, mode 0600 — the blob contains refresh
+ * tokens.
+ *
+ * Writes go through a private temp file and an atomic rename: a truncated
+ * cache would silently sign the user out.
+ */
+
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+	chmodSync,
+	statSync,
+	renameSync,
+	unlinkSync,
+	readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { ICachePlugin, TokenCacheContext } from "@azure/msal-node";
+import { getAgentDir } from "../config/index.ts";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+export function getCacheDir(): string {
+	return join(getAgentDir(), "pi-teams-tokens");
+}
+
+/** Filesystem-safe cache key for an account+tenant pair. */
+export function cacheKey(account: string, tenantId: string): string {
+	const clean = (value: string) => value.toLowerCase().replace(/[^a-z0-9._-]/g, "_");
+	return `${clean(account)}__${clean(tenantId)}`;
+}
+
+export function getCachePath(account: string, tenantId: string): string {
+	return join(getCacheDir(), `${cacheKey(account, tenantId)}.json`);
+}
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
+function readBlob(path: string): string | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		// Older files, or a cache copied between machines, may be too permissive
+		// for something holding refresh tokens.
+		try {
+			const mode = statSync(path).mode & 0o777;
+			if (mode !== 0o600) chmodSync(path, 0o600);
+		} catch {
+			/* ignore */
+		}
+		return readFileSync(path, "utf-8");
+	} catch {
+		return undefined;
+	}
+}
+
+function writeBlob(path: string, blob: string): void {
+	const dir = getCacheDir();
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+	const tmpPath = `${path}.${process.pid}.tmp`;
+	try {
+		writeFileSync(tmpPath, blob, { encoding: "utf-8", mode: 0o600 });
+		chmodSync(tmpPath, 0o600);
+		renameSync(tmpPath, path);
+	} catch {
+		try {
+			unlinkSync(tmpPath);
+		} catch {
+			/* ignore */
+		}
+		// A cache that cannot be written is a degraded session, not a failed one:
+		// the tokens still work until the process exits.
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+/** Build the cache plugin for one account+tenant. */
+export function createCachePlugin(account: string, tenantId: string): ICachePlugin {
+	const path = getCachePath(account, tenantId);
+
+	return {
+		async beforeCacheAccess(context: TokenCacheContext): Promise<void> {
+			const blob = readBlob(path);
+			if (blob) context.tokenCache.deserialize(blob);
+		},
+		async afterCacheAccess(context: TokenCacheContext): Promise<void> {
+			if (context.cacheHasChanged) writeBlob(path, context.tokenCache.serialize());
+		},
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Inspection
+// ---------------------------------------------------------------------------
+
+/** What the status surfaces need to know, readable without MSAL or a network call. */
+export interface CacheSummary {
+	/** A cache file exists and holds an account */
+	present: boolean;
+	/** Signed-in identity, when the cache holds one */
+	username?: string;
+	name?: string;
+	/** Epoch milliseconds at which the newest access token expires */
+	expiresAt?: number;
+	/** Whether that access token is still valid */
+	fresh: boolean;
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Read the identity and expiry out of a cache file.
+ *
+ * The blob is MSAL's own schema, so this reads it defensively: a shape change
+ * upstream must degrade to "not signed in" in the status line, never throw in
+ * the middle of rendering the TUI.
+ */
+export function readCacheSummary(account: string, tenantId: string): CacheSummary {
+	const blob = readBlob(getCachePath(account, tenantId));
+	if (!blob) return { present: false, fresh: false };
+
+	try {
+		const parsed = JSON.parse(blob) as Record<string, any>;
+
+		const accounts = Object.values(parsed.Account ?? {}) as any[];
+		const first = accounts[0];
+
+		const tokens = Object.values(parsed.AccessToken ?? {}) as any[];
+		// expires_on is seconds-since-epoch, as a string, in MSAL's schema.
+		const expiries = tokens
+			.map((token) => Number(token?.expires_on))
+			.filter((value) => Number.isFinite(value) && value > 0);
+		const expiresAt = expiries.length > 0 ? Math.max(...expiries) * 1000 : undefined;
+
+		return {
+			present: accounts.length > 0 || tokens.length > 0,
+			username: first?.username,
+			name: first?.name,
+			expiresAt,
+			fresh: expiresAt !== undefined && expiresAt - 5 * 60 * 1000 > Date.now(),
+		};
+	} catch {
+		return { present: false, fresh: false };
+	}
+}
+
+/** Delete one cached session. Returns true when a file was removed. */
+export function removeCache(account: string, tenantId: string): boolean {
+	const path = getCachePath(account, tenantId);
+	if (!existsSync(path)) return false;
+	try {
+		unlinkSync(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Delete every cached session. Returns how many were removed. */
+export function removeAllCaches(): number {
+	const dir = getCacheDir();
+	if (!existsSync(dir)) return 0;
+
+	let removed = 0;
+	for (const entry of readdirSync(dir)) {
+		if (!entry.endsWith(".json")) continue;
+		try {
+			unlinkSync(join(dir, entry));
+			removed += 1;
+		} catch {
+			/* skip what we cannot remove */
+		}
+	}
+	return removed;
+}
+
+/** Every cached session on disk, for `teams_status` and the doctor. */
+export function listCachedSessions(): Array<{ key: string; summary: CacheSummary }> {
+	const dir = getCacheDir();
+	if (!existsSync(dir)) return [];
+
+	const sessions: Array<{ key: string; summary: CacheSummary }> = [];
+	for (const entry of readdirSync(dir)) {
+		if (!entry.endsWith(".json")) continue;
+		const key = entry.replace(/\.json$/, "");
+		const blob = readBlob(join(dir, entry));
+		if (!blob) continue;
+		try {
+			const parsed = JSON.parse(blob) as Record<string, any>;
+			const first = (Object.values(parsed.Account ?? {}) as any[])[0];
+			sessions.push({
+				key,
+				summary: { present: true, username: first?.username, name: first?.name, fresh: false },
+			});
+		} catch {
+			/* ignore an unreadable cache file */
+		}
+	}
+	return sessions;
+}