@patimweb/pi-teams 1.13.0 → 1.15.0

package/docs/listen-mode.md

@@ -46,10 +46,11 @@ never sees.
 | `autoStart` | `false` | whether a session with a UI may start the watcher without being asked |
 | `intervalSeconds` | `60` | seconds between polls (minimum 15) |
 | `chats` | `[]` | **where** pi listens: glob patterns matched against topic, label, chat ID and participant names. Empty means every recent chat. |
-| `from` | `[]` | **who** pi listens to: glob patterns matched against display name, UPN and e-mail. Empty means any sender. |
+| `from` | `[]` | **who** pi listens to: glob patterns matched against display name, UPN and e-mail — so `*@contoso.com` covers a whole domain. Graph sends a sender without address; pi fills it in from the chat's member list or the directory. Empty means any sender. |
 | `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 |
+| `dispatch` | `{ "mode": "session" }` | where a wake is answered: in this session, or by one pi process per chat. See [below](#one-pi-process-per-chat). |
 
 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,87 @@ 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.
+
+In [dispatch mode](#one-pi-process-per-chat) every worker is pinned to its chat
+for its whole life: it exists to answer that one conversation.
+
+## One pi process per chat
+
+By default 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, and when
+Anna asked for something that takes twenty minutes, Bob waits twenty minutes.
+
+`dispatch.mode: "process"` hands every chat a pi process of its own:
+
+```json
+"watch": {
+  "dispatch": {
+    "mode": "process",
+    "maxConcurrent": 3,
+    "maxWorkers": 6,
+    "idleMinutes": 30,
+    "freshAfterHours": 72,
+    "args": ["--model", "provider/model-id"],
+    "stopWords": ["stop", "stopp", "abbrechen"],
+    "resetWords": ["neues thema", "new topic"],
+    "historyReaders": ["you@contoso.com"]
+  }
+}
+```
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `mode` | `"session"` | `"process"` switches the worker pool on |
+| `maxConcurrent` | `3` | chats worked on at the same time (1-16); more wait in line |
+| `maxWorkers` | `6` | processes kept alive, busy or idle; the longest-idle one makes room |
+| `idleMinutes` | `30` | an idle worker exits after this; its session stays on disk |
+| `freshAfterHours` | `72` | a chat quiet for longer starts a fresh session (`0` = always continue) |
+| `command` | `"pi"` | the pi executable |
+| `args` | `[]` | extra arguments for every worker, e.g. the model |
+| `stopWords` | `stop, stopp, abbrechen, abbruch, cancel` | a message that is only this word aborts the running work |
+| `resetWords` | `neues thema, new topic, reset` | a message that is only this word starts the chat over |
+| `historyReaders` | `[]` | who may use `teams_history` from their one-to-one chat with pi |
+
+How it behaves:
+
+| In Teams | What happens |
+|----------|--------------|
+| Messages in different chats | answered in parallel, each by its chat's worker |
+| Next message in the same chat | the chat's session continues, with the whole conversation so far |
+| A message while the worker is busy | steered into the running turn: read after the current step, not after the task |
+| `stopp` | the running turn is aborted; the model confirms in one line |
+| `neues Thema` | the worker ends, the chat starts a fresh session; the old one stays on disk |
+| More busy chats than `maxConcurrent` | the next chat waits for a free slot; a newer message replaces its waiting one |
+
+Each worker runs `pi --mode rpc --session-dir <agent dir>/pi-teams-chats/<hash>`
+with `--continue` while the chat's last session is recent. It loads the same
+extensions and config as any pi, with three differences set through its
+environment (`PI_TEAMS_WORKER_CHAT` and friends): it never starts a watcher, it
+may write to its own chat only, and `teams_watch`, `teams_setup` and
+`teams_logout` are closed to it. Dialogs a worker would show are cancelled,
+because nobody sits in front of it, so run it with `safetyLevel: "open"` and
+keep the guardrails in `from`, the pin and the permission rules.
+
+The watching session only routes. `/teams-dispatch` shows which chats are being
+worked on, which are idle and which wait.
+
+### What pi said in other chats
+
+Separate sessions mean that no single context knows what pi told somebody else.
+Two logs do, and `teams_history` reads them:
+
+- `kind: "sent"`: every message pi sent, from the audit log (`audit: true`).
+- `kind: "dispatch"`: every request a worker picked up and a short form of its
+  answer, from `pi-teams-dispatch.jsonl` in the agent directory.
+
+Nothing from one chat reaches another chat's context by itself. Inside a worker
+the tool answers only in a one-to-one chat with a person listed in
+`historyReaders`; the watching 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 (audit log), or what the per-chat workers were asked and answered (dispatch journal). 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 |
@@ -74,6 +75,7 @@ usual; correcting a channel post stays in the Teams client.
 | `/teams-login` | Sign in to Teams as yourself |
 | `/teams-inbox` | What needs your attention right now |
 | `/teams-listen` | Listen mode: `on`, `off`, or `status` |
+| `/teams-dispatch` | Listen mode with one pi process per chat: who is being worked on, who is idle, who waits |
 | `/teams-permissions` | What pi may and may not do |
 | `/teams-doctor` | Diagnose the setup |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.13.0",
+  "version": "1.15.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,70 @@ export interface WatchConfig {
 	cooldownSeconds?: number;
 	/** Hard cap on wakes per hour, across all chats (default: 10) */
 	maxTriggersPerHour?: number;
+	/**
+	 * How a wake reaches a model. See `DispatchConfig`. Absent means the
+	 * classic behaviour: every wake is a turn in this pi session.
+	 */
+	dispatch?: DispatchConfig;
+}
+
+/**
+ * Where the answer to a wake is worked out.
+ *
+ * `session` (default) queues every wake as a follow-up in the pi session that
+ * runs the watcher. One chat at a time: while pi works on one request, every
+ * other chat waits.
+ *
+ * `process` gives every chat a pi process of its own (`pi --mode rpc`), with a
+ * session of its own that carries on from message to message. Different chats
+ * are answered in parallel; messages in the same chat stay in order, and one
+ * that arrives while the worker is busy is steered into the running turn. The
+ * watching session itself only routes.
+ */
+export interface DispatchConfig {
+	/** "session" (default) or "process" */
+	mode?: DispatchMode;
+	/** Chats worked on at the same time (default: 3, 1-16) */
+	maxConcurrent?: number;
+	/** Worker processes kept alive, busy or idle (default: 6, at least maxConcurrent, max 32) */
+	maxWorkers?: number;
+	/** An idle worker exits after this many minutes; its session stays (default: 30) */
+	idleMinutes?: number;
+	/**
+	 * A chat quiet for longer than this starts a fresh session instead of
+	 * continuing the last one (default: 72, 0 = always continue).
+	 */
+	freshAfterHours?: number;
+	/** The pi executable (default: "pi") */
+	command?: string;
+	/** Extra arguments for every worker, e.g. ["--model", "provider/id"] */
+	args?: string[];
+	/** A message consisting of one of these aborts the running work (case-insensitive) */
+	stopWords?: string[];
+	/** A message consisting of one of these starts a fresh session for the chat */
+	resetWords?: string[];
+	/**
+	 * 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;
+	 * the watching session itself is never restricted.
+	 */
+	historyReaders?: string[];
+}
+
+export type DispatchMode = "session" | "process";
+
+/** A dispatch config after every default and clamp has been applied. */
+export interface ResolvedDispatchConfig {
+	mode: DispatchMode;
+	maxConcurrent: number;
+	maxWorkers: number;
+	idleMinutes: number;
+	freshAfterHours: number;
+	command: string;
+	args: string[];
+	stopWords: string[];
+	resetWords: string[];
+	historyReaders: string[];
 }
 
 /**
@@ -189,6 +253,7 @@ export interface ResolvedWatchConfig {
 	mentionOnly: ResolvedMentionOnly;
 	cooldownSeconds: number;
 	maxTriggersPerHour: number;
+	dispatch: ResolvedDispatchConfig;
 }
 
 /**
@@ -384,6 +449,25 @@ export const WATCH_DEFAULTS: ResolvedWatchConfig = {
 	mentionOnly: { default: false, chats: [], people: [] },
 	cooldownSeconds: 300,
 	maxTriggersPerHour: 10,
+	dispatch: {
+		mode: "session",
+		maxConcurrent: 3,
+		maxWorkers: 6,
+		idleMinutes: 30,
+		freshAfterHours: 72,
+		command: "pi",
+		args: [],
+		stopWords: ["stop", "stopp", "abbrechen", "abbruch", "cancel"],
+		resetWords: ["neues thema", "new topic", "reset"],
+		historyReaders: [],
+	},
+};
+
+const DISPATCH_BOUNDS = {
+	maxConcurrent: { min: 1, max: 16 },
+	maxWorkers: { min: 1, max: 32 },
+	idleMinutes: { min: 1, max: 1440 },
+	freshAfterHours: { min: 0, max: 8760 },
 };
 
 /**
@@ -802,6 +886,36 @@ export function resolveWatchConfig(
 			WATCH_BOUNDS.maxTriggersPerHour,
 			WATCH_DEFAULTS.maxTriggersPerHour,
 		),
+		dispatch: resolveDispatchConfig(pick("dispatch")),
+	};
+}
+
+/**
+ * Normalise the dispatch settings. Exported for tests.
+ *
+ * `maxWorkers` is raised to `maxConcurrent` when set lower: a worker that is
+ * busy is alive, so fewer live workers than parallel chats is not a limit but
+ * a contradiction.
+ */
+export function resolveDispatchConfig(value: DispatchConfig | undefined): ResolvedDispatchConfig {
+	const d = WATCH_DEFAULTS.dispatch;
+	const v = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+	const words = (list: unknown, fallback: string[]): string[] =>
+		Array.isArray(list)
+			? list.filter((w): w is string => typeof w === "string" && w.trim() !== "").map((w) => w.trim().toLowerCase())
+			: fallback;
+	const maxConcurrent = clamp(v.maxConcurrent, DISPATCH_BOUNDS.maxConcurrent, d.maxConcurrent);
+	return {
+		mode: v.mode === "process" ? "process" : "session",
+		maxConcurrent,
+		maxWorkers: Math.max(maxConcurrent, clamp(v.maxWorkers, DISPATCH_BOUNDS.maxWorkers, d.maxWorkers)),
+		idleMinutes: clamp(v.idleMinutes, DISPATCH_BOUNDS.idleMinutes, d.idleMinutes),
+		freshAfterHours: clamp(v.freshAfterHours, DISPATCH_BOUNDS.freshAfterHours, d.freshAfterHours),
+		command: typeof v.command === "string" && v.command.trim() ? v.command.trim() : d.command,
+		args: Array.isArray(v.args) ? v.args.filter((a): a is string => typeof a === "string") : [...d.args],
+		stopWords: words(v.stopWords, d.stopWords),
+		resetWords: words(v.resetWords, d.resetWords),
+		historyReaders: normalizePatterns(v.historyReaders),
 	};
 }
 

package/src/extension/index.ts

@@ -11,6 +11,7 @@ import { Box, Text } from "@earendil-works/pi-tui";
 
 import {
 	ensureConfigTemplate,
+	getAgentDir,
 	getConfigPath,
 	setWatchConfig,
 	type ResolvedMentionOnly,
@@ -38,7 +39,11 @@ import {
 } 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 { ChatDispatcher, excerpt } from "../watch/dispatch.ts";
+import { controlAction } from "../watch/control.ts";
+import { workerIdentity, workerViolation } from "../watch/worker.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,
@@ -137,6 +143,7 @@ const tools = [
 	teamsUpdateMessageTool,
 	teamsDeleteMessageTool,
 	teamsInboxTool,
+	teamsHistoryTool,
 	// Presence
 	teamsGetPresenceTool,
 	teamsSetPresenceTool,
@@ -178,6 +185,37 @@ export default function (pi: ExtensionAPI) {
 	 */
 	let watchSignature: string | undefined;
 
+	/**
+	 * Set when this process is a chat worker started by a dispatcher: it answers
+	 * one chat, never watches, and may write nowhere else (see ../watch/worker.ts).
+	 */
+	const worker = workerIdentity();
+
+	/** The per-chat worker pool, in dispatch mode `process`. Created on the first wake. */
+	let dispatcher: ChatDispatcher | undefined;
+	/** The context the dispatcher reports problems to. */
+	let dispatchCtx: any;
+
+	const dispatcherFor = (conn: TeamsConnection, ctx: any): ChatDispatcher => {
+		dispatchCtx = ctx;
+		if (dispatcher) {
+			dispatcher.configure(conn.watch.dispatch);
+			return dispatcher;
+		}
+		dispatcher = new ChatDispatcher({
+			config: conn.watch.dispatch,
+			agentDir: getAgentDir(),
+			cwd: ctx?.cwd ?? process.cwd(),
+			onError: (message) => dispatchCtx?.ui?.notify?.(message, "warning"),
+		});
+		return dispatcher;
+	};
+
+	const stopDispatcher = () => {
+		dispatcher?.stopAll();
+		dispatcher = undefined;
+	};
+
 	/** The last polling error the user was told about, so it is said once. */
 	let reportedWatchError: string | undefined;
 
@@ -222,10 +260,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 +267,30 @@ 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);
+
+				// Dispatch mode: the chat's own worker answers, in parallel with other chats.
+				if (conn.watch.dispatch.mode === "process") {
+					const message = withSenderAddresses(event.message, event.chat);
+					dispatcherFor(conn, ctx).deliver({
+						chatId: event.chat.id,
+						label: event.chat.label,
+						chatType: event.chat.chatType,
+						from: message.from?.displayName,
+						peer: message.from?.mail ?? message.from?.upn,
+						prompt,
+						request: excerpt(message.text),
+						control: controlAction(message, conn.watch.dispatch, event.me?.displayName),
+					});
+					return;
+				}
+
+				// Session mode: 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;
@@ -384,12 +441,40 @@ export default function (pi: ExtensionAPI) {
 					conn.watch.from.length > 0 ? `people: ${conn.watch.from.join(", ")}` : "any sender",
 					mentionSummary(conn.watch.mentionOnly),
 					runtime ? `${runtime.wakesThisHour} wake(s) this hour` : "not running in this session",
+					conn.watch.dispatch.mode === "process"
+						? `one process per chat (${dispatcher?.status().busy ?? 0}/${conn.watch.dispatch.maxConcurrent} busy)`
+						: "answers in this session",
 				].join(" · "),
 				"info",
 			);
 		},
 	});
 
+	pi.registerCommand("teams-dispatch", {
+		description: "Show the per-chat workers of listen mode (dispatch mode process)",
+		handler: async (_args, ctx) => {
+			const conn = refresh();
+			if (!conn || conn.watch.dispatch.mode !== "process") {
+				ctx.ui.notify("Teams dispatch: off. Every wake is a turn in this session (watch.dispatch.mode).", "info");
+				return;
+			}
+			const status = dispatcher?.status();
+			if (!status || status.alive + status.queued === 0) {
+				ctx.ui.notify(`Teams dispatch: no worker running (max ${conn.watch.dispatch.maxConcurrent} in parallel).`, "info");
+				return;
+			}
+			const minutes = (ms: number) => `${Math.max(0, Math.round(ms / 60_000))} min`;
+			ctx.ui.notify(
+				[
+					`Teams dispatch: ${status.busy}/${status.maxConcurrent} busy, ${status.alive} alive, ${status.queued} waiting`,
+					...status.chats.map((c) => `- ${c.label}: ${c.busy ? `working for ${minutes(c.sinceMs)}` : `idle for ${minutes(c.sinceMs)}`}`),
+					...status.waiting.map((c) => `- ${c.label}: waiting for a slot`),
+				].join("\n"),
+				"info",
+			);
+		},
+	});
+
 	pi.registerCommand("teams-inbox", {
 		description: "Show what needs your attention in Microsoft Teams",
 		handler: async (_args, ctx) => {
@@ -456,7 +541,9 @@ 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 chat worker (--mode rpc, so hasUI is true) is excluded by name: it is
+		// started by the watcher and must never become one.
+		if (connection.watch.autoStart && ctx.hasUI && !worker) startWatch(ctx, { explicit: true });
 
 		paintStatus(ctx);
 
@@ -515,6 +602,26 @@ export default function (pi: ExtensionAPI) {
 		// The timer would be unref'd anyway, but a poll in flight during shutdown
 		// would still be a Graph call for a session that is gone.
 		stopWatch();
+		// Workers end with the session that started them; their sessions stay on disk.
+		stopDispatcher();
+	});
+
+	// 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);
 	});
 
 	// -----------------------------------------------------------------------
@@ -528,6 +635,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
@@ -596,6 +706,7 @@ export default function (pi: ExtensionAPI) {
 			// A watcher polling a session that was just removed only produces
 			// errors; leaving it running would be noise, not service.
 			stopWatch();
+			stopDispatcher();
 		} else if (WATCH_CONFIG_TOOLS.has(event.toolName)) {
 			// Only `enable` is a decision. A status call, or a re-read after
 			// teams_setup, may stop the loop but never start it.

package/src/graph/mappers.ts

@@ -52,7 +52,8 @@ export function mapPerson(raw: Raw | undefined): PersonRef | undefined {
 	const name = identity.displayName ?? identity.userPrincipalName ?? identity.email;
 	if (!name && !identity.id) return undefined;
 	return {
-		id: identity.id ?? undefined,
+		// A chat member's `id` is the *membership* id; the person is `userId`.
+		id: identity.userId ?? identity.id ?? undefined,
 		displayName: name ?? "(unknown)",
 		upn: identity.userPrincipalName ?? undefined,
 		mail: identity.email ?? identity.mail ?? undefined,

package/src/graph/me.ts

@@ -20,6 +20,26 @@ export async function getMe(conn: TeamsConnection, signal?: AbortSignal): Promis
 	return { ...user, tenantId: conn.tenantId };
 }
 
+/**
+ * UPN and mail of one user, by object id.
+ *
+ * A chat message's sender carries only id and display name, so a listen rule
+ * like `*@contoso.com` has nothing to match against without this lookup.
+ */
+export async function getUserAddresses(
+	conn: TeamsConnection,
+	userId: string,
+	signal?: AbortSignal,
+): Promise<{ upn?: string; mail?: string }> {
+	const raw = await graphRequest<Record<string, string | null | undefined>>(
+		conn,
+		"GET",
+		`/users/${encodeURIComponent(userId)}`,
+		{ query: { $select: "userPrincipalName,mail" }, signal },
+	);
+	return { upn: raw?.userPrincipalName ?? undefined, mail: raw?.mail ?? undefined };
+}
+
 /**
  * Find people by name, UPN or e-mail.
  *

package/src/tools/teams-history.ts

@@ -0,0 +1,152 @@
+/**
+ * teams_history — what pi wrote in Teams, and what the chat workers were asked.
+ *
+ * In dispatch mode every chat has a session of its own, so no single context
+ * knows what pi said elsewhere. This tool answers "what did you tell Anna
+ * today?" from the two logs that do know: the audit log (every message pi
+ * sent, see ../safety/audit.ts) and the dispatch journal (every request a chat
+ * worker picked up, and its answer, see ../watch/dispatch.ts).
+ *
+ * Reading across chats is exactly what the per-chat sessions exist to prevent
+ * by default, so inside a chat worker the tool answers only in a one-to-one
+ * chat with somebody listed in `watch.dispatch.historyReaders`. The watching
+ * session — the user at the keyboard — is never restricted.
+ */
+
+import { existsSync, openSync, readSync, closeSync, statSync } from "node:fs";
+import { Type } from "typebox";
+import { getAgentDir } from "../config/index.ts";
+import { matchesPattern } from "../config/scope.ts";
+import { getAuditPath } from "../safety/audit.ts";
+import { getDispatchJournalPath } from "../watch/dispatch.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.dispatch.historyReaders may look across chats, from their one-to-one chat with pi."
+	);
+}
+
+interface HistoryParams {
+	kind?: "sent" | "dispatch";
+	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 kind = params.kind ?? "sent";
+	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;
+		const haystack =
+			kind === "sent"
+				? `${entry.target ?? ""} ${entry.summary ?? ""}`
+				: `${entry.chat ?? ""} ${entry.chatId ?? ""} ${entry.from ?? ""}`;
+		return haystack.toLowerCase().includes(needle);
+	});
+
+	const shown = hits.slice(-limit);
+	if (shown.length === 0) return kind === "sent" ? "No messages sent in that window." : "No dispatch entries in that window.";
+
+	const lines = shown.map((entry) => {
+		const at = new Date(entry.at).toLocaleString();
+		if (kind === "sent") {
+			const failed = entry.error ? ` (failed: ${entry.error})` : "";
+			return `- ${at} · ${entry.tool} → ${entry.target}: ${entry.summary}${failed}`;
+		}
+		const parts = [`- ${at} · ${entry.chat} · ${entry.event}`];
+		if (entry.from) parts.push(`from ${entry.from}`);
+		if (entry.request) parts.push(`asked: ${entry.request}`);
+		if (entry.result) parts.push(`answered: ${entry.result}`);
+		if (entry.durationMs) parts.push(`${Math.round(entry.durationMs / 1000)} s`);
+		if (entry.detail) parts.push(entry.detail);
+		return parts.join(" · ");
+	});
+	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 did in Teams across chats: kind 'sent' lists messages pi sent (from the audit log), kind " +
+		"'dispatch' lists requests the per-chat workers picked up and what they answered. Use it when someone asks " +
+		"what pi told another person or chat. Read-only.",
+	parameters: Type.Object({
+		kind: Type.Optional(
+			Type.Union([Type.Literal("sent"), Type.Literal("dispatch")], {
+				description: "'sent' (default): messages pi sent. 'dispatch': requests and answers of the chat workers.",
+			}),
+		),
+		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.dispatch.historyReaders ?? [];
+			const refusal = historyRefusal(workerIdentity(), readers);
+			if (refusal) return errorResult(refusal);
+
+			const path = (params.kind ?? "sent") === "sent" ? getAuditPath() : getDispatchJournalPath(getAgentDir());
+			const text = renderHistory(readJsonlTail(path), params);
+			return textResult(text, { path });
+		});
+	},
+};