dsh-deeppilot 0.9.14 → 0.9.16

package/lib/index.js

@@ -3,6 +3,7 @@ import { X509Certificate, createHash, createPrivateKey, createPublicKey, randomB
 import { access, appendFile, chmod, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { WebSocketServer } from "ws";
+import { deflateRawSync } from "node:zlib";
 import { homedir, networkInterfaces } from "node:os";
 import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import z from "@deepseek-ai/schemastery";
@@ -292,6 +293,23 @@ function sanitizeImageName(value) {
 function sanitizeDocumentField(value, maxChars) {
 	return value.replace(/[\u0000-\u001F\u007F]/g, " ").trim().slice(0, maxChars);
 }
+/**
+* 解析关注集合：字符串数组、去重、去空、超长 ID 丢弃，最多取前 16 个。
+* 不合法时返回 undefined。auth.prove 上宁可退回全量广播也不因优化字段拒绝认证；
+* c2s.session.watch 由行校验先拒绝非法载荷。
+*/
+function parseWatchSessions(value) {
+	if (!Array.isArray(value)) return void 0;
+	const ids = /* @__PURE__ */ new Set();
+	for (const item of value) {
+		if (typeof item !== "string") continue;
+		const id = item.trim();
+		if (id.length === 0 || id.length > 256) continue;
+		ids.add(id);
+		if (ids.size >= 16) break;
+	}
+	return [...ids];
+}
 /** 二进制模式下导出与附件的单块字节数。连接在发送缓冲降到 256 KiB 以下才发
 *  下一块，缓冲峰值约 512 KiB，远低于 4 MiB 的慢客户端断开线。 */
 const BINARY_CHUNK_BYTES = 262144;
@@ -305,6 +323,13 @@ function encodeBinaryFrame(header, body) {
 	frame.set(body, 5 + headerBytes.length);
 	return frame;
 }
+function encodeCompressedFrame(json) {
+	const deflated = deflateRawSync(Buffer.from(json, "utf8"), { level: 1 });
+	const frame = Buffer.allocUnsafe(1 + deflated.length);
+	frame.writeUInt8(2, 0);
+	deflated.copy(frame, 1);
+	return frame;
+}
 // src/auth-rate-limit.ts
 const DEFAULT_AUTH_RATE_POLICY = {
 	windowMs: 6e4,
@@ -485,7 +510,7 @@ function defaultLevel(kind) {
 function sanitizeText(value, maxChars) {
 	return value.replace(/[\u0000-\u001f\u007f-\u009f]+/gu, " ").replace(/\s+/g, " ").trim().slice(0, maxChars);
 }
-function normalizeReason(reason) {
+function normalizeReason$1(reason) {
 	return sanitizeText(reason, MAX_REASON_CHARS).replace(/\s+/g, "-");
 }
 /**
@@ -566,7 +591,7 @@ var DiagnosticsStore = class {
 		const event = {
 			ts,
 			kind,
-			reason: normalizeReason(reason),
+			reason: normalizeReason$1(reason),
 			level: extra.level ?? defaultLevel(kind),
 			...attemptId !== void 0 ? { attemptId } : {},
 			...source !== void 0 ? { source } : {},
@@ -1991,6 +2016,12 @@ function userMessageSource(data) {
 	if (obj.source && typeof obj.source === "object") return obj.source;
 	if (obj.message && typeof obj.message === "object" && obj.message.source && typeof obj.message.source === "object") return obj.message.source;
 }
+/** Source kind of one user/message payload (`user`, `schedule`, injected
+* context kinds, …); undefined on legacy hosts that record no source. */
+function userMessageSourceKind(data) {
+	const kind = userMessageSource(data)?.kind;
+	return typeof kind === "string" ? kind : void 0;
+}
 /** Wire role for one user/message payload. A payload without any readable
 * source degrades to 'user' so history written by older hosts stays visible;
 * a present source follows the host's own trajectory rule — anything whose
@@ -2223,7 +2254,12 @@ function withoutEditBodies(edit) {
 function truncate(text, max) {
 	return text.length <= max ? text : text.slice(0, max - 1) + "…";
 }
-function projectHistory(events) {
+/**
+* `touched`（可选，增量 tail 用）：记录每一行最后一次被哪个事件改动，键为行的 seq。
+* 行由自身事件生成时等于它的 seq；工具结果合并回较早的工具调用行时更新为结果事件的
+* seq。增量 tail 据此找出「sinceSeq 之后改动过的行」，而不只是 seq 更大的行。
+*/
+function projectHistory(events, touched) {
 	const messages = [];
 	const toolByCall = /* @__PURE__ */ new Map();
 	for (const entry of events) {
@@ -2232,6 +2268,7 @@ function projectHistory(events) {
 			seq: event.seq,
 			ts: tsOf(event)
 		};
+		touched?.set(event.seq, Math.max(touched.get(event.seq) ?? event.seq, event.seq));
 		switch (event.type) {
 			case "system/message": break;
 			case "user/message":
@@ -2285,6 +2322,7 @@ function projectHistory(events) {
 						summary
 					};
 					if (attachments.attachments) Object.assign(target, attachments);
+					touched?.set(target.seq, Math.max(touched.get(target.seq) ?? target.seq, event.seq));
 				} else messages.push({
 					...base,
 					role: "tool",
@@ -2605,12 +2643,13 @@ const sessionRows = [
 			const invalid = requireSessionId(checked.value);
 			if (invalid) return invalid;
 			if (!isOptionalField(checked.value, "tailCount", (v) => isInteger(v, 1, 1e4))) return reject$1("E_PROTOCOL", "invalid tailCount");
+			if (!isOptionalField(checked.value, "sinceSeq", (v) => typeof v === "number" && Number.isFinite(v) && v >= 0)) return reject$1("E_PROTOCOL", "invalid sinceSeq");
 			return checked;
 		},
 		handle: async (ctx, payload) => {
 			const sessionId = payload.sessionId;
 			const buffered = ctx.bufferOpenEvents(sessionId);
-			if (!await ctx.bridge.openSession(ctx, sessionId, payload.tailCount ?? 100)) {
+			if (!await ctx.bridge.openSession(ctx, sessionId, payload.tailCount ?? 100, payload.sinceSeq)) {
 				ctx.discardOpenBuffer(sessionId, buffered);
 				return ctx.fail("E_NOT_FOUND", "session history unavailable");
 			}
@@ -2632,6 +2671,24 @@ const sessionRows = [
 			ctx.send("s2c.ack", {});
 		}
 	},
+	{
+		type: "c2s.session.watch",
+		stage: "authenticated",
+		scopes: READ,
+		capability: "sessionInterest",
+		doc: "PROTOCOL.md c2s.session.watch",
+		validate: (payload) => {
+			const checked = payloadObject(payload);
+			if (!checked.ok) return checked;
+			const ids = checked.value.sessionIds;
+			if (!Array.isArray(ids) || ids.length > 16 || !ids.every((id) => isText(id, 256))) return reject$1("E_PROTOCOL", `sessionIds must be an array of at most 16 session ids`);
+			return checked;
+		},
+		handle: (ctx, payload) => {
+			ctx.setWatchedSessions(parseWatchSessions(payload.sessionIds) ?? []);
+			ctx.send("s2c.ack", {});
+		}
+	},
 	{
 		type: "c2s.session.create",
 		stage: "authenticated",
@@ -4070,6 +4127,8 @@ var ConnectionGate = class {
 			scopes: this.scopes,
 			widgetClient: this.widgetClient,
 			resumeCursor: this.widgetClient ? void 0 : resumeCursor,
+			watchSessions: this.widgetClient ? void 0 : parseWatchSessions(p.watchSessions),
+			acceptsDeflate: Array.isArray(p.acceptEncoding) && p.acceptEncoding.includes("deflate-raw"),
 			deviceName,
 			appVersion
 		});
@@ -4124,6 +4183,7 @@ var ConnectionGate = class {
 			fail: (code, message) => host.fail(env.id, code, message),
 			close: (code, reason) => host.close(code, reason),
 			canReceive: (scope) => host.canReceive(scope),
+			accepts: (type, payload) => host.accepts(type, payload),
 			push: (type, payload, seq) => host.push(type, payload, seq),
 			lastCursor: () => host.lastCursor(),
 			replay: (entries) => host.replay(entries),
@@ -4133,6 +4193,7 @@ var ConnectionGate = class {
 			discardOpenBuffer: (sessionId, buffer) => host.discardOpenBuffer(sessionId, buffer),
 			flushOpenBuffer: (sessionId, buffer) => host.flushOpenBuffer(sessionId, buffer),
 			closeOpenSession: (sessionId) => host.closeOpenSession(sessionId),
+			setWatchedSessions: (sessionIds) => host.setWatchedSessions(sessionIds),
 			nextLiveActivityGeneration: () => host.nextLiveActivityGeneration(),
 			get liveActivityGeneration() {
 				return host.liveActivityGeneration;
@@ -4169,6 +4230,14 @@ var BridgeConnection = class {
 	*/
 	openingSessionEvents = /* @__PURE__ */ new Map();
 	openSessions = /* @__PURE__ */ new Set();
+	/**
+	* 关注集合（能力 `sessionInterest`）：客户端本机有缓存、需要保持最新的会话。
+	* undefined = 旧客户端从未声明，照旧收全部会话事件。来源：auth.prove 的
+	* `watchSessions`（须在重放前生效）与之后的 c2s.session.watch（整体替换）。
+	*/
+	watchedSessions;
+	/** 客户端认证时声明接受 deflate-raw（能力 `compressedFrames`）；认证前一律文本帧。 */
+	compressDownlink = false;
 	liveActivityRegistrationGeneration = 0;
 	pendingLiveActivityId;
 	lastActivity = Date.now();
@@ -4224,6 +4293,8 @@ var BridgeConnection = class {
 			fail: (id, code, message) => connection.fail(id, code, message),
 			close: (code, reason) => connection.close(code, reason),
 			canReceive: (scope) => connection.canReceive(scope),
+			accepts: (type, payload) => connection.accepts(type, payload),
+			setWatchedSessions: (sessionIds) => connection.setWatchedSessions(sessionIds),
 			push: (type, payload, seq) => connection.push(type, payload, seq),
 			lastCursor: () => connection.lastCursor(),
 			replay: (entries) => connection.replay(entries),
@@ -4309,7 +4380,23 @@ var BridgeConnection = class {
 	canReceive(scope) {
 		return this.identity?.scopes.has(scope) ?? false;
 	}
+	/**
+	* 关注过滤：只管按会话投递的两类帧。正在打开（tail 未发出、事件进缓冲）、
+	* 已打开或在关注集合里的会话放行；未声明关注集合的连接全部放行。
+	*/
+	accepts(type, payload) {
+		if (this.watchedSessions === void 0) return true;
+		if (type !== "s2c.session.event" && type !== "s2c.session.queue") return true;
+		const sessionId = payload?.sessionId;
+		if (typeof sessionId !== "string") return true;
+		return this.openSessions.has(sessionId) || this.openingSessionEvents.has(sessionId) || this.watchedSessions.has(sessionId);
+	}
+	/** c2s.session.watch：整体替换关注集合；也让从未声明的连接切到按关注投递。 */
+	setWatchedSessions(sessionIds) {
+		this.watchedSessions = new Set(sessionIds);
+	}
 	push(type, payload, seq) {
+		if (!this.accepts(type, payload)) return;
 		if (type === "s2c.notify") payload = {
 			...payload,
 			hostAudience: this.deps.audience
@@ -4346,8 +4433,11 @@ var BridgeConnection = class {
 	/** 认证成功：门只做安全判定，欢迎与重放归连接（数据面）。 */
 	onAuthenticated(identity) {
 		this.identity = identity;
+		if (identity.watchSessions !== void 0) this.watchedSessions = new Set(identity.watchSessions);
+		this.compressDownlink = identity.acceptsDeflate;
 		const cursor = identity.resumeCursor;
 		const canResume = cursor !== void 0 && this.deps.bridge.canResumeFrom(cursor);
+		const routes = identity.widgetClient ? void 0 : this.deps.routes?.();
 		this.send("s2c.welcome", {
 			protocolVersion: 2,
 			serverVersion: this.deps.serverVersion,
@@ -4355,7 +4445,8 @@ var BridgeConnection = class {
 			scopes: [...identity.scopes],
 			capabilities: this.deps.bridge.capabilities,
 			cursor: this.deps.bridge.currentCursor(),
-			resumed: canResume
+			resumed: canResume,
+			...routes !== void 0 ? { routes } : {}
 		});
 		if (!identity.widgetClient) this.deps.bridge.addSink(this);
 		if (cursor !== void 0) {
@@ -4405,7 +4496,16 @@ var BridgeConnection = class {
 			this.close(1013, "client too slow");
 			return;
 		}
-		this.ws.send(body === void 0 ? JSON.stringify(envelope) : encodeBinaryFrame(envelope, body));
+		if (body !== void 0) {
+			this.ws.send(encodeBinaryFrame(envelope, body));
+			return;
+		}
+		const json = JSON.stringify(envelope);
+		if (this.compressDownlink && Buffer.byteLength(json) > 8192) {
+			this.ws.send(encodeCompressedFrame(json));
+			return;
+		}
+		this.ws.send(json);
 	}
 	fail(id, code, message) {
 		this.send("s2c.error", {
@@ -5489,7 +5589,9 @@ function pushContent(notification, mode) {
 * Relay connectivity self-test used by the settings page "测试中继" button.
 *
 * Two steps mirror what zero-touch enrollment actually does:
-*   1. health  — GET {url}/healthz        → is the relay reachable?
+*   1. health  — GET {url}/healthz        → is the relay reachable? The
+*      relay's `version` (relay 0.2.0+) is appended to the message for
+*      troubleshooting; it never affects the verdict.
 *   2. enroll  — POST {url}/v1/enroll     → does the shared key grant a token?
 *
 * The enroll step doubles as a repair path: a token it issues is handed back
@@ -5499,6 +5601,16 @@ function pushContent(notification, mode) {
 * Transport is injectable (`fetchImpl`) so tests never touch the network.
 */
 const DEFAULT_TIMEOUT_MS = 6e3;
+/**
+* semver-shaped characters only, bounded: the value comes from a remote
+* server and is rendered verbatim in the settings page.
+*/
+const RELAY_VERSION_PATTERN = /^[0-9A-Za-z.+-]{1,32}$/;
+/** Display-only relay version from a /healthz body; undefined for older relays or unsafe values. */
+function relayVersionOf(body) {
+	const version = body?.version;
+	return typeof version === "string" && RELAY_VERSION_PATTERN.test(version) ? version : void 0;
+}
 async function requestJson(fetchImpl, url, init, timeoutMs) {
 	const response = await fetchImpl(url, {
 		...init,
@@ -5523,13 +5635,16 @@ async function runRelayProbe(options) {
 		const startedAt = Date.now();
 		const { status, body } = await requestJson(fetchImpl, `${base}/healthz`, { method: "GET" }, timeoutMs);
 		const latencyMs = Date.now() - startedAt;
-		if (status === 200 && body?.ok === true) steps.push({
-			id: "health",
-			ok: true,
-			message: "中继服务可达",
-			latencyMs
-		});
-		else steps.push({
+		if (status === 200 && body?.ok === true) {
+			const version = relayVersionOf(body);
+			const message = version ? `中继服务可达（版本 ${version}）` : "中继服务可达";
+			steps.push({
+				id: "health",
+				ok: true,
+				message,
+				latencyMs
+			});
+		} else steps.push({
 			id: "health",
 			ok: false,
 			message: `中继响应异常（HTTP ${status}）`,
@@ -6273,7 +6388,7 @@ var TransportReconciler = class {
 function createLocalTransport(deps) {
 	return new TransportReconciler({
 		keyOf: (config) => ({
-			enabled: config.enabled === true && config.local?.enabled !== false,
+			enabled: config.enabled === true,
 			port: normalizeLocalPort(config.local?.port)
 		}),
 		skipWhenDisabled: true,
@@ -6341,7 +6456,7 @@ function createLocalTransport(deps) {
 			};
 		}
 	}, deps.config, deps.log, {
-		phase: deps.config().enabled === true && deps.config().local?.enabled !== false ? "starting" : "disabled",
+		phase: deps.config().enabled === true ? "starting" : "disabled",
 		port: normalizeLocalPort(deps.config().local?.port),
 		endpoints: [],
 		updatedAt: Date.now()
@@ -6905,6 +7020,230 @@ function unwrapStreamItem(item) {
 	} : nested;
 	return item;
 }
+// src/quiet-completion.ts
+/**
+* 计划任务按需完成通知（#35）。
+*
+* heartbeat 式计划任务大多数轮次"一切正常"，每轮都推「任务完成」是噪音。插件
+* 给计划任务会话提供一个 Agent 工具：Agent 按任务提示词里的规则判断本轮不需要
+* 提醒时调用它，本轮成功结束就不发完成通知（不写 s2c.notify、不推 APNs）。
+* 失败、审批、提问照常通知；模型忘了调用时照常提醒，宁可多一次打扰也不漏报。
+*
+* 职责划分：
+* - scheduledTurnOf：同步读宿主会话日志，判定当前这一轮是否由计划任务投递驱动。
+*   工具的 `when` 与 `execute` 都在宿主进程内同步调用它，不依赖桥接层异步收到的
+*   事件（实测 `when` 求值时本轮 user/message 尚未落盘，桥接层也还没收到）。
+* - QuietCompletionTracker：计划任务会话的粘性集合，以及每个会话"本轮已请求静默"
+*   的记录；HostBridge 在 user/message 与 turn.end 处调用它。
+* - quietCompletionTool：面向模型的工具定义，由 index.ts 注册到宿主 `ctx.tools`。
+*
+* 只在宿主级计划任务（`schedulesHost`，DSH 0.2.2 起）上注册：0.2.1 的
+* `tools.register` 不支持 `when`，多余参数会被静默忽略，工具会变成全局可见。
+*/
+const QUIET_COMPLETION_TOOL_NAME = "deeppilot_skip_completion_notice";
+/** 往回扫描会话日志的上限：一轮内的事件远少于此，防止异常长轮次拖慢步骤准备。 */
+const MAX_TURN_SCAN_EVENTS = 2e3;
+function sessionLogOf(agent) {
+	const session = agent?.session;
+	if (!session || typeof session.id !== "string" || typeof session.seq !== "number" || typeof session.eventAt !== "function") return;
+	return session;
+}
+function sourceKindOf(value) {
+	const kind = value?.source?.kind;
+	return typeof kind === "string" ? kind : void 0;
+}
+/** 一次 inbox 拼接里插入的条目（按插入顺序）及其目标队列。 */
+function insertedOf(event) {
+	if (event.type !== "agent/inbox/spliced") return void 0;
+	const data = event.data;
+	const items = Array.isArray(data?.inserted) ? data.inserted : [];
+	return items.length > 0 ? {
+		target: data?.target,
+		items
+	} : void 0;
+}
+/**
+* 判定当前这一轮是否由计划任务投递驱动（同步读宿主会话日志，DSH 0.2.2-rc.1 实测形状）。
+*
+* 宿主把待处理消息先拼进 inbox（`agent/inbox/spliced`，带条目本体与目标队列），
+* `turn/start` 之后的拼接只是取走（`removedCount`，不带内容），条目随后才落成
+* user/message。因此按 inbox 插入判定：
+* - 本轮开始之后插入 `next-step` 的用户条目 = 用户中途插话，不算；
+* - 本轮开始时取走的是上一轮开始之后插入 `next-turn` 的条目；其中最后插入的一条
+*   来源为 `schedule` 才算（计划任务投递）；来源为 `user` 不算；
+* - 同为 `schedule` 来源的任务变更提示插入的是 `next-step`（宿主注明"不是投递"），不参与判定；
+* - 扫不到本轮 `turn/start` 时按普通轮次处理，宁可照常提醒。
+*/
+function scheduledTurnOf(session) {
+	const floor = Math.max(0, session.seq - MAX_TURN_SCAN_EVENTS);
+	let turn;
+	let seenTurnStart = false;
+	for (let seq = session.seq - 1; seq >= floor; seq--) {
+		const event = session.eventAt(seq);
+		if (!event) continue;
+		if (event.type === "turn/start") {
+			if (seenTurnStart) break;
+			seenTurnStart = true;
+			const value = event.data?.turn;
+			if (typeof value === "number") turn = value;
+			continue;
+		}
+		const splice = insertedOf(event);
+		if (splice === void 0) continue;
+		if (!seenTurnStart) {
+			if (splice.target === "next-step" && splice.items.some((item) => sourceKindOf(item) === "user")) return {
+				scheduled: false,
+				...turn !== void 0 ? { turn } : {}
+			};
+			continue;
+		}
+		if (splice.target !== "next-turn") continue;
+		for (let index = splice.items.length - 1; index >= 0; index--) {
+			const kind = sourceKindOf(splice.items[index]);
+			if (kind === "user") return {
+				scheduled: false,
+				...turn !== void 0 ? { turn } : {}
+			};
+			if (kind === "schedule") return {
+				scheduled: true,
+				...turn !== void 0 ? { turn } : {}
+			};
+		}
+	}
+	return {
+		scheduled: false,
+		...turn !== void 0 ? { turn } : {}
+	};
+}
+var QuietCompletionTracker = class {
+	/**
+	* 判定过计划任务轮次的会话。粘性集合：加入后不再移除，工具不按轮出现或消失。
+	* 宿主每次工具列表变化都会往会话追加一条工具增减消息并让提示词缓存失效，
+	* 按轮开关会让同一会话反复产生这类消息。
+	*/
+	scheduleSessions = /* @__PURE__ */ new Set();
+	quiet = /* @__PURE__ */ new Map();
+	/** 启动时用宿主任务列表里的投递目标会话预热，避免重启后工具先消失再出现。 */
+	seed(sessionIds) {
+		for (const sessionId of sessionIds) if (sessionId) this.scheduleSessions.add(sessionId);
+	}
+	isScheduleSession(sessionId) {
+		return this.scheduleSessions.has(sessionId);
+	}
+	/** 加入粘性集合；返回是否为新加入（调用方据此记一次日志）。 */
+	markScheduleSession(sessionId) {
+		if (this.scheduleSessions.has(sessionId)) return false;
+		this.scheduleSessions.add(sessionId);
+		return true;
+	}
+	/** 工具执行：只在计划任务轮次内生效。 */
+	requestQuiet(sessionId, verdict, seq) {
+		if (sessionId === void 0 || !verdict.scheduled) return {
+			suppressed: false,
+			note: "This run was not started by a scheduled task; the completion notification will be sent as usual."
+		};
+		this.quiet.set(sessionId, {
+			...verdict.turn !== void 0 ? { turn: verdict.turn } : {},
+			seq
+		});
+		return { suppressed: true };
+	}
+	/**
+	* 桥接层观察到 user/message：用户在请求静默之后插话（日志位置更晚）就撤销静默，
+	* 本轮照常提醒。计划任务与注入上下文不影响。
+	*/
+	noteUserMessage(sessionId, sourceKind, seq) {
+		const request = this.quiet.get(sessionId);
+		if (request === void 0 || sourceKind !== "user") return;
+		if (seq === void 0 || seq > request.seq) this.quiet.delete(sessionId);
+	}
+	/**
+	* turn.end 时调用。返回 true 表示本轮完成通知应被抑制：成功结束、且本轮请求过静默。
+	* 轮次号能对上时按轮次号判定；迟到的上一轮 turn.end 保留本轮的请求。
+	*/
+	consumeTurnEnd(sessionId, ok, turn, seq) {
+		const request = this.quiet.get(sessionId);
+		if (request === void 0) return false;
+		if (turn !== void 0 && request.turn !== void 0) {
+			if (turn < request.turn) return false;
+			this.quiet.delete(sessionId);
+			return ok && turn === request.turn;
+		}
+		if (seq !== void 0 && seq < request.seq) return false;
+		this.quiet.delete(sessionId);
+		return ok;
+	}
+};
+const DESCRIPTION = [
+	"Call this during a scheduled run only when the task prompt says the user does not need to be notified",
+	"for results like this one. It suppresses only this run's \"task completed\" notification; approvals,",
+	"questions and errors still notify. Do not call it if anything needs the user's attention, or if the",
+	"prompt gives no such rule."
+].join(" ");
+/** reason 归一化：非字符串按空串处理，去首尾空白并截断。 */
+function normalizeReason(raw) {
+	const text = typeof raw === "string" ? raw.trim() : "";
+	return text.length > 200 ? text.slice(0, 200) : text;
+}
+/**
+* 面向模型的工具定义（宿主 ToolDefinition 原始形状：JSON Schema 参数、输出 schema
+* 与 render、execute）。`log` 只记会话 ID、结果与 reason 长度：reason 由模型撰写，
+* 可能引用结果内容，按插件日志约定不打正文。
+*/
+function quietCompletionTool(tracker, log = () => {}) {
+	return {
+		name: QUIET_COMPLETION_TOOL_NAME,
+		description: DESCRIPTION,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			required: ["reason"],
+			properties: { reason: {
+				type: "string",
+				description: `Why this run does not need the user's attention (at most 200 characters).`
+			} }
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				required: ["suppressed"],
+				properties: {
+					suppressed: { type: "boolean" },
+					note: { type: "string" }
+				}
+			},
+			render(_args, value) {
+				return [{
+					type: "text",
+					text: value.suppressed ? "The completion notification for this run will not be sent." : value.note ?? "The completion notification will be sent as usual."
+				}];
+			}
+		},
+		async execute(args, exec) {
+			const session = sessionLogOf(exec.agent);
+			const reason = normalizeReason(args?.reason);
+			const result = session === void 0 ? tracker.requestQuiet(void 0, { scheduled: false }, 0) : tracker.requestQuiet(session.id, scheduledTurnOf(session), session.seq);
+			log(`quiet completion requested session=${session?.id ?? "?"} suppressed=${result.suppressed} reasonChars=${reason.length}`);
+			return result;
+		}
+	};
+}
+/**
+* 注册工具。`when`：粘性集合内的会话直接放行；否则同步判定本轮是否计划任务轮次，
+* 是则加入集合（首轮即可见，`new` 目标每次新建的会话同样可见）。普通会话看不到。
+* 返回宿主给的注销函数。
+*/
+function registerQuietCompletionTool(tools, tracker, log = () => {}) {
+	return tools.register(quietCompletionTool(tracker, log), { when: (context) => {
+		const session = sessionLogOf(context.agent);
+		if (session === void 0) return false;
+		if (tracker.isScheduleSession(session.id)) return true;
+		if (!scheduledTurnOf(session).scheduled) return false;
+		if (tracker.markScheduleSession(session.id)) log(`quiet completion: session joined scheduled set session=${session.id}`);
+		return true;
+	} });
+}
 // src/host-capabilities.ts
 const pluginUpdateProbes = /* @__PURE__ */ new WeakMap();
 function setPluginUpdateProbe(proxy, probe) {
@@ -6936,6 +7275,10 @@ function capabilityBits(proxy, pushOutlet) {
 		historyPaging: true,
 		replay: true,
 		binaryFrames: true,
+		sessionInterest: true,
+		compressedFrames: true,
+		incrementalTail: true,
+		routeHints: true,
 		approvals: true,
 		questions: true,
 		pendingSnapshot: true,
@@ -7213,6 +7556,10 @@ var AssistantStream = class {
 };
 // src/host-bridge.ts
 const MAX_RING_DEFAULT = 2e3;
+/** 补发量超过它就改发 s2c.resync（经 Funnel 实测吞吐 40～80 KB/s，约 6～12 秒）。 */
+const REPLAY_RESYNC_BYTES = 524288;
+/** 只改了用量统计的列表推送，同一会话这段时间内最多推一次（第二批 P5）。 */
+const SUMMARY_STATS_THROTTLE_MS = 5e3;
 /**
 * Process-wide bridge state: session mirror, pending approvals/questions,
 * and the per-device replay ring. Consumes the in-process mux/host streams
@@ -7225,6 +7572,13 @@ var HostBridge = class {
 	log;
 	id = ++BRIDGE_SEQ;
 	summaries = /* @__PURE__ */ new Map();
+	/**
+	* 列表推送节流（连接传输第二批 P5）。每个会话最近一次推出去的摘要指纹，
+	* 用来丢掉内容完全相同的重复推送；只改了 `stats` 的变化按 SUMMARY_STATS_THROTTLE_MS
+	* 合并，状态、标题、任务清单、待处理标记、活动描述的变化照旧立即推。
+	*/
+	summaryPushed = /* @__PURE__ */ new Map();
+	summaryStatsTimers = /* @__PURE__ */ new Map();
 	activeTools = /* @__PURE__ */ new Map();
 	approvals = /* @__PURE__ */ new Map();
 	questions = /* @__PURE__ */ new Map();
@@ -7233,6 +7587,8 @@ var HostBridge = class {
 	* and restore them. Excluded from `summaries` and from the live broadcast. */
 	archivedSummaries = /* @__PURE__ */ new Map();
 	subagentSessionIds = /* @__PURE__ */ new Set();
+	/** 计划任务按需完成通知（quiet-completion.ts）：index.ts 用它注册 Agent 工具。 */
+	quietCompletion = new QuietCompletionTracker();
 	/**
 	* 每个会话最近一次已知的队列（inbox 投影的折叠结果）及其指纹。来源是实时
 	* 投影通知或打开会话时读到的基线；指纹用来丢掉内容没变的重复通知。
@@ -7415,16 +7771,35 @@ var HostBridge = class {
 	* reader without interactions.respond never gets the missed approval
 	* frames back (R1/P2).
 	*/
+	/**
+	* 按序补发游标之后的帧。先按权限与关注集合筛出该 sink 真正会收到的帧，
+	* 估算字节数超过 REPLAY_RESYNC_BYTES 时改发 `s2c.resync`：补发是同步一次性
+	* 写出的，经 Funnel 时插件这侧看不到积压，大补发会把之后所有请求响应堵在
+	* 链路上（实测 450 帧堵 37 秒）。重新同步让客户端只拉列表和正在看的会话。
+	*/
 	resumeFrom(cursor, target) {
 		const oldest = this.ring.length > 0 ? this.ring[0].seq : this.cursor + 1;
 		if (cursor + 1 < oldest) return false;
 		const receivers = target !== void 0 ? [target] : [...this.sinks];
-		for (const entry of this.ring) if (entry.seq > cursor) for (const sink of receivers) {
-			const need = pushScopeFor(entry.type, entry.payload);
-			if (need === void 0 || !sink.canReceive(need)) continue;
-			sink.replay([entry]);
+		for (const sink of receivers) {
+			const window = [];
+			let bytes = 0;
+			for (const entry of this.ring) {
+				if (entry.seq <= cursor) continue;
+				const need = pushScopeFor(entry.type, entry.payload);
+				if (need === void 0 || !sink.canReceive(need)) continue;
+				if (sink.accepts && !sink.accepts(entry.type, entry.payload)) continue;
+				window.push(entry);
+				bytes += Buffer.byteLength(JSON.stringify(entry.payload) ?? "");
+			}
+			if (bytes > 524288) {
+				this.log?.(`resume window ${bytes}B over ${REPLAY_RESYNC_BYTES}B; sending resync`);
+				sink.resync();
+				continue;
+			}
+			for (const entry of window) sink.replay([entry]);
+			sink.replayDone();
 		}
-		for (const sink of receivers) sink.replayDone();
 		return true;
 	}
 	refreshLiveActivities() {
@@ -7480,10 +7855,41 @@ var HostBridge = class {
 		this.runMuxStream();
 		this.refreshSummaries();
 	}
+	/**
+	* 用宿主任务列表里的投递目标会话预热计划任务会话集合，避免插件重启后工具
+	* 先消失、等下一次投递再出现（每次变化都会给会话追加工具增减消息）。
+	* `new` 目标没有固定会话，只能从最近一次投递回执里取。失败只记日志：集合仍会
+	* 在下一次投递时补上。由 index.ts 在 schedule 服务就绪、注册工具时调用。
+	*/
+	async seedQuietCompletionSessions() {
+		if (this.hostSchedule === void 0) return;
+		const sessionIds = [];
+		let offset = 0;
+		for (;;) {
+			const result = await this.listHostSchedules({
+				limit: HOST_SCHEDULE_PAGE_SIZE,
+				offset
+			});
+			if (!result.ok) {
+				this.log?.(`quiet completion seed skipped: ${result.code}`);
+				return;
+			}
+			for (const task of result.value.tasks) {
+				if (task.target.kind !== "new") sessionIds.push(task.target.sessionId);
+				if (task.lastDelivery) sessionIds.push(task.lastDelivery.targetSessionId);
+			}
+			offset += result.value.tasks.length;
+			if (result.value.tasks.length === 0 || offset >= result.value.total) break;
+		}
+		if (this.disposed) return;
+		this.quietCompletion.seed(sessionIds);
+	}
 	dispose() {
 		if (this.disposed) return;
 		this.disposed = true;
 		this.abort.abort();
+		for (const timer of this.summaryStatsTimers.values()) clearTimeout(timer);
+		this.summaryStatsTimers.clear();
 		this.assistantStream.dispose();
 		this.sinks.clear();
 		this.sinkSessions.clear();
@@ -7570,6 +7976,7 @@ var HostBridge = class {
 				if (event.type === "turn/end") this.assistantStream.abandon(sessionId);
 				if (event.type === "agent-preset/selected") this.record("s2c.skills.changed", { sessionId });
 				this.noteActivity(sessionId, event);
+				if (event.type === "user/message") this.quietCompletion.noteUserMessage(sessionId, userMessageSourceKind(event.data), event.seq);
 				this.captureAssistantText(sessionId, event);
 				const projection = projectEvent(sessionId, event);
 				this.captureActivity(sessionId, event, projection?.data.tool);
@@ -7582,7 +7989,12 @@ var HostBridge = class {
 						...streamId && projection.kind === "message.final" ? { streamId } : {}
 					}
 				});
-				if (projection?.kind === "turn.end") this.emitTurnCompletedNotify(sessionId, projection.data.ok === true);
+				if (projection?.kind === "turn.end") {
+					const ok = projection.data.ok === true;
+					const turn = event.data?.turn;
+					if (this.quietCompletion.consumeTurnEnd(sessionId, ok, typeof turn === "number" ? turn : void 0, event.seq)) this.log?.(`completion notice skipped by scheduled run session=${sessionId}`);
+					else this.emitTurnCompletedNotify(sessionId, ok);
+				}
 				break;
 			}
 			case "session/projection": {
@@ -7732,6 +8144,8 @@ var HostBridge = class {
 			this.archivedSummaries = nextArchived;
 			const removedIds = [...previousIds].filter((id) => !next.has(id));
 			for (const id of this.lastAssistantText.keys()) if (!next.has(id)) this.lastAssistantText.delete(id);
+			for (const id of removedIds) this.forgetSummaryPush(id);
+			for (const row of next.values()) this.noteSummaryPushed(row);
 			this.record("s2c.sessions.delta", {
 				upserted: [...next.values()],
 				removedIds
@@ -7851,11 +8265,62 @@ var HostBridge = class {
 		this.pushSummary(row);
 	}
 	pushSummary(row) {
+		const full = JSON.stringify(row);
+		const previous = this.summaryPushed.get(row.id);
+		if (previous?.full === full) return;
+		const withoutStats = JSON.stringify({
+			...row,
+			stats: void 0
+		});
+		const now = Date.now();
+		if (previous !== void 0 && previous.withoutStats === withoutStats && now - previous.at < 5e3) {
+			if (!this.summaryStatsTimers.has(row.id)) {
+				const timer = setTimeout(() => {
+					this.summaryStatsTimers.delete(row.id);
+					const latest = this.summaries.get(row.id);
+					if (latest && !this.disposed) this.pushSummary(latest);
+				}, SUMMARY_STATS_THROTTLE_MS - (now - previous.at));
+				timer.unref?.();
+				this.summaryStatsTimers.set(row.id, timer);
+			}
+			return;
+		}
+		const pending = this.summaryStatsTimers.get(row.id);
+		if (pending !== void 0) {
+			clearTimeout(pending);
+			this.summaryStatsTimers.delete(row.id);
+		}
+		this.summaryPushed.set(row.id, {
+			full,
+			withoutStats,
+			at: now
+		});
 		this.record("s2c.sessions.delta", {
 			upserted: [row],
 			removedIds: []
 		});
 	}
+	noteSummaryPushed(row) {
+		const pending = this.summaryStatsTimers.get(row.id);
+		if (pending !== void 0) {
+			clearTimeout(pending);
+			this.summaryStatsTimers.delete(row.id);
+		}
+		this.summaryPushed.set(row.id, {
+			full: JSON.stringify(row),
+			withoutStats: JSON.stringify({
+				...row,
+				stats: void 0
+			}),
+			at: Date.now()
+		});
+	}
+	forgetSummaryPush(sessionId) {
+		const pending = this.summaryStatsTimers.get(sessionId);
+		if (pending !== void 0) clearTimeout(pending);
+		this.summaryStatsTimers.delete(sessionId);
+		this.summaryPushed.delete(sessionId);
+	}
 	listSessions() {
 		return [...this.summaries.values()].sort((a, b) => b.lastActivityTs - a.lastActivityTs);
 	}
@@ -7919,7 +8384,7 @@ var HostBridge = class {
 		} catch {}
 	}
 	/** Tail history for an opened session; pushes s2c.session.tail to the sink. */
-	async openSession(sink, sessionId, tailCount) {
+	async openSession(sink, sessionId, tailCount, sinceSeq) {
 		try {
 			const response = await this.apiProxy.sessions.history({
 				rpcId: randomUUID(),
@@ -7930,14 +8395,26 @@ var HostBridge = class {
 			});
 			if (!response.result || !response.result.ok) return false;
 			const result = response.result.value;
-			const page = limitSessionPageMessages(projectHistory(result.events ?? []));
+			const events = result.events ?? [];
+			const touched = /* @__PURE__ */ new Map();
+			const projected = projectHistory(events, touched);
+			const page = limitSessionPageMessages(projected);
 			const messages = page.messages;
 			const oldestSeq = messages.length > 0 ? messages[0].seq : 0;
-			sink.push("s2c.session.tail", {
+			const hasMore = Boolean(result.hasMore) || page.dropped > 0;
+			const delta = sinceSeq === void 0 ? void 0 : incrementalTail(events, projected, touched, sinceSeq);
+			sink.push("s2c.session.tail", delta === void 0 ? {
 				sessionId,
 				messages,
 				oldestSeq,
-				hasMore: Boolean(result.hasMore) || page.dropped > 0
+				hasMore
+			} : {
+				sessionId,
+				messages: delta,
+				oldestSeq,
+				hasMore,
+				incremental: true,
+				sinceSeq
 			});
 			this.deriveTitleFallback(sessionId, messages);
 			this.refreshProjections(sessionId).then(() => this.pushQueueSnapshot(sink, sessionId));
@@ -8220,6 +8697,7 @@ var HostBridge = class {
 			this.archivedSessionIds = new Set((response.result.value.archivedSessionIds ?? []).map(String));
 			this.summaries.delete(sessionId);
 			this.lastAssistantText.delete(sessionId);
+			this.forgetSummaryPush(sessionId);
 			this.record("s2c.sessions.delta", {
 				upserted: [],
 				removedIds: [sessionId]
@@ -9502,6 +9980,25 @@ function receiptFailureReason(receipt) {
 * 区间与 wire 行校验（tailCount 1..10000、limit 1..500）共用投影 module 的
 * 常量——「一页能要多少条消息」本是一条规则，原先散在三处。
 */
+/**
+* 增量 tail（能力 `incrementalTail`）：返回 sinceSeq 之后改动过的行；不能保证完整时
+* 返回 undefined，调用方回退全量。三种回退：
+* - 窗口没覆盖到 sinceSeq（最旧事件比它新）：中间可能有事件没取到；
+* - sinceSeq 比窗口里最新事件还新：客户端的视图和主机对不上（例如历史被改写）；
+* - 增量本身超过单页 900 KB 预算。
+*/
+function incrementalTail(events, projected, touched, sinceSeq) {
+	if (events.length === 0) return void 0;
+	let oldest = Infinity;
+	let newest = -Infinity;
+	for (const { event } of events) {
+		if (event.seq < oldest) oldest = event.seq;
+		if (event.seq > newest) newest = event.seq;
+	}
+	if (oldest > sinceSeq || sinceSeq > newest) return void 0;
+	const limited = limitSessionPageMessages(projected.filter((message) => (touched.get(message.seq) ?? message.seq) > sinceSeq));
+	return limited.dropped > 0 ? void 0 : limited.messages;
+}
 function clampTail(n) {
 	if (!Number.isFinite(n)) return 100;
 	return Math.max(10, Math.min(500, Math.floor(n)));
@@ -11824,6 +12321,25 @@ function requestClientIdentity(req) {
 	}
 	return normalizedAddress(req.socket.remoteAddress) ?? "unknown";
 }
+// src/welcome-routes.ts
+/**
+* welcome.routes（能力 routeHints）的纯计算：局域网监听在线且有指纹时给 RFC1918 地址
+* （顺序沿用 localLANIPv4Addresses 的物理网卡优先），Funnel 在线时给公网地址；两者都没有
+* 时返回 undefined，welcome 不带该字段。
+*/
+function welcomeRoutes(local, remote, addresses) {
+	const lanAddresses = addresses.filter(isPrivateIPv4);
+	const lan = local.phase === "online" && local.tlsFingerprint && lanAddresses.length > 0 ? {
+		urls: localEndpointURLs(lanAddresses, local.port),
+		tlsFingerprint: local.tlsFingerprint
+	} : void 0;
+	const remoteURL = remote.phase === "online" ? remote.publicURL : void 0;
+	if (lan === void 0 && remoteURL === void 0) return void 0;
+	return {
+		...lan ? { lan } : {},
+		...remoteURL ? { remote: { url: remoteURL } } : {}
+	};
+}
 // src/lan-tls.ts
 const LAN_TLS_COMMON_NAME = "dsh-deeppilot";
 const LAN_TLS_KEY_FILE = "key.pem";
@@ -12466,6 +12982,7 @@ function apply(ctx, options) {
 						try {
 							const connection = new BridgeConnection(ws, {
 								bridge,
+								routes: phoneRoutes,
 								devices,
 								serverVersion: SERVER_VERSION,
 								audience,
@@ -12554,6 +13071,12 @@ function apply(ctx, options) {
 		dataDir,
 		log
 	});
+	/**
+	* welcome.routes（能力 routeHints）：手机据此在同一 Wi-Fi 下先走局域网、在外走 Funnel。
+	* 局域网只给 RFC1918 地址（不含 tailnet 的 100.64/10：手机未入 tailnet 时只会白等超时），
+	* 物理网卡优先；Funnel 只在 online 时给。每次 welcome 现算：地址与 Funnel 状态都会变。
+	*/
+	const phoneRoutes = () => welcomeRoutes(localTransport.status(), remoteTransport.status(), localLANIPv4Addresses());
 	const localStatus = (addresses) => {
 		const state = localTransport.status();
 		return {
@@ -12634,6 +13157,20 @@ function apply(ctx, options) {
 			if (state.bridge === bridge) state.bridge = void 0;
 			bridge.dispose();
 		}, "deeppilot: host streams");
+		apiCtx.inject(["tools", "schedule"], (sub) => {
+			if (bridge.capabilities.schedulesHost !== true) {
+				log("quiet completion tool not registered: host-level schedules unavailable");
+				return;
+			}
+			const tools = sub.tools;
+			if (typeof tools?.register !== "function") {
+				log("quiet completion tool not registered: tools service unavailable", "warn");
+				return;
+			}
+			sub.effect(() => registerQuietCompletionTool(tools, bridge.quietCompletion, (message) => log(message)), "deeppilot: quiet completion tool");
+			log("quiet completion tool registered");
+			bridge.seedQuietCompletionSessions();
+		});
 	});
 	ctx.effect(() => async () => {
 		closeAllConnections();