dsh-deeppilot 0.9.14 → 0.9.15

package/lib/index.d.ts

@@ -1140,6 +1140,42 @@ interface PushOutlet {
    */
   isAvailable(): boolean;
 }
+interface QuietCompletionResult {
+  suppressed: boolean;
+  note?: string;
+}
+interface TurnVerdict {
+  /** 本轮最近一条驱动消息是计划任务投递（且其后没有用户消息）。 */
+  scheduled: boolean;
+  /** 本轮 `turn/start` 的轮次号；日志里读不到时为 undefined。 */
+  turn?: number;
+}
+declare class QuietCompletionTracker {
+  /**
+   * 判定过计划任务轮次的会话。粘性集合：加入后不再移除，工具不按轮出现或消失。
+   * 宿主每次工具列表变化都会往会话追加一条工具增减消息并让提示词缓存失效，
+   * 按轮开关会让同一会话反复产生这类消息。
+   */
+  private readonly scheduleSessions;
+  private readonly quiet;
+  /** 启动时用宿主任务列表里的投递目标会话预热，避免重启后工具先消失再出现。 */
+  seed(sessionIds: Iterable<string>): void;
+  isScheduleSession(sessionId: string): boolean;
+  /** 加入粘性集合；返回是否为新加入（调用方据此记一次日志）。 */
+  markScheduleSession(sessionId: string): boolean;
+  /** 工具执行：只在计划任务轮次内生效。 */
+  requestQuiet(sessionId: string | undefined, verdict: TurnVerdict, seq: number): QuietCompletionResult;
+  /**
+   * 桥接层观察到 user/message：用户在请求静默之后插话（日志位置更晚）就撤销静默，
+   * 本轮照常提醒。计划任务与注入上下文不影响。
+   */
+  noteUserMessage(sessionId: string, sourceKind: string | undefined, seq: number | undefined): void;
+  /**
+   * turn.end 时调用。返回 true 表示本轮完成通知应被抑制：成功结束、且本轮请求过静默。
+   * 轮次号能对上时按轮次号判定；迟到的上一轮 turn.end 保留本轮的请求。
+   */
+  consumeTurnEnd(sessionId: string, ok: boolean, turn: number | undefined, seq: number | undefined): boolean;
+}
 interface PromptDocument {
   name: string;
   mediaType: string;
@@ -1191,6 +1227,8 @@ export declare class HostBridge {
    * and restore them. Excluded from `summaries` and from the live broadcast. */
   private archivedSummaries;
   private subagentSessionIds;
+  /** 计划任务按需完成通知（quiet-completion.ts）：index.ts 用它注册 Agent 工具。 */
+  readonly quietCompletion: QuietCompletionTracker;
   /**
    * 每个会话最近一次已知的队列（inbox 投影的折叠结果）及其指纹。来源是实时
    * 投影通知或打开会话时读到的基线；指纹用来丢掉内容没变的重复通知。
@@ -1274,6 +1312,13 @@ export declare class HostBridge {
   private record;
   /** Start consuming host + mux streams. Idempotent; aborts on dispose(). */
   start(): void;
+  /**
+   * 用宿主任务列表里的投递目标会话预热计划任务会话集合，避免插件重启后工具
+   * 先消失、等下一次投递再出现（每次变化都会给会话追加工具增减消息）。
+   * `new` 目标没有固定会话，只能从最近一次投递回执里取。失败只记日志：集合仍会
+   * 在下一次投递时补上。由 index.ts 在 schedule 服务就绪、注册工具时调用。
+   */
+  seedQuietCompletionSessions(): Promise<void>;
   dispose(): void;
   private runHostStream;
   private runMuxStream;

package/lib/index.js

@@ -485,7 +485,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 +566,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 +1991,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
@@ -6905,6 +6911,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) {
@@ -7233,6 +7463,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 投影的折叠结果）及其指纹。来源是实时
 	* 投影通知或打开会话时读到的基线；指纹用来丢掉内容没变的重复通知。
@@ -7480,6 +7712,35 @@ 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;
@@ -7570,6 +7831,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 +7844,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": {
@@ -12634,6 +12901,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();