@patimweb/pi-teams 1.7.3 → 1.9.0

package/src/tools/teams-download-files.ts

@@ -7,7 +7,8 @@
  * returns the paths, so a reader can open them.
  */
 
-import { join } from "node:path";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { homedir } from "node:os";
 import { Type } from "typebox";
 import { getAgentDir } from "../config/index.ts";
 import { saveMessageFiles, type SavedFile, type SkippedFile } from "../graph/media.ts";
@@ -47,7 +48,13 @@ export const teamsDownloadFilesTool = {
 		limit: Type.Optional(
 			Type.Number({ description: "How many recent messages to scan (default 10, max 50)" }),
 		),
-		dir: Type.Optional(Type.String({ description: "Directory to save into (default: pi-teams-files)" })),
+		dir: Type.Optional(
+			Type.String({
+				description:
+					"Directory to save into. Must be inside the working directory, the pi agent directory, or the " +
+					"configured downloadDir. Defaults to the agent directory.",
+			}),
+		),
 		account: AccountParam,
 		tenant: TenantParam,
 	}),
@@ -106,7 +113,7 @@ export const teamsDownloadFilesTool = {
 					: await listChannelMessages(conn, channel, { max: scanLimit, signal });
 			}
 
-			const dir = params.dir ?? join(getAgentDir(), "pi-teams-files", slug);
+			const dir = resolveDownloadDir(params.dir, join(getAgentDir(), "pi-teams-files", slug), conn.downloadDir);
 
 			const saved: SavedFile[] = [];
 			const skipped: SkippedFile[] = [];
@@ -143,3 +150,40 @@ async function one(message: MessageSummary | undefined, messageId: string): Prom
 	if (!message) throw new TargetError(`No message ${messageId} in this conversation.`);
 	return [message];
 }
+
+/**
+ * Where the download may land.
+ *
+ * The directory is a tool parameter, so it is chosen by the model — and the
+ * model is reading messages other people wrote. Confining it keeps a download
+ * from landing in `~/.ssh` or a shell profile: the working directory and the
+ * agent directory are always allowed, and a user who wants somewhere else says
+ * so once in the configuration rather than per call.
+ *
+ * `~` is expanded first, because a path that silently means a literal `./~`
+ * would be its own small surprise.
+ */
+export function resolveDownloadDir(
+	requested: string | undefined,
+	fallback: string,
+	configured: string | undefined,
+): string {
+	if (!requested) return configured ? resolve(expandHome(configured)) : fallback;
+
+	const target = resolve(expandHome(requested));
+	const roots = [resolve(process.cwd()), resolve(getAgentDir())];
+	if (configured) roots.push(resolve(expandHome(configured)));
+
+	if (roots.some((root) => target === root || target.startsWith(root + sep))) return target;
+
+	throw new TargetError(
+		`Refusing to write downloads to "${target}". Allowed: ${roots.join(", ")}. ` +
+			`Set "downloadDir" in pi-teams.json to allow another location.`,
+	);
+}
+
+function expandHome(value: string): string {
+	if (value === "~") return homedir();
+	if (value.startsWith("~/") || value.startsWith("~\\")) return join(homedir(), value.slice(2));
+	return isAbsolute(value) ? value : value;
+}

package/src/tools/teams-watch.ts

@@ -53,6 +53,7 @@ const CURSOR_NOTES = [
 /** Renders the effective settings the same way the config file would. */
 function describe(watch: {
 	enabled: boolean;
+	autoStart: boolean;
 	intervalSeconds: number;
 	chats: string[];
 	from: string[];
@@ -62,6 +63,7 @@ function describe(watch: {
 }): string {
 	return [
 		`- enabled: ${watch.enabled}`,
+		`- starts with a session: ${watch.autoStart}`,
 		`- poll every: ${watch.intervalSeconds} s`,
 		`- chats: ${watch.chats.length > 0 ? watch.chats.map((c) => `\`${c}\``).join(", ") : "every chat with recent activity"}`,
 		`- people: ${watch.from.length > 0 ? watch.from.map((p) => `\`${p}\``).join(", ") : "any sender"}`,
@@ -82,8 +84,9 @@ function runtimeLines(runtime: WatchRuntimeStatus | undefined, conn: TeamsConnec
 		return [
 			"Nothing is polling in this session.",
 			"",
-			"Listen mode is read when a pi session starts. If the config says `enabled: true` and this "
-				+ "says otherwise, start a new session — or switch it with the `/teams-listen` command.",
+			"Listen mode starts only when it is switched on here — `/teams-listen on`, or "
+				+ "`teams_watch action: enable`. A stored `enabled: true` does not start it by itself: "
+				+ "set `watch.autoStart` if a session is meant to start listening on its own.",
 		];
 	}
 

package/src/utils/errors.ts

@@ -23,6 +23,34 @@ export class GraphError extends Error {
 	}
 }
 
+/**
+ * Raised when something asks us to send the access token somewhere it must not go.
+ *
+ * Message content is attacker-controlled — a file attachment's `contentUrl` and
+ * an `<img src>` in the body are both written by whoever sent the message — so a
+ * download URL that is not the tenant's own Graph endpoint is refused rather
+ * than fetched with an `Authorization` header.
+ */
+export class UntrustedHostError extends Error {
+	readonly url: string;
+	readonly expectedOrigin: string;
+	constructor(url: string, expectedOrigin: string) {
+		let host = url;
+		try {
+			host = new URL(url).host;
+		} catch {
+			/* keep the raw string */
+		}
+		super(
+			`Refusing to send your Microsoft Graph token to "${host}". ` +
+				`Only ${expectedOrigin} is trusted with it.`,
+		);
+		this.name = "UntrustedHostError";
+		this.url = url;
+		this.expectedOrigin = expectedOrigin;
+	}
+}
+
 /** Raised when a scope rule blocks an operation. */
 export class ScopeDeniedError extends Error {
 	readonly target: string;
@@ -49,6 +77,7 @@ const CONSENT_HINTS: Record<string, string> = {
 /** Normalize any thrown value into a readable, actionable message. */
 export function formatGraphError(error: unknown): string {
 	if (error instanceof ScopeDeniedError) return error.message;
+	if (error instanceof UntrustedHostError) return error.message;
 
 	if (error instanceof GraphError) {
 		switch (error.code) {

package/src/watch/loop.ts

@@ -328,6 +328,15 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 
 	let stopped = false;
 	let timer: ReturnType<typeof setTimeout> | undefined;
+	/**
+	 * The tick currently running, if any.
+	 *
+	 * Every tick schedules the next one when it finishes, so two ticks running at
+	 * once would leave two chains behind and quietly double the polling rate for
+	 * the rest of the session. `poll()` therefore joins the tick in flight
+	 * instead of starting a second one.
+	 */
+	let inFlight: Promise<void> | undefined;
 	let me: SignedInUser | undefined;
 	let meResolved = false;
 	let failureCount = 0;
@@ -343,7 +352,7 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 
 	const schedule = (delayMs: number) => {
 		if (stopped) return;
-		timer = setTimeout(() => void tick(), delayMs);
+		timer = setTimeout(() => void runTick(), delayMs);
 		// Do not hold the process open for a poll that can wait.
 		timer.unref?.();
 	};
@@ -406,14 +415,31 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 			options.onError?.(status.lastError);
 		}
 
-		options.onTick?.(status);
+		// Outside the try above on purpose, and guarded on its own: a throwing
+		// status callback must not become an unhandled rejection that takes the
+		// watcher down without a word.
+		try {
+			options.onTick?.(status);
+		} catch {
+			/* a footer that cannot render is not worth stopping the loop for */
+		}
+
 		schedule(watch.intervalSeconds * 1000 * Math.min(2 ** failureCount, 10));
 	}
 
+	/** Run a tick unless one is already running; either way, resolve with it. */
+	function runTick(): Promise<void> {
+		if (inFlight) return inFlight;
+		inFlight = tick().finally(() => {
+			inFlight = undefined;
+		});
+		return inFlight;
+	}
+
 	// The first tick is immediate: it answers what is still open since the last
 	// run, and a user who switched listen mode on should not wait a full interval
 	// to see it alive.
-	void tick();
+	void runTick();
 
 	return {
 		stop() {
@@ -424,9 +450,15 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 		},
 		status: () => ({ ...status, wakesThisHour: wakesThisHour(state, Date.now()) }),
 		async poll() {
+			// Join a tick already in flight rather than racing it; only start one
+			// when nothing is running.
+			if (inFlight) {
+				await inFlight;
+				return;
+			}
 			if (timer) clearTimeout(timer);
 			timer = undefined;
-			await tick();
+			await runTick();
 		},
 	};
 }

package/src/watch/pin.ts

@@ -0,0 +1,109 @@
+/**
+ * Listen mode — pinning the answer to the chat that asked for it.
+ *
+ * A wake puts somebody else's words into pi's prompt, and pi holds tools that
+ * write in the user's name. The prompt asks it to answer only the chat it was
+ * woken for, but an instruction inside a message is exactly the thing that can
+ * talk a model out of following an instruction in a prompt. So the rule is
+ * enforced here instead: while an answer is pending, sending anywhere other
+ * than the chat that woke pi is refused by the safety interceptor.
+ *
+ * This is deliberately narrow. It gates outgoing messages only — the tools that
+ * speak to other people — and not reading, presence or the calendar, because a
+ * pin that blocks unrelated work would be a bug the user meets far more often
+ * than an attack.
+ *
+ * Module state rather than a parameter: the interceptor sees a tool call, not a
+ * turn, and one session runs one watcher.
+ */
+
+/**
+ * How long a pin can survive without the turn ending.
+ *
+ * The pin is normally cleared when the agent settles. The timeout is the
+ * backstop for the case where that never arrives — a crash, a cancelled run —
+ * so a stuck pin cannot lock the user out of their own tools.
+ */
+export const PIN_TTL_MS = 15 * 60 * 1000;
+
+interface Pin {
+	chatId: string;
+	/** Chat label, for the refusal message */
+	label: string;
+	at: number;
+}
+
+let pin: Pin | undefined;
+
+/** Pin the answer of the turn that is about to start to one chat. */
+export function pinWakeTarget(chatId: string, label: string, now = Date.now()): void {
+	pin = { chatId, label, at: now };
+}
+
+/** Release the pin. Safe to call when there is none. */
+export function clearWakeTarget(): void {
+	pin = undefined;
+}
+
+/** The chat an answer is currently owed to, if any. */
+export function getWakeTarget(now = Date.now()): { chatId: string; label: string } | undefined {
+	if (!pin) return undefined;
+	if (now - pin.at > PIN_TTL_MS) {
+		pin = undefined;
+		return undefined;
+	}
+	return { chatId: pin.chatId, label: pin.label };
+}
+
+/**
+ * Tools that speak to people, and must therefore stay inside the pinned chat.
+ *
+ * Reading, presence and calendar tools are absent on purpose: they do not put
+ * words in anyone's inbox, and gating them would break ordinary work for no
+ * security gain.
+ */
+const OUTGOING_TOOLS = new Set<string>([
+	"teams_send_chat_message",
+	"teams_send_channel_message",
+	"teams_reply_channel_message",
+	"teams_create_chat",
+	"teams_chat_members",
+	"teams_update_message",
+	"teams_react",
+]);
+
+/**
+ * Why this call must not go through while an answer is pinned, or undefined.
+ *
+ * The chat is matched on its ID, because that is what the wake prompt hands the
+ * model and the only identifier that cannot be talked into meaning a different
+ * conversation.
+ */
+export function pinViolation(
+	toolName: string,
+	params: Record<string, unknown>,
+	now = Date.now(),
+): string | undefined {
+	const target = getWakeTarget(now);
+	if (!target) return undefined;
+	if (!OUTGOING_TOOLS.has(toolName)) return undefined;
+
+	const explain = (what: string) =>
+		`Listen mode is answering "${target.label}". ${what} Only that chat may be written to until the ` +
+		`answer is done — a message can ask for anything, and this is the part that does not take its word for it.`;
+
+	if (toolName === "teams_send_channel_message" || toolName === "teams_reply_channel_message") {
+		return explain("This would post in a channel.");
+	}
+	if (toolName === "teams_create_chat") {
+		return explain("This would start a different conversation.");
+	}
+
+	const chat = typeof params.chat === "string" ? params.chat : undefined;
+	if (!chat) return explain("This does not name the chat it would write to.");
+	if (chat !== target.chatId) {
+		return explain(`This would write to "${chat}" instead.`);
+	}
+
+	return undefined;
+}