@patimweb/pi-teams 1.14.0 → 2.0.0

package/docs/listen-mode.md

@@ -50,6 +50,7 @@ never sees.
 | `mentionOnly` | `false` | whether a message has to address you: `true`/`false`, or `{ default, chats, people }` for overrides. See [below](#who-has-to-address-pi). |
 | `cooldownSeconds` | `300` | stay quiet in a chat after waking pi for it |
 | `maxTriggersPerHour` | `10` | hard cap on wakes per hour |
+| `historyReaders` | `[]` | who may use `teams_history` from their one-to-one chat, where each chat has a process of its own. See [below](#parallel-chats-with-pi-lanes). |
 
 Set it globally, or per account — the account level wins field by field.
 `teams_watch` writes the same keys; `/teams-listen` writes to the session's
@@ -152,6 +153,48 @@ untouched, because a gate that blocked ordinary work would be met far more often
 than an attack. It is released when the turn ends, and expires by itself after
 15 minutes so a turn that never ends cannot lock you out of your own tools.
 
+The pin is taken when the wake's prompt actually **enters the transcript**, not
+when the message is picked up. A wake that arrives while pi is still answering
+another chat waits in the queue; pinning it right away would take the pin away
+from the answer that is still being written, and that answer would be refused.
+
+A process that answers one chat only (see [below](#parallel-chats-with-pi-lanes))
+is pinned to it for its whole life.
+
+## Parallel chats with pi-lanes
+
+Every wake is a follow-up in the session that runs the watcher. That session
+works on one chat at a time: while it answers Anna, Bob waits.
+
+With [pi-lanes](https://github.com/Smotherer007/pi-lanes) installed, every
+chat gets a pi process of its own, with a session that carries on from message
+to message; different chats are answered in parallel. pi-teams does not do the
+routing itself. Before each wake prompt it emits a hint on pi's event bus
+(`pi-lanes:route`), and a router takes it from there. Without a router nobody
+listens, and everything stays as described above.
+
+The hint carries:
+
+| Field | Value |
+|-------|-------|
+| `lane` | `teams:<account>:<chat id>`: same chat, same process and session |
+| `env` | `PI_TEAMS_WORKER_CHAT` and friends (below) |
+| `command` | the newest message without mention and punctuation, so "Neo, stopp!" reads as `stopp` |
+| `trusted` | `true` only in a one-to-one chat with a person in `historyReaders` |
+
+A process started with `PI_TEAMS_WORKER_CHAT` answers that chat only: it is
+pinned to it for good, never starts a watcher of its own, and `teams_watch`,
+`teams_setup` and `teams_logout` are closed to it. Listen mode also starts on
+its own only in the terminal session (`ctx.mode === "tui"`), never in a pi
+driven over RPC.
+
+### What pi said in other chats
+
+Separate processes mean that no single context knows what pi told somebody
+else. The audit log does (`audit: true`), and `teams_history` reads it. In a
+process that answers one chat the tool works only in a one-to-one chat with a
+person listed in `historyReaders`; the terminal session is never restricted.
+
 ## Cost
 
 Each wake costs a model turn. That is what the filters and the hourly cap are

package/docs/tools.md

@@ -21,6 +21,7 @@ the default account. See [configuration.md](configuration.md).
 | Tool | Description |
 |------|-------------|
 | `teams_inbox` | Chats with new messages plus recent mentions of you |
+| `teams_history` | What pi sent across chats, from the audit log. Read-only; see [listen mode](listen-mode.md#what-pi-said-in-other-chats) |
 | `teams_list_chats` | Recent chats with a preview of the last message |
 | `teams_read_chat` | Messages of one chat |
 | `teams_list_teams` | Teams you belong to |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.14.0",
+  "version": "2.0.0",
   "description": "Microsoft Teams integration for pi coding agent — acts fully as the signed-in user across multiple accounts and tenants: chats, channels, meetings, presence, with configurable guardrails",
   "keywords": [
     "pi-package",

package/src/config/index.ts

@@ -135,6 +135,13 @@ export interface WatchConfig {
 	cooldownSeconds?: number;
 	/** Hard cap on wakes per hour, across all chats (default: 10) */
 	maxTriggersPerHour?: number;
+	/**
+	 * People who may, from their one-to-one chat with pi, read what pi wrote in
+	 * other chats (`teams_history`). Matched like `from`. Empty means nobody.
+	 * Only matters where a pi process answers a single chat, e.g. a lane run by
+	 * pi-lanes; the session a person types in is never restricted.
+	 */
+	historyReaders?: string[];
 }
 
 /**
@@ -189,6 +196,7 @@ export interface ResolvedWatchConfig {
 	mentionOnly: ResolvedMentionOnly;
 	cooldownSeconds: number;
 	maxTriggersPerHour: number;
+	historyReaders: string[];
 }
 
 /**
@@ -384,6 +392,7 @@ export const WATCH_DEFAULTS: ResolvedWatchConfig = {
 	mentionOnly: { default: false, chats: [], people: [] },
 	cooldownSeconds: 300,
 	maxTriggersPerHour: 10,
+	historyReaders: [],
 };
 
 /**
@@ -802,6 +811,7 @@ export function resolveWatchConfig(
 			WATCH_BOUNDS.maxTriggersPerHour,
 			WATCH_DEFAULTS.maxTriggersPerHour,
 		),
+		historyReaders: normalizePatterns(pick("historyReaders")),
 	};
 }
 

package/src/extension/index.ts

@@ -34,11 +34,16 @@ import {
 	setActiveWatchLoop,
 	startWatchLoop,
 	stopActiveWatchLoop,
+	type WatchEvent as WakeEvent,
 	type WatchLoop,
 } from "../watch/loop.ts";
 import { composeWatchPrompt } from "../watch/prompt.ts";
 import { setChatReadState } from "../graph/chats.ts";
-import { clearWakeTarget, pinViolation, pinWakeTarget } from "../watch/pin.ts";
+import { claimWakePin, clearWakeTarget, pinViolation, queueWakePin } from "../watch/pin.ts";
+import { commandText } from "../watch/control.ts";
+import { workerEnv, workerIdentity, workerViolation } from "../watch/worker.ts";
+import { matchesPattern } from "../config/scope.ts";
+import { withSenderAddresses } from "../watch/index.ts";
 import { readWatchCursor, writeWatchCursor } from "../watch/cursor.ts";
 
 import { teamsSetupTool } from "../tools/teams-setup.ts";
@@ -71,6 +76,7 @@ import { teamsChatMembersTool } from "../tools/teams-chat-members.ts";
 import { teamsAvailabilityTool } from "../tools/teams-availability.ts";
 import { teamsDeleteMessageTool } from "../tools/teams-delete-message.ts";
 import { teamsInboxTool } from "../tools/teams-inbox.ts";
+import { teamsHistoryTool } from "../tools/teams-history.ts";
 import { teamsWatchTool } from "../tools/teams-watch.ts";
 import {
 	teamsGetPresenceTool,
@@ -101,6 +107,48 @@ function mentionSummary(mentionOnly: ResolvedMentionOnly): string {
 	return overrides > 0 ? `${base} (${overrides} override${overrides === 1 ? "" : "s"})` : base;
 }
 
+/**
+ * The event-bus channel a lane router listens on (pi-lanes). Emitting on it is
+ * free when nobody listens, so pi-teams needs no dependency on the router.
+ */
+const LANE_HINT_CHANNEL = "pi-lanes:route";
+
+/** One line, at most `max` characters. */
+function oneLine(text: string | undefined, max = 160): string | undefined {
+	const flat = text?.replace(/\s+/g, " ").trim();
+	if (!flat) return undefined;
+	return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/**
+ * The routing hint for one wake: which conversation it belongs to, and what
+ * the process that answers it must know about itself.
+ *
+ * - `lane` is the chat, per account: same chat, same lane and session.
+ * - `env` pins that process to the chat (../watch/worker.ts).
+ * - `command` is the newest message without mention and punctuation, so the
+ *   router can recognise "stopp" or "neues Thema".
+ * - `trusted` is true only in a one-to-one chat with a `historyReaders` entry:
+ *   the only place where looking at other conversations is allowed.
+ */
+export function laneHint(conn: TeamsConnection, event: WakeEvent, prompt: string) {
+	const message = withSenderAddresses(event.message, event.chat);
+	const oneOnOne = event.chat.chatType === "oneOnOne";
+	const address = message.from?.mail ?? message.from?.upn;
+	const peer = oneOnOne ? address : undefined;
+	const trusted = !!peer && conn.watch.historyReaders.some((pattern) => matchesPattern(pattern, peer));
+	return {
+		text: prompt,
+		lane: `teams:${conn.account}:${event.chat.id}`,
+		label: `Teams: ${event.chat.label}`,
+		env: workerEnv({ chatId: event.chat.id, label: event.chat.label, chatType: event.chat.chatType, peer }),
+		command: commandText(message, event.me?.displayName),
+		request: oneLine(message.text),
+		from: message.from?.displayName,
+		trusted,
+	};
+}
+
 /** Every tool, in the order they appear in the documentation. */
 const tools = [
 	// Setup & session
@@ -137,6 +185,7 @@ const tools = [
 	teamsUpdateMessageTool,
 	teamsDeleteMessageTool,
 	teamsInboxTool,
+	teamsHistoryTool,
 	// Presence
 	teamsGetPresenceTool,
 	teamsSetPresenceTool,
@@ -178,6 +227,12 @@ export default function (pi: ExtensionAPI) {
 	 */
 	let watchSignature: string | undefined;
 
+	/**
+	 * Set when this process answers one chat only (a lane started for it, see
+	 * ../watch/worker.ts): it never watches, and may write nowhere else.
+	 */
+	const worker = workerIdentity();
+
 	/** The last polling error the user was told about, so it is said once. */
 	let reportedWatchError: string | undefined;
 
@@ -222,10 +277,6 @@ export default function (pi: ExtensionAPI) {
 			cursor: readWatchCursor(conn.account, conn.tenantId),
 			persistCursor: (seen) => writeWatchCursor(conn.account, conn.tenantId, seen),
 			onWake: (event) => {
-				// Pin before the prompt is delivered: the turn it starts may only
-				// answer the chat that woke pi, and the message it is about to read
-				// was written by somebody else.
-				pinWakeTarget(event.chat.id, event.chat.label);
 				// Mark the chat read the moment pi picks it up: with read receipts on,
 				// the sender sees the "seen" eye right away — the closest thing to a
 				// typing indicator Graph offers (there is no typing API for users).
@@ -233,7 +284,20 @@ export default function (pi: ExtensionAPI) {
 				if (event.me?.id) {
 					void setChatReadState(conn, event.chat.id, event.me, true).catch(() => undefined);
 				}
-				pi.sendUserMessage(composeWatchPrompt(event, event.me), { deliverAs: "followUp" });
+				const prompt = composeWatchPrompt(event, event.me);
+
+				// Tell a router which conversation this prompt belongs to. With
+				// pi-lanes installed, every chat is answered by a pi process of its
+				// own, in parallel with the others; without it nobody listens and the
+				// prompt takes the usual way into this session.
+				pi.events.emit(LANE_HINT_CHANNEL, laneHint(conn, event, prompt));
+
+				// The turn this prompt starts may only answer the chat that woke pi.
+				// The pin is taken when the prompt enters the transcript, not now:
+				// while pi is busy the prompt waits in the queue, and pinning here
+				// would take the pin away from the answer still being written.
+				queueWakePin(prompt, event.chat.id, event.chat.label);
+				pi.sendUserMessage(prompt, { deliverAs: "followUp" });
 			},
 			onTick: (status) => {
 				if (!status.lastError) reportedWatchError = undefined;
@@ -456,7 +520,10 @@ export default function (pi: ExtensionAPI) {
 		// and the same config: autoStart there would run a second watcher that
 		// answers chats inside a throwaway process and advances the shared cursor,
 		// so the real session never sees those messages.
-		if (connection.watch.autoStart && ctx.hasUI) startWatch(ctx, { explicit: true });
+		// A pi driven over RPC (a lane, an IDE) has a UI too, but nobody is
+		// typing in it: only the terminal session listens on its own.
+		const interactive = (ctx.mode ?? (ctx.hasUI ? "tui" : "print")) === "tui";
+		if (connection.watch.autoStart && interactive && !worker) startWatch(ctx, { explicit: true });
 
 		paintStatus(ctx);
 
@@ -517,6 +584,24 @@ export default function (pi: ExtensionAPI) {
 		stopWatch();
 	});
 
+	// A queued wake prompt has entered the transcript: its turn starts now, so
+	// this is when the answer gets pinned to its chat.
+	pi.on("message_start", async (event: any) => {
+		const message = event?.message;
+		if (message?.role !== "user") return;
+		const content = message.content;
+		const text =
+			typeof content === "string"
+				? content
+				: Array.isArray(content)
+					? content
+							.filter((part: any) => part?.type === "text" && typeof part.text === "string")
+							.map((part: any) => part.text)
+							.join("")
+					: "";
+		if (text) claimWakePin(text);
+	});
+
 	// -----------------------------------------------------------------------
 	// Safety interceptor
 	// -----------------------------------------------------------------------
@@ -528,6 +613,9 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
+		const workerBlock = workerViolation(event.toolName, worker);
+		if (workerBlock) return { block: true, reason: workerBlock };
+
 		if (!isMutationTool(event.toolName)) return;
 
 		// A tool may target a different account than the session default, so the

package/src/tools/teams-history.ts

@@ -0,0 +1,128 @@
+/**
+ * teams_history — what pi wrote in Teams, across chats.
+ *
+ * When every chat is answered by a pi process of its own (a lane, e.g. with
+ * pi-lanes), no single context knows what pi said elsewhere. The audit log
+ * does (every message pi sent, see ../safety/audit.ts), and this tool reads it
+ * to answer "what did you tell Anna today?".
+ *
+ * Reading across chats is exactly what separate processes prevent by default,
+ * so in a process that answers one chat the tool works only in a one-to-one
+ * chat with somebody listed in `watch.historyReaders`. The session a person
+ * types in is never restricted.
+ */
+
+import { existsSync, openSync, readSync, closeSync, statSync } from "node:fs";
+import { Type } from "typebox";
+import { matchesPattern } from "../config/scope.ts";
+import { getAuditPath } from "../safety/audit.ts";
+import { workerIdentity, type WorkerIdentity } from "../watch/worker.ts";
+import { errorResult, run, textResult, type ToolContext, type ToolResult } from "./shared.ts";
+
+/** How much of the end of a log is read. Old entries are the least asked for. */
+const TAIL_BYTES = 2 * 1024 * 1024;
+
+/** The last `TAIL_BYTES` of a JSONL file, parsed. Broken lines are skipped. */
+export function readJsonlTail(path: string, maxBytes = TAIL_BYTES): Record<string, any>[] {
+	if (!existsSync(path)) return [];
+	const size = statSync(path).size;
+	const start = Math.max(0, size - maxBytes);
+	const buffer = Buffer.alloc(size - start);
+	const fd = openSync(path, "r");
+	try {
+		readSync(fd, buffer, 0, buffer.length, start);
+	} finally {
+		closeSync(fd);
+	}
+	const lines = buffer.toString("utf-8").split("\n");
+	if (start > 0) lines.shift(); // first line is cut
+	const entries: Record<string, any>[] = [];
+	for (const line of lines) {
+		if (!line.trim()) continue;
+		try {
+			entries.push(JSON.parse(line));
+		} catch {
+			/* skip */
+		}
+	}
+	return entries;
+}
+
+/**
+ * Why this process may not read across chats, or undefined when it may.
+ * Exported for tests.
+ */
+export function historyRefusal(identity: WorkerIdentity | undefined, readers: string[]): string | undefined {
+	if (!identity) return undefined;
+	const allowed =
+		identity.chatType === "oneOnOne" &&
+		!!identity.peer &&
+		readers.some((pattern) => matchesPattern(pattern, identity.peer!));
+	if (allowed) return undefined;
+	return (
+		"What pi wrote in other chats is not available in this chat. Each chat keeps its own context, and only " +
+		"the people listed in watch.historyReaders may look across chats, from their one-to-one chat with pi."
+	);
+}
+
+interface HistoryParams {
+	chat?: string;
+	sinceHours?: number;
+	limit?: number;
+}
+
+/** Filter and render log entries. Exported for tests. */
+export function renderHistory(entries: Record<string, any>[], params: HistoryParams, now = Date.now()): string {
+	const limit = Math.min(Math.max(params.limit ?? 20, 1), 200);
+	const since = now - Math.min(Math.max(params.sinceHours ?? 24, 1), 24 * 90) * 3_600_000;
+	const needle = params.chat?.trim().toLowerCase();
+
+	const hits = entries.filter((entry) => {
+		const at = Date.parse(entry.at ?? "");
+		if (!Number.isFinite(at) || at < since) return false;
+		if (!needle) return true;
+		return `${entry.target ?? ""} ${entry.summary ?? ""}`.toLowerCase().includes(needle);
+	});
+
+	const shown = hits.slice(-limit);
+	if (shown.length === 0) return "No messages sent in that window.";
+
+	const lines = shown.map((entry) => {
+		const at = new Date(entry.at).toLocaleString();
+		const failed = entry.error ? ` (failed: ${entry.error})` : "";
+		return `- ${at} · ${entry.tool} → ${entry.target}: ${entry.summary}${failed}`;
+	});
+	const more = hits.length > shown.length ? `\n\n(${hits.length - shown.length} older entries not shown)` : "";
+	return lines.join("\n") + more;
+}
+
+export const teamsHistoryTool = {
+	name: "teams_history",
+	description:
+		"Look up what pi sent in Teams across chats (from the audit log). Use it when someone asks what pi told " +
+		"another person or chat. Read-only.",
+	parameters: Type.Object({
+		chat: Type.Optional(Type.String({ description: "Only entries whose chat or person contains this text" })),
+		sinceHours: Type.Optional(Type.Number({ description: "How far back, in hours (default 24, max 2160)" })),
+		limit: Type.Optional(Type.Number({ description: "Most recent entries to show (default 20, max 200)" })),
+	}),
+	promptSnippet: "Look up what pi wrote in other Teams chats",
+
+	async execute(
+		_toolCallId: string,
+		params: HistoryParams,
+		_signal: AbortSignal | undefined,
+		_onUpdate: undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> {
+		return run(async () => {
+			const readers = ctx.connection?.watch.historyReaders ?? [];
+			const refusal = historyRefusal(workerIdentity(), readers);
+			if (refusal) return errorResult(refusal);
+
+			const path = getAuditPath();
+			const text = renderHistory(readJsonlTail(path), params);
+			return textResult(text, { path });
+		});
+	},
+};

package/src/watch/control.ts

@@ -0,0 +1,45 @@
+/**
+ * Listen mode — the text of a trigger, as a command.
+ *
+ * A router such as pi-lanes can treat a short message as a control word
+ * ("stopp", "neues Thema") instead of a request. It needs the message the way
+ * the person meant it: without the mention of pi in front, without
+ * punctuation. This module produces exactly that, and nothing more; which
+ * words mean what is the router's business.
+ */
+
+import type { MessageSummary } from "../types.ts";
+
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Lower-case the text and drop mentions, punctuation and extra spaces. */
+export function normalizeCommand(text: string, names: string[] = []): string {
+	let result = ` ${text.toLowerCase()} `;
+	const sorted = [...new Set(names.map((n) => n.trim().toLowerCase()).filter(Boolean))].sort((a, b) => b.length - a.length);
+	for (const name of sorted) {
+		result = result.replace(new RegExp(`(^|[\\s@])${escapeRegExp(name)}(?=[\\s,.:;!?]|$)`, "g"), " ");
+	}
+	return result
+		.replace(/@/g, " ")
+		.replace(/[.,;:!?"'„“”«»()[\]]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * The names pi can be addressed by, for stripping a leading mention.
+ *
+ * "Neo (neoimpulse)" is mentioned as "Neo" in Teams, so the part before the
+ * first space or bracket counts as well.
+ */
+export function selfNames(displayName: string | undefined): string[] {
+	if (!displayName) return [];
+	const short = displayName.split(/[\s(]/)[0] ?? "";
+	return [displayName, short].filter(Boolean);
+}
+
+/** The newest message as a command: no mentions, no punctuation, lower case. */
+export function commandText(message: Pick<MessageSummary, "text" | "mentions">, myDisplayName?: string): string {
+	const names = [...(message.mentions ?? []).map((m) => m.displayName), ...selfNames(myDisplayName)];
+	return normalizeCommand(message.text ?? "", names);
+}

package/src/watch/pin.ts

@@ -17,6 +17,8 @@
  * turn, and one session runs one watcher.
  */
 
+import { workerIdentity, type WorkerIdentity } from "./worker.ts";
+
 /**
  * How long a pin can survive without the turn ending.
  *
@@ -35,6 +37,57 @@ interface Pin {
 
 let pin: Pin | undefined;
 
+/**
+ * Wakes whose prompt is queued but whose turn has not started yet.
+ *
+ * A wake is delivered as a follow-up: when pi is busy it waits in the queue.
+ * Pinning at wake time would therefore move the pin away from the answer that
+ * is still being written — the reply to chat A would be refused because chat B
+ * had just arrived. The pin is taken instead when the queued prompt actually
+ * enters the transcript (see `claimWakePin`), keyed by its exact text.
+ */
+const pending = new Map<string, Pin>();
+
+/** The worker identity of this process, read once. Overridable for tests. */
+let worker: WorkerIdentity | undefined = workerIdentity();
+
+/** Tests only: pretend this process is (or is not) a chat worker. */
+export function setWorkerIdentityForTests(identity: WorkerIdentity | undefined): void {
+	worker = identity;
+}
+
+/**
+ * Remember a queued wake, so its pin can be taken when its turn starts.
+ *
+ * Entries older than the pin TTL are dropped on the way: a prompt that never
+ * made it into a turn (cancelled queue, restart) must not pin a later one.
+ */
+export function queueWakePin(prompt: string, chatId: string, label: string, now = Date.now()): void {
+	for (const [text, entry] of pending) {
+		if (now - entry.at > PIN_TTL_MS) pending.delete(text);
+	}
+	pending.set(prompt, { chatId, label, at: now });
+}
+
+/**
+ * A user message entered the transcript: if it is a queued wake, pin it now.
+ *
+ * Returns whether a pin was taken. Anything else — typed input, other
+ * extensions' prompts — leaves the pin alone.
+ */
+export function claimWakePin(text: string, now = Date.now()): boolean {
+	const entry = pending.get(text);
+	if (!entry) return false;
+	pending.delete(text);
+	pin = { chatId: entry.chatId, label: entry.label, at: now };
+	return true;
+}
+
+/** How many wakes are queued but not yet pinned. */
+export function pendingWakePins(): number {
+	return pending.size;
+}
+
 /** 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 };
@@ -45,8 +98,17 @@ export function clearWakeTarget(): void {
 	pin = undefined;
 }
 
+/** Tests only: forget every queued wake as well. */
+export function resetWakePinsForTests(): void {
+	pin = undefined;
+	pending.clear();
+}
+
 /** The chat an answer is currently owed to, if any. */
 export function getWakeTarget(now = Date.now()): { chatId: string; label: string } | undefined {
+	// A chat worker is pinned for its whole life: it exists to answer one chat,
+	// so there is no turn after which it may write anywhere else.
+	if (worker) return { chatId: worker.chatId, label: worker.label };
 	if (!pin) return undefined;
 	if (now - pin.at > PIN_TTL_MS) {
 		pin = undefined;

package/src/watch/worker.ts

@@ -0,0 +1,79 @@
+/**
+ * Listen mode — who a chat worker is.
+ *
+ * Where a chat is answered by a pi process of its own (a lane, e.g. with
+ * pi-lanes), that process loads this extension like any other, so it has to
+ * know two things the moment it starts: that it must never run a watcher of
+ * its own, and which single chat it may write to.
+ *
+ * Both travel in the environment, set by the router that starts the lane (see
+ * `laneHint` in ../extension/index.ts). An environment variable is the one
+ * channel that exists before the first line of the extension runs, and the
+ * model cannot change it.
+ */
+
+/** Environment variables a chat worker is started with. */
+export const WORKER_ENV = {
+	/** The chat this worker answers, and the only one it may write to */
+	chat: "PI_TEAMS_WORKER_CHAT",
+	/** Chat label, for refusal messages and the session name */
+	label: "PI_TEAMS_WORKER_LABEL",
+	/** "oneOnOne" | "group" | "meeting" */
+	chatType: "PI_TEAMS_WORKER_CHAT_TYPE",
+	/**
+	 * Address of the other person, set for one-to-one chats only.
+	 *
+	 * Used to decide whether this chat may look at what pi wrote elsewhere
+	 * (`teams_history`). In a group chat there is no single person to ask, so
+	 * the variable is absent and the answer is no.
+	 */
+	peer: "PI_TEAMS_WORKER_PEER",
+} as const;
+
+export interface WorkerIdentity {
+	chatId: string;
+	label: string;
+	chatType?: string;
+	peer?: string;
+}
+
+/** The chat this process works for, or undefined in an ordinary pi session. */
+export function workerIdentity(env: NodeJS.ProcessEnv = process.env): WorkerIdentity | undefined {
+	const chatId = env[WORKER_ENV.chat]?.trim();
+	if (!chatId) return undefined;
+	return {
+		chatId,
+		label: env[WORKER_ENV.label]?.trim() || chatId,
+		chatType: env[WORKER_ENV.chatType]?.trim() || undefined,
+		peer: env[WORKER_ENV.peer]?.trim() || undefined,
+	};
+}
+
+/** The environment a worker for this chat is started with. */
+export function workerEnv(identity: WorkerIdentity): Record<string, string> {
+	const env: Record<string, string> = {
+		[WORKER_ENV.chat]: identity.chatId,
+		[WORKER_ENV.label]: identity.label,
+	};
+	if (identity.chatType) env[WORKER_ENV.chatType] = identity.chatType;
+	if (identity.peer) env[WORKER_ENV.peer] = identity.peer;
+	return env;
+}
+
+/**
+ * Tools a chat worker may not call at all.
+ *
+ * A worker answers one conversation. Switching listen mode, rewriting the
+ * config or signing the account out would change what every other worker and
+ * the watcher itself do, which is not a decision one chat gets to make.
+ */
+export const WORKER_FORBIDDEN_TOOLS = new Set<string>(["teams_watch", "teams_setup", "teams_logout"]);
+
+export function workerViolation(toolName: string, identity: WorkerIdentity | undefined): string | undefined {
+	if (!identity) return undefined;
+	if (!WORKER_FORBIDDEN_TOOLS.has(toolName)) return undefined;
+	return (
+		`This pi process answers the Teams chat "${identity.label}" only. ${toolName} changes listen mode or the ` +
+		"account for every chat, so it is not available here. Ask the user to do it in the main session."
+	);
+}