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

package/extensions/wechat/README.md

@@ -61,7 +61,9 @@ How the `send_wechat` call and its result look in the transcript — the call li
   can drive the agent; `allowedPeers` opts in others. An entry matches either id
   form (`alice` or `alice@im.wechat`), and a refused sender is named in
   `/wechat status` and in one terminal notice, so the id to allowlist can be
-  copied from either.
+  copied from either. `a` on the control screen or `/wechat allow [peer]` writes
+  one entry into the project config; the running bridge picks it up on the next
+  `/reload` or restart, and the confirmation names the file.
 - **Session-bound** — the bridge runs while an account is stored and the Pi
   process is alive; it starts on `session_start`, and `/wechat logout` clears the
   account and stops it. The peer sessions outlive it on disk.
@@ -74,8 +76,11 @@ 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 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. |
+| `/wechat history <peer> [n]` | Print that peer's recent messages (default 10, max 20); read-only, and works without a live session. |
+| `/wechat allow [peer]` | Add a refused sender to `wechat.allowedPeers` in the project `.pi/bytefly.json`, after a confirmation that names the file. Without an argument it offers the refused senders. |
 | `/wechat logout` | Confirm, then clear credentials, drop the bridge, and stop polling. |
 | `/wechat help` | List the subcommands with a line each. |
 
@@ -98,10 +103,15 @@ one-step recovery.
 
 In the TUI, `/wechat` opens a control screen with the account, connection
 state, owner, per-peer conversation rows (what each peer is doing, how long, and
-what is queued behind it), activity counters, and any pending remote prompt. Keys: `l` log in
-or reconnect, `n` start a new session, `o` log out, `r` refresh, 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.
+what is queued behind it), activity counters, and the waiting remote prompt
+(peer, question, and age).
+`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.
 
 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
@@ -182,7 +192,7 @@ inside the answer it is already waiting for — not with a second “working on
 | Situation | What the peer gets |
 |---|---|
 | 1st message, session idle | typing, then the answer (no acknowledgement: there is nothing to wait for) |
-| 1st message, session busy | typing, `收到，正在处理…` at 4 s, `终端会话正忙…` at 60 s, the answer when the session frees |
+| 1st message, peer busy | typing, `收到，正在处理…` at 4 s, `前面还有一条正在处理…` at 60 s, the answer when the slot frees |
 | 2nd message after the acknowledgement, still queued | nothing new; it is merged into the same turn and the one answer covers both in order |
 | 2nd message while a turn runs | no new acknowledgement; it becomes its own turn and answer after the first |
 | 3rd…Nth in a burst | same as the queued case; past eight queued, one line asking to wait |
@@ -304,6 +314,9 @@ never touches the stored cursor.
 
 ## Troubleshooting
 
+- **First, run `/wechat doctor`.** It prints the connection, token age, last
+  poll, poller lock, per-peer queue/session age, and the last failure, which
+  answers most "why is the bot quiet?" questions in one screen.
 - **`Another Pi session is already polling this WeChat account.`** — one runtime
   owns the account at a time, tracked by `<agent-dir>/wechat/poller.lock`.
   Quit the other `pi` process. A lock left by a process that already exited is
@@ -382,7 +395,7 @@ sessions are in-process).
 
 | Integration point | Detail |
 |---|---|
-| Command | `pi.registerCommand("wechat", …)` — `login`, `new`, `status`, `stop <peer>`, `reset <peer>`, `logout`, `help`; bare `/wechat` opens the control screen. |
+| 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. |
 | 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. |
@@ -465,12 +478,17 @@ status, which is what the old start/stop guidance used to do.
 | File | Responsibility |
 |---|---|
 | `index.ts` | Factory: gate, register the command and tool, wire the lifecycle events, build the bridge, open peer sessions from the host context. |
-| `bridge.ts` | The shared loop: poll, admission, media, typing, notices, reply transport, connection state, abort; hands each message to the peer worker. |
+| `bridge.ts` | The composition root: wires the poll loop, delivery, presence, admission, and inbound modules to the live client/account/cursor/state; owns the connection lifecycle, slash dispatch, the status snapshot, and `sendToOwner`. |
+| `poll.ts` | The long-poll loop: `getupdates`, the watchdog and retry, backoff, cursor persistence, and the expiry stop. |
+| `deliver.ts` | The one outbound text path (reply, dialog preface, `send_wechat`) plus file delivery: flatten, split, number, expiry, rejection, and the once-per-outage notice. |
+| `presence.ts` | Typing, acknowledgement, and the slow/busy lines; all per-peer wait timers in one registry. |
+| `admission.ts` | The rolling-hour turn budget and the per-peer serial admission chain. |
+| `inbound.ts` | Inbound media resolution (download, decrypt, save, attach) and the hand-off to a peer's session. |
 | `peer-session.ts` | One SDK `AgentSession` per peer: workspace, model, history under the state dir, dialogs bound to that peer, this bridge excluded from its resources, and the channel prompt appended. |
 | `channel.ts` | The phone-chat contract appended to a peer session's system prompt. |
 | `peer-worker.ts` | Per-peer queue, one turn at a time (`concurrency`), prompt/abort/reset, streamed reply parts, idle-session sweep. |
 | `reply-pipeline.ts` | Where a streamed answer is split (paragraph, quiet period, size), sent in order, and finished without duplicating a part. |
-| `commands.ts` | `/wechat login|new|status|logout|help`: the verb table that drives the help text and completions, the dispatch, the panel, login, and logout; `login`/`new`/`logout` decline and `status` degrades to the summary while a peer turn runs. |
+| `commands.ts` | `/wechat login|new|status|stop|reset|logout|help`: the verb table that drives the help text and completions, the dispatch, the panel, login/logout, and the per-peer stop/reset; `login`/`new`/`logout` decline and `status` degrades to the summary while a peer turn runs. |
 | `tools.ts` | The `send_wechat` tool (owner-only proactive text). |
 | `client.ts` | iLink HTTP client (QR, getupdates, sendmessage, file sendmessage, getuploadurl, getconfig, sendtyping, CDN download/upload) with an injected runner. |
 | `media.ts` | Media key/encrypt/decrypt, padded size, upload/download URL, MIME sniff, filename sanitize, and save helpers. |
@@ -478,17 +496,21 @@ status, which is what the old start/stop guidance used to do.
 | `login.ts` | QR login state machine. |
 | `qrcode.ts` | QR matrix → Unicode half-block terminal lines. |
 | `login-screen.ts` | The `/wechat login` screen (`ctx.ui.custom`), drawn from the `lib/tui/` kit (`titleRule`, `clip`, `isCloseKey`). |
-| `status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`) and the pure one-line/body renderers, drawn from the `lib/tui/` kit (`titleRule`, `keyValueRow`, `paint`). |
+| `status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`): live facts, a focusable peer list with stop/reset/history keys, and the pure one-line/body renderers, drawn from the `lib/tui/` kit (`titleRule`, `keyValueRow`, `listRow`, `paint`, `IdCursor`). |
 | `config.ts` | The `wechat` section of `bytefly.json` loading and normalization. |
 | `credentials.ts` | `credentials.json` (`0600`, every stored account and the active one). |
 | `state.ts` | `state.json` (cursor, owner, per-peer tokens, recent message ids). |
 | `lock.ts` | Poller lockfile. |
-| `format.ts` | Sanitize, chunk, and label helpers. |
+| `format.ts` | Sanitize, chunk, and label helpers (text only). |
+| `notices.ts` | The peer-facing notice catalog: one line per kind, in the peer's language. |
+| `errors.ts` | `messageOf`, the one error-to-line helper every notice and tool error uses. |
+| `timer.ts` | The timer seam: the cancellable one-shot `ArmTimer`, `defaultTimer`, and the abortable `defaultSleep`. |
 | `interaction.ts` | The WeChat `InteractionChannel`: pending-prompt state machine and reply routing. |
 | `prompt.ts` | Pure prompt formatting and reply parsing. |
 | `remote-ui.ts` | The peer session's UI context: dialogs and notices bound to that peer, the `askHuman` marker that delivers the file/text preface, and the `remotePrompts` switch. |
 | `slash.ts` | Inbound slash commands: the built-in registry (`/new`, `/stop`, `/status`, `/history`, `/help`), the session controls an action may invoke, and the pure parse/lookup/expand helpers. |
 | `history.ts` | Read-only `/history`: opens the peer's newest session, formats the last user/assistant messages, and never writes. |
+| `doctor.ts` | The plain-text `/wechat doctor` report: connection/token age, poll, lock, peer sessions, recent failures, and config. |
 | `types.ts` | Wire and domain types. |
 
 ## Testing

package/extensions/wechat/admission.ts

@@ -0,0 +1,104 @@
+/**
+ * Per-peer admission bookkeeping: the rolling-hour turn budget and the serial
+ * admission chain.
+ *
+ * A burst of media messages must keep its arrival order and count against the
+ * queue cap before its download completes, so a slot is reserved when the
+ * message is accepted and each peer's admissions run one after another. The
+ * budget is in memory; a reload starts a fresh hour.
+ */
+
+import type { InboundItem } from "./types.ts";
+import { peerKey } from "./format.ts";
+
+/** A rolling-hour turn budget per peer. */
+export interface TurnBudget {
+	/** Reserve a turn; false when the peer has used its hourly allowance. */
+	allow(peer: string): boolean;
+	/** Drop every counter (a new connection). */
+	reset(): void;
+}
+
+export function createTurnBudget(limit: number, now: () => number): TurnBudget {
+	const turnTimes = new Map<string, number[]>();
+	return {
+		allow(peer: string): boolean {
+			if (limit <= 0) return true;
+			const key = peerKey(peer);
+			const at = now();
+			const cutoff = at - 60 * 60 * 1000;
+			const times = (turnTimes.get(key) ?? []).filter((entry) => entry >= cutoff);
+			if (times.length >= limit) {
+				turnTimes.set(key, times);
+				return false;
+			}
+			times.push(at);
+			turnTimes.set(key, times);
+			return true;
+		},
+		reset(): void {
+			turnTimes.clear();
+		},
+	};
+}
+
+export interface AdmissionQueueDeps {
+	/** Resolve media and hand the message to the peer's session. */
+	admit: (item: InboundItem) => Promise<void>;
+	/** A message that could not be admitted at all. */
+	notify: (message: string, kind?: "info" | "warning" | "error") => void;
+}
+
+/** The per-peer serial admission chain. */
+export interface AdmissionQueue {
+	/** Reserve a slot and admit in arrival order. */
+	enqueue(item: InboundItem): void;
+	/** Slots reserved but not yet queued (downloads in flight). */
+	pending(peer: string): number;
+	/** Drop the bookkeeping (a new connection). */
+	reset(): void;
+}
+
+export function createAdmissionQueue(deps: AdmissionQueueDeps): AdmissionQueue {
+	/** Messages being resolved (media download) before they reach the queue. */
+	const admitting = new Map<string, number>();
+	/** Per-peer admission chain, so two media messages keep their arrival order. */
+	const chains = new Map<string, Promise<void>>();
+
+	return {
+		enqueue(item: InboundItem): void {
+			const peer = item.peer;
+			admitting.set(peer, (admitting.get(peer) ?? 0) + 1);
+			const previous = chains.get(peer) ?? Promise.resolve();
+			const next = previous
+				.then(async () => {
+					await deps.admit(item);
+				})
+				.catch((error) => {
+					// One bad admission must not stall the peer's chain forever.
+					deps.notify(
+						`WeChat could not accept a message: ${error instanceof Error ? error.message : String(error)}`,
+						"warning",
+					);
+				})
+				.finally(() => {
+					const left = (admitting.get(peer) ?? 1) - 1;
+					if (left > 0) admitting.set(peer, left);
+					else admitting.delete(peer);
+				});
+			chains.set(peer, next);
+			void next.finally(() => {
+				if (chains.get(peer) === next) chains.delete(peer);
+			});
+		},
+
+		pending(peer: string): number {
+			return admitting.get(peer) ?? 0;
+		},
+
+		reset(): void {
+			admitting.clear();
+			chains.clear();
+		},
+	};
+}