@gavin-hu/my-pi-agent 0.11.1 → 0.11.3

package/extensions/wechat/inbound.ts

@@ -0,0 +1,152 @@
+/**
+ * Inbound media and the hand-off to a peer's session.
+ *
+ * An image is downloaded, decrypted, and attached as model image content; a file
+ * is saved under the media directory and referenced by path. Every failure is
+ * counted so the peer can be told, because an attachment the bridge could not
+ * read must not look like the model ignoring a photo.
+ */
+
+import type { ImageContent } from "@earendil-works/pi-ai";
+import type { BotCredentials, InboundItem } from "./types.ts";
+import type { WechatClient } from "./client.ts";
+import type { PeerItem } from "./peer-worker.ts";
+import { messageOf } from "./errors.ts";
+import { decodeMediaKey, decryptEcb, saveMedia, sniffImageMime } from "./media.ts";
+import { notice } from "./notices.ts";
+
+/** What the inbound side needs from the bridge; every value is read at call time. */
+export interface InboundDeps {
+	client: () => WechatClient | undefined;
+	account: () => BotCredentials | undefined;
+	signal: () => AbortSignal | undefined;
+	maxMediaBytes: () => number;
+	mediaDir: () => string;
+	now: () => number;
+	notify: (message: string, kind?: "info" | "warning" | "error") => void;
+	/** Answer a message that has nothing readable. */
+	reply: (item: InboundItem, text: string) => Promise<unknown>;
+	/** Hand a resolved message to the peer's own session. */
+	enqueue: (item: PeerItem) => void;
+	pruneTyping: () => void;
+	isRunning: () => boolean;
+}
+
+/** Resolve inbound media and admit the message to the peer's queue. */
+export interface InboundAdmission {
+	admit(item: InboundItem): Promise<void>;
+	/** Media the bridge dropped since this connection opened. */
+	dropped(): number;
+	/** Reset the dropped counter (a new connection). */
+	reset(): void;
+}
+
+export function createInboundAdmission(deps: InboundDeps): InboundAdmission {
+	let mediaDropped = 0;
+	let mediaCounter = 0;
+
+	/**
+	 * Download, decrypt, and split what the peer sent into a prompt text and image
+	 * blocks. A file is saved and referenced by path; an image becomes model image
+	 * content. Every failure is counted so the peer can be told.
+	 */
+	async function resolveMedia(item: InboundItem): Promise<{
+		images: ImageContent[];
+		files: string[];
+		dropped: number;
+	}> {
+		const images: ImageContent[] = [];
+		const files: string[] = [];
+		let dropped = 0;
+		const client = deps.client();
+		for (const ref of item.media) {
+			if (!client) break;
+			try {
+				const cipher = await client.downloadCdn(ref.media, deps.signal());
+				if (cipher.byteLength > deps.maxMediaBytes()) {
+					mediaDropped += 1;
+					dropped += 1;
+					deps.notify(`WeChat media dropped: over ${deps.maxMediaBytes()} bytes.`, "warning");
+					continue;
+				}
+				if (ref.kind === "file") {
+					if (!ref.media.aes_key) throw new Error("missing AES key");
+					const plain = decryptEcb(cipher, decodeMediaKey(ref.media.aes_key));
+					mediaCounter += 1;
+					const path = saveMedia(deps.mediaDir(), `${deps.now()}-${mediaCounter}-${ref.fileName}`, plain);
+					files.push(`[WeChat file: ${ref.fileName} saved to ${path}]`);
+				} else {
+					// Without a key the bytes are not the image the peer sent; attaching them
+					// anyway would hand the model a corrupt JPEG.
+					const key = ref.aeskey ?? ref.media.aes_key;
+					if (!key) throw new Error("missing AES key");
+					const plain = decryptEcb(cipher, decodeMediaKey(key));
+					images.push({
+						type: "image",
+						data: Buffer.from(plain).toString("base64"),
+						mimeType: sniffImageMime(plain),
+					});
+				}
+			} catch (error) {
+				mediaDropped += 1;
+				dropped += 1;
+				deps.notify(`WeChat media dropped: ${messageOf(error)}`, "warning");
+			}
+		}
+		return { images, files, dropped };
+	}
+
+	return {
+		/**
+		 * Resolve media, then hand the message to the peer's own session.
+		 *
+		 * An attachment the bridge could not read is never silent: the model gets a
+		 * `[WeChat media skipped]` block and the peer's reply opens with one line, so a
+		 * failed download cannot look like the model ignoring a photo. A message with
+		 * nothing readable is answered here instead of starting an empty turn.
+		 */
+		async admit(item: InboundItem): Promise<void> {
+			let text = item.text;
+			let images: ImageContent[] | undefined;
+			let prefix: string | undefined;
+			if (item.media.length > 0) {
+				const resolved = await resolveMedia(item);
+				if (!deps.isRunning()) return;
+				if (!text && resolved.images.length === 0 && resolved.files.length === 0) {
+					if (resolved.dropped > 0) prefix = notice("media", item.language, resolved.dropped);
+					await deps.reply(item, prefix ?? notice("unsupported", item.language));
+					deps.pruneTyping();
+					return;
+				}
+				if (resolved.dropped > 0) {
+					prefix = notice("media", item.language, resolved.dropped);
+					text = [text, `[WeChat media skipped: ${resolved.dropped}]`].filter(Boolean).join("\n");
+				}
+				if (resolved.files.length > 0) text = [text, ...resolved.files].filter(Boolean).join("\n");
+				images = resolved.images.length > 0 ? resolved.images : undefined;
+			}
+			if (!text && !images) {
+				await deps.reply(item, notice("unsupported", item.language));
+				deps.pruneTyping();
+				return;
+			}
+			const queued: PeerItem = {
+				peer: item.peer,
+				text,
+				images,
+				prefix,
+				language: item.language,
+				contextToken: item.contextToken,
+			};
+			deps.enqueue(queued);
+		},
+
+		dropped(): number {
+			return mediaDropped;
+		},
+
+		reset(): void {
+			mediaDropped = 0;
+		},
+	};
+}

package/extensions/wechat/index.ts

@@ -20,9 +20,10 @@ import { paint } from "../../lib/tui/tokens.ts";
 import { createBridge, type Bridge, type BridgeState } from "./bridge.ts";
 import { createFetchRunner, WechatClient, type WechatClientOptions } from "./client.ts";
 import { registerCommands, type CommandDeps } from "./commands.ts";
+import { messageOf } from "./errors.ts";
 import { loadWechatConfig } from "./config.ts";
 import { clearCredentials, primaryAccount, saveAccount, wechatDir } from "./credentials.ts";
-import { acquireLock, lockPath, refreshLock, releaseLock } from "./lock.ts";
+import { acquireLock, lockPath, readLock, refreshLock, releaseLock } from "./lock.ts";
 import { openPeerSession, type PeerSession, type PeerSessionOptions } from "./peer-session.ts";
 import { createPeerUIContext } from "./remote-ui.ts";
 import { peerKey } from "./format.ts";
@@ -126,6 +127,7 @@ export default function wechat(pi: ExtensionAPI, deps: WechatDeps = {}): void {
 			acquireLock: () => acquireLock(lockPath(), lockDeps()),
 			refreshLock: () => refreshLock(lockPath(), lockDeps()),
 			releaseLock: () => releaseLock(lockPath(), process.pid),
+			loadLock: () => readLock(lockPath()),
 			notify: (message, kind) => {
 				ctxRef?.ui.notify(message, kind);
 			},
@@ -157,7 +159,7 @@ export default function wechat(pi: ExtensionAPI, deps: WechatDeps = {}): void {
 			bridge = bridge ?? build(ctx);
 			bridge.open();
 		} catch (error) {
-			ctx.ui.notify(`WeChat did not connect: ${error instanceof Error ? error.message : String(error)}`, "warning");
+			ctx.ui.notify(`WeChat did not connect: ${messageOf(error)}`, "warning");
 		}
 	};
 
@@ -179,6 +181,8 @@ export default function wechat(pi: ExtensionAPI, deps: WechatDeps = {}): void {
 		},
 		saveAccount,
 		primaryAccount,
+		readHistory: (peer, count) =>
+			readPeerHistory(ctxRef?.cwd ?? process.cwd(), join(wechatDir(), "sessions"), peer, count),
 		logout: () => {
 			clearCredentials();
 			// The account is the on/off switch: without one there is nothing to report,

package/extensions/wechat/interaction.ts

@@ -19,7 +19,8 @@ import {
 	type InteractionChannel,
 	type InteractionRequest,
 } from "../../lib/interaction.ts";
-import { notice, type PeerLanguage } from "./format.ts";
+import { type PeerLanguage } from "./format.ts";
+import { notice } from "./notices.ts";
 import { formatPrompt, parsePromptAnswer } from "./prompt.ts";
 import { defaultTimer, type ArmTimer } from "./timer.ts";
 
@@ -37,6 +38,8 @@ export interface WechatInteractionDeps {
 	language: () => PeerLanguage;
 	/** Arm a cancellable one-shot timer. Defaults to a real, unref'd `setTimeout`. */
 	armTimer?: ArmTimer;
+	/** Clock for the prompt's start time; defaults to `Date.now`. */
+	now?: () => number;
 }
 
 export interface WechatInteractionChannel extends InteractionChannel {
@@ -44,13 +47,27 @@ export interface WechatInteractionChannel extends InteractionChannel {
 	handleInbound(peer: string, text: string): boolean;
 	/** Whether a prompt is currently waiting for a reply. */
 	hasPending(): boolean;
+	/** The waiting prompt, for the control screen; undefined when none waits. */
+	pendingInfo(): PendingPromptInfo | undefined;
+	/** Withdraw the waiting prompt: tell the peer and resolve it cancelled. */
+	cancel(): void;
 	/** Drop any pending prompt (turn settled or the bridge stopped). */
 	reset(): void;
 }
 
+/** The waiting prompt, as the control screen reads it. */
+export interface PendingPromptInfo {
+	peer: string;
+	kind: InteractionRequest["kind"];
+	title: string;
+	/** When the prompt was registered, in epoch milliseconds. */
+	startedAt: number;
+}
+
 interface Pending {
 	request: InteractionRequest;
 	peer: string;
+	startedAt: number;
 	resolve: (answer: InteractionAnswer) => void;
 	signal?: AbortSignal;
 	onAbort: () => void;
@@ -60,6 +77,7 @@ interface Pending {
 
 export function createWechatInteractionChannel(deps: WechatInteractionDeps): WechatInteractionChannel {
 	const arm = deps.armTimer ?? defaultTimer;
+	const now = deps.now ?? Date.now;
 	let pending: Pending | undefined;
 	/**
 	 * Free text captured from a `select` "Other" reply, per peer: the immediately
@@ -87,6 +105,26 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 			return pending !== undefined;
 		},
 
+		pendingInfo(): PendingPromptInfo | undefined {
+			const current = pending;
+			return current === undefined
+				? undefined
+				: {
+						peer: current.peer,
+						kind: current.request.kind,
+						title: current.request.title,
+						startedAt: current.startedAt,
+					};
+		},
+
+		cancel(): void {
+			if (!pending) return;
+			// The peer saw the prompt; one line says it was withdrawn. `reset` is the
+			// silent cleanup path and deliberately does not send this.
+			void deps.send(notice("timeout", deps.language()));
+			settle({ kind: "cancelled" });
+		},
+
 		async post(text: string, signal?: AbortSignal): Promise<void> {
 			await deps.send(text, signal);
 		},
@@ -116,7 +154,7 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 			const cancelTimers: Array<() => void> = [];
 			const answer = new Promise<InteractionAnswer>((resolve) => {
 				const onAbort = () => settle({ kind: "cancelled" });
-				pending = { request, peer, resolve, signal, onAbort, cancelTimers };
+				pending = { request, peer, startedAt: now(), resolve, signal, onAbort, cancelTimers };
 				signal?.addEventListener("abort", onAbort, { once: true });
 				// An ignored question must not freeze the session: nudge once, then
 				// cancel so the model gets a clean answer instead of a hang.

package/extensions/wechat/lock.ts

@@ -48,10 +48,19 @@ function parseLock(text: string): LockInfo | undefined {
 	}
 }
 
+/** The raw lock record, or undefined when the file is missing or corrupt. */
+export function readLock(path: string): LockInfo | undefined {
+	try {
+		if (!existsSync(path)) return undefined;
+		return parseLock(readFileSync(path, "utf-8"));
+	} catch {
+		return undefined;
+	}
+}
+
 /** True when the existing lock blocks a new owner. */
 export function isLocked(path: string, deps: LockDeps): boolean {
-	if (!existsSync(path)) return false;
-	const info = parseLock(readFileSync(path, "utf-8"));
+	const info = readLock(path);
 	if (!info) return false;
 	if (info.pid === deps.pid) return false;
 	const stale = deps.now() - info.at > (deps.staleMs ?? DEFAULT_STALE_MS);

package/extensions/wechat/login.ts

@@ -7,6 +7,7 @@
  */
 
 import { DEFAULT_BASE_URL, type WechatClient } from "./client.ts";
+import { messageOf } from "./errors.ts";
 import type { BotCredentials, QrResponse, QrStatus } from "./types.ts";
 
 /** Categorical meaning of a `get_qrcode_status` value. */
@@ -62,25 +63,6 @@ export interface LoginOptions {
 	requestVerifyCode?: () => Promise<string | undefined>;
 }
 
-/** Default sleep, aborted by `signal`. */
-export function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
-	return new Promise((resolve, reject) => {
-		if (signal?.aborted) {
-			reject(new Error("aborted"));
-			return;
-		}
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(new Error("aborted"));
-		};
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}
-
 /** Poll a started login until it settles. */
 export async function waitForLogin(client: WechatClient, qr: QrResponse, options: LoginOptions): Promise<LoginOutcome> {
 	const interval = options.intervalMs ?? 2000;
@@ -91,7 +73,7 @@ export async function waitForLogin(client: WechatClient, qr: QrResponse, options
 			status = await client.pollQrStatus(qr.qrcode, verifyCode, options.signal);
 		} catch (error) {
 			if (options.signal?.aborted) return { kind: "cancelled" };
-			return { kind: "error", message: error instanceof Error ? error.message : String(error) };
+			return { kind: "error", message: messageOf(error) };
 		}
 		options.onStatus?.(status.status);
 

package/extensions/wechat/notices.ts

@@ -0,0 +1,76 @@
+/**
+ * The short peer-facing notices the bridge sends on its own.
+ *
+ * Every one is a single line in the peer's language: WeChat pings per message,
+ * so a notice has to earn its bubble. Kept apart from `format.ts` so the text
+ * helpers stay text helpers and the notice catalog can be reviewed in one place.
+ */
+
+import type { PeerLanguage } from "./format.ts";
+
+/** One stock line the bridge can send outside a reply. */
+export type NoticeKind =
+	| "ack"
+	| "busy"
+	| "stillWorking"
+	| "overflow"
+	| "media"
+	| "unsupported"
+	| "stopped"
+	| "noText"
+	| "compacted"
+	| "budget"
+	| "promptWaiting"
+	| "timeout"
+	| "failed"
+	| "newBusy";
+
+const NOTICES: Record<NoticeKind, Record<PeerLanguage, string>> = {
+	ack: { zh: "收到，正在处理…", en: "Got it — working on it." },
+	busy: {
+		zh: "前面还有一条正在处理，你的消息排在后面，轮到你就回你。",
+		en: "Your message is queued behind another conversation; I'll answer as soon as it's free.",
+	},
+	stillWorking: {
+		zh: "还在处理这条，稍等一下…",
+		en: "Still working on this one — a moment…",
+	},
+	overflow: { zh: "消息有点多，稍后再发。", en: "Too many messages queued — please wait a moment." },
+	media: {
+		zh: "有 {n} 个附件没能读取，可以重发或直接说明。",
+		en: "Couldn't open {n} attachment(s) — please resend or describe it.",
+	},
+	unsupported: {
+		zh: "语音（无转写）和视频暂不支持，请发文字或图片。",
+		en: "Voice without a transcript and video aren't supported — please send text or an image.",
+	},
+	stopped: { zh: "已停止。", en: "Stopped." },
+	noText: {
+		zh: "这条处理完了，但没有文字输出。",
+		en: "That turn finished without any text to send.",
+	},
+	compacted: {
+		zh: "对话较长，上下文已压缩；更早的细节可能记不全。",
+		en: "The conversation was compacted to stay within context; earlier details may be fuzzy.",
+	},
+	budget: {
+		zh: "这一小时的消息有点多，稍后再试。",
+		en: "You've reached this hour's message limit — please try again later.",
+	},
+	promptWaiting: {
+		zh: "还在等你的回复，约 1 分钟后超时。",
+		en: "Still waiting for your reply — this expires in about a minute.",
+	},
+	timeout: { zh: "问题超时，已取消。", en: "That question timed out." },
+	failed: { zh: "处理失败，请稍后重试。", en: "Something went wrong — please try again." },
+	newBusy: {
+		zh: "正在处理当前消息，稍后再发送 /new。",
+		en: "Still working on your last message — send /new again after it finishes.",
+	},
+};
+
+/** Render one notice, with `{n}` replaced when a count applies. */
+export function notice(kind: NoticeKind, lang: PeerLanguage, count?: number): string {
+	const text = NOTICES[kind][lang];
+	return count === undefined ? text : text.replace("{n}", String(count));
+}

package/extensions/wechat/peer-worker.ts

@@ -24,6 +24,7 @@
  */
 
 import type { ImageContent } from "@earendil-works/pi-ai";
+import { messageOf } from "./errors.ts";
 import type { PeerSession } from "./peer-session.ts";
 import { createReplyPipeline } from "./reply-pipeline.ts";
 
@@ -50,8 +51,6 @@ export interface PeerWorkerDeps {
 	openSession: (peer: string, options: { fresh: boolean }) => Promise<PeerSession>;
 	/** Deliver one turn's text to the peer; false stops the rest of a stream. */
 	send: (item: PeerItem, text: string) => Promise<boolean>;
-	/** Read the peer's own recent messages, for `/history`; read-only. */
-	readHistory?: (peer: string, count: number) => Promise<string>;
 	/** The fallback line for a turn that produced no text. */
 	fallback: (item: PeerItem, reason: TurnFallback) => string;
 	/** A turn started / finished for this item, for typing and notices. */
@@ -76,6 +75,8 @@ export interface PeerState {
 	queued: number;
 	/** How long the running turn has been going, in milliseconds. */
 	runningMs?: number;
+	/** How long the peer's session has been open, when one is open. */
+	sessionAgeMs?: number;
 }
 
 export interface PeerSnapshot {
@@ -96,8 +97,6 @@ export interface PeerWorker {
 	/** The turn running right now, if any (one with the default concurrency). */
 	current(): PeerItem | undefined;
 	state(peer: string): PeerState;
-	/** The peer's own recent messages, for `/history`. */
-	history(peer: string, count: number): Promise<string>;
 	snapshot(): PeerSnapshot[];
 	/** Drop every session; queued messages are dropped with them. */
 	close(): Promise<void>;
@@ -113,6 +112,8 @@ interface PeerEntry {
 	/** Monotonic start time of the running turn, for `runningMs`. */
 	startedAt?: number;
 	session?: PeerSession;
+	/** When the current session opened, for the doctor's session age. */
+	sessionSince?: number;
 	opening?: Promise<PeerSession>;
 	disposeTimer?: () => void;
 }
@@ -167,15 +168,18 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 	function stateOf(peer: string): PeerState {
 		const target = peers.get(peer);
 		if (!target) return { status: "idle", queued: 0 };
+		const sessionAge =
+			target.sessionSince === undefined ? undefined : { sessionAgeMs: Math.max(0, now() - target.sessionSince) };
 		if (target.running) {
 			return {
 				status: "running",
 				queued: target.queue.length + target.merged,
 				runningMs: target.startedAt === undefined ? 0 : now() - target.startedAt,
+				...sessionAge,
 			};
 		}
 		const queued = target.queue.length + target.merged;
-		return { status: queued > 0 ? "queued" : "idle", queued };
+		return { status: queued > 0 ? "queued" : "idle", queued, ...sessionAge };
 	}
 
 	/** Drop the peer's session and queue. */
@@ -185,6 +189,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 		cancelIdleSweep(target);
 		target.session?.dispose();
 		target.session = undefined;
+		target.sessionSince = undefined;
 		target.opening = undefined;
 	}
 
@@ -215,6 +220,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 						throw new Error("The WeChat bridge closed while opening the session.");
 					}
 					target.session = opened;
+					target.sessionSince = now();
 					return opened;
 				})
 				.finally(() => {
@@ -284,10 +290,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			const wasAborted = aborted.delete(item.peer);
 			reason = wasAborted ? "stopped" : "failed";
 			if (!wasAborted) {
-				deps.notify?.(
-					`WeChat turn failed for ${item.peer}: ${error instanceof Error ? error.message : String(error)}`,
-					"warning",
-				);
+				deps.notify?.(`WeChat turn failed for ${item.peer}: ${messageOf(error)}`, "warning");
 			}
 		} finally {
 			unsubscribe();
@@ -323,10 +326,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 					const opened = await sessionFor(peer, target);
 					await runTurn(item, opened);
 				} catch (error) {
-					deps.notify?.(
-						`WeChat session failed for ${item.peer}: ${error instanceof Error ? error.message : String(error)}`,
-						"error",
-					);
+					deps.notify?.(`WeChat session failed for ${item.peer}: ${messageOf(error)}`, "error");
 					await deps.send(item, deps.fallback(item, "failed"));
 				} finally {
 					target.running = undefined;
@@ -387,10 +387,6 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			return stateOf(peer);
 		},
 
-		history(peer: string, count: number): Promise<string> {
-			return deps.readHistory?.(peer, count) ?? Promise.resolve("");
-		},
-
 		snapshot(): PeerSnapshot[] {
 			return [...peers.keys()].map((peer) => ({ peer, state: stateOf(peer) }));
 		},

package/extensions/wechat/poll.ts

@@ -0,0 +1,146 @@
+/**
+ * The long-poll loop for one account.
+ *
+ * Weixin holds a `getupdates` request for a server-chosen duration; the loop
+ * feeds every returned message to the bridge, advances the stored cursor, and
+ * keeps the poller lock fresh. A wedged request is retried at once with the same
+ * cursor (nothing is skipped), a transport error backs off, and an expired token
+ * stops the loop.
+ */
+
+import type { BotCredentials, WeixinMessage } from "./types.ts";
+import { isSessionExpired, type WechatClient } from "./client.ts";
+import { messageOf } from "./errors.ts";
+
+const BACKOFF_MS = 2000;
+/** Poll watchdog when the server has not told us its long-poll hold yet. */
+const POLL_TIMEOUT_FALLBACK_MS = 90_000;
+/** Never trust a server hint below this, so a busy loop cannot be papered over. */
+const POLL_TIMEOUT_FLOOR_MS = 30_000;
+/** Slack above the server's hold before a poll counts as wedged. */
+const POLL_TIMEOUT_MARGIN_MS = 15_000;
+
+/**
+ * How long one `getupdates` request may hang before it is treated as wedged: the
+ * server's own hold time plus a margin, so a half-open connection cannot stop
+ * inbound traffic without a word.
+ */
+export function defaultPollTimeout(serverHintMs: number | undefined): number {
+	return Math.max(serverHintMs ?? POLL_TIMEOUT_FALLBACK_MS, POLL_TIMEOUT_FLOOR_MS) + POLL_TIMEOUT_MARGIN_MS;
+}
+
+/** What the loop needs from the bridge; every value is read at call time. */
+export interface PollDeps {
+	client: () => WechatClient | undefined;
+	account: () => BotCredentials | undefined;
+	/** The server's requested hold, when the operator configured one. */
+	holdMs: () => number | undefined;
+	cursor: () => string;
+	setCursor: (cursor: string) => void;
+	saveState: () => void;
+	sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+	notify: (message: string, kind?: "info" | "warning" | "error") => void;
+	/** The token expired; the bridge clears its running state and reports it. */
+	onExpired: () => void;
+	onMessages: (messages: WeixinMessage[]) => void;
+	refreshLock: () => void;
+	isRunning: () => boolean;
+	now: () => number;
+	/** Report the last poll attempt, for the doctor/status. */
+	onPoll?: (result: { at: number; error?: string; holdMs?: number }) => void;
+	pollTimeout: (serverHintMs: number | undefined) => number;
+}
+
+/** The poll loop for one connection. */
+export interface PollLoop {
+	/** Run until `signal` aborts, the connection closes, or the token expires. */
+	run(signal: AbortSignal): Promise<void>;
+}
+
+export function createPollLoop(deps: PollDeps): PollLoop {
+	return {
+		async run(signal: AbortSignal): Promise<void> {
+			// The server tells us how long it holds a poll; remember it so the watchdog
+			// can be tight instead of the generic fallback.
+			let serverHint: number | undefined;
+			/** One notice per failure episode, so a flapping link is reported once. */
+			let timeoutNotified = false;
+			let rejectedNotified = false;
+			while (deps.isRunning() && !signal.aborted) {
+				const client = deps.client();
+				const account = deps.account();
+				if (!client || !account) break;
+				const watchdogMs = deps.pollTimeout(serverHint ?? deps.holdMs());
+				// A cancellable watchdog: `AbortSignal.timeout` cannot be cleared, and a
+				// pending timer per poll would keep the process awake long after the request
+				// settled. Unref'd, so a wedged poll never holds a shutdown open either.
+				const watchdog = new AbortController();
+				const watchdogTimer = setTimeout(() => watchdog.abort(), watchdogMs);
+				(watchdogTimer as { unref?: () => void }).unref?.();
+				let response;
+				try {
+					response = await client.getUpdates(account, deps.cursor(), AbortSignal.any([signal, watchdog.signal]), {
+						holdMs: deps.holdMs(),
+					});
+				} catch (error) {
+					if (signal.aborted || !deps.isRunning()) break;
+					if (watchdog.signal.aborted) {
+						deps.onPoll?.({
+							at: deps.now(),
+							error: `timed out after ${Math.round(watchdogMs / 1000)}s`,
+						});
+						// A wedged request, not a server answer: retry at once with the same
+						// cursor, so nothing is skipped, and say so once.
+						if (!timeoutNotified) {
+							timeoutNotified = true;
+							deps.notify(`WeChat poll timed out after ${Math.round(watchdogMs / 1000)}s; retrying.`, "warning");
+						}
+						continue;
+					}
+					deps.onPoll?.({ at: deps.now(), error: messageOf(error) });
+					deps.notify(`WeChat poll failed: ${messageOf(error)}`, "warning");
+					try {
+						await deps.sleep(BACKOFF_MS, signal);
+					} catch {
+						break;
+					}
+					continue;
+				} finally {
+					clearTimeout(watchdogTimer);
+				}
+				if (!response) break;
+				if (response.timeoutMs !== undefined && response.timeoutMs > 0) serverHint = response.timeoutMs;
+				if (isSessionExpired(response)) {
+					deps.onExpired();
+					return;
+				}
+				if ((response.ret ?? 0) !== 0 || (response.errcode ?? 0) !== 0) {
+					// A body-level rejection (bad cursor, rate limit, revoked token) is not an
+					// empty poll: report it once and back off instead of hammering the API.
+					if (!rejectedNotified) {
+						rejectedNotified = true;
+						const code = (response.ret ?? 0) !== 0 ? response.ret : (response.errcode ?? 0);
+						deps.onPoll?.({ at: deps.now(), error: `rejected ret ${code}` });
+						deps.notify(`WeChat poll rejected (ret ${code}); retrying.`, "warning");
+					}
+					try {
+						await deps.sleep(BACKOFF_MS, signal);
+					} catch {
+						break;
+					}
+					continue;
+				}
+				timeoutNotified = false;
+				rejectedNotified = false;
+				const next = response.buf;
+				if (next && next !== deps.cursor()) {
+					deps.setCursor(next);
+					deps.saveState();
+				}
+				deps.onMessages(response.msgs);
+				deps.refreshLock();
+				deps.onPoll?.({ at: deps.now(), holdMs: serverHint ?? deps.holdMs() });
+			}
+		},
+	};
+}