@gavin-hu/my-pi-agent 0.11.2 → 0.11.4

package/extensions/wechat/doctor.ts

@@ -0,0 +1,122 @@
+/**
+ * The plain-text health report behind `/wechat doctor`.
+ *
+ * It answers the operator's first question — why is the bot quiet or slow? — from
+ * facts the bridge already has: the connection, the token's age, the last poll,
+ * the poller lock, per-peer sessions, and the last send/poll failure. Pure, so
+ * the wording and the age math are unit-tested without a bridge.
+ */
+
+import { formatDuration } from "../../lib/format.ts";
+import type { BridgeStatus } from "./bridge.ts";
+import type { WechatConfig } from "./config.ts";
+import type { BotCredentials } from "./types.ts";
+import { peerLabel } from "./format.ts";
+
+export interface DoctorInput {
+	/** Undefined when the bridge has never been built in this runtime. */
+	status?: BridgeStatus;
+	account?: BotCredentials;
+	config: WechatConfig;
+	now: number;
+}
+
+const LABEL = 11;
+
+/** One `Label      value` line. */
+function row(label: string, value: string): string {
+	return `${label.padEnd(LABEL)}${value}`;
+}
+
+/** `3.2s` since `at`, or a placeholder. */
+function age(now: number, at: number | undefined): string {
+	return at === undefined ? "unknown" : `${formatDuration(Math.max(0, now - at))} ago`;
+}
+
+function connection(status: BridgeStatus | undefined, account: BotCredentials | undefined, now: number): string {
+	if (status?.paused) return "paused · run /wechat resume";
+	if (!status?.open) {
+		return status?.expired ? "expired · run /wechat login" : "closed";
+	}
+	const owner = status.owner ? peerLabel(status.owner) : "unclaimed";
+	const token = account ? `${formatDuration(Math.max(0, now - account.createdAt))} old` : "unknown age";
+	return `open · owner ${owner} · token ${token}`;
+}
+
+function poll(status: BridgeStatus | undefined, now: number): string {
+	if (!status) return "not started";
+	const last =
+		status.lastPollAt === undefined
+			? "no poll yet"
+			: `last ${formatDuration(Math.max(0, now - status.lastPollAt))} ago`;
+	const hold = status.pollHoldMs === undefined ? "server hold" : `hold ${formatDuration(status.pollHoldMs)}`;
+	const error = status.lastPollError ? ` · error: ${status.lastPollError}` : "";
+	return `${last} · ${hold}${error}`;
+}
+
+function lockLine(status: BridgeStatus | undefined, now: number): string {
+	const lock = status?.lock;
+	if (!lock) return status?.open ? "not held" : "not running";
+	return `pid ${lock.pid} · ${age(now, lock.at)}`;
+}
+
+function peers(status: BridgeStatus | undefined): string[] {
+	if (!status || status.peerStates.length === 0) return [row("Peers", "none")];
+	const running = status.peerStates.filter((entry) => entry.state.status === "running").length;
+	const lines = [row("Peers", `${status.peerStates.length} · ${running} running · ${status.queued} queued`)];
+	for (const entry of status.peerStates) {
+		const state = entry.state;
+		const what =
+			state.status === "running"
+				? `running ${formatDuration(state.runningMs ?? 0)}`
+				: state.status === "queued"
+					? `queued ${state.queued}`
+					: "idle";
+		const session = state.sessionAgeMs === undefined ? "" : ` · session ${formatDuration(state.sessionAgeMs)}`;
+		lines.push(row(`  ${peerLabel(entry.peer)}`, `${what}${session}`));
+	}
+	return lines;
+}
+
+function recent(status: BridgeStatus | undefined): string {
+	const errors = [
+		status?.lastSendError ? `send: ${status.lastSendError}` : undefined,
+		status?.lastPollError ? `poll: ${status.lastPollError}` : undefined,
+	].filter((entry): entry is string => entry !== undefined);
+	return row("Recent", errors.length > 0 ? errors.join(" · ") : "no recent failure");
+}
+
+function media(status: BridgeStatus | undefined): string {
+	const dropped = status?.mediaDropped ?? 0;
+	const refused = status?.refused ?? 0;
+	const names = status?.refusedPeers.join(", ");
+	return row(
+		"Media",
+		`${dropped} dropped · ${refused} refused${names ? ` (${names})` : ""} · ${status?.promptPending ? "prompt waiting" : "no prompt"}`,
+	);
+}
+
+function configLine(config: WechatConfig): string {
+	const overrides = Object.keys(config.peers).length;
+	const limits = config.maxTurnsPerHour > 0 ? `${config.maxTurnsPerHour} turns/h` : "no turn cap";
+	return row(
+		"Config",
+		`typing ${config.typingIndicator ? "on" : "off"} · prompts ${config.remotePrompts ? "on" : "off"} · ` +
+			`${config.allowedPeers.length} allowed · ${overrides} peer override(s) · ${limits}`,
+	);
+}
+
+/** The doctor report, one line per fact. */
+export function doctorReport(input: DoctorInput): string {
+	const { status, account, config, now } = input;
+	return [
+		"wechat — health",
+		row("Connection", connection(status, account, now)),
+		row("Poll", poll(status, now)),
+		row("Lock", lockLine(status, now)),
+		...peers(status),
+		recent(status),
+		media(status),
+		configLine(config),
+	].join("\n");
+}

package/extensions/wechat/index.ts

@@ -23,7 +23,7 @@ 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";
@@ -43,6 +43,8 @@ export function wechatChip(theme: Theme, state: BridgeState): string | undefined
 			return paint(theme, "ok", `${GLYPHS.wechat} wechat`);
 		case "expired":
 			return paint(theme, "bad", `${GLYPHS.wechat} wechat expired`);
+		case "paused":
+			return paint(theme, "warn", `${GLYPHS.wechat} wechat paused`);
 		case "stopped":
 			return undefined;
 	}
@@ -127,6 +129,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);
 			},
@@ -153,7 +156,7 @@ export default function wechat(pi: ExtensionAPI, deps: WechatDeps = {}): void {
 	const autoStart = (ctx: ExtensionContext): void => {
 		if (ctx.mode !== "tui" && ctx.mode !== "rpc") return;
 		if (!primaryAccount()) return;
-		if (bridge?.status().open) return;
+		if (bridge?.status().open || bridge?.status().paused) return;
 		try {
 			bridge = bridge ?? build(ctx);
 			bridge.open();
@@ -180,6 +183,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

@@ -38,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 {
@@ -45,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;
@@ -61,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
@@ -88,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);
 		},
@@ -117,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/peer-worker.ts

@@ -75,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 {
@@ -110,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;
 }
@@ -164,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. */
@@ -182,6 +189,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 		cancelIdleSweep(target);
 		target.session?.dispose();
 		target.session = undefined;
+		target.sessionSince = undefined;
 		target.opening = undefined;
 	}
 
@@ -212,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(() => {

package/extensions/wechat/poll.ts

@@ -45,6 +45,9 @@ export interface PollDeps {
 	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;
 }
 
@@ -82,6 +85,10 @@ export function createPollLoop(deps: PollDeps): PollLoop {
 				} 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) {
@@ -90,6 +97,7 @@ export function createPollLoop(deps: PollDeps): PollLoop {
 						}
 						continue;
 					}
+					deps.onPoll?.({ at: deps.now(), error: messageOf(error) });
 					deps.notify(`WeChat poll failed: ${messageOf(error)}`, "warning");
 					try {
 						await deps.sleep(BACKOFF_MS, signal);
@@ -112,6 +120,7 @@ export function createPollLoop(deps: PollDeps): PollLoop {
 					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 {
@@ -130,6 +139,7 @@ export function createPollLoop(deps: PollDeps): PollLoop {
 				}
 				deps.onMessages(response.msgs);
 				deps.refreshLock();
+				deps.onPoll?.({ at: deps.now(), holdMs: serverHint ?? deps.holdMs() });
 			}
 		},
 	};