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

package/extensions/wechat/{slash.ts → commands/slash.ts}

@@ -10,8 +10,8 @@
  * Value-only: no module-level state.
  */
 
-import { type PeerLanguage } from "./format.ts";
-import { notice } from "./notices.ts";
+import { type PeerLanguage } from "../text/format.ts";
+import { notice } from "../text/notices.ts";
 
 /** The two command kinds. */
 export type SlashKind = "snippet" | "action";
@@ -37,6 +37,42 @@ export interface SlashSessionControls {
 	history?: (count: number) => Promise<string>;
 }
 
+/** What a builder needs to bind the session controls to one sender. */
+export interface SlashControlsDeps {
+	/** What that peer's conversation is doing. */
+	state: (peer: string) => SlashPeerState;
+	/** The title of a dialog waiting on that peer, if one waits. */
+	prompt: (peer: string) => string | undefined;
+	/** Drop the peer's conversation, so the next message starts empty. */
+	reset: (peer: string) => void;
+	/** Stop the peer's running turn; false when nothing was running. */
+	stop: (peer: string) => boolean;
+	/** The last `count` messages of the peer's own conversation. */
+	history: (peer: string, count: number) => Promise<string>;
+}
+
+/**
+ * The controls one action runs against, for the peer that typed the command.
+ *
+ * The registry owns what a command may do; the bridge owns the queue and the
+ * channels, so it supplies them here and keeps no per-peer session shape of its
+ * own.
+ */
+export function slashControls(peer: string, deps: SlashControlsDeps): SlashSessionControls {
+	return {
+		newSession: () => {
+			deps.reset(peer);
+		},
+		stop: () => deps.stop(peer),
+		status: () => {
+			const waiting = deps.prompt(peer);
+			const state = deps.state(peer);
+			return waiting === undefined ? state : { ...state, prompt: waiting };
+		},
+		history: (count) => deps.history(peer, count),
+	};
+}
+
 /** The environment an action handler runs in. */
 export interface SlashContext {
 	/** Text after the command name, trimmed. */

package/extensions/wechat/dialog/channels.ts

@@ -0,0 +1,136 @@
+/**
+ * One interaction channel per peer.
+ *
+ * Two peers' turns can run at once ({@link PEER_CONCURRENCY}), and a forwarded
+ * dialog is only unambiguous if the channel that asks knows which peer it is
+ * asking — so each peer owns a channel, and a reply can only answer its own
+ * peer's prompt. This registry builds them lazily, routes an inbound message to
+ * that peer's channel, and aggregates what waits so the control screen and
+ * `/wechat status` can name each waiting peer.
+ *
+ * It also owns the dialogs' outbound path — the flush of buffered text, the
+ * prompt gate, and the deliverer call — because that path is per peer and belongs
+ * with the channel that uses it rather than with the bridge that wires it.
+ *
+ * Value-only: the map lives in the closure.
+ */
+
+import type { PendingPromptInfo, WechatInteractionChannel } from "./interaction.ts";
+import { createWechatInteractionChannel } from "./interaction.ts";
+import type { PeerLanguage } from "../text/format.ts";
+import type { ArmTimer } from "../timer.ts";
+
+/** What the registry needs from the bridge; the turn's item carries the token. */
+export interface PeerChannelDeps {
+	/** Put buffered assistant text on the wire before a prompt or a file. */
+	flush: (peer: string) => Promise<void>;
+	/** Send one dialog message to a peer as that peer's next bubble. */
+	send: (peer: string, text: string, signal?: AbortSignal) => Promise<boolean>;
+	/** Send one local file to a peer. */
+	sendFile: (peer: string, path: string, name: string, signal?: AbortSignal) => Promise<boolean>;
+	/** Whether the peer owns a running turn, so a prompt has somewhere to land. */
+	active: (peer: string) => boolean;
+	/** The language the peer writes in, for the prompt and the timeout notices. */
+	language: (peer: string) => PeerLanguage;
+	/** Arm a cancellable one-shot timer. Defaults to a real, unref'd one. */
+	armTimer?: ArmTimer;
+	/** Clock for a prompt's start time; defaults to `Date.now`. */
+	now?: () => number;
+}
+
+export interface PeerChannels {
+	/** This peer's channel, created on first use. */
+	for(peer: string): WechatInteractionChannel;
+	/** Route an inbound message to the peer's pending prompt; true when it answered one. */
+	handleInbound(peer: string, text: string): boolean;
+	/** The prompt one peer is waiting on, if any. */
+	pendingFor(peer: string): PendingPromptInfo | undefined;
+	/** Every waiting prompt, oldest channel first. */
+	prompts(): PendingPromptInfo[];
+	/** Whether that peer — or with no argument, any peer — has a prompt waiting. */
+	hasPending(peer?: string): boolean;
+	/** Withdraw every waiting prompt, telling each peer. */
+	cancelAll(): Promise<void>;
+	/** Drop every channel and its waiting prompt, silently. */
+	reset(): void;
+}
+
+export function createPeerChannels(deps: PeerChannelDeps): PeerChannels {
+	const channels = new Map<string, WechatInteractionChannel>();
+
+	function build(peer: string): WechatInteractionChannel {
+		let channel: WechatInteractionChannel | undefined;
+		/**
+		 * Dialog text is only sent while its prompt is registered; the timeout,
+		 * waiting, and withdrawal lines force their way through. Reading the channel
+		 * this closure builds keeps one owner for "is a prompt waiting".
+		 */
+		const allowed = (options?: { force?: boolean }): boolean =>
+			options?.force === true || (channel?.hasPending() ?? false);
+
+		channel = createWechatInteractionChannel({
+			peer,
+			send: async (text, signal, options) => {
+				if (!allowed(options)) return false;
+				await deps.flush(peer);
+				return deps.send(peer, text, signal);
+			},
+			sendFile: async (path, name, signal, options) => {
+				if (!allowed(options)) return false;
+				await deps.flush(peer);
+				return deps.sendFile(peer, path, name, signal);
+			},
+			active: () => deps.active(peer),
+			language: () => deps.language(peer),
+			armTimer: deps.armTimer,
+			now: deps.now,
+		});
+		return channel;
+	}
+
+	return {
+		for(peer: string): WechatInteractionChannel {
+			const existing = channels.get(peer);
+			if (existing) return existing;
+			const created = build(peer);
+			channels.set(peer, created);
+			return created;
+		},
+
+		handleInbound(peer: string, text: string): boolean {
+			// Only a channel that exists can be waiting, so an inbound message never
+			// creates one for a peer that has not been asked anything.
+			return channels.get(peer)?.handleInbound(text) ?? false;
+		},
+
+		pendingFor(peer: string): PendingPromptInfo | undefined {
+			return channels.get(peer)?.pendingInfo();
+		},
+
+		prompts(): PendingPromptInfo[] {
+			const waiting: PendingPromptInfo[] = [];
+			for (const channel of channels.values()) {
+				const info = channel.pendingInfo();
+				if (info) waiting.push(info);
+			}
+			return waiting;
+		},
+
+		hasPending(peer?: string): boolean {
+			if (peer !== undefined) return channels.get(peer)?.hasPending() ?? false;
+			for (const channel of channels.values()) if (channel.hasPending()) return true;
+			return false;
+		},
+
+		async cancelAll(): Promise<void> {
+			for (const channel of channels.values()) {
+				if (channel.hasPending()) await channel.cancel();
+			}
+		},
+
+		reset(): void {
+			for (const channel of channels.values()) channel.reset();
+			channels.clear();
+		},
+	};
+}

package/extensions/wechat/{interaction.ts → dialog/interaction.ts}

@@ -1,11 +1,13 @@
 /**
  * The WeChat implementation of {@link InteractionChannel}: it forwards a dialog
- * prompt to the peer that owns the current turn and resolves when that peer
- * replies.
+ * prompt to one peer and resolves when that peer replies.
  *
- * It depends only on injected `send`/`sendFile`/`activePeer` accessors and a
- * timer seam, never on the bridge or HTTP client, so it is unit-tested without
- * I/O. The bridge owns the poll loop and hands each inbound message to
+ * One channel serves one peer. That is what lets two peers' turns run at once
+ * without a dialog becoming ambiguous: the channel knows who it is asking, so a
+ * reply can only answer its own peer's prompt. It depends only on injected
+ * `send`/`sendFile`/`active` accessors and a timer seam, never on the bridge or
+ * HTTP client, so it is unit-tested without I/O. The bridge owns the poll loop,
+ * keeps one channel per peer (`channels.ts`), and hands each inbound message to
  * {@link WechatInteractionChannel.handleInbound}.
  *
  * A prompt is bounded: a peer who never answers cannot hold the session open, so
@@ -18,23 +20,25 @@ import {
 	type InteractionAnswer,
 	type InteractionChannel,
 	type InteractionRequest,
-} from "../../lib/interaction.ts";
-import { type PeerLanguage } from "./format.ts";
-import { notice } from "./notices.ts";
+} from "../../../lib/interaction.ts";
+import { type PeerLanguage } from "../text/format.ts";
+import { notice } from "../text/notices.ts";
 import { formatPrompt, parsePromptAnswer } from "./prompt.ts";
-import { defaultTimer, type ArmTimer } from "./timer.ts";
+import { defaultTimer, type ArmTimer } from "../timer.ts";
 
 /** How long a forwarded prompt waits before it is cancelled. */
 export const PROMPT_TIMEOUT_MS = 180_000;
 
 export interface WechatInteractionDeps {
-	/** Send one text message to the owning peer; `force` bypasses the prompt-active gate. */
+	/** The one peer this channel asks. */
+	peer: string;
+	/** Send one text message to the peer; `force` bypasses the prompt-active gate. */
 	send: (text: string, signal?: AbortSignal, options?: { force?: boolean }) => Promise<boolean>;
-	/** Send a local file to the owning peer; `force` bypasses the prompt-active gate. */
+	/** Send a local file to the peer; `force` bypasses the prompt-active gate. */
 	sendFile: (path: string, name: string, signal?: AbortSignal, options?: { force?: boolean }) => Promise<boolean>;
-	/** The peer that owns the in-flight turn, or undefined when there is none. */
-	activePeer: () => string | undefined;
-	/** The language the owning peer writes in, for the timeout notices. */
+	/** Whether the peer owns a turn right now, so a prompt has somewhere to land. */
+	active: () => boolean;
+	/** The language the peer writes in, for the timeout notices. */
 	language: () => PeerLanguage;
 	/** Arm a cancellable one-shot timer. Defaults to a real, unref'd `setTimeout`. */
 	armTimer?: ArmTimer;
@@ -48,8 +52,8 @@ export interface WechatInteractionChannel extends InteractionChannel {
 	 * previous one when it ends: the optional channel member, made concrete here.
 	 */
 	setPromptTimeout(ms: number): () => void;
-	/** Consume an inbound message as a reply; true when it was one. */
-	handleInbound(peer: string, text: string): boolean;
+	/** Consume an inbound message as a reply to this peer's prompt. */
+	handleInbound(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. */
@@ -73,7 +77,6 @@ export interface PendingPromptInfo {
 
 interface Pending {
 	request: InteractionRequest;
-	peer: string;
 	startedAt: number;
 	resolve: (answer: InteractionAnswer) => void;
 	signal?: AbortSignal;
@@ -92,11 +95,11 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 	 */
 	let scopedTimeoutMs: number | undefined;
 	/**
-	 * Free text captured from a `select` "Other" reply, per peer: the immediately
-	 * following `input` for that peer returns it. Keyed so one peer's free text can
-	 * never become another peer's answer.
+	 * Free text captured from a `select` "Other" reply: the immediately following
+	 * `input` for this peer returns it. One value, because one channel asks one peer
+	 * — another peer's free text cannot reach this channel at all.
 	 */
-	const other = new Map<string, string>();
+	let other: string | undefined;
 
 	function settle(answer: InteractionAnswer): void {
 		const current = pending;
@@ -110,7 +113,7 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 
 	return {
 		isActive(): boolean {
-			return deps.activePeer() !== undefined;
+			return deps.active();
 		},
 
 		language(): PeerLanguage {
@@ -126,7 +129,7 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 			return current === undefined
 				? undefined
 				: {
-						peer: current.peer,
+						peer: deps.peer,
 						kind: current.request.kind,
 						title: current.request.title,
 						startedAt: current.startedAt,
@@ -164,27 +167,24 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 		},
 
 		async request(request: InteractionRequest, signal?: AbortSignal): Promise<InteractionAnswer> {
-			// A `select` that resolved to "Other" stashes its text for that peer; the
-			// immediately following `input` from the same peer returns it without
-			// another round-trip.
-			const asking = deps.activePeer();
-			const stashed = asking === undefined ? undefined : other.get(asking);
-			if (request.kind === "input" && asking !== undefined && stashed !== undefined) {
-				other.delete(asking);
+			// A `select` that resolved to "Other" stashes its text; the immediately
+			// following `input` returns it without another round-trip.
+			const stashed = other;
+			if (request.kind === "input" && stashed !== undefined) {
+				other = undefined;
 				return { kind: "value", value: stashed };
 			}
-			if (request.kind !== "input" && asking !== undefined) other.delete(asking);
+			if (request.kind !== "input") other = undefined;
 
 			if (signal?.aborted || !this.isActive()) return { kind: "cancelled" };
 			if (pending) return { kind: "cancelled" };
 
 			// Register the pending prompt before the send await so a fast reply is
 			// never lost to the round-trip, then send and fail closed.
-			const peer = deps.activePeer() as string;
 			const cancelTimers: Array<() => void> = [];
 			const answer = new Promise<InteractionAnswer>((resolve) => {
 				const onAbort = () => settle({ kind: "cancelled" });
-				pending = { request, peer, startedAt: now(), resolve, signal, onAbort, cancelTimers };
+				pending = { request, 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.
@@ -204,9 +204,9 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 			return await answer;
 		},
 
-		handleInbound(peer: string, text: string): boolean {
+		handleInbound(text: string): boolean {
 			const current = pending;
-			if (!current || current.peer !== peer) return false;
+			if (!current) return false;
 			const parsed = parsePromptAnswer(current.request, text);
 			switch (parsed.kind) {
 				case "retry":
@@ -215,7 +215,7 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 					});
 					return true;
 				case "other":
-					other.set(peer, parsed.text);
+					other = parsed.text;
 					settle({ kind: "value", value: INTERACTION_OTHER_LABEL });
 					return true;
 				case "value":
@@ -231,7 +231,7 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 		},
 
 		reset(): void {
-			other.clear();
+			other = undefined;
 			scopedTimeoutMs = undefined;
 			settle({ kind: "cancelled" });
 		},

package/extensions/wechat/{prompt.ts → dialog/prompt.ts}

@@ -9,8 +9,8 @@
  * the {@link INTERACTION_OTHER_LABEL} option so the caller can collect it once.
  */
 
-import { INTERACTION_OTHER_LABEL, type InteractionRequest } from "../../lib/interaction.ts";
-import { sanitizeInbound, type PeerLanguage } from "./format.ts";
+import { INTERACTION_OTHER_LABEL, type InteractionRequest } from "../../../lib/interaction.ts";
+import { sanitizeInbound, type PeerLanguage } from "../text/format.ts";
 
 /** A parsed reply: a resolved answer, the "other" choice, or a retry. */
 export type PromptParse =

package/extensions/wechat/{remote-ui.ts → dialog/remote-ui.ts}

@@ -24,7 +24,7 @@ import {
 	type InteractionAnswer,
 	type InteractionChannel,
 	type InteractionRequest,
-} from "../../lib/interaction.ts";
+} from "../../../lib/interaction.ts";
 
 function valueOf(answer: InteractionAnswer): string | undefined {
 	return answer.kind === "value" ? answer.value : undefined;

package/extensions/wechat/index.ts

@@ -19,18 +19,18 @@ import { isPidAlive } from "../../lib/spawn.ts";
 import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { createBridge, type Bridge, type BridgeState } from "./bridge.ts";
-import { createFetchRunner, WechatClient, type WechatClientOptions } from "./client.ts";
-import { registerCommands, type CommandDeps } from "./commands.ts";
+import { createFetchRunner, WechatClient, type WechatClientOptions } from "./transport/client.ts";
+import { registerCommands, type CommandDeps } from "./commands/commands.ts";
 import { messageOf } from "./errors.ts";
 import { loadWechatConfig } from "./config.ts";
-import { clearCredentials, primaryAccount, saveAccount, wechatDir } from "./credentials.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";
-import { readPeerHistory } from "./history.ts";
-import { SLASH_COMMANDS } from "./slash.ts";
-import { readState, statePath, writeState } from "./state.ts";
+import { clearCredentials, primaryAccount, saveAccount, wechatDir } from "./state/credentials.ts";
+import { acquireLock, lockPath, readLock, refreshLock, releaseLock } from "./state/lock.ts";
+import { openPeerSession, type PeerSession, type PeerSessionOptions } from "./peer/peer-session.ts";
+import { createPeerUIContext } from "./dialog/remote-ui.ts";
+import { peerKey } from "./text/format.ts";
+import { readPeerHistory } from "./commands/history.ts";
+import { SLASH_COMMANDS } from "./commands/slash.ts";
+import { readState, statePath, writeState } from "./state/state.ts";
 import { registerTools } from "./tools.ts";
 
 /**

package/extensions/wechat/intake.ts

@@ -0,0 +1,245 @@
+/**
+ * Inbound messages: admission, the slash commands a message may carry, and the hand-off to
+ * the sender's own session.
+ *
+ * This is the path a message takes from the poll loop to a turn, and it is the one part of
+ * the bridge that is a *sequence of decisions* rather than wiring: who is refused, what is
+ * a replay, what is a command, what is an answer to a pending prompt, and what is queued or
+ * turned away. The bridge keeps the connection lifecycle and the status snapshot; it hands
+ * this module the live state it reads, and nothing here touches the client or the lock.
+ *
+ * Every dependency whose value changes across a connection is a function, because a
+ * reconnect replaces the account, the state, and the worker rather than mutating them.
+ */
+
+import type { AdmissionQueue, TurnBudget } from "./peer/admission.ts";
+import type { PeerWorker } from "./peer/peer-worker.ts";
+import type { Presence } from "./peer/presence.ts";
+import type { PeerChannels } from "./dialog/channels.ts";
+import { messageOf } from "./errors.ts";
+import { findPeer, recordInbound, rememberMessage, seenMessage } from "./state/state.ts";
+import { parseInbound, peerKey, peerLabel, peerLanguage, type PeerLanguage } from "./text/format.ts";
+import { notice } from "./text/notices.ts";
+import {
+	expandSnippet,
+	findSlashCommand,
+	parseSlash,
+	slashControls,
+	type SlashCommand,
+	type SlashContext,
+} from "./commands/slash.ts";
+import type { BotCredentials, InboundItem, WechatState, WeixinMessage } from "./types.ts";
+import type { MessageTarget } from "./transport/deliver.ts";
+import type { WechatConfig } from "./config.ts";
+
+/**
+ * Whether `peer` may drive the agent: the owner, or an explicit extra. Either id
+ * form is accepted (with or without `@im.wechat`), so a label copied from the
+ * control screen is not silently refused.
+ */
+export function isAllowedPeer(peer: string, owner: string | undefined, allowedPeers: string[]): boolean {
+	const key = peerKey(peer);
+	if (owner !== undefined && peerKey(owner) === key) return true;
+	return allowedPeers.some((allowed) => peerKey(allowed) === key);
+}
+
+/** True when a message is inbound from a human (not the bot's own echo). */
+export function isInboundMessage(message: WeixinMessage): message is WeixinMessage & { from_user_id: string } {
+	return message.message_type !== 2 && typeof message.from_user_id === "string" && message.from_user_id !== "";
+}
+
+/** Inbound messages held while a turn runs; beyond this the peer is told to wait. */
+export const MAX_QUEUE = 8;
+
+/** Senders refused since the connection opened, capped so a spam run cannot fill the list. */
+const REFUSED_LABEL_CAP = 5;
+
+/**
+ * The peer's language: from this text, else the last one they wrote.
+ *
+ * A Chinese message is evidence of Chinese. Its absence is not evidence of English, or a
+ * short reply ("ok", "1") would flip an established conversation back; English is the
+ * fallback, so it needs no record of its own.
+ */
+export function createLanguageOf(languages: Map<string, PeerLanguage>): (peer: string, text?: string) => PeerLanguage {
+	return (peer, text) => {
+		if (text && peerLanguage(text) === "zh") languages.set(peer, "zh");
+		return languages.get(peer) ?? "en";
+	};
+}
+
+/** Drop a peer's cached reply token, so the next inbound message replaces it. */
+export function createForgetToken(deps: {
+	state: () => WechatState;
+	saveState: (state: WechatState) => void;
+}): (peer: string) => void {
+	return (peer) => {
+		const state = deps.state();
+		const entry = findPeer(state, peer);
+		if (!entry?.lastContextToken) return;
+		delete entry.lastContextToken;
+		deps.saveState(state);
+	};
+}
+
+/** A counter two modules share: this one bumps it, the status snapshot reads it. */
+export interface Counter {
+	value: number;
+}
+
+/** Everything the inbound path reads, as the bridge hands it in. */
+export interface IntakeDeps {
+	/** The live state: replaced when a re-login changes the owner. */
+	state: () => WechatState;
+	saveState: (state: WechatState) => void;
+	/** The live account, for the owner a message is compared against. */
+	account: () => BotCredentials | undefined;
+	config: WechatConfig;
+	now: () => number;
+	notify: (message: string, kind?: "info" | "warning" | "error") => void;
+	/** The live worker: a connect or disconnect replaces it. */
+	worker: () => PeerWorker | undefined;
+	channels: PeerChannels;
+	presence: Presence;
+	budget: TurnBudget;
+	admission: AdmissionQueue;
+	languageOf: (peer: string, text?: string) => PeerLanguage;
+	/** Send one bubble to a peer for the bridge's own notices. */
+	reply: (target: MessageTarget, text: string) => Promise<boolean>;
+	readHistory: (peer: string, count: number) => Promise<string>;
+	/** Senders refused since the connection opened, and their labels. */
+	refused: Counter;
+	refusedPeers: Set<string>;
+	/** Peers already told the queue is full, until it drains. */
+	overflow: Set<string>;
+	slashCommands: readonly SlashCommand[];
+}
+
+/**
+ * The inbound path: one function per message, with the command runner and the language
+ * lookup it needs beside it.
+ */
+export function createIntake(deps: IntakeDeps): { handleMessage: (message: WeixinMessage) => void } {
+	const { config, channels, presence, budget, admission, languageOf, notify } = deps;
+
+	/** Run a slash action out-of-band and reply to the sender; never starts a turn. */
+	async function runSlashAction(command: SlashCommand, target: MessageTarget, args: string): Promise<void> {
+		if (!command.run) return;
+		const worker = deps.worker();
+		const ctx: SlashContext = {
+			args,
+			peer: target.peer,
+			reply: async (text) => {
+				await deps.reply(target, text);
+			},
+			activeTurn: worker?.state(target.peer).status === "running",
+			language: languageOf(target.peer),
+			session: slashControls(target.peer, {
+				state: (peer) => worker?.state(peer) ?? { status: "idle", queued: 0 },
+				prompt: (peer) => channels.pendingFor(peer)?.title,
+				reset: (peer) => {
+					worker?.reset(peer);
+				},
+				stop: (peer) => worker?.abort(peer) ?? false,
+				history: (peer, count) => deps.readHistory(peer, count),
+			}),
+		};
+		try {
+			await command.run(ctx);
+		} catch (error) {
+			notify(`WeChat command /${command.name} failed: ${messageOf(error)}`, "warning");
+			await deps.reply(target, `Command /${command.name} failed.`);
+		}
+	}
+
+	function handleMessage(message: WeixinMessage): void {
+		if (!isInboundMessage(message)) return;
+		const state = deps.state();
+		const worker = deps.worker();
+		const peer = message.from_user_id;
+		const { text: rawText, media, unsupported } = parseInbound(message.item_list);
+		const owner = state.ownerId ?? deps.account()?.ilinkUserId;
+		// Admission comes first: a refused sender never reaches the state file, a
+		// pending prompt, or the queue.
+		if (!isAllowedPeer(peer, owner, config.allowedPeers)) {
+			deps.refused.value += 1;
+			const label = peerLabel(peer);
+			// Name a new sender once, so the operator can allowlist it from the
+			// terminal; the cap keeps a spam run from filling the list.
+			if (deps.refusedPeers.size < REFUSED_LABEL_CAP && !deps.refusedPeers.has(label)) {
+				deps.refusedPeers.add(label);
+				notify(`WeChat refused a message from ${label}. Add it to allowedPeers to admit.`, "warning");
+			}
+			return;
+		}
+		// A server replay of an already handled message must not answer twice. The
+		// id is persisted, so a reload or reconnect cannot resurrect it.
+		const messageId = message.message_id;
+		if (typeof messageId === "number" && messageId !== 0 && seenMessage(state, peer, messageId)) return;
+
+		let text = rawText;
+		const cap = config.maxInboundChars;
+		if (text.length > cap) {
+			const total = text.length;
+			text = `${text.slice(0, cap)}\n[WeChat message truncated: showing ${cap} of ${total} characters]`;
+			notify(`WeChat message truncated to ${cap} characters.`, "warning");
+		}
+
+		const now = deps.now();
+		recordInbound(state, peer, message.context_token, now);
+		if (typeof messageId === "number" && messageId !== 0) rememberMessage(state, peer, messageId, now);
+		deps.saveState(state);
+
+		const target = { peer, contextToken: message.context_token ?? findPeer(state, peer)?.lastContextToken };
+		// A command is not an answer: while a dialog waits the model is blocked on it,
+		// so /stop and /status must reach their handlers or the peer's only way out is
+		// the prompt timing out. A message with media is never a command, and an
+		// unknown command falls through to the model as ordinary text.
+		const slash = media.length === 0 ? parseSlash(text) : undefined;
+		const command = slash ? findSlashCommand(deps.slashCommands, slash.name) : undefined;
+		if (command && slash) {
+			if (command.ownerOnly && peerKey(peer) !== peerKey(owner ?? "")) {
+				deps.refused.value += 1;
+				return;
+			}
+			if (command.kind === "snippet") {
+				text = expandSnippet(command, slash.args);
+			} else {
+				void runSlashAction(command, target, slash.args);
+				return;
+			}
+		}
+		// A reply to a pending prompt is consumed here, before queueing, so it never
+		// starts a turn of its own. A duplicate answer was stopped by the id check.
+		if (channels.handleInbound(peer, text)) return;
+		const language = languageOf(peer, text);
+		const item: InboundItem = { ...target, text, media, language };
+		if (!text && media.length === 0) {
+			// Nothing to read. A voice note without a transcript or a video is
+			// answered, so the peer knows it did not reach the agent.
+			if (unsupported > 0) void deps.reply(item, notice("unsupported", language));
+			return;
+		}
+		// A slot is reserved here, before the download, so a burst of media cannot
+		// all pass the check and then enqueue together.
+		if (!budget.allow(peer)) {
+			void deps.reply(item, notice("budget", language));
+			return;
+		}
+		const busy = (worker?.state(peer).queued ?? 0) + admission.pending(peer);
+		if (busy >= MAX_QUEUE) {
+			// Refuse rather than grow without bound; one notice per episode, not per
+			// dropped message.
+			if (!deps.overflow.has(peer)) {
+				deps.overflow.add(peer);
+				void deps.reply(item, notice("overflow", language));
+			}
+			return;
+		}
+		presence.keepTyping(peer, item.contextToken);
+		presence.armAck(item);
+		admission.enqueue(item);
+	}
+
+	return { handleMessage };
+}

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

@@ -8,8 +8,8 @@
  * budget is in memory; a reload starts a fresh hour.
  */
 
-import type { InboundItem } from "./types.ts";
-import { peerKey } from "./format.ts";
+import type { InboundItem } from "../types.ts";
+import { peerKey } from "../text/format.ts";
 
 /** A rolling-hour turn budget per peer. */
 export interface TurnBudget {