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

package/extensions/wechat/README.md

@@ -76,6 +76,8 @@ How the `send_wechat` call and its result look in the transcript — the call li
 | `/wechat login` | QR login; on scan, stores credentials, replaces a running poller, and starts the bridge. |
 | `/wechat new` | Start a fresh *host* session. Peer conversations are independent and survive it; they use an inbound `/new`. |
 | `/wechat status` | The same control screen as a bare `/wechat` (the one-line summary while a peer turn runs). |
+| `/wechat pause` | Stop polling new messages; running turns may finish and reply. The poller lock is released, so another runtime may take the account. |
+| `/wechat resume` | Reacquire the lock and poll again; reports when another runtime already holds it. |
 | `/wechat doctor` | Print a read-only health report: connection and token age, last poll and hold, lock holder, per-peer session/queue, recent failures. |
 | `/wechat stop <peer>` | Stop that peer's running turn; reports when nothing was running. |
 | `/wechat reset <peer>` | Start a fresh conversation for that peer; refused while its turn runs. |
@@ -108,10 +110,18 @@ what is queued behind it), activity counters, and the waiting remote prompt
 `j`/`k` (or the arrows) move the focus over peer rows; `s` stops the focused
 peer's turn and `d` starts a fresh conversation for it, both in place; `h` closes
 the screen and prints that peer's history; `a` closes it and offers the refused
-senders to allow; `c` withdraws the waiting prompt. `l` logs in or reconnects,
-`n` starts a new session, `o` logs out, `r` refreshes, and Esc closes. The
-subcommands above are shortcuts for the same actions and the only route outside
-the TUI; an unknown subcommand reports the valid ones.
+senders to allow; `c` withdraws the waiting prompt; `p` pauses or resumes
+polling. `l` logs in or reconnects, `n` starts a new session, `o` logs out,
+`r` refreshes, and Esc closes. The subcommands above are shortcuts for the same
+actions and the only route outside the TUI; an unknown subcommand reports the
+valid ones.
+
+Pause is per runtime and keeps the account and peer sessions: a running turn
+may finish and reply, a waiting prompt is withdrawn with the timeout notice,
+and the poller lock is released so another runtime can take over. Resume
+reacquires the lock and reports when another runtime holds it. `/reload` or a
+restart builds a new bridge and resumes polling, so pause is a temporary mute,
+not a persistent switch.
 
 A peer turn runs in its own session, but it still owns the bridge, so a `/wechat`
 command typed at the terminal declines while one is running: `status` prints the
@@ -395,16 +405,16 @@ sessions are in-process).
 
 | Integration point | Detail |
 |---|---|
-| Command | `pi.registerCommand("wechat", …)` — `login`, `new`, `status`, `doctor`, `stop <peer>`, `reset <peer>`, `history <peer> [n]`, `allow [peer]`, `logout`, `help`; bare `/wechat` opens the control screen. |
+| Command | `pi.registerCommand("wechat", …)` — `login`, `new`, `status`, `pause`, `resume`, `doctor`, `stop <peer>`, `reset <peer>`, `history <peer> [n]`, `allow [peer]`, `logout`, `help`; bare `/wechat` opens the control screen. |
 | Tools | `send_wechat` — owner-only proactive text; registered at factory time with `exposure: "direct"`, `executionMode: "sequential"`, `openWorldHint: true`. |
 | Events | `session_start` (record the live context, auto-start the bridge when an account exists); `session_shutdown` (idempotent stop). No host run events: peer turns are not the host session's runs. |
 | Sessions | `openPeerSession` creates one SDK `AgentSession` per peer (`createAgentSession`, `SessionManager.continueRecent` under `<agent-dir>/wechat/sessions/<peer>/`), inheriting the host's model and thinking level. `DefaultResourceLoader` standard discovery minus this bridge (`withoutWechatExtensions`), so a peer session cannot start a second poller, plus a short channel contract appended to the system prompt so the model knows it is answering in a phone chat window. When `peers[<id>].tools` is set, only those names stay active. |
 | Turn ownership | `peer-worker.ts`: a serial queue per peer, `session.prompt()`/`session.abort()`, `getLastAssistantText()` for the answer, and one idle sweep per session. `concurrency` defaults to 1 so a forwarded dialog has one owner. |
 | Slash commands | Admitted inbound text is matched against `SLASH_COMMANDS` in `handleMessage`; a snippet is expanded into the turn, an action runs out-of-band and replies, and an unknown command falls through. Actions act on the sender through `SlashSessionControls` (`newSession` → worker reset, `stop` → worker abort, `status` → worker state, `history` → a read-only read of that peer's newest session). |
 | Peer dialogs | `bindExtensions({ mode: "rpc", uiContext })` on each peer session, with `createPeerUIContext(channel)` routing `select`/`confirm`/`input`/`editor` to that peer and marking the context for `askHuman`'s file/text preface. The terminal's shared `ctx.ui` is deliberately not adapted: a host turn is never answered remotely, so its dialogs stay local even while a peer turn runs. |
-| Status | The bridge's connection state (`running` / `expired` / `stopped`) is published through `onStateChange` to `ctx.ui.setStatus(STATUS_KEYS.wechat, …)`; an expiry keeps a persistent error chip, and the status bar renders it on line 2. |
+| Status | The bridge's connection state (`running` / `paused` / `expired` / `stopped`) is published through `onStateChange` to `ctx.ui.setStatus(STATUS_KEYS.wechat, …)`; an expiry keeps a persistent error chip, pause keeps a warning chip, and the status bar renders it on line 2. |
 | State | Files under `<agent-dir>/wechat/`; the bridge is not authoritative UI, so nothing is stored in the transcript. |
-| Lifecycle | The factory only registers. The poll loop starts on `session_start` when an account is stored (and after `/wechat login`); `session_shutdown` closes it. One bridge per extension runtime: it is built once, `open()` is a no-op while running (so the RPC double `session_start` on a session switch cannot start a second poller), and shutdown is idempotent, so the reload and replacement paths (`/reload`, `/new`, resume, fork — all of which re-run the factory and emit shutdown before the new start) each end with exactly one poller. `/wechat` screens use `ctx.ui.custom`, so they degrade (status) or decline (login, logout) while a peer turn runs. |
+| Lifecycle | The factory only registers. The poll loop starts on `session_start` when an account is stored (and after `/wechat login`); `session_shutdown` closes it. One bridge per extension runtime: it is built once, `open()` is a no-op while running or paused (so the RPC double `session_start` on a session switch cannot start a second poller or resume a paused one), and shutdown is idempotent, so the reload and replacement paths (`/reload`, `/new`, resume, fork — all of which re-run the factory and emit shutdown before the new start) each end with exactly one poller. `pause()` stops the loop and releases the lock while keeping the worker, so a running turn can finish; `resume()` reacquires the lock and starts a new loop. Pause is runtime-local, so a reload or restart starts a fresh running bridge. `/wechat` screens use `ctx.ui.custom`, so they degrade (status) or decline (login, logout) while a peer turn runs. |
 
 ## Design notes
 

package/extensions/wechat/bridge.ts

@@ -65,7 +65,7 @@ export function isInboundMessage(message: WeixinMessage): message is WeixinMessa
 }
 
 /** The bridge's connection state, published to the UI for the status chip. */
-export type BridgeState = "stopped" | "running" | "expired";
+export type BridgeState = "stopped" | "running" | "expired" | "paused";
 
 export interface BridgeDeps {
 	config: WechatConfig;
@@ -107,6 +107,8 @@ export interface BridgeStatus {
 	open: boolean;
 	/** Whether the bridge stopped because the session expired and needs a re-login. */
 	expired: boolean;
+	/** Whether the operator paused polling; the account and peer sessions are kept. */
+	paused: boolean;
 	owner?: string;
 	peerCount: number;
 	queued: number;
@@ -146,6 +148,10 @@ export interface SendResult {
 export interface Bridge {
 	open(): void;
 	close(): Promise<void>;
+	/** Stop polling new messages; running turns may finish. False when not running. */
+	pause(): Promise<boolean>;
+	/** Reacquire the lock and start polling again. False when not paused or the lock is taken. */
+	resume(): Promise<boolean>;
 	shutdown(): Promise<void>;
 	/** Stop one peer's running turn; false when that peer is idle. */
 	stop(peer: string): boolean;
@@ -165,6 +171,7 @@ export function createBridge(deps: BridgeDeps): Bridge {
 	const sleep = deps.sleep ?? defaultSleep;
 	const armTimer = deps.armTimer ?? defaultTimer;
 	let running = false;
+	let paused = false;
 	let expired = false;
 	let startedAt: number | undefined;
 	let lastPollAt: number | undefined;
@@ -195,11 +202,12 @@ export function createBridge(deps: BridgeDeps): Bridge {
 
 	/** Report the current connection state to the host, for a status chip. */
 	function publishState(): void {
-		deps.onStateChange?.(running ? "running" : expired ? "expired" : "stopped");
+		deps.onStateChange?.(running ? "running" : expired ? "expired" : paused ? "paused" : "stopped");
 	}
 
 	function handleExpired(): void {
 		running = false;
+		paused = false;
 		expired = true;
 		// An expiry can be discovered by a send while the loop is parked in
 		// `getUpdates`; abort it so it cannot wake up beside a later `open()`.
@@ -491,6 +499,21 @@ export function createBridge(deps: BridgeDeps): Bridge {
 		}
 	}
 
+	/**
+	 * Serialize lifecycle transitions. A pause and a resume from the control
+	 * screen, or a shutdown racing either, must not leave two poll loops or a
+	 * released lock behind a running bridge.
+	 */
+	let lifecycle: Promise<void> = Promise.resolve();
+	function serial<T>(work: () => Promise<T>): Promise<T> {
+		const run = lifecycle.then(work, work);
+		lifecycle = run.then(
+			() => undefined,
+			() => undefined,
+		);
+		return run;
+	}
+
 	return {
 		open(): void {
 			if (running) return;
@@ -523,6 +546,7 @@ export function createBridge(deps: BridgeDeps): Bridge {
 				deps.saveState(state);
 			}
 			running = true;
+			paused = false;
 			expired = false;
 			resetEphemeral();
 			startedAt = deps.now();
@@ -563,28 +587,71 @@ export function createBridge(deps: BridgeDeps): Bridge {
 			});
 		},
 
-		async close(): Promise<void> {
-			if (!running && !abort) {
+		close(): Promise<void> {
+			return serial(async () => {
+				running = false;
+				paused = false;
+				expired = false;
+				abort?.abort();
+				abort = undefined;
+				try {
+					await loopPromise;
+				} catch {
+					// Errors are surfaced by the loop's own catch.
+				}
+				loopPromise = undefined;
+				// A paused bridge has no loop and no abort controller but still owns a
+				// worker, so close it unconditionally rather than leaking the sessions.
+				const closing = worker;
+				worker = undefined;
+				await closing?.close();
+				resetEphemeral();
+				publishState();
+				releaseSafe();
+			});
+		},
+
+		pause(): Promise<boolean> {
+			return serial(async () => {
+				if (!running) return false;
+				running = false;
+				paused = true;
+				// Clear the abort controller before withdrawing the prompt: its send must
+				// not be cancelled by the poll abort that follows.
+				const stopping = abort;
+				abort = undefined;
+				if (interaction.hasPending()) interaction.cancel();
+				stopping?.abort();
+				try {
+					await loopPromise;
+				} catch {
+					// Errors are surfaced by the loop's own catch.
+				}
+				loopPromise = undefined;
+				// No poller means no lock to keep: another runtime may take the account
+				// while this one is paused. Resume reacquires it and reports a conflict.
 				releaseSafe();
 				publishState();
-				return;
-			}
-			running = false;
-			expired = false;
-			abort?.abort();
-			abort = undefined;
-			try {
-				await loopPromise;
-			} catch {
-				// Errors are surfaced by the loop's own catch.
-			}
-			loopPromise = undefined;
-			const closing = worker;
-			worker = undefined;
-			await closing?.close();
-			resetEphemeral();
-			publishState();
-			releaseSafe();
+				return true;
+			});
+		},
+
+		resume(): Promise<boolean> {
+			return serial(async () => {
+				if (!paused || expired || !worker || !account) return false;
+				if (!deps.acquireLock()) {
+					notify("Another Pi session is already polling this WeChat account.", "warning");
+					return false;
+				}
+				paused = false;
+				running = true;
+				abort = new AbortController();
+				loopPromise = poll.run(abort.signal).catch((error) => {
+					notify(`WeChat bridge stopped: ${messageOf(error)}`, "error");
+				});
+				publishState();
+				return true;
+			});
 		},
 
 		async shutdown(): Promise<void> {
@@ -609,6 +676,7 @@ export function createBridge(deps: BridgeDeps): Bridge {
 				peerStates: states,
 				open: running,
 				expired,
+				paused,
 				owner: state.ownerId ?? account?.ilinkUserId,
 				peerCount: Object.keys(state.peers).length,
 				queued: states.reduce((total, entry) => total + entry.state.queued, 0),

package/extensions/wechat/commands.ts

@@ -61,6 +61,8 @@ export const WECHAT_COMMANDS = [
 	{ verb: "login", description: "Log in by QR; on a scan, store the account and start the bridge" },
 	{ verb: "new", description: "Start a fresh host session (peer conversations are independent)" },
 	{ verb: "status", description: "Open the control screen (a one-line summary outside the TUI)" },
+	{ verb: "pause", description: "Stop polling new messages; running turns may finish" },
+	{ verb: "resume", description: "Resume polling after /wechat pause" },
 	{ verb: "doctor", description: "Print a health report: token age, last poll, lock, peers, failures" },
 	{ verb: "stop", description: "Stop one peer's running turn: /wechat stop <peer>" },
 	{ verb: "reset", description: "Start a fresh conversation for one peer: /wechat reset <peer>" },
@@ -124,6 +126,36 @@ async function runDoctor(ctx: ExtensionContext, deps: CommandDeps): Promise<void
 	);
 }
 
+/** Pause or resume polling; the account and peer sessions stay in place. */
+async function runPauseToggle(ctx: ExtensionContext, deps: CommandDeps, resume: boolean): Promise<void> {
+	const bridge = deps.getBridge();
+	if (!bridge) {
+		ctx.ui.notify("WeChat is not running.", "warning");
+		return;
+	}
+	if (resume) {
+		if (!bridge.status().paused) {
+			ctx.ui.notify("WeChat is not paused.");
+			return;
+		}
+		const ok = await bridge.resume();
+		ctx.ui.notify(
+			ok ? "WeChat polling resumed." : "WeChat could not resume; check the terminal notice.",
+			ok ? "info" : "warning",
+		);
+		return;
+	}
+	const ok = await bridge.pause();
+	ctx.ui.notify(
+		ok
+			? "WeChat polling paused. Running turns may finish; no new messages will arrive."
+			: bridge.status().paused
+				? "WeChat is already paused."
+				: "WeChat is not running.",
+		ok ? "info" : "warning",
+	);
+}
+
 /** Add a refused sender to the project config after the operator confirms. */
 async function runAllow(ctx: ExtensionContext, deps: CommandDeps, peerArg?: string): Promise<void> {
 	if (!ctx.hasUI) {
@@ -313,6 +345,14 @@ async function runPanel(ctx: ExtensionCommandContext, deps: CommandDeps): Promis
 						bridge.channel().cancel();
 						return "Cancelled the waiting prompt.";
 					},
+					togglePause: async () => {
+						const bridge = deps.getBridge();
+						if (!bridge) return "WeChat bridge is not running.";
+						if (bridge.status().paused) {
+							return (await bridge.resume()) ? "Resumed polling." : "Could not resume; see the notice.";
+						}
+						return (await bridge.pause()) ? "Paused polling. Running turns may finish." : "WeChat is not running.";
+					},
 				},
 				requestRender: () => tui.requestRender(),
 			}),
@@ -410,6 +450,10 @@ async function dispatch(
 			return runHistory(ctx, deps, peerArg);
 		case "allow":
 			return runAllow(ctx, deps, peerArg || undefined);
+		case "pause":
+			return runPauseToggle(ctx, deps, false);
+		case "resume":
+			return runPauseToggle(ctx, deps, true);
 		case "stop":
 			return runPeerAction(ctx, deps, "stop", peerArg);
 		case "reset":
@@ -425,7 +469,7 @@ async function dispatch(
 export function registerCommands(pi: ExtensionAPI, deps: CommandDeps): void {
 	pi.registerCommand("wechat", {
 		description:
-			"WeChat bridge. /wechat opens the control screen (login | new | status | doctor | stop | reset | history | allow | logout | help)",
+			"WeChat bridge. /wechat opens the control screen (login | new | status | pause | resume | doctor | stop | reset | history | allow | logout | help)",
 		getArgumentCompletions: completeSubcommand,
 		handler: async (args, ctx) => {
 			const [sub = "status", ...rest] = args.trim().split(/\s+/).filter(Boolean);

package/extensions/wechat/doctor.ts

@@ -34,6 +34,7 @@ function age(now: number, at: number | undefined): string {
 }
 
 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";
 	}

package/extensions/wechat/index.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;
 	}
@@ -154,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();

package/extensions/wechat/status-screen.ts

@@ -24,7 +24,7 @@ import { peerLabel } from "./format.ts";
 import type { BotCredentials } from "./types.ts";
 
 /** User-facing connection word; the internal `BridgeState` stays running/stopped. */
-export type StatusConnection = "open" | "expired" | "closed";
+export type StatusConnection = "open" | "expired" | "paused" | "closed";
 
 /**
  * What the status screen closed with: a global action, a peer history request,
@@ -69,7 +69,7 @@ const MAX_PEER_ROWS = 5;
 
 /** The connection word for a bridge status, or `closed` when there is none. */
 export function connectionOf(status: BridgeStatus | undefined): StatusConnection {
-	return status?.open ? "open" : status?.expired ? "expired" : "closed";
+	return status?.paused ? "paused" : status?.open ? "open" : status?.expired ? "expired" : "closed";
 }
 
 /** Build the view from the stored account and the live bridge status. */
@@ -146,6 +146,8 @@ function connectionText(connection: StatusConnection): string {
 			return "open";
 		case "expired":
 			return "expired";
+		case "paused":
+			return "paused";
 		case "closed":
 			return "closed";
 	}
@@ -158,6 +160,8 @@ function connectionRole(connection: StatusConnection): TuiRole {
 			return "ok";
 		case "expired":
 			return "bad";
+		case "paused":
+			return "warn";
 		case "closed":
 			return "meta";
 	}
@@ -193,6 +197,9 @@ export function statusBody(view: StatusView, theme: Theme, width: number, select
 	if (view.connection === "expired") {
 		lines.push("");
 		lines.push(clip(`  ${paint(theme, "bad", "Session expired — press l to log in again.")}`, target));
+	} else if (view.connection === "paused") {
+		lines.push("");
+		lines.push(clip(`  ${paint(theme, "warn", "Paused — press p to resume polling.")}`, target));
 	} else if (view.connection === "closed" && view.account) {
 		lines.push("");
 		lines.push(clip(`  ${paint(theme, "meta", "Not connected — press l to log in again.")}`, target));
@@ -251,6 +258,8 @@ export interface StatusActions {
 	reset(peer: string): string;
 	/** Withdraw the waiting prompt; returns the line to flash. */
 	cancelPrompt(): string;
+	/** Pause or resume polling; async because it settles the poll loop first. */
+	togglePause(): string | Promise<string>;
 }
 
 export interface StatusScreenOptions {
@@ -325,6 +334,27 @@ export class StatusScreenComponent implements Component {
 			this.setFlash(undefined);
 			return;
 		}
+		if (data === "p" || data === "P") {
+			if (!view.bridge) {
+				this.setFlash("WeChat is not running.");
+				return;
+			}
+			const outcome = this.options.actions?.togglePause();
+			if (!outcome) {
+				this.setFlash("Pause is unavailable here.");
+				return;
+			}
+			if (typeof outcome === "string") {
+				this.setFlash(outcome);
+				return;
+			}
+			this.setFlash(view.connection === "paused" ? "Resuming…" : "Pausing…");
+			void outcome.then(
+				(line) => this.setFlash(line),
+				() => this.setFlash("Pause action failed."),
+			);
+			return;
+		}
 		if (data === "a" || data === "A") {
 			this.options.onClose({ kind: "allow" });
 			return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, memory, wechat, and bytefly.",
   "keywords": [
     "pi-package",