@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/extensions/wechat/{peer-worker.ts → peer/peer-worker.ts}

@@ -10,13 +10,18 @@
  *
  * Contract:
  *
- * - One turn at a time per peer, and by default one turn at a time overall
- *   (`concurrency`), so a forwarded dialog always has a single owning peer.
- * - A message that arrives while its peer is already waiting behind a turn is
- *   merged into the waiting one, so a burst is answered once, in order.
+ * - One turn at a time per peer, and by default two peers' turns at once
+ *   (`PEER_CONCURRENCY`), so each answered peer owns its dialog through its own
+ *   interaction channel. A third peer waits for a slot and is told so.
+ * - Every message is its own turn, in arrival order. A message that arrives
+ *   while a turn runs waits for its own turn and answer; nothing is merged.
  * - A turn's answer is the text it produced. A requested `/stop` says `stopped`
  *   and drops the partial answer, a finished turn with no text says `noText`,
  *   and a thrown turn says `failed` — never silence.
+ * - A close that abandons the session says `abandoned` once per peer that still
+ *   had work, after its turn stops and before its session goes. The turn's own
+ *   line is suppressed then, and each notice carries its own deadline, so a
+ *   connection that never answers cannot hold the exit.
  * - The session is opened lazily, reset on request, and disposed after an idle
  *   timeout, so a peer who stops writing does not keep a context alive.
  *
@@ -24,10 +29,11 @@
  */
 
 import type { ImageContent } from "@earendil-works/pi-ai";
-import { messageOf } from "./errors.ts";
+import { messageOf } from "../errors.ts";
+import type { NoticeKind } from "../text/notices.ts";
 import type { PeerSession } from "./peer-session.ts";
-import { createReplyPipeline } from "./reply-pipeline.ts";
-import { defaultTimer, type ArmTimer } from "./timer.ts";
+import { createReplyPipeline, type ReplyPipeline } from "./reply-pipeline.ts";
+import { defaultTimer, type ArmTimer } from "../timer.ts";
 
 /** One admitted, media-resolved inbound message. */
 export interface PeerItem {
@@ -45,13 +51,13 @@ export interface PeerItem {
 }
 
 /** What the worker says to the peer when a turn ends without text of its own. */
-export type TurnFallback = "stopped" | "noText" | "failed" | "compacted";
+export type TurnFallback = Extract<NoticeKind, "stopped" | "abandoned" | "noText" | "failed" | "compacted">;
 
 export interface PeerWorkerDeps {
 	/** Open (or resume) one peer's session; the bridge owns the directory layout. */
 	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>;
+	/** Deliver one line to the peer; false stops the rest of a stream. */
+	send: (item: PeerItem, text: string, options?: { signal?: AbortSignal }) => Promise<boolean>;
 	/** 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. */
@@ -59,7 +65,7 @@ export interface PeerWorkerDeps {
 	onSettled?: (item: PeerItem) => void;
 	/** A session or turn failure worth showing on the terminal. */
 	notify?: (message: string, kind?: "info" | "warning" | "error") => void;
-	/** Turns running at once across peers. Default 1, so a dialog has one owner. */
+	/** Turns running at once across peers. Defaults to {@link PEER_CONCURRENCY}. */
 	concurrency?: number;
 	/** Dispose an idle session after this long. `0` disables the idle sweep. */
 	idleTimeoutMs?: number;
@@ -86,7 +92,7 @@ export interface PeerSnapshot {
 }
 
 export interface PeerWorker {
-	/** Queue one message; resolves as soon as it is queued or merged. */
+	/** Queue one message; it is never merged into another. */
 	enqueue(item: PeerItem): void;
 	/** Stop the running turn for `peer`; false when nothing was running. */
 	abort(peer: string): boolean;
@@ -95,20 +101,32 @@ export interface PeerWorker {
 	 * Refused while a turn runs, and the queued messages go with it.
 	 */
 	reset(peer: string): boolean;
-	/** The turn running right now, if any (one with the default concurrency). */
-	current(): PeerItem | undefined;
+	/** The turn running for this peer, if any. */
+	running(peer: string): PeerItem | undefined;
+	/** Flush buffered assistant text for a running peer before a prompt/file. */
+	flush(peer: string): Promise<void>;
 	state(peer: string): PeerState;
 	snapshot(): PeerSnapshot[];
 	/** Drop every session; queued messages are dropped with them. */
-	close(): Promise<void>;
+	close(options?: { abandon?: boolean }): Promise<void>;
 }
 
 const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 
+/**
+ * Peers whose turns run at once.
+ *
+ * Two, because a phone chat rarely has more than two conversations in flight and
+ * every concurrent turn is a full model run on the user's budget; the rest wait
+ * in a fair queue and are acknowledged, exactly as a second peer waits today.
+ */
+export const PEER_CONCURRENCY = 2;
+
+/** How long a shutdown waits for its one notice per peer before giving up. */
+const ABANDON_NOTICE_MS = 5000;
+
 interface PeerEntry {
 	queue: PeerItem[];
-	/** Messages merged into the waiting item, so `queued` counts real messages. */
-	merged: number;
 	running?: PeerItem;
 	/** Monotonic start time of the running turn, for `runningMs`. */
 	startedAt?: number;
@@ -119,38 +137,28 @@ interface PeerEntry {
 	disposeTimer?: () => void;
 }
 
-/** Merge a waiting item with a newer one from the same peer. */
-function mergeItems(first: PeerItem, next: PeerItem): PeerItem {
-	const images = [...(first.images ?? []), ...(next.images ?? [])];
-	return {
-		peer: first.peer,
-		text: first.text && next.text ? `${first.text}\n${next.text}` : first.text || next.text,
-		images: images.length > 0 ? images : undefined,
-		// The first item's prefix still describes an attachment the model never saw.
-		prefix: first.prefix,
-		language: next.language,
-		contextToken: next.contextToken ?? first.contextToken,
-	};
-}
-
 export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 	const now = deps.now ?? Date.now;
 	const armTimer = deps.armTimer ?? defaultTimer;
 	const idleTimeoutMs = deps.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-	const concurrency = Math.max(1, deps.concurrency ?? 1);
+	const concurrency = Math.max(1, deps.concurrency ?? PEER_CONCURRENCY);
 	const peers = new Map<string, PeerEntry>();
+	/** Active reply pipelines, so a dialog can flush buffered text first. */
+	const pipelines = new Map<string, ReplyPipeline>();
 	/** Peers whose running turn the peer asked to stop, so it reads as stopped. */
 	const aborted = new Set<string>();
 	/** Peers whose next session must start empty (`/new`). */
 	const fresh = new Set<string>();
 	let running = 0;
-	let currentItem: PeerItem | undefined;
+	/** When each queued item arrived, so the next free slot goes to the oldest wait. */
+	const arrived = new WeakMap<PeerItem, number>();
+	let arrivals = 0;
 	let closed = false;
 
 	function entry(peer: string): PeerEntry {
 		const existing = peers.get(peer);
 		if (existing) return existing;
-		const created: PeerEntry = { queue: [], merged: 0 };
+		const created: PeerEntry = { queue: [] };
 		peers.set(peer, created);
 		return created;
 	}
@@ -168,12 +176,12 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 		if (target.running) {
 			return {
 				status: "running",
-				queued: target.queue.length + target.merged,
+				queued: target.queue.length,
 				runningMs: target.startedAt === undefined ? 0 : now() - target.startedAt,
 				...sessionAge,
 			};
 		}
-		const queued = target.queue.length + target.merged;
+		const queued = target.queue.length;
 		return { status: queued > 0 ? "queued" : "idle", queued, ...sessionAge };
 	}
 
@@ -251,6 +259,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			partChars: deps.partChars,
 			quietMs: deps.quietMs,
 		});
+		pipelines.set(item.peer, pipeline);
 		/** The session compacted this turn, so the peer is told its older detail is fuzzy. */
 		let compacted = false;
 		const unsubscribe = session.subscribe((event) => {
@@ -289,17 +298,27 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			}
 		} finally {
 			unsubscribe();
+			pipelines.delete(item.peer);
 		}
+		// A closing worker has already said, once, that the session ended.
+		if (closed) return;
 		if (reason) await sendPart(deps.fallback(item, reason));
 		if (compacted) await sendPart(deps.fallback(item, "compacted"));
 	}
 
 	/** The next peer with work, so a finished turn can hand its slot on. */
+	/** The next peer with work, oldest queued message first so no peer starves. */
 	function nextRunnable(): [string, PeerEntry] | undefined {
+		let picked: [string, PeerEntry] | undefined;
 		for (const [peer, target] of peers) {
-			if (!target.running && target.queue.length > 0) return [peer, target];
+			if (target.running || target.queue.length === 0) continue;
+			const waiting = target.queue[0];
+			const oldest = picked?.[1].queue[0];
+			if (!picked || (waiting && oldest && (arrived.get(waiting) ?? 0) < (arrived.get(oldest) ?? 0))) {
+				picked = [peer, target];
+			}
 		}
-		return undefined;
+		return picked;
 	}
 
 	/** Start turns until the concurrency limit or the queues are empty. */
@@ -309,11 +328,9 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			if (!next) return;
 			const [peer, target] = next;
 			const item = target.queue.shift() as PeerItem;
-			target.merged = 0;
 			target.running = item;
 			target.startedAt = now();
 			running += 1;
-			currentItem = item;
 			cancelIdleSweep(target);
 			deps.onStart?.(item);
 			void (async () => {
@@ -322,12 +339,13 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 					await runTurn(item, opened);
 				} catch (error) {
 					deps.notify?.(`WeChat session failed for ${item.peer}: ${messageOf(error)}`, "error");
-					await deps.send(item, deps.fallback(item, "failed"));
+					// A closing worker says one line of its own instead: the peer does not need
+					// two reasons, and the second send may well fail on the dying connection.
+					if (!closed) await deps.send(item, deps.fallback(item, "failed"));
 				} finally {
 					target.running = undefined;
 					target.startedAt = undefined;
 					running -= 1;
-					currentItem = undefined;
 					deps.onSettled?.(item);
 					armIdleSweep(target);
 					wake();
@@ -336,20 +354,51 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 		}
 	}
 
+	/** One abandon notice; true when the deadline, not the transport, gave up on it. */
+	async function announce(item: PeerItem): Promise<boolean> {
+		const controller = new AbortController();
+		const cancel = armTimer(ABANDON_NOTICE_MS, () => controller.abort());
+		try {
+			await deps.send(item, deps.fallback(item, "abandoned"), { signal: controller.signal });
+			return controller.signal.aborted;
+		} catch (error) {
+			// A send the deadline cancelled rejects like any aborted request; that is the
+			// deadline's report. Anything else is the transport's own failure.
+			if (controller.signal.aborted) return true;
+			deps.notify?.(`WeChat could not tell ${item.peer} the session ended: ${messageOf(error)}`, "warning");
+			return false;
+		} finally {
+			cancel();
+		}
+	}
+
+	/**
+	 * Tell every peer that still had work that the session ended.
+	 *
+	 * One line per peer, sent after the turns have stopped and before the sessions
+	 * go. Each send carries its own deadline, so a connection that never answers
+	 * cannot hold the exit; a deadline is reported here because the deliverer keeps
+	 * an aborted send quiet — an abort is normally the peer's own `/stop`.
+	 */
+	async function announceAbandoned(items: readonly PeerItem[]): Promise<void> {
+		const gaveUp = await Promise.all(items.map((item) => announce(item)));
+		for (const [index, timedOut] of gaveUp.entries()) {
+			if (!timedOut) continue;
+			deps.notify?.(
+				`WeChat could not tell ${items[index]?.peer ?? ""} the session ended: no reply in ${ABANDON_NOTICE_MS / 1000} s.`,
+				"warning",
+			);
+		}
+	}
+
 	return {
 		enqueue(item: PeerItem): void {
 			if (closed) return;
 			const target = entry(item.peer);
-			const tail = target.queue.at(-1);
-			// A non-empty queue means this peer's turn has not started yet, so the
-			// burst is answered once, in send order. The merged count keeps `queued`
-			// honest so the bridge can cap a flood and the panel can report it.
-			if (tail) {
-				target.queue[target.queue.length - 1] = mergeItems(tail, item);
-				target.merged += 1;
-			} else {
-				target.queue.push(item);
-			}
+			// One message, one turn: a queued item is never folded into another.
+			arrivals += 1;
+			arrived.set(item, arrivals);
+			target.queue.push(item);
 			wake();
 		},
 
@@ -368,14 +417,17 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			releaseSession(peer);
 			if (target) {
 				target.queue = [];
-				target.merged = 0;
 				cancelIdleSweep(target);
 			}
 			return true;
 		},
 
-		current(): PeerItem | undefined {
-			return currentItem;
+		running(peer: string): PeerItem | undefined {
+			return peers.get(peer)?.running;
+		},
+
+		async flush(peer: string): Promise<void> {
+			await pipelines.get(peer)?.flush();
 		},
 
 		state(peer: string): PeerState {
@@ -386,8 +438,18 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			return [...peers.keys()].map((peer) => ({ peer, state: stateOf(peer) }));
 		},
 
-		async close(): Promise<void> {
+		async close(options?: { abandon?: boolean }): Promise<void> {
 			closed = true;
+			// Captured before the teardown forgets it: a running turn and a queue that
+			// never started are both an answer the peer will not get.
+			const abandoned: PeerItem[] = [];
+			if (options?.abandon) {
+				for (const target of peers.values()) {
+					const item = target.running ?? target.queue[0];
+					if (item) abandoned.push(item);
+				}
+			}
+			pipelines.clear();
 			const runningAborts = [...peers.values()]
 				.filter((target) => target.session)
 				.map((target) => target.session?.session.abort());
@@ -398,6 +460,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			}
 			aborted.clear();
 			fresh.clear();
+			await announceAbandoned(abandoned);
 		},
 	};
 }

package/extensions/wechat/{presence.ts → peer/presence.ts}

@@ -9,12 +9,12 @@
  * notice is bounded to one per wait episode.
  */
 
-import type { BotCredentials } from "./types.ts";
-import type { WechatClient } from "./client.ts";
+import type { BotCredentials } from "../types.ts";
+import type { WechatClient } from "../transport/client.ts";
 import type { PeerState } from "./peer-worker.ts";
-import type { PeerLanguage } from "./format.ts";
-import { notice } from "./notices.ts";
-import { createTimerMap, type ArmTimer } from "./timer.ts";
+import type { PeerLanguage } from "../text/format.ts";
+import { notice } from "../text/notices.ts";
+import { createTimerMap, type ArmTimer } from "../timer.ts";
 
 /** How long a fetched typing ticket is reused. */
 const TYPING_TTL_MS = 5 * 60 * 1000;
@@ -44,7 +44,8 @@ export interface PresenceDeps {
 	/** Send one stock line to the peer (chunked by the bridge). */
 	send: (peer: string, contextToken: string | undefined, text: string) => Promise<unknown>;
 	/** A forwarded dialog is waiting; its own reminder covers the wait. */
-	promptPending: () => boolean;
+	/** Whether that peer is waiting on a dialog, so "still working" would be noise. */
+	promptPending: (peer: string) => boolean;
 }
 
 /** One message a notice refers to. */
@@ -180,7 +181,7 @@ export function createPresence(deps: PresenceDeps): Presence {
 			if (!isRunning(peer)) return;
 			// A turn waiting on an unanswered dialog is not "still working": the
 			// prompt itself nudges, and saying both reads as noise.
-			if (deps.promptPending()) return;
+			if (deps.promptPending(peer)) return;
 			void deps.send(peer, contextToken, notice("stillWorking", deps.languageOf(peer)));
 		});
 	}
@@ -204,14 +205,13 @@ export function createPresence(deps: PresenceDeps): Presence {
 	 * the same thing without spending a bubble.
 	 */
 	function armAck(target: PresenceTarget): void {
-		// A turn for this peer is already running: its own progress notice covers
-		// this message, so a second acknowledgement would be noise.
-		if (isRunning(target.peer)) return;
+		// A message can be queued behind a running turn; it still gets one
+		// acknowledgement after the delay, but not one per message.
 		if (acks.has(target.peer)) return;
 		const last = ackedAt.get(target.peer);
 		if (last !== undefined && deps.now() - last < ACK_REPEAT_MS) return;
 		acks.arm(target.peer, ACK_DELAY_MS, () => {
-			if (!hasWork(target.peer) || isRunning(target.peer)) return;
+			if (!hasWork(target.peer)) return;
 			ackedAt.set(target.peer, deps.now());
 			void deps.send(target.peer, target.contextToken, notice("ack", deps.languageOf(target.peer)));
 			// Still waiting after a minute behind another turn: say why.

package/extensions/wechat/{reply-pipeline.ts → peer/reply-pipeline.ts}

@@ -11,7 +11,7 @@
  * drive it.
  */
 
-import type { ArmTimer } from "./timer.ts";
+import type { ArmTimer } from "../timer.ts";
 
 export interface ReplyPipelineDeps {
 	/** Send one part to the peer. Parts arrive strictly in order. */
@@ -27,6 +27,8 @@ export interface ReplyPipelineDeps {
 export interface ReplyPipeline {
 	/** Add streamed text; parts go out as boundaries are crossed. */
 	push(delta: string): void;
+	/** Send the current buffer now, in order; used before a dialog or file. */
+	flush(): Promise<void>;
 	/** Send whatever is left and resolve once every part is out. */
 	finish(): Promise<void>;
 	/** Drop the unsent remainder (an aborted turn) and cancel the timer. */
@@ -106,6 +108,13 @@ export function createReplyPipeline(deps: ReplyPipelineDeps): ReplyPipeline {
 		enqueue(part);
 	}
 
+	async function flushBuffer(): Promise<void> {
+		cancelQuiet();
+		enqueue(buffer);
+		buffer = "";
+		await chain;
+	}
+
 	return {
 		push(delta: string): void {
 			if (!delta) return;
@@ -125,11 +134,10 @@ export function createReplyPipeline(deps: ReplyPipelineDeps): ReplyPipeline {
 			scheduleQuiet();
 		},
 
+		flush: flushBuffer,
+
 		async finish(): Promise<void> {
-			cancelQuiet();
-			enqueue(buffer);
-			buffer = "";
-			await chain;
+			await flushBuffer();
 		},
 
 		drop(): void {

package/extensions/wechat/{credentials.ts → state/credentials.ts}

@@ -9,8 +9,8 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_BASE_URL } from "./client.ts";
-import type { BotCredentials, CredentialsFile } from "./types.ts";
+import { DEFAULT_BASE_URL } from "../transport/client.ts";
+import type { BotCredentials, CredentialsFile } from "../types.ts";
 
 /** The bridge's directory under the agent dir. */
 export function wechatDir(): string {

package/extensions/wechat/{state.ts → state/state.ts}

@@ -8,9 +8,10 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { PeerState, SeenMessage, WechatState } from "./types.ts";
+import type { BotCredentials, PeerState, SeenMessage, WechatState } from "../types.ts";
+import type { MessageTarget } from "../transport/deliver.ts";
 import { wechatDir } from "./credentials.ts";
-import { peerKey } from "./format.ts";
+import { peerKey } from "../text/format.ts";
 
 /** How long a handled message id is remembered for a replay. */
 export const SEEN_TTL_MS = 60 * 60 * 1000;
@@ -114,6 +115,17 @@ export function findPeer(state: WechatState, peer: string): PeerState | undefine
 	return state.peers[storedKey(state, peer)];
 }
 
+/**
+ * Who a proactive send goes to, and the token that carries it.
+ *
+ * Either id form may be stored: the owner id comes from the login response and the
+ * token from an inbound `from_user_id`, and they need not agree.
+ */
+export function ownerTarget(state: WechatState, account: BotCredentials): MessageTarget {
+	const peer = state.ownerId ?? account.ilinkUserId;
+	return { peer, contextToken: findPeer(state, peer)?.lastContextToken };
+}
+
 /** Whether this message id was already handled for the peer. */
 export function seenMessage(state: WechatState, peer: string, id: number): boolean {
 	const key = peerKey(peer);

package/extensions/wechat/{format.ts → text/format.ts}

@@ -3,9 +3,9 @@
  * and shorten peer ids for display. The peer-facing notices live in `notices.ts`.
  */
 
-import { stripControlChars } from "../../lib/format.ts";
-import { sanitizeFileName } from "./media.ts";
-import type { CDNMedia, MediaRef, MessageItem } from "./types.ts";
+import { stripControlChars } from "../../../lib/format.ts";
+import { sanitizeFileName } from "../transport/media.ts";
+import type { CDNMedia, MediaRef, MessageItem } from "../types.ts";
 
 /**
  * Prepare inbound WeChat text before it becomes a user turn: strip terminal

package/extensions/wechat/{notices.ts → text/notices.ts}

@@ -17,6 +17,7 @@ export type NoticeKind =
 	| "media"
 	| "unsupported"
 	| "stopped"
+	| "abandoned"
 	| "noText"
 	| "compacted"
 	| "budget"
@@ -27,14 +28,14 @@ export type NoticeKind =
 	| "newBusy";
 
 const NOTICES: Record<NoticeKind, Record<PeerLanguage, string>> = {
-	ack: { zh: "收到，正在排队，轮到就回你。", en: "Got it — queued; I'll answer when it's my turn." },
+	ack: { zh: "收到，排队中，轮到就回。", en: "Queued — I'll answer next." },
 	busy: {
-		zh: "前面还有一条正在处理，你的消息排在后面，轮到你就回你。",
-		en: "Your message is queued behind another conversation; I'll answer as soon as it's free.",
+		zh: "还在处理前一条，轮到就回。",
+		en: "Still on the previous message; yours is next.",
 	},
 	stillWorking: {
-		zh: "还在处理这条，发送 /stop 可取消。",
-		en: "Still working — send /stop to cancel.",
+		zh: "还在处理，/stop 可取消。",
+		en: "Still working — /stop cancels.",
 	},
 	overflow: { zh: "消息有点多，稍后再发。", en: "Too many messages queued — please wait a moment." },
 	media: {
@@ -46,6 +47,10 @@ const NOTICES: Record<NoticeKind, Record<PeerLanguage, string>> = {
 		en: "Voice without a transcript and video aren't supported — please send text or an image.",
 	},
 	stopped: { zh: "已停止。", en: "Stopped." },
+	abandoned: {
+		zh: "会话已停止，这条还没答完。恢复后再发一次即可。",
+		en: "The session stopped before this answer finished — send it again when it's back.",
+	},
 	noText: {
 		zh: "这条处理完了，但没有文字输出。",
 		en: "That turn finished without any text to send.",
@@ -59,8 +64,8 @@ const NOTICES: Record<NoticeKind, Record<PeerLanguage, string>> = {
 		en: "You've reached this hour's message limit — please try again later.",
 	},
 	promptWaiting: {
-		zh: "还在等你的回复，回复「取消」可跳过。",
-		en: "Still waiting for your reply — reply “cancel” to skip this.",
+		zh: "等你回复；回复「取消」跳过。",
+		en: "Waiting for your reply — reply cancel to skip.",
 	},
 	timeout: { zh: "问题超时，已取消。", en: "That question timed out." },
 	withdrawn: { zh: "问题已撤回。", en: "That question was withdrawn." },
@@ -71,6 +76,9 @@ const NOTICES: Record<NoticeKind, Record<PeerLanguage, string>> = {
 	},
 };
 
+/** Every kind the bridge can send, so a check over the catalogue cannot miss one. */
+export const NOTICE_KINDS = Object.keys(NOTICES) as NoticeKind[];
+
 /** 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];

package/extensions/wechat/tools.ts

@@ -2,11 +2,13 @@
  * Model-facing registration for the `send_wechat` tool.
  *
  * The bridge replies to inbound messages automatically; this tool is for the
- * agent to message the owner proactively. It is deliberately owner-only and
- * text-only: the model cannot choose a recipient, so untrusted generated text
- * cannot be aimed at an arbitrary WeChat account.
+ * agent to message the owner proactively. It is deliberately owner-only: the
+ * model cannot choose a recipient, so untrusted generated text cannot be aimed at
+ * an arbitrary WeChat account. It carries one text or one local image, and an
+ * image arrives as a picture rather than a document.
  */
 
+import { basename } from "node:path";
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
@@ -19,11 +21,20 @@ import type { Bridge } from "./bridge.ts";
 export const TOOL_NAME = "send_wechat";
 
 const WechatSendParams = Type.Object({
-	text: Type.String({
-		minLength: 1,
-		maxLength: 4000,
-		description: "The message to send to the WeChat owner. Plain text.",
-	}),
+	text: Type.Optional(
+		Type.String({
+			minLength: 1,
+			maxLength: 4000,
+			description: "The message to send to the WeChat owner. Plain text.",
+		}),
+	),
+	image: Type.Optional(
+		Type.String({
+			minLength: 1,
+			maxLength: 4096,
+			description: "Path to a local image to send instead, as a picture. One of text or image.",
+		}),
+	),
 });
 type WechatSendArgs = Static<typeof WechatSendParams>;
 
@@ -49,12 +60,13 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 		name: TOOL_NAME,
 		label: "WeChat send",
 		description: [
-			"Send a plain-text WeChat message to the account owner from the running bridge (start it with /wechat login).",
+			"Send a WeChat message — plain text, or one local image as a picture — to the account owner from the running bridge (start it with /wechat login).",
 			"The recipient is always the owner and cannot be chosen.",
 		].join(" "),
-		promptSnippet: "Send a plain-text WeChat message to the account owner.",
+		promptSnippet: "Send a WeChat text or image to the account owner.",
 		promptGuidelines: [
 			"Use send_wechat only to message the owner proactively, not to answer an inbound WeChat message (the bridge replies automatically).",
+			"Give one of text or image: a plot or screenshot goes as a path, not described in words.",
 			"Keep messages concise and do not include secrets unless the user asked for them.",
 		],
 		parameters: WechatSendParams,
@@ -64,16 +76,21 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 
 		async execute(_toolCallId, params) {
 			const args = params as WechatSendArgs;
+			if ((args.text === undefined) === (args.image === undefined)) {
+				return sendResult(false, "Give exactly one of text or image.");
+			}
 			const bridge = deps.getBridge();
 			if (!bridge) {
 				return sendResult(false, "WeChat bridge is not started. Run /wechat login first.");
 			}
-			const outcome = await bridge.sendToOwner(args.text);
+			const outcome = await bridge.sendToOwner(args.text, args.image);
 			return sendResult(outcome.ok, outcome.error);
 		},
 
 		renderCall(args, theme, context) {
-			const body = (args as { text?: unknown }).text;
+			const { text, image } = args as { text?: unknown; image?: unknown };
+			// An image is named by its file, so a call line never carries a whole path.
+			const body = typeof image === "string" ? basename(image) : text;
 			const label = context.argsComplete && typeof body === "string" ? body : "…";
 			return callLine(theme, context.lastComponent, TOOL_NAME, label);
 		},