dsh-qqbot 1.0.0

package/lib/index.js

@@ -0,0 +1,811 @@
+import Schema from "@deepseek-ai/schemastery";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+//#region lib/types/protocol.js
+/**
+* Pure QQ official bot protocol helpers: gateway opcodes, event intents,
+* REST endpoints, access-token and gateway URL fetches, inbound dispatch
+* parsing, and outbound text chunking. Everything here is I/O- and timer-free
+* except the two `fetch` wrappers, so the rest is unit-testable directly.
+* @module @deepseek-ai/dsh-qqbot/protocol
+*/
+/** Gateway opcodes from the QQ official bot WebSocket protocol. */
+const QQ_OP = {
+	DISPATCH: 0,
+	HEARTBEAT: 1,
+	IDENTIFY: 2,
+	RESUME: 6,
+	RECONNECT: 7,
+	INVALID_SESSION: 9,
+	HELLO: 10,
+	HEARTBEAT_ACK: 11
+};
+/**
+* Intent bit for group @-mention and C2C private-message events. The single
+* `1 << 25` (`GROUP_AND_C2C_EVENT`) intent delivers both, so the bridge
+* subscribes to it and nothing else.
+*/
+const QQ_INTENT_GROUP_AND_C2C = 1 << 25;
+/** Access-token mint endpoint; independent of the sandbox selection. */
+const QQ_TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
+const API_HOST = "https://api.sgroup.qq.com";
+const SANDBOX_HOST = "https://sandbox.api.sgroup.qq.com";
+/** Default access-token TTL (seconds) when the response omits `expires_in`. */
+const DEFAULT_EXPIRES_IN_SECONDS = 7200;
+/** Default outbound chunk length in UTF-16 code units. */
+const QQ_MAX_MESSAGE_LENGTH = 2e3;
+/**
+* Resolve the REST API base for the selected environment.
+* @param sandbox - whether the sandbox host is in use.
+* @returns the `https://api.sgroup.qq.com` or sandbox equivalent origin.
+*/
+function apiBase(sandbox) {
+	return sandbox ? SANDBOX_HOST : API_HOST;
+}
+/**
+* REST path for sending a message to a group.
+* @param groupOpenid - the target group's openid.
+* @returns the `/v2/groups/{groupOpenid}/messages` path.
+*/
+function groupMessagesPath(groupOpenid) {
+	return `/v2/groups/${groupOpenid}/messages`;
+}
+/**
+* REST path for sending a private message to a user.
+* @param userOpenid - the target user's openid.
+* @returns the `/v2/users/{userOpenid}/messages` path.
+*/
+function c2cMessagesPath(userOpenid) {
+	return `/v2/users/${userOpenid}/messages`;
+}
+/**
+* Mint an access token from the robot app id and secret.
+* @param creds - the robot credentials.
+* @param fetchImpl - injectable fetch (defaults to the global).
+* @param now - injectable epoch-ms clock (defaults to `Date.now`).
+* @returns the token with its absolute expiry.
+*/
+async function fetchAccessToken(creds, fetchImpl = fetch, now = Date.now) {
+	const response = await fetchImpl(QQ_TOKEN_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			appId: creds.appId,
+			clientSecret: creds.appSecret
+		})
+	});
+	if (!response.ok) throw new Error(`qqbot: token request failed (HTTP ${response.status})`);
+	const data = await response.json();
+	if (typeof data.access_token !== "string" || data.access_token.length === 0) throw new Error("qqbot: token response missing access_token");
+	const expiresIn = typeof data.expires_in === "number" ? data.expires_in : DEFAULT_EXPIRES_IN_SECONDS;
+	return {
+		accessToken: data.access_token,
+		expiresAt: now() + expiresIn * 1e3
+	};
+}
+/**
+* Resolve the WebSocket gateway URL for the selected environment.
+* @param accessToken - the current access token.
+* @param sandbox - whether the sandbox host is in use.
+* @param fetchImpl - injectable fetch (defaults to the global).
+* @returns the gateway WebSocket URL.
+*/
+async function fetchGatewayUrl(accessToken, sandbox, fetchImpl = fetch) {
+	const response = await fetchImpl(`${apiBase(sandbox)}/gateway`, { headers: { Authorization: `QQBot ${accessToken}` } });
+	if (!response.ok) throw new Error(`qqbot: gateway request failed (HTTP ${response.status})`);
+	const data = await response.json();
+	if (typeof data.url !== "string" || data.url.length === 0) throw new Error("qqbot: gateway response missing url");
+	return data.url;
+}
+/**
+* Parse one gateway text frame into its opcode and the fields that op carries.
+* @param raw - the frame payload (expected to be a JSON string).
+* @returns the parsed message, or `undefined` for non-text or malformed frames.
+*/
+function parseRawGatewayMessage(raw) {
+	if (typeof raw !== "string") return void 0;
+	let payload;
+	try {
+		payload = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (payload === null || typeof payload !== "object") return void 0;
+	const record = payload;
+	const op = record["op"];
+	if (typeof op !== "number") return void 0;
+	const data = record["d"];
+	if (op === QQ_OP.DISPATCH) {
+		const type = record["t"];
+		const seq = record["s"];
+		return {
+			op,
+			...typeof type === "string" ? { type } : {},
+			...typeof seq === "number" ? { seq } : {},
+			data
+		};
+	}
+	if (op === QQ_OP.HELLO && data !== null && typeof data === "object") {
+		const interval = data["heartbeat_interval"];
+		return {
+			op,
+			...typeof interval === "number" ? { heartbeatInterval: interval } : {}
+		};
+	}
+	return { op };
+}
+/**
+* Narrow a dispatch event to an answerable {@link QqMessage}. Group events
+* require a `group_openid`; C2C events require an `author.user_openid`. Other
+* event types (READY, RESUMED, and every non-message event) return `undefined`.
+* @param type - the dispatch event type (`t`).
+* @param data - the dispatch payload (`d`).
+* @returns the normalized message, or `undefined` when the event is not answerable.
+*/
+function parseMessageEvent(type, data) {
+	if (data === null || typeof data !== "object") return void 0;
+	const record = data;
+	const id = record["id"];
+	const content = record["content"];
+	const authorRaw = record["author"];
+	if (typeof id !== "string" || typeof content !== "string") return void 0;
+	const author = authorRaw !== null && typeof authorRaw === "object" ? authorRaw : {};
+	const authorBlock = {
+		...typeof author["id"] === "string" ? { id: author["id"] } : {},
+		...typeof author["user_openid"] === "string" ? { userOpenid: author["user_openid"] } : {},
+		...typeof author["member_openid"] === "string" ? { memberOpenid: author["member_openid"] } : {},
+		...typeof author["username"] === "string" ? { username: author["username"] } : {}
+	};
+	if (type === "GROUP_AT_MESSAGE_CREATE") {
+		const groupOpenid = record["group_openid"];
+		if (typeof groupOpenid !== "string" || groupOpenid.length === 0) return void 0;
+		return {
+			kind: "group",
+			id,
+			content,
+			author: authorBlock,
+			groupOpenid
+		};
+	}
+	if (type === "C2C_MESSAGE_CREATE") {
+		const userOpenid = author["user_openid"];
+		if (typeof userOpenid !== "string" || userOpenid.length === 0) return void 0;
+		return {
+			kind: "c2c",
+			id,
+			content,
+			author: authorBlock,
+			userOpenid
+		};
+	}
+}
+/**
+* Strip QQ mention tags from group message text. The platform may deliver
+* `<@!12345>` or `<@OPENID>`; both are removed so only the user's words remain.
+* @param text - the raw group message content.
+* @returns the text with mentions removed and surrounding whitespace trimmed.
+*/
+function stripMentions(text) {
+	return text.replace(/<@[^>]{1,64}>/g, "").trim();
+}
+/**
+* Split outbound text into chunks no longer than `max` UTF-16 code units.
+* An empty input yields no chunks (nothing to send).
+* @param text - the reply text.
+* @param max - the per-chunk ceiling.
+* @returns zero or more bounded chunks.
+*/
+function splitMessage(text, max = QQ_MAX_MESSAGE_LENGTH) {
+	if (text.length === 0) return [];
+	if (text.length <= max) return [text];
+	const chunks = [];
+	for (let index = 0; index < text.length; index += max) chunks.push(text.slice(index, index + max));
+	return chunks;
+}
+/**
+* Build the ordered request bodies for one reply. The first chunk carries the
+* triggering `msg_id` so the platform renders it as a reply; subsequent chunks
+* share it with an increasing `msg_seq`, streaming the multi-chunk reply.
+* @param text - the reply text.
+* @param msgId - the inbound message id being answered, when known.
+* @returns the ordered request bodies, or an empty array for empty text.
+*/
+function buildSendPayloads(text, msgId) {
+	return splitMessage(text).map((chunk, index) => {
+		const body = {
+			content: chunk,
+			msg_type: 0
+		};
+		if (msgId !== void 0 && msgId.length > 0) {
+			body["msg_id"] = msgId;
+			body["msg_seq"] = index + 1;
+		}
+		return body;
+	});
+}
+//#endregion
+//#region lib/types/gateway.js
+/**
+* QQ official bot gateway client: token refresh, WebSocket connection,
+* heartbeat, reconnect, inbound dispatch, and outbound message sending.
+* The socket and fetch implementations are injectable so tests can drive the
+* state machine without a live platform.
+* @module @deepseek-ai/dsh-qqbot/gateway
+*/
+const DEFAULT_TOKEN_MARGIN_MS = 6e4;
+const DEFAULT_MAX_RECONNECT_DELAY_MS = 3e4;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 45e3;
+const MIN_HEARTBEAT_INTERVAL_MS = 5e3;
+/**
+* Long-lived connection to the QQ gateway. `start()` connects once; a drop
+* after READY schedules an exponential-backoff reconnect. The client owns the
+* access token and exposes {@link sendText} for reply delivery.
+*/
+var QqGatewayClient = class {
+	creds;
+	sandbox;
+	onMessage;
+	logger;
+	fetchImpl;
+	socketFactory;
+	tokenMarginMs;
+	maxReconnectDelayMs;
+	now;
+	accessToken;
+	tokenExpiresAt = 0;
+	socket;
+	heartbeatTimer;
+	reconnectTimer;
+	seq = 0;
+	reconnectAttempts = 0;
+	closed = false;
+	constructor(options) {
+		this.creds = options.creds;
+		this.sandbox = options.sandbox;
+		this.onMessage = options.onMessage;
+		this.logger = options.logger ?? { warn: () => {} };
+		this.fetchImpl = options.fetchImpl ?? fetch;
+		this.socketFactory = options.socketFactory ?? ((url) => new WebSocket(url));
+		this.tokenMarginMs = options.tokenMarginMs ?? DEFAULT_TOKEN_MARGIN_MS;
+		this.maxReconnectDelayMs = options.maxReconnectDelayMs ?? DEFAULT_MAX_RECONNECT_DELAY_MS;
+		this.now = options.now ?? Date.now;
+	}
+	/**
+	* Return a usable access token, refreshing it when absent or near expiry.
+	* @returns the current access token.
+	*/
+	async ensureToken() {
+		if (this.accessToken !== void 0 && this.tokenExpiresAt - this.now() > this.tokenMarginMs) return this.accessToken;
+		const token = await fetchAccessToken(this.creds, this.fetchImpl, this.now);
+		this.accessToken = token.accessToken;
+		this.tokenExpiresAt = token.expiresAt;
+		return token.accessToken;
+	}
+	/** Connect (and, on a later drop, reconnect) to the gateway. */
+	async start() {
+		if (this.closed) return;
+		try {
+			await this.connectOnce();
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			this.logger.warn(`qqbot: connect failed: ${detail}`);
+			this.scheduleReconnect();
+		}
+	}
+	/**
+	* Permanently close the client: stop timers, cancel reconnects, and close
+	* the live socket. Idempotent.
+	*/
+	close() {
+		this.closed = true;
+		this.stopHeartbeat();
+		if (this.reconnectTimer !== void 0) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = void 0;
+		}
+		const socket = this.socket;
+		this.socket = void 0;
+		if (socket !== void 0) socket.close(1e3);
+	}
+	/**
+	* Deliver one reply to a chat. Chunks the text to the platform limit and
+	* posts each chunk with the triggering message id threaded as a reply.
+	* @param path - the REST path from {@link groupMessagesPath} or {@link c2cMessagesPath}.
+	* @param text - the reply text.
+	* @param msgId - the inbound message id being answered.
+	*/
+	async sendText(path, text, msgId) {
+		const token = await this.ensureToken();
+		const base = apiBase(this.sandbox);
+		for (const body of buildSendPayloads(text, msgId)) {
+			const response = await this.fetchImpl(`${base}${path}`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: `QQBot ${token}`
+				},
+				body: JSON.stringify(body)
+			});
+			if (!response.ok) {
+				const detail = await response.text().catch(() => "");
+				throw new Error(`qqbot: send failed (HTTP ${response.status}): ${detail}`);
+			}
+		}
+	}
+	/** Mint a token, resolve the gateway URL, and complete one socket session. */
+	async connectOnce() {
+		const token = await this.ensureToken();
+		const url = await fetchGatewayUrl(token, this.sandbox, this.fetchImpl);
+		await this.openSocket(url, token);
+	}
+	/** Open the socket and resolve once READY (or RESUME) arrives. */
+	openSocket(url, token) {
+		return new Promise((resolve, reject) => {
+			const socket = this.socketFactory(url);
+			this.socket = socket;
+			let ready = false;
+			socket.onopen = () => {
+				this.logger.debug?.(`qqbot: socket open ${url}`);
+			};
+			socket.onmessage = (event) => {
+				const message = parseRawGatewayMessage(event.data);
+				if (message === void 0) return;
+				switch (message.op) {
+					case QQ_OP.HELLO:
+						this.startHeartbeat(message.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL_MS);
+						socket.send(JSON.stringify({
+							op: QQ_OP.IDENTIFY,
+							d: {
+								token: `QQBot ${token}`,
+								intents: QQ_INTENT_GROUP_AND_C2C,
+								shard: [0, 1]
+							}
+						}));
+						break;
+					case QQ_OP.DISPATCH:
+						if (message.seq !== void 0) this.seq = message.seq;
+						if (message.type === "READY" || message.type === "RESUMED") {
+							ready = true;
+							this.reconnectAttempts = 0;
+							resolve();
+						} else if (message.type !== void 0) {
+							const inbound = parseMessageEvent(message.type, message.data);
+							if (inbound !== void 0) this.onMessage(inbound);
+						}
+						break;
+					case QQ_OP.HEARTBEAT_ACK: break;
+					case QQ_OP.RECONNECT:
+					case QQ_OP.INVALID_SESSION:
+						this.logger.warn("qqbot: gateway requested reconnect");
+						socket.close(4e3);
+				}
+			};
+			socket.onerror = (error) => {
+				const detail = error instanceof Error ? error.message : String(error);
+				this.logger.warn(`qqbot: socket error: ${detail}`);
+			};
+			socket.onclose = (event) => {
+				this.stopHeartbeat();
+				if (this.socket !== socket) return;
+				this.socket = void 0;
+				if (!ready) reject(/* @__PURE__ */ new Error(`qqbot: socket closed before READY (code=${event.code ?? "unknown"})`));
+				else if (!this.closed) this.scheduleReconnect();
+			};
+		});
+	}
+	/** Start the heartbeat interval, replacing any previous one. */
+	startHeartbeat(intervalMs) {
+		this.stopHeartbeat();
+		const interval = Math.max(intervalMs, MIN_HEARTBEAT_INTERVAL_MS);
+		this.heartbeatTimer = setInterval(() => {
+			const socket = this.socket;
+			if (socket === void 0) return;
+			socket.send(JSON.stringify({
+				op: QQ_OP.HEARTBEAT,
+				d: this.seq
+			}));
+		}, interval);
+	}
+	stopHeartbeat() {
+		if (this.heartbeatTimer !== void 0) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = void 0;
+		}
+	}
+	/** Schedule one reconnect attempt with exponential backoff. */
+	scheduleReconnect() {
+		if (this.closed || this.reconnectTimer !== void 0) return;
+		const exponent = Math.min(this.reconnectAttempts, 5);
+		const delay = Math.min(1e3 * 2 ** exponent, this.maxReconnectDelayMs);
+		this.reconnectAttempts += 1;
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = void 0;
+			this.start();
+		}, delay);
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* QQ official bot bridge for DeepSeek Harness.
+*
+* Answers @-mentions in group chat and private C2C messages by routing them
+* into one harness session the user selects from the conversation window. The
+* `/qqbot on` command binds the dispatching agent (its context and cwd) to the
+* QQ gateway; `/qqbot off` disconnects. Nothing connects until a session opts
+* in, and QQ messages then arrive as ordinary user messages on that agent.
+*
+* The robot identity (AppID/AppSecret) lives in the `qqbot` settings section —
+* the Settings → QQ Bot page of the web GUI — with the composition entry as
+* the base layer and `QQBOT_APP_ID`/`QQBOT_APP_SECRET` as an environment
+* fallback. Committed settings changes restart a live gateway in place.
+*
+* The bridge is also an approval answerer for its bound agent: a tool call that
+* asks for confirmation is forwarded to the originating QQ chat as a prompt,
+* and the user's "允许" / "拒绝" reply settles the request.
+*
+* @module dsh-qqbot
+*/
+const name = "qqbot";
+/** The bridge binds the session's existing agent; commands and session events drive it. */
+const inject = ["agents", "commands"];
+/** Plugin config: robot identity plus the API environment selection. */
+const Config = Schema.object({
+	appId: Schema.string(),
+	appSecret: Schema.string().role("secret"),
+	sandbox: Schema.boolean()
+});
+/** Environment variable fallback for the robot application id. */
+const QQBOT_APP_ID_ENV = "QQBOT_APP_ID";
+/** Environment variable fallback for the robot application secret. */
+const QQBOT_APP_SECRET_ENV = "QQBOT_APP_SECRET";
+/** Settings namespace carrying the robot identity (Settings → QQ Bot). */
+const QQBOT_SETTINGS_NAMESPACE = settingsNamespace("qqbot");
+/** Prompt section name registered on the bound agent's scope. */
+const QQBOT_CHANNEL_SECTION = "qqbot:channel";
+/** Prompt section order: after the persona, before tool guidance. */
+const QQBOT_CHANNEL_ORDER = 10;
+/**
+* The QQ-channel instructions, registered verbatim on the bound agent while a
+* session is connected. Kept as a literal export so the README and tests quote
+* the exact text.
+*/
+const QQBOT_CHANNEL_PROMPT = [
+	"你正在通过 QQ 与用户交流，消息可能来自私聊或群聊（群聊中用户会 @你）。",
+	"",
+	"请遵守以下约定：",
+	"- 默认使用与用户相同的语言回复，中文用户请使用简体中文。",
+	"- 回复简洁自然、直奔主题，单条控制在 2000 字以内；更长的内容会被自动分段发送。",
+	"- 可以使用 Markdown（加粗、行内代码、代码块、列表），但避免复杂表格和深层嵌套。",
+	"- 群聊消息以 `[昵称]: 内容` 的形式出现，直接回答该用户的问题，不要评论格式本身。",
+	"- 不要主动提及你通过 QQ 接入、底层模型或平台，除非用户直接询问。"
+].join("\n");
+/** The plugin's channel section, built from the exported literals. */
+const channelSection = {
+	name: QQBOT_CHANNEL_SECTION,
+	order: 10,
+	text: QQBOT_CHANNEL_PROMPT
+};
+/** Whole-answer words accepted as an approval grant. */
+const ALLOW_ANSWERS = /* @__PURE__ */ new Set([
+	"允许",
+	"允许执行",
+	"同意",
+	"可以",
+	"是",
+	"确认",
+	"y",
+	"yes",
+	"ok",
+	"allow",
+	"accept",
+	"1"
+]);
+/** Whole-answer words accepted as an approval rejection. */
+const REJECT_ANSWERS = /* @__PURE__ */ new Set([
+	"拒绝",
+	"不同意",
+	"禁止",
+	"否",
+	"取消",
+	"n",
+	"no",
+	"deny",
+	"reject",
+	"0"
+]);
+/**
+* Parse an inbound QQ reply into an approval decision, or leave it undefined
+* when it is not an answer. Matches the whole normalized text, then its first
+* whitespace/punctuation-delimited token ("允许。" → allow, "同意 执行" → allow).
+* @param text - the raw inbound message content.
+* @returns the decision, or undefined when the text is not an answer.
+*/
+function parseAnswer(text) {
+	const normalized = stripMentions(text).trim().toLowerCase();
+	if (normalized.length === 0) return void 0;
+	if (ALLOW_ANSWERS.has(normalized)) return "allowed-once";
+	if (REJECT_ANSWERS.has(normalized)) return "rejected";
+	const first = normalized.split(/[\s,，。.!！?？、:：;；/]+/u)[0] ?? "";
+	if (ALLOW_ANSWERS.has(first)) return "allowed-once";
+	if (REJECT_ANSWERS.has(first)) return "rejected";
+}
+/**
+* Resolve robot credentials from a config section, then environment, then
+* fail loud.
+* @param config - the validated section (settings-resolved or composition entry).
+* @returns the concrete credentials.
+*/
+function resolveCredentials(config) {
+	const appId = config.appId ?? process.env["QQBOT_APP_ID"];
+	const appSecret = config.appSecret ?? process.env["QQBOT_APP_SECRET"];
+	if (appId === void 0 || appId.length === 0 || appSecret === void 0 || appSecret.length === 0) throw new Error(`qqbot: appId and appSecret are required; set them in Settings → QQ Bot, or export ${QQBOT_APP_ID_ENV}/${QQBOT_APP_SECRET_ENV}`);
+	return {
+		appId,
+		appSecret
+	};
+}
+/**
+* Mount the QQ bot bridge. It registers the `/qqbot` command and connects the
+* gateway only when a session runs `/qqbot on`; the bound agent's own scope,
+* history, and cwd are reused unchanged. While bound, it also answers that
+* agent's approval requests through the originating QQ chat.
+* @param ctx - Cordis context carrying the agent registry, commands, and session events.
+* @param config - composition entry; the user layer of the `qqbot` settings
+*   namespace resolves over it once a settings provider is mounted.
+*/
+function apply(ctx, config) {
+	const logger = ctx.logger;
+	let readSection = () => config;
+	let boundAgent;
+	let boundSectionDispose;
+	let gateway;
+	let gatewaySettings;
+	const originByMessage = /* @__PURE__ */ new Map();
+	const originByTurn = /* @__PURE__ */ new Map();
+	const replyText = /* @__PURE__ */ new Map();
+	let currentOrigin;
+	let pendingApproval;
+	/** Resolve the identity the bridge uses right now, or throw for the caller. */
+	function resolveCurrentCredentials() {
+		return resolveCredentials(readSection());
+	}
+	/** Resolve the reply path for one inbound message. */
+	function replyPathOf(message) {
+		if (message.kind === "c2c") return c2cMessagesPath(message.userOpenid);
+		return groupMessagesPath(message.groupOpenid);
+	}
+	/** Normalize inbound content into the model-visible user text, or drop it. */
+	function toUserText(message) {
+		const trimmed = message.content.trim();
+		if (message.kind === "group") {
+			const cleaned = stripMentions(trimmed);
+			if (cleaned.length === 0) return "";
+			return `[${message.author.username ?? message.author.id ?? "QQ 用户"}]: ${cleaned}`;
+		}
+		return trimmed;
+	}
+	/** Route one inbound message into the bound agent, recording its reply origin. */
+	function routeMessage(message) {
+		const pending = pendingApproval;
+		if (pending !== void 0) {
+			const answer = parseAnswer(message.content);
+			if (answer !== void 0) pending.settle(answer);
+			return;
+		}
+		const agent = boundAgent;
+		if (agent === void 0) return;
+		const text = toUserText(message);
+		if (text.length === 0) return;
+		const userMessage = createUserMessage({
+			content: [{
+				type: "text",
+				text
+			}],
+			source: { kind: "user" }
+		});
+		originByMessage.set(userMessage.id, {
+			replyPath: replyPathOf(message),
+			msgId: message.id
+		});
+		agent.followup(userMessage);
+	}
+	/** Connect the gateway for the first bound session, or reuse the live one. */
+	function ensureGateway() {
+		if (gateway === void 0) {
+			const creds = resolveCurrentCredentials();
+			gatewaySettings = {
+				appId: creds.appId,
+				appSecret: creds.appSecret,
+				sandbox: readSection().sandbox === true
+			};
+			gateway = new QqGatewayClient({
+				creds: {
+					appId: creds.appId,
+					appSecret: creds.appSecret
+				},
+				sandbox: gatewaySettings.sandbox,
+				logger,
+				onMessage: (message) => {
+					routeMessage(message);
+				}
+			});
+		}
+		return gateway;
+	}
+	/** Bind a session: register its channel section, then connect the gateway. */
+	function bind(agent) {
+		try {
+			resolveCurrentCredentials();
+		} catch (_missingCredentials) {
+			return `QQ bot credentials are not configured. Set AppID/AppSecret in Settings → QQ Bot, or export ${QQBOT_APP_ID_ENV}/${QQBOT_APP_SECRET_ENV}.`;
+		}
+		boundAgent = agent;
+		boundSectionDispose = agent.ctx.systemPrompt.section(channelSection);
+		ensureGateway().start().catch((error) => {
+			const detail = error instanceof Error ? error.message : String(error);
+			logger.warn(`qqbot: gateway start failed: ${detail}`);
+		});
+		return null;
+	}
+	/**
+	* Re-evaluate the settings section against the live gateway: removed
+	* credentials close it; a changed identity or sandbox flag restarts it with
+	* the new values, keeping the binding.
+	*/
+	function rejudgeSettings() {
+		const active = gateway;
+		if (active === void 0) return;
+		let creds;
+		try {
+			creds = resolveCurrentCredentials();
+		} catch (_missingCredentials) {
+			logger.warn("qqbot: credentials removed while connected; gateway closed");
+			active.close();
+			gateway = void 0;
+			gatewaySettings = void 0;
+			return;
+		}
+		const sandbox = readSection().sandbox === true;
+		const current = gatewaySettings;
+		if (current !== void 0 && current.appId === creds.appId && current.appSecret === creds.appSecret && current.sandbox === sandbox) return;
+		active.close();
+		gateway = void 0;
+		gatewaySettings = void 0;
+		if (boundAgent === void 0) return;
+		ensureGateway().start().catch((error) => {
+			const detail = error instanceof Error ? error.message : String(error);
+			logger.warn(`qqbot: gateway restart failed: ${detail}`);
+		});
+	}
+	/** Disconnect and drop the binding, unwinding the scoped section. */
+	function unbind() {
+		if (pendingApproval !== void 0) pendingApproval.settle("cancelled");
+		boundAgent = void 0;
+		if (boundSectionDispose !== void 0) {
+			boundSectionDispose();
+			boundSectionDispose = void 0;
+		}
+		originByMessage.clear();
+		originByTurn.clear();
+		replyText.clear();
+		currentOrigin = void 0;
+		if (gateway !== void 0) {
+			gateway.close();
+			gateway = void 0;
+		}
+		gatewaySettings = void 0;
+	}
+	/** Forward one approval to the originating QQ chat and await the user's answer. */
+	function forwardApproval(req, origin) {
+		const current = gateway;
+		if (current === void 0) return Promise.resolve("unavailable");
+		const reason = req.reason ?? "";
+		const prompt = reason.length > 0 ? `[审批] 工具 \`${req.toolName}\`（${reason}）请求执行。回复「允许」或「拒绝」。` : `[审批] 工具 \`${req.toolName}\` 请求执行。回复「允许」或「拒绝」。`;
+		return new Promise((resolve) => {
+			let settled = false;
+			const settle = (outcome) => {
+				if (settled) return;
+				settled = true;
+				pendingApproval = void 0;
+				req.signal?.removeEventListener("abort", onAbort);
+				resolve(outcome);
+			};
+			const onAbort = () => {
+				settle("cancelled");
+			};
+			pendingApproval = { settle };
+			req.signal?.addEventListener("abort", onAbort, { once: true });
+			current.sendText(origin.replyPath, prompt, origin.msgId).catch(() => {
+				settle("unavailable");
+			});
+		});
+	}
+	ctx.on("agent/inbox/claimed", ({ agent, message, turn }) => {
+		if (agent !== boundAgent) return;
+		const origin = originByMessage.get(message.id);
+		if (origin !== void 0) {
+			originByTurn.set(turn, origin);
+			currentOrigin = origin;
+		}
+	});
+	ctx.on("session/event", (session, event) => {
+		const agent = boundAgent;
+		if (agent === void 0 || session !== agent.session) return;
+		if (event.type === "assistant/message") {
+			const text = event.data.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+			replyText.set(event.data.turn, text);
+		} else if (event.type === "turn/end") {
+			currentOrigin = void 0;
+			const origin = originByTurn.get(event.data.turn);
+			const text = replyText.get(event.data.turn);
+			originByTurn.delete(event.data.turn);
+			replyText.delete(event.data.turn);
+			if (origin === void 0 || text === void 0 || text.trim().length === 0) return;
+			const current = gateway;
+			if (current === void 0) return;
+			current.sendText(origin.replyPath, text, origin.msgId).catch((error) => {
+				const detail = error instanceof Error ? error.message : String(error);
+				logger.warn(`qqbot: reply failed: ${detail}`);
+			});
+		}
+	});
+	ctx.on("approval/request", (req, next) => {
+		if (req.agent !== boundAgent) return next();
+		const origin = currentOrigin;
+		if (origin === void 0) return next();
+		return forwardApproval(req, origin);
+	}, { prepend: true });
+	ctx.on("agent/disposed", ({ agent }) => {
+		if (agent !== boundAgent) return;
+		if (pendingApproval !== void 0) pendingApproval.settle("unavailable");
+		boundAgent = void 0;
+		boundSectionDispose = void 0;
+		originByMessage.clear();
+		originByTurn.clear();
+		replyText.clear();
+		currentOrigin = void 0;
+	});
+	ctx.commands.register({
+		name: "qqbot",
+		description: "Connect or disconnect the QQ official bot for this session (/qqbot on | off)",
+		handler: (invocation) => {
+			const input = invocation.rawInput.trim();
+			if (input === "on") {
+				const failure = bind(invocation.agent);
+				if (failure !== null) return {
+					kind: "error",
+					text: failure
+				};
+				return {
+					kind: "success",
+					text: "QQ bot connected; this session now answers QQ messages."
+				};
+			}
+			if (input === "off") {
+				unbind();
+				return {
+					kind: "success",
+					text: "QQ bot disconnected."
+				};
+			}
+			return {
+				kind: "error",
+				text: "usage: /qqbot on | /qqbot off"
+			};
+		}
+	});
+	installSettingsSection(ctx, QQBOT_SETTINGS_NAMESPACE, Config, config, {
+		setSource: (current) => {
+			readSection = current;
+		},
+		onChange: () => {
+			rejudgeSettings();
+		}
+	});
+	ctx.effect(() => () => {
+		unbind();
+	}, "qqbot");
+}
+//#endregion
+export { Config, QQBOT_APP_ID_ENV, QQBOT_APP_SECRET_ENV, QQBOT_CHANNEL_ORDER, QQBOT_CHANNEL_PROMPT, QQBOT_CHANNEL_SECTION, QQBOT_SETTINGS_NAMESPACE, apply, inject, name, parseAnswer };