@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

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

@@ -32,8 +32,8 @@ import {
 	SessionManager,
 } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
-import { WECHAT_CHANNEL_PROMPT } from "./channel.ts";
-import { peerKey } from "./format.ts";
+import { WECHAT_CHANNEL_PROMPT } from "../text/channel.ts";
+import { peerKey } from "../text/format.ts";
 
 /** The SDK pieces a peer session needs; injected so tests never load resources. */
 export interface PeerSessionSeams {

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.
+ * - 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, type ReplyPipeline } from "./reply-pipeline.ts";
-import { defaultTimer, type ArmTimer } from "./timer.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,18 +101,30 @@ 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[];
 	running?: PeerItem;
@@ -123,7 +141,7 @@ 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>();
@@ -132,7 +150,9 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 	/** 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 {
@@ -280,16 +300,25 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			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. */
@@ -302,7 +331,6 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			target.running = item;
 			target.startedAt = now();
 			running += 1;
-			currentItem = item;
 			cancelIdleSweep(target);
 			deps.onStart?.(item);
 			void (async () => {
@@ -311,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();
@@ -325,11 +354,50 @@ 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);
 			// One message, one turn: a queued item is never folded into another.
+			arrivals += 1;
+			arrived.set(item, arrivals);
 			target.queue.push(item);
 			wake();
 		},
@@ -354,8 +422,8 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 			return true;
 		},
 
-		current(): PeerItem | undefined {
-			return currentItem;
+		running(peer: string): PeerItem | undefined {
+			return peers.get(peer)?.running;
 		},
 
 		async flush(peer: string): Promise<void> {
@@ -370,8 +438,17 @@ 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)
@@ -383,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)));
 		});
 	}

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. */

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"
@@ -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.",
@@ -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);
 		},

package/extensions/wechat/{client.ts → transport/client.ts}

@@ -9,7 +9,7 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { asNumber } from "../../lib/config.ts";
+import { asNumber } from "../../../lib/config.ts";
 import { mediaDownloadUrl } from "./media.ts";
 import type {
 	BotCredentials,
@@ -21,7 +21,7 @@ import type {
 	SendTypingResponse,
 	UpdatesResponse,
 	WeixinMessage,
-} from "./types.ts";
+} from "../types.ts";
 
 /** Fixed public API base used for QR login. */
 export const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
@@ -324,6 +324,30 @@ export class WechatClient {
 		};
 	}
 
+	/** `POST /ilink/bot/sendmessage` — send one image. */
+	async sendImageMessage(
+		account: BotCredentials,
+		args: { to: string; media: CDNMedia; midSize: number; aeskey: string; contextToken?: string },
+		signal?: AbortSignal,
+	): Promise<SendResponse> {
+		const url = `${account.baseUrl}/ilink/bot/sendmessage`;
+		const msg: Record<string, unknown> = {
+			from_user_id: "",
+			to_user_id: args.to,
+			client_id: randomUUID(),
+			message_type: 2,
+			message_state: 2,
+			item_list: [{ type: 2, image_item: { media: args.media, mid_size: args.midSize, aeskey: args.aeskey } }],
+		};
+		if (args.contextToken) msg.context_token = args.contextToken;
+		const data = await this.post(url, this.authHeaders(account), { msg, base_info: this.baseInfo() }, signal);
+		return {
+			ret: asNumber(data.ret),
+			errcode: asNumber(data.errcode),
+			errmsg: asString(data.errmsg),
+		};
+	}
+
 	/** `POST /ilink/bot/getconfig` — the per-user typing ticket. */
 	async getConfig(
 		account: BotCredentials,

package/extensions/wechat/{deliver.ts → transport/deliver.ts}

@@ -8,11 +8,12 @@
  * token is forgotten so the next inbound message can replace it.
  */
 
-import type { BotCredentials } from "./types.ts";
+import type { BotCredentials } from "../types.ts";
 import { isSessionExpired, rejectionOf, WechatError, type WechatClient } from "./client.ts";
-import { messageOf } from "./errors.ts";
-import { chunkText, toWechatText } from "./format.ts";
-import { sendLocalFile } from "./outbound.ts";
+import { messageOf } from "../errors.ts";
+import { chunkText, toWechatText } from "../text/format.ts";
+import { basename } from "node:path";
+import { sendLocalFile, sendLocalImage } from "./outbound.ts";
 
 /** One addressed text destination. */
 export interface MessageTarget {
@@ -63,6 +64,8 @@ export interface Deliverer {
 	prompt(target: MessageTarget, text: string, signal?: AbortSignal): Promise<boolean>;
 	/** Upload and send a local file to a peer. */
 	file(target: MessageTarget, filePath: string, fileName: string, signal?: AbortSignal): Promise<boolean>;
+	/** Upload and send a local image to a peer, as a picture. */
+	image(target: MessageTarget, filePath: string, signal?: AbortSignal): Promise<boolean>;
 	/** Message the owner; returns the tool's result instead of logging. */
 	toOwner(owner: string, contextToken: string | undefined, text: string, signal?: AbortSignal): Promise<DeliveryResult>;
 	/** Forget the one-notice-per-outage state (a new connection). */
@@ -163,6 +166,33 @@ export function createDeliverer(deps: DeliveryDeps): Deliverer {
 		return delivery.ok;
 	}
 
+	/**
+	 * Send one attachment, reporting a failure the model cannot see otherwise.
+	 *
+	 * The sender reports only success, and a caller may fall back to text; without
+	 * this report the operator would never know the attachment was dropped.
+	 */
+	function media(
+		target: MessageTarget,
+		label: "file" | "image",
+		name: string,
+		send: (client: WechatClient, account: BotCredentials, signal?: AbortSignal) => Promise<boolean>,
+		signal?: AbortSignal,
+	): Promise<boolean> {
+		return serialize(target.peer, async () => {
+			const client = deps.client();
+			const account = deps.account();
+			if (!client || !account) return false;
+			const sent = await send(client, account, signal);
+			if (!sent && !signal?.aborted) {
+				deps.onSendError?.(`${label} delivery failed: ${name}`);
+				deps.notify(`WeChat ${label} delivery failed for ${name}.`, "warning");
+			}
+			if (sent) deps.onSent?.();
+			return sent;
+		});
+	}
+
 	return {
 		reply(target, text, signal) {
 			return serialize(target.peer, () => deliverWithNotice(target, text, "reply", signal));
@@ -173,30 +203,44 @@ export function createDeliverer(deps: DeliveryDeps): Deliverer {
 		},
 
 		file(target, filePath, fileName, signal) {
-			return serialize(target.peer, async () => {
-				const client = deps.client();
-				const account = deps.account();
-				if (!client || !account) return false;
-				const sent = await sendLocalFile({
-					client,
-					account,
-					cdnBaseUrl: deps.cdnBaseUrl,
-					maxBytes: deps.maxMediaBytes,
-					to: target.peer,
-					contextToken: target.contextToken,
-					filePath,
-					fileName,
-					signal,
-				});
-				// `sendLocalFile` reports only success, and the caller may fall back to text;
-				// without this line the operator would never know the attachment was dropped.
-				if (!sent && !signal?.aborted) {
-					deps.onSendError?.(`file delivery failed: ${fileName}`);
-					deps.notify(`WeChat file delivery failed for ${fileName}.`, "warning");
-				}
-				if (sent) deps.onSent?.();
-				return sent;
-			});
+			return media(
+				target,
+				"file",
+				fileName,
+				(client, account, abortSignal) =>
+					sendLocalFile({
+						client,
+						account,
+						cdnBaseUrl: deps.cdnBaseUrl,
+						maxBytes: deps.maxMediaBytes,
+						to: target.peer,
+						contextToken: target.contextToken,
+						filePath,
+						fileName,
+						signal: abortSignal,
+					}),
+				signal,
+			);
+		},
+
+		image(target, filePath, signal) {
+			return media(
+				target,
+				"image",
+				basename(filePath),
+				(client, account, abortSignal) =>
+					sendLocalImage({
+						client,
+						account,
+						cdnBaseUrl: deps.cdnBaseUrl,
+						maxBytes: deps.maxMediaBytes,
+						to: target.peer,
+						contextToken: target.contextToken,
+						filePath,
+						signal: abortSignal,
+					}),
+				signal,
+			);
 		},
 
 		toOwner(owner, contextToken, text, signal) {