@patimweb/pi-teams 1.14.0 → 1.15.0

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,78 @@
+/**
+ * Listen mode — who a chat worker is.
+ *
+ * In dispatch mode (`watch.dispatch.mode: "process"`) every chat that wakes pi
+ * gets a pi process of its own. 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 dispatcher when it spawns the
+ * worker. 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."
+	);
+}