@eddyskywalker/dsh-chatgpt-subscription 0.43.0 → 0.44.0

package/lib/entry-progress-updates-CkGJr_fe.js

@@ -0,0 +1,1004 @@
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { z } from "zod";
+/**
+* 判断是否该催促。达到阈值即触发，注入之后调用方把计数清零。
+* @param rounds - 自上次进展更新以来的连续轮次数。
+* @returns 是否达到 {@link NUDGE_THRESHOLD}。
+*/
+function shouldNudge(rounds) {
+	return rounds >= 8;
+}
+/**
+* 把进展列表截断到环形缓冲上限，保留最新的一批。
+* @param list - 任意长度的进展列表（不会被就地修改）。
+* @returns 截断后的新数组。
+*/
+function capUpdates(list) {
+	return list.length <= 50 ? [...list] : list.slice(list.length - 50);
+}
+/** 进程内自增序号，只用于拼出稳定 id；不含任何运行时依赖。 */
+let sequence = 0;
+/**
+* 生成一条进展的稳定 id。
+* @param at - 产生时刻（Unix 毫秒）。
+* @returns 形如 `pu-<时间戳>-<序号>` 的字符串。
+*/
+function nextUpdateId(at) {
+	sequence += 1;
+	return `pu-${at}-${sequence}`;
+}
+/**
+* 创建一个空的进展更新 store。
+* @returns 新的会话维度 store。
+*/
+function createProgressUpdateStore() {
+	let current = {
+		updates: [],
+		roundsSinceUpdate: 0,
+		nudges: 0
+	};
+	return {
+		state: () => current,
+		push: (update) => {
+			current = {
+				...current,
+				updates: capUpdates([...current.updates, update])
+			};
+			return current;
+		},
+		bumpRound: () => {
+			current = {
+				...current,
+				roundsSinceUpdate: current.roundsSinceUpdate + 1
+			};
+			return current.roundsSinceUpdate;
+		},
+		markUpdated: () => {
+			current = {
+				...current,
+				roundsSinceUpdate: 0
+			};
+			return current;
+		},
+		markNudged: () => {
+			current = {
+				...current,
+				roundsSinceUpdate: 0,
+				nudges: current.nudges + 1
+			};
+			return current;
+		},
+		reset: () => {
+			current = {
+				updates: [],
+				roundsSinceUpdate: 0,
+				nudges: 0
+			};
+			return current;
+		}
+	};
+}
+//#endregion
+//#region src/host/progress-updates/tool.ts
+/** 注册的工具名。冻结契约的一部分，不要改动。 */
+const NOTIFY_USER_TOOL = "progress_update";
+/** 工具关闭时返回给模型的文本（canonical 输出的 render，而不是抛错）。 */
+const DISABLED_OUTPUT_TEXT = "Progress updates are disabled; the update was not displayed.";
+/** 工具描述的最终全文。 */
+const PROGRESS_UPDATE_DESCRIPTION = [
+	"Report progress to the user without ending your turn.",
+	"Two updates are part of the job, not optional narration: send one BEFORE your first tool call of a multi-step task (the plan), and one BEFORE your final answer (what was done and what was verified).",
+	"Use it during the rest of the work so the user can follow along and correct course early:",
+	"state your plan near the beginning of the task (what you will do, and in what order);",
+	"report a meaningful conclusion the moment you have it (a key fact, the root cause, a verified assumption) rather than narrating every step;",
+	"give a stage judgement when one phase ends and the next begins (where things stand, what happens next);",
+	"explain what you are waiting for before a long wait such as a test run, an install, or a build;",
+	"and say what blocks you — and what you will try next, or what you need from the user — when you are stuck.",
+	"Each update has one short title line (plain text, no Markdown, no trailing period) with the details in the message body.",
+	"Do not repeat a status that has not changed.",
+	"When you run as a subagent, describe only your own subtask: finishing your subtask is not the same as finishing the overall task."
+].join(" ");
+/**
+* 构造 progress_update 工具。
+* @param deps - 依赖：当前开关与进展接收端。
+* @returns 可注册的工具定义。
+*/
+function createProgressUpdateTool(deps) {
+	return defineTool({
+		name: NOTIFY_USER_TOOL,
+		description: PROGRESS_UPDATE_DESCRIPTION,
+		parameters: {
+			title: {
+				type: "string",
+				description: "One line, about 60 characters at most, in the user's language: plain text, no Markdown, no trailing period."
+			},
+			message: {
+				type: "string",
+				required: true,
+				description: "The details, about 1000 characters at most, in light Markdown: one paragraph of prose plus a few bullets. Tables are supported: when several items share fields, use a GFM pipe table (header row plus a | --- | separator row) instead of one item per line."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { displayed: {
+					type: "boolean",
+					description: "Whether the update was actually shown to the user."
+				} }
+			},
+			render(_args, value) {
+				return [{
+					type: "text",
+					text: value.displayed ? "Progress update displayed." : DISABLED_OUTPUT_TEXT
+				}];
+			}
+		},
+		async execute(args, exec) {
+			if (!deps.isEnabled()) return { displayed: false };
+			const sink = deps.sink?.();
+			if (sink === void 0) return { displayed: false };
+			const at = Date.now();
+			const source = deps.sourceOf?.(exec);
+			const update = {
+				id: nextUpdateId(at),
+				message: args.message,
+				at,
+				...args.title === void 0 || args.title.trim() === "" ? {} : { title: args.title.trim() },
+				...source === void 0 ? {} : { source }
+			};
+			return { displayed: sink.push(update) };
+		}
+	});
+}
+//#endregion
+//#region src/host/progress-updates/nudge.ts
+/** 注入到模型上下文里的催促正文。 */
+const NUDGE_TEXT = [
+	"You have made a run of tool calls without reporting progress to the user.",
+	"If you are still in the middle of multi-step work, send one progress update now with the progress_update tool:",
+	"one short title line and the details in the body — what you have established so far, where things stand, and what you are doing next.",
+	"Skip it when there is genuinely nothing new to report."
+].join(" ");
+/** 催促上下文在消息来源上的 kind（供客户端与日志区分这类注入）。 */
+const NUDGE_SOURCE_KIND = "progress-updates-nudge";
+/**
+* 造一条催促上下文。
+* @param sequence - 本会话第几次催促，写进 notice 摘要便于日志辨认。
+* @returns 可直接放进 `additionalContexts` 的用户角色消息。
+*/
+function createNudgeContext(sequence) {
+	return createUserMessage({
+		content: [{
+			type: "text",
+			text: NUDGE_TEXT
+		}],
+		source: {
+			kind: NUDGE_SOURCE_KIND,
+			form: "notice",
+			summary: `progress update nudge #${sequence}`
+		}
+	});
+}
+/**
+* 找出一次工具调用所属的**计数会话**：子会话归并到最近的顶层祖先，整棵委派
+* 树共用一个计数器。
+* @param agent - 事件里的调用方 agent。
+* @param sessions - 会话查找表，缺省时退化为只认调用方自己的会话。
+* @returns 计数用的会话 id，无法判定时返回 undefined。
+*/
+function counterSessionIdOf(agent, sessions) {
+	const own = stringOf$1(agent?.session?.header?.id) ?? stringOf$1(agent?.id);
+	if (own === void 0) return void 0;
+	if (sessions === void 0) return own;
+	let current = own;
+	let header = agent?.session?.header;
+	for (let depth = 0; depth < 16 && current !== void 0; depth += 1) {
+		const resolved = header ?? sessions.get(current)?.header;
+		if (resolved === void 0) return current;
+		const parentId = stringOf$1(resolved.parentSession);
+		if (parentId === void 0) return current;
+		const parent = sessions.get(parentId);
+		if (parent === void 0) return current;
+		header = parent.header;
+		current = parentId;
+	}
+	return current;
+}
+/**
+* 读一次工具调用所属的「步」标识，用于把同一个模型步里的多条工具结果合并成一轮。
+*
+* 拿不到 turnBoundary（没有 agent-loop，或宿主不是真实会话）时返回 undefined，
+* 调用方退化为按工具结果计数——宁可多计，也不要漏掉催促。
+* @param agent - 事件里的调用方 agent。
+* @param projections - 会话投影服务，可选。
+* @returns 该步的唯一键，或 undefined。
+*/
+function stepKeyOf(agent, projections) {
+	if (projections === void 0) return void 0;
+	const session = agent?.session;
+	if (session === void 0) return void 0;
+	try {
+		const seq = projections.stateOf(session, "turnBoundary")?.lastStepStartSeq;
+		return typeof seq === "number" ? `step:${seq}` : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* 读一个未知字段为字符串。
+* @param value - 候选值。
+* @returns 字符串，或任何其它类型的 undefined。
+*/
+function stringOf$1(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+//#endregion
+//#region src/host/progress-updates/prompt.ts
+/**
+* 系统提示词引导：让模型知道「多步任务里要主动汇报进展」这件事该怎么用。
+*
+* 文本用函数形式提供（而不是静态字符串）：开关关闭时返回空串，装配期就地
+* 抹掉引导，不需要重启会话、也不需要重挂插件行。
+*
+* ## 为什么是英文
+*
+* 提示词是写给模型看的，不是写给用户看的：同一段要求在英文下最短、歧义最少，
+* 也和工具描述（`tool.ts` 的 `PROGRESS_UPDATE_DESCRIPTION`，本来就是英文）保持
+* 同一套措辞。用户看到的语言由 {@link progressLanguageDirective} 单独钉住——
+* 「指令用英文」与「输出用中文」是两件事，不要混在一起。
+*
+* @module dsh-chatgpt-subscription/host/progress-updates/prompt
+*/
+/**
+* 本模块提示词分节的名称，全局唯一（重复注册会抛错）。
+*
+* 保留原插件的 `plugin:progress-updates` 拼写：会话里已有的分节名不能因为搬家
+* 而变成第二个分节。
+*/
+const PROGRESS_SECTION_NAME = "plugin:progress-updates";
+/** 允许的取值，供设置解析做白名单校验（配置里写错就等于没写）。 */
+const PROGRESS_UPDATE_LANGUAGES = [
+	"auto",
+	"zh",
+	"en"
+];
+/**
+* 引导词正文。写法对齐 Kimi 的「进展更新」：先说清多步任务早期的思路，再报
+* 有意义的结论、阶段判断、长等待与阻塞；每条给一行标题，细节放正文；不重复
+* 没有变化的状态。开头与结尾两条被提成硬要求——没有它们，面板在任务的两端
+* 都是空的。
+*/
+const PROGRESS_GUIDANCE = [
+	"## Progress updates",
+	"",
+	"During multi-step work you can call `progress_update` to report progress without ending your turn and without spending a question: report, then keep working.",
+	"",
+	"**Two updates are mandatory — missing either one means the job is not finished:**",
+	"",
+	"- **Opening**: before the first tool call of the task, send one update stating the plan (which steps, what you touch first). The user must be able to redirect you before you disappear into execution.",
+	"- **Closing**: after the work is done and before your final answer, send one update stating the result (what changed, what was verified, what is left). The panel and the conversation both close on this line.",
+	"",
+	"Beyond those two, these moments are worth a report:",
+	"- **Early planning**: the opening update covers it; report again only when the plan really changes (different approach, smaller scope, a broken premise).",
+	"- **A meaningful conclusion**: a key fact, a root cause, a verified assumption — report the conclusion itself, not \"I just read a file\".",
+	"- **A stage judgement**: one phase ends and the next begins — one line on where things stand and what happens next.",
+	"- **Before a long wait**: a test run, an install, a build — say what you are waiting for and roughly how long.",
+	"- **When blocked**: missing information, missing permission, an external failure — say where you are stuck, what you will try next, or what you need from the user.",
+	"",
+	"How to write one:",
+	"- One short title line (plain text, no Markdown, no trailing period); the details go in the message body.",
+	"- The body uses light Markdown: one paragraph of prose plus a few bullets. **When several rows share fields, use a GFM pipe table** (header row plus a `| --- |` separator row) instead of one item per line.",
+	"- Do not repeat a status that has not changed: if the last update already said it is running, it needs no second report.",
+	"- A progress update is for the user, not for the log: write it in human words, do not restate tool arguments.",
+	"",
+	"When you run as a subagent: describe only your own subtask progress. Finishing your subtask is not the same as finishing the overall task — do not report the overall progress as done."
+].join("\n");
+/**
+* 每个语言档位对应的一句指令。
+*
+* 只约束输出的标题与正文，不约束引导词本身；三条都必须自洽——`auto` 不许在
+* 用户说中文时滑回英文，`zh`/`en` 则明确压过对话语言。
+*/
+const PROGRESS_LANGUAGE_DIRECTIVES = {
+	auto: "Write the title and the message of every progress update in the language the user is writing in, whatever it is. Follow the conversation; do not fall back to English unless the user does.",
+	zh: "Write the title and the message of every progress update in Simplified Chinese, even when the conversation is in another language.",
+	en: "Write the title and the message of every progress update in English, even when the conversation is in another language."
+};
+/**
+* 取一个语言档位的指令文本；未知取值按 `auto` 处理。
+* @param language - 配置里读到的语言档位。
+* @returns 追加到引导词末尾的一句指令。
+*/
+function progressLanguageDirective(language) {
+	return PROGRESS_LANGUAGE_DIRECTIVES[language] ?? PROGRESS_LANGUAGE_DIRECTIVES.auto;
+}
+/**
+* 生成提示词分节的文本提供者。
+*
+* 文本与开关无关，这是刻意的：系统提示是缓存前缀的第一段，会话中途改一个字
+* 就会让整段前缀失效、整段重新计费（Kimi 的缓存是内容前缀匹配）。开关的语义
+* 因此只留给工具自己——关闭时 `execute` 直接返回 `displayed:false`。
+* @param language - 读取当前输出语言的函数；缺省按 `auto` 处理。
+* @returns 引导词加语言指令。
+*/
+function progressSectionText(language = () => "auto") {
+	return () => PROGRESS_GUIDANCE + "\n\n" + progressLanguageDirective(language());
+}
+//#endregion
+//#region src/host/progress-updates/projection.ts
+/**
+* 「进展更新」的会话投影：把日志里的 progress_update 调用折叠成一条条进展。
+*
+* ## 为什么要有它
+*
+* 进展更新原来只活在进程内的一个 Map 里（`store.ts` 的环形缓冲）：重开对话、
+* 刷新页面、宿主重启之后那份状态就没了，用户看到的是「进展面板空了」。而数据其实
+* 一直没丢 —— `progress_update` 的每次调用本身就是一条 `tool/call` 会话事件，
+* 早已被 DSH 持久化。所以这里把**日志**当成唯一真源：事件提交时折叠一次，读的
+* 时候就是一份可以直接回放的历史。
+*
+* ## 为什么不 import 投影包
+*
+* `@deepseek-ai/dsh-session-projection` **不在** peerDependencies 里：本插件要
+* 同时支持 0.1.2-alpha.5 ~ 0.2.1-rc.2，那一串宿主里有的根本没有这个包，运行时
+* import 会让整个插件在那代宿主上装载失败。所以这里按**结构化类型**自己声明
+* 契约（与 `nudge.ts` 的 `NudgeSessionLookup` / `TurnBoundaryLookup` 同一套
+* 做法），运行时只经 `ctx.get('sessionProjections')` 拿服务。
+*
+* ## 折叠是日志重放路径，任何情况都不许抛错
+*
+* `apply` 在每条提交事件上跑一次。这里抛出一次，毁掉的不只是本单元：重放链路
+* 会当场断掉，会话可能连读都读不出来。所以对事件形状一律**不信任** —— 不是
+* tool/call、不是 progress_update、arguments 不是合法 JSON、message 不是字符串、
+* seq/time 不是数字 —— 全部原样返回**同一个 state 引用**（`Object.is` 相等，
+* 下游零工作）。
+*
+* ## id 为什么用 seq，还要带上会话 id
+*
+* 客户端（`src/client/progress-updates/host-source.ts` 的 `sameList`）按 id 比较
+* 两份快照，面板列表也拿 id 当 React key。时间戳会随重放时的时钟漂移，seq 不会：
+* 同一段日志重放两次必须得到**逐字相同**的 id。会话 id 后缀解决的是另一半问题 ——
+* 读值要合并整棵委派树（见 `index.ts` 的 `projectionUpdatesOf`），而 seq 在
+* 每个会话里都从 0 开始，只带 seq 的话根会话与子会话的第一条进展会撞 id。
+*
+* @module dsh-chatgpt-subscription/host/progress-updates/projection
+*/
+/** 投影键：宿主读状态、客户端取 wire 值都用这个名字。 */
+const PROGRESS_UPDATES_PROJECTION_KEY = "progressUpdates";
+/** 单条进展的 schema：与 `ProgressUpdate` 逐字同形。 */
+const UPDATE_SCHEMA = z.object({
+	id: z.string(),
+	title: z.string().optional(),
+	message: z.string(),
+	at: z.number(),
+	source: z.string().optional()
+});
+/** 折叠状态的 schema（宿主状态）。 */
+const progressUpdatesStateSchema = z.object({
+	updates: z.array(UPDATE_SCHEMA),
+	source: z.string().optional()
+});
+/** wire 值的 schema（客户端看到的数组）。 */
+const progressUpdatesViewSchema = z.array(UPDATE_SCHEMA);
+/**
+* 造一条进展的稳定 id。
+* @param seq - 事件在会话日志里的序号（重放稳定）。
+* @param source - 所属会话 id；拿不到时省略后缀。
+* @returns 形如 `pu-<seq>-<sessionId>` 的字符串。
+*/
+function updateIdOf(seq, source) {
+	return source === void 0 ? "pu-" + seq : "pu-" + seq + "-" + source;
+}
+/**
+* 读一个未知值为非空字符串。
+* @param value - 候选值。
+* @returns 非空字符串，其它类型的 undefined。
+*/
+function stringOf(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/**
+* 把 `tool/call` 里的 `arguments` 原文解析成进展内容。
+*
+* **任何一点不对就返回 undefined**（而不是抛错，也不是造一条半截进展）：这是重放
+* 路径，一条形状坏掉的历史事件只该被跳过。
+* @param raw - 工具入参 JSON 原文。
+* @returns 正文与（去空白后的）可选标题。
+*/
+function parseArguments(raw) {
+	if (typeof raw !== "string") return void 0;
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const record = value;
+	if (typeof record.message !== "string") return void 0;
+	const title = typeof record.title === "string" ? record.title.trim() : "";
+	return title === "" ? { message: record.message } : {
+		message: record.message,
+		title
+	};
+}
+/**
+* 把 PTC 子调用里的 `arguments`（**已解析的对象**）读成进展内容。
+*
+* 与 {@link parseArguments} 只差一层：那条路径拿到的是模型吐出的 JSON 原文，
+* 这条拿到的是宿主已经归一化过的对象（见 `dsh-tools` 的 `PtcDispatchEventData`）。
+* 同样是"任何一点不对就返回 undefined"，同样不抛错。
+* @param raw - 已归一化的入参对象。
+* @returns 正文与（去空白后的）可选标题。
+*/
+function parseDispatchedArguments(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return void 0;
+	const record = raw;
+	if (typeof record.message !== "string") return void 0;
+	const title = typeof record.title === "string" ? record.title.trim() : "";
+	return title === "" ? { message: record.message } : {
+		message: record.message,
+		title
+	};
+}
+/**
+* 造一个进展折叠单元。
+*
+* 每次登记都要一份**新的**定义对象：它是纯函数集合，没有跨会话的状态，但把
+* `init` 闭包里的会话头漏进来就会把不同会话串成一份。
+* @returns 可交给 `sessionProjections.register` 的定义。
+*/
+function progressUpdatesProjection() {
+	return {
+		key: PROGRESS_UPDATES_PROJECTION_KEY,
+		stateVersion: 2,
+		stateSchema: progressUpdatesStateSchema,
+		init(header) {
+			const source = stringOf(header?.id);
+			return source === void 0 ? { updates: [] } : {
+				updates: [],
+				source
+			};
+		},
+		apply(state, event) {
+			const isNative = event?.type === "tool/call";
+			const isDispatch = event?.type === "tool/ptc-dispatch";
+			if (!isNative && !isDispatch) return state;
+			const data = event.data;
+			if (typeof data !== "object" || data === null) return state;
+			if (data.name !== "progress_update") return state;
+			const body = isNative ? parseArguments(data.arguments) : parseDispatchedArguments(data.arguments);
+			if (body === void 0) return state;
+			const seq = event.seq;
+			if (typeof seq !== "number" || !Number.isFinite(seq)) return state;
+			const at = event.time;
+			if (typeof at !== "number" || !Number.isFinite(at)) return state;
+			const update = {
+				id: updateIdOf(seq, state.source),
+				message: body.message,
+				at,
+				...body.title === void 0 ? {} : { title: body.title },
+				...state.source === void 0 ? {} : { source: state.source }
+			};
+			return {
+				...state,
+				updates: capUpdates([...state.updates, update])
+			};
+		},
+		wire: {
+			viewSchema: progressUpdatesViewSchema,
+			view: (state) => state.updates
+		}
+	};
+}
+/**
+* 读一个会话上折叠出来的进展。
+*
+* 两条读取路径，都按**不可用就当没读到**处理（返回 undefined，调用方回退到内存
+* 实现）：先问 `stateOf`（宿主状态，最直接），没有再问 `snapshot`（wire 切面，
+* 老一点的投影服务上只有它）。读出来的值一律过 schema，形状不对就当投影不可用 ——
+* 宁可用进程内那份，也不要把一份坏数据渲染成历史。
+* @param projections - 会话投影服务。
+* @param session - 会话对象。
+* @returns 该会话的进展；投影不可用时 undefined。
+*/
+function readProjectedUpdates(projections, session) {
+	const stateOf = projections.stateOf;
+	if (typeof stateOf === "function") {
+		let state;
+		try {
+			state = stateOf.call(projections, session, PROGRESS_UPDATES_PROJECTION_KEY);
+		} catch {
+			return;
+		}
+		if (state === void 0) return void 0;
+		const parsed = progressUpdatesStateSchema.safeParse(state);
+		return parsed.success ? parsed.data.updates : void 0;
+	}
+	const snapshot = projections.snapshot;
+	if (typeof snapshot !== "function") return void 0;
+	let values;
+	try {
+		values = snapshot.call(projections, session, [PROGRESS_UPDATES_PROJECTION_KEY])?.values;
+	} catch {
+		return;
+	}
+	if (values === void 0) return void 0;
+	const parsed = progressUpdatesViewSchema.safeParse(values[PROGRESS_UPDATES_PROJECTION_KEY]);
+	return parsed.success ? parsed.data : void 0;
+}
+/**
+* 把多个会话的进展合并成一份。
+*
+* 按 `at` 升序排（同一毫秒时按输入顺序，JS 的排序是稳定的：传入方把"被查询的
+* 会话自己"放在最前面），再按 {@link MAX_UPDATES} 截断保留最新的。整棵委派树共用
+* 一份进展是今天的语义，所以合并后的上限与单会话一致，不随子会话数量膨胀。
+* @param lists - 各会话各自的进展（每条已各自截断过）。
+* @returns 合并后的进展，最多 {@link MAX_UPDATES} 条。
+*/
+function mergeProjectedUpdates(lists) {
+	const merged = [].concat(...lists.map((list) => [...list]));
+	merged.sort((left, right) => left.at - right.at);
+	return capUpdates(merged);
+}
+//#endregion
+//#region src/host/progress-updates/routes.ts
+/** 进展读取路由的完整路径。 */
+const PROGRESS_UPDATES_PATH = "/api/dsh-progress-updates/updates";
+/** 路由默认的 JSON 响应头。 */
+const JSON_HEADERS = {
+	"content-type": "application/json; charset=utf-8",
+	"referrer-policy": "no-referrer"
+};
+/**
+* 断言本次请求来自本机。
+*
+* 进展内容会包含用户在会话里做的事，属于个人数据，所以只有 loopback（桌面端
+* 自己）能读：socket 地址是权威判断，Host 头必须也是 loopback 权威（挡住 DNS
+* 重绑定），`X-Forwarded-For` 永远不信任。
+* @param request - 进来的 HTTP 请求。
+* @returns 是否放行。
+*/
+function isLoopbackRequest(request) {
+	if (!isLoopbackAddress(request.socket.remoteAddress)) return false;
+	const host = request.headers.host;
+	if (typeof host !== "string" || host === "") return false;
+	let hostname;
+	try {
+		hostname = new URL("http://" + host).hostname.toLowerCase();
+	} catch {
+		return false;
+	}
+	if (!isLoopbackHostname(hostname)) return false;
+	return request.headers["sec-fetch-site"] !== "cross-site";
+}
+/** socket 远端地址是否落在 loopback 范围（127/8、::1、IPv4-mapped）。 */
+function isLoopbackAddress(address) {
+	if (address === void 0) return false;
+	const normalized = address.toLowerCase();
+	if (normalized === "::1") return true;
+	if (normalized.startsWith("::ffff:")) return isIPv4Loopback(normalized.slice(7));
+	return isIPv4Loopback(normalized);
+}
+/** IPv4 127/8 判定（四段十进制，首段为 127）。 */
+function isIPv4Loopback(v4) {
+	const parts = v4.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** 主机名是否指向 loopback 权威（localhost、[::1]、127/8）。 */
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	return isIPv4Loopback(hostname);
+}
+/**
+* 写一个 JSON 响应。
+* @param res - 响应对象。
+* @param status - HTTP 状态码。
+* @param body - 要序列化的值。
+* @param headers - 追加或覆盖的头。
+*/
+function writeJson(res, status, body, headers = {}) {
+	res.writeHead(status, {
+		...JSON_HEADERS,
+		...headers
+	});
+	res.end(JSON.stringify(body));
+}
+/**
+* 进展读取路由：`GET /api/dsh-progress-updates/updates?session=<id>`。
+*
+* 返回 `{ updates: ProgressUpdate[] }`。响应带 no-store：这个列表随 agent 干活
+* 实时变化，缓存住就等于展示过期进展。
+* @param reader - 进展读取面。
+* @returns 可注册的 route。
+*/
+function makeProgressUpdatesRoute(reader) {
+	return {
+		kind: "exact",
+		path: PROGRESS_UPDATES_PATH,
+		handler: (req, res) => {
+			if (!isLoopbackRequest(req)) {
+				writeJson(res, 403, {
+					ok: false,
+					error: "forbidden: loopback-only"
+				});
+				return;
+			}
+			const session = new URL(req.url ?? "/", "http://127.0.0.1").searchParams.get("session") ?? "";
+			writeJson(res, 200, { updates: reader.updatesOf(session) }, { "cache-control": "no-store" });
+		}
+	};
+}
+//#endregion
+//#region src/host/progress-updates/index.ts
+/**
+* 读取一个配置字段，沿着 volatile 活引用取当前值。
+* @param field - 字段本身。
+* @returns 当前值，或字段缺失时的 undefined。
+*/
+function readProgressConfigField(field) {
+	if (field === void 0 || field === null) return void 0;
+	if (typeof field === "object" && typeof field.get === "function") return field.get();
+	return field;
+}
+/**
+* 解析一次读取的有效设置：每次调用都重读活引用，因此设置保存后立刻生效。
+* @param config - 主入口收到的插件配置（活引用或普通值）。
+* @returns 生效的开关与催促阈值。
+*/
+function resolveProgressUpdatesSettings(config) {
+	const enabled = readProgressConfigField(config?.progressUpdates);
+	const threshold = readProgressConfigField(config?.progressUpdatesNudgeThreshold);
+	const language = readProgressConfigField(config?.progressUpdatesLanguage);
+	return {
+		enabled: enabled !== false,
+		nudgeThreshold: typeof threshold === "number" && Number.isSafeInteger(threshold) && threshold > 0 ? threshold : 8,
+		language: language !== void 0 && PROGRESS_UPDATE_LANGUAGES.includes(language) ? language : "auto"
+	};
+}
+/** 血缘回溯的深度上限：与 `nudge.ts` 的 `counterSessionIdOf` 同一个数。 */
+const LINEAGE_DEPTH_LIMIT = 16;
+/**
+* 找出一个会话的全部子孙（广度优先，只看 `sessions.list()` 里活跃的那些）。
+*
+* 重开对话之后历史子孙并不在 `list()` 里 —— 那时它们各自的进展本来就取不到，
+* 这里能做的只是把**当前活跃**的那几支合进来，剩下的等它们 attach。
+* @param rootId - 祖先会话 id。
+* @param sessions - 会话服务。
+* @returns 子孙会话（不含根自己），按发现顺序。
+*/
+function descendantSessionsOf(rootId, sessions) {
+	const list = sessions.list;
+	if (typeof list !== "function") return [];
+	let all;
+	try {
+		all = list.call(sessions);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(all) || all.length === 0) return [];
+	/** 父会话 id → 直接子会话。 */
+	const childrenOf = /* @__PURE__ */ new Map();
+	for (const session of all) {
+		const parent = typeof session?.header?.parentSession === "string" ? session.header.parentSession : void 0;
+		if (parent === void 0) continue;
+		const bucket = childrenOf.get(parent);
+		if (bucket === void 0) childrenOf.set(parent, [session]);
+		else bucket.push(session);
+	}
+	const found = [];
+	const seen = /* @__PURE__ */ new Set([rootId]);
+	let frontier = [rootId];
+	for (let depth = 0; depth < LINEAGE_DEPTH_LIMIT && frontier.length > 0; depth += 1) {
+		const next = [];
+		for (const parentId of frontier) for (const child of childrenOf.get(parentId) ?? []) {
+			const childId = typeof child.header?.id === "string" ? child.header.id : void 0;
+			if (childId !== void 0) {
+				if (seen.has(childId)) continue;
+				seen.add(childId);
+				next.push(childId);
+			}
+			found.push(child);
+		}
+		frontier = next;
+	}
+	return found;
+}
+/**
+* 已挂载的模块登记表，走一个 global symbol：同一个包的两份模块实例（npm 拷贝与
+* 仓库 link）仍然共享一次判定，而重复注册同名工具或同名提示词分节会让宿主启动
+* 失败。
+*/
+const MOUNTED = Symbol.for("dsh-chatgpt-subscription.mounted-modules");
+/** 本模块在登记表里的名字。 */
+const MODULE_ID = "progress-updates";
+/**
+* 把一条催促挂到一个 post-execute 决策上，同时保住该决策原有的附加上下文。
+* @param decision - `next()` 交回来的决策。
+* @param context - 要追加的催促上下文。
+* @returns 追加后的决策（形状不变）。
+*/
+function withNudge(decision, context) {
+	const additionalContexts = [...decision.additionalContexts ?? [], context];
+	if (decision.kind === "block") return {
+		kind: "block",
+		feedback: decision.feedback,
+		additionalContexts
+	};
+	if (decision.value !== void 0) return {
+		kind: "accept",
+		value: decision.value,
+		additionalContexts
+	};
+	if (decision.content !== void 0) return {
+		kind: "accept",
+		content: decision.content,
+		additionalContexts
+	};
+	return {
+		kind: "accept",
+		additionalContexts
+	};
+}
+/**
+* 单实例守卫：本模块已挂载时放弃本次安装。
+* @param ctx - 宿主上下文。
+* @returns 释放函数（交出挂载权）；已经挂载过时返回 undefined。
+*/
+function claimMount(ctx) {
+	const registry = globalThis;
+	const existing = registry[MOUNTED];
+	const mounted = existing instanceof Set ? existing : /* @__PURE__ */ new Set();
+	if (existing !== mounted) registry[MOUNTED] = mounted;
+	if (mounted.has(MODULE_ID)) return void 0;
+	mounted.add(MODULE_ID);
+	const release = () => {
+		mounted.delete(MODULE_ID);
+	};
+	if (typeof ctx.effect === "function") ctx.effect(() => release, "dsh-chatgpt-subscription: progress updates mount");
+	return release;
+}
+/**
+* 挂载「进展更新」的宿主半边。
+* @param ctx - 宿主插件上下文。
+* @param options - 挂载选项（设置读取器）。
+* @returns 卸载函数；重复挂载时返回一个空操作。
+*/
+function installProgressUpdates(ctx, options) {
+	const release = claimMount(ctx);
+	if (release === void 0) return () => void 0;
+	/** 每次调用重新读服务：宿主树可能在本模块挂载之后才 settle，读一次存下来会漏。 */
+	const serviceOf = (name) => {
+		const read = ctx.get;
+		return typeof read === "function" ? read.call(ctx, name) : void 0;
+	};
+	/** 登记一个副作用；上下文没有 effect 时立即执行（测试用假上下文）。 */
+	const track = (execute, label) => {
+		if (typeof ctx.effect === "function") ctx.effect(execute, label);
+		else execute();
+	};
+	/** 会话查找表：够把子会话回溯到顶层祖先即可。 */
+	const sessionsOf = () => serviceOf("sessions");
+	/** 会话投影服务：只用来读 turnBoundary，把同一个模型步里的多条工具结果合并成一轮。 */
+	const projectionsOf = () => serviceOf("sessionProjections");
+	/**
+	* 会话投影服务：登记/读取进展折叠。
+	*
+	* 与 {@link projectionsOf} 是同一个服务的两份结构化视图（`nudge` 那边只读
+	* `turnBoundary`，这里读写进展键），分开写是为了让各自的类型面只声明自己真正
+	* 用到的成员。服务缺席（老宿主、没装 agent-loop）时是 undefined。
+	*/
+	const sessionProjectionsOf = () => serviceOf("sessionProjections");
+	/**
+	* 登记进展折叠单元。服务缺席时**安静跳过**：这是可选服务，缺了只是回到内存
+	* 实现（今天的行为），不是一次安装失败。
+	*/
+	track(() => {
+		const projections = sessionProjectionsOf();
+		if (typeof projections?.register !== "function") return () => void 0;
+		try {
+			return projections.register(progressUpdatesProjection());
+		} catch (error) {
+			serviceOf("logger")?.warn("[dsh-chatgpt-subscription] progress updates projection not registered: " + String(error));
+			return () => void 0;
+		}
+	}, "dsh-chatgpt-subscription: progress update projection");
+	/** 会话维度状态；键是计数会话 id（子会话已归并到顶层祖先）。 */
+	const stores = /* @__PURE__ */ new Map();
+	/** 已经计过数的「步」：同一个模型步里的后续工具结果不再重复计数。 */
+	const countedSteps = /* @__PURE__ */ new Map();
+	/**
+	* 取一个计数会话的 store，按需创建。
+	* @param key - 计数会话 id。
+	* @returns 该会话的 store。
+	*/
+	const storeOf = (key) => {
+		let store = stores.get(key);
+		if (store === void 0) {
+			store = createProgressUpdateStore();
+			stores.set(key, store);
+		}
+		return store;
+	};
+	/**
+	* 一次工具调用归属的计数会话 id。
+	* @param exec - 工具执行上下文（或任意带 agent 的对象）。
+	* @returns 计数会话 id；判定不出来时归入 `session` 这一桶。
+	*/
+	const counterKeyOf = (exec) => counterSessionIdOf(exec?.agent, sessionsOf()) ?? "session";
+	/**
+	* 从会话日志折叠出来的进展 —— 面板的**首选**取数路径。
+	*
+	* 读三样东西，任缺其一就返回 undefined，让调用方回退到内存实现：
+	* 会话服务、投影服务，以及"这个 id 对应的会话对象"。最后一件事在重开对话之后
+	* 并不必然成立：`sessions` 里只有**活跃**会话，历史会话要等宿主 attach 上来
+	* 才读得到 —— 那之前面板显示的是内存里那一份（通常为空），attach 之后同一个
+	* 轮询请求就能读到完整历史。
+	*
+	* 合并范围是**整棵委派树**：今天的语义是一个子会话的进展归并到顶层祖先的桶里，
+	* 折叠之后靠 `header.parentSession` 把子孙找回来（与 `nudge.ts` 的 lineage
+	* 走法同一套，深度上限 16 是防一条损坏的日志把这里变成死循环），按 `at` 升序
+	* 排 —— 子会话汇报的进展因此落在它真正发生的那个时间点上，而不是全排在最后。
+	* @param sessionId - 浏览器问的会话 id。
+	* @returns 合并后的进展；这条路径不可用时 undefined。
+	*/
+	const projectionUpdatesOf = (sessionId) => {
+		if (sessionId === "") return void 0;
+		const sessions = sessionsOf();
+		if (sessions === void 0) return void 0;
+		const projections = sessionProjectionsOf();
+		if (projections === void 0) return void 0;
+		let own;
+		try {
+			own = sessions.get?.(sessionId);
+		} catch {
+			return;
+		}
+		if (own === void 0) return void 0;
+		const updates = readProjectedUpdates(projections, own);
+		if (updates === void 0) return void 0;
+		const lists = [updates];
+		for (const child of descendantSessionsOf(sessionId, sessions)) {
+			const childUpdates = readProjectedUpdates(projections, child);
+			if (childUpdates !== void 0) lists.push(childUpdates);
+		}
+		return lists.length === 1 ? updates : mergeProjectedUpdates(lists);
+	};
+	/**
+	* 浏览器半边的读取面：给定会话 id 就交出那个会话的进展快照。
+	*
+	* **先投影、后内存**：投影是从已持久化的会话日志折出来的，重开对话、刷新页面、
+	* 宿主重启之后都还在；内存 `stores` 只在投影这条路不可用时兜底（老宿主没有
+	* 投影服务、会话还没 attach、或者压根没装会话服务）。
+	*
+	* 请求不带 session（或带一个本进程没见过的 id）时，回退到那个"合成会话桶"：
+	* 这是单会话部署里的常态，也是插件第一次被调用、祖先血缘还没建立时的落点。
+	*/
+	const reader = { updatesOf: (sessionId) => {
+		const projected = projectionUpdatesOf(sessionId);
+		if (projected !== void 0) return projected;
+		const direct = stores.get(sessionId);
+		if (direct !== void 0) return direct.state().updates;
+		if (sessionId !== "") {
+			const merged = counterSessionIdOf({ id: sessionId }, sessionsOf());
+			const parent = merged === void 0 ? void 0 : stores.get(merged);
+			if (parent !== void 0) return parent.state().updates;
+			return [];
+		}
+		const fallback = stores.get("session");
+		return fallback === void 0 ? [] : fallback.state().updates;
+	} };
+	track(() => {
+		const tools = serviceOf("tools");
+		if (tools === void 0) {
+			serviceOf("logger")?.warn("[dsh-chatgpt-subscription] progress updates tool skipped: no tools service");
+			return () => void 0;
+		}
+		const tool = createProgressUpdateTool({
+			isEnabled: () => options.settings().enabled,
+			sink: () => ({ push: (update) => {
+				if (!options.settings().enabled) return false;
+				storeOf(update.source ?? "session").push(update);
+				return true;
+			} }),
+			sourceOf: (exec) => counterKeyOf(exec)
+		});
+		return tools.register(tool);
+	}, "dsh-chatgpt-subscription: progress update tool");
+	track(() => {
+		const systemPrompt = serviceOf("systemPrompt");
+		if (systemPrompt === void 0) return () => void 0;
+		return systemPrompt.section({
+			name: PROGRESS_SECTION_NAME,
+			order: 220,
+			text: progressSectionText(() => options.settings().language)
+		});
+	}, "dsh-chatgpt-subscription: progress update prompt section");
+	track(() => {
+		const webServer = serviceOf("webServer");
+		if (webServer === void 0) return () => void 0;
+		return webServer.register(makeProgressUpdatesRoute(reader));
+	}, "dsh-chatgpt-subscription: progress update route");
+	const disposeListener = ctx.on?.("tools/post-execute", (async (exec, _result, next) => {
+		const decision = await next();
+		const current = options.settings();
+		if (!current.enabled) return decision;
+		const key = counterKeyOf(exec);
+		const store = storeOf(key);
+		if (exec.name === "progress_update") {
+			store.markUpdated();
+			const reportedStep = stepKeyOf(exec.agent, projectionsOf());
+			if (reportedStep !== void 0) countedSteps.set(key, reportedStep);
+			return decision;
+		}
+		const step = stepKeyOf(exec.agent, projectionsOf());
+		if (step !== void 0) {
+			if (countedSteps.get(key) === step) return decision;
+			countedSteps.set(key, step);
+		}
+		const rounds = store.bumpRound();
+		if (!(current.nudgeThreshold === 8 ? shouldNudge(rounds) : rounds >= current.nudgeThreshold)) return decision;
+		const nudges = store.markNudged().nudges;
+		return withNudge(decision, createNudgeContext(nudges));
+	}));
+	return () => {
+		disposeListener?.();
+		stores.clear();
+		countedSteps.clear();
+		release();
+	};
+}
+//#endregion
+//#region src/entry-progress-updates.ts
+/** Loader 行名；patch 里的行 id 另由 bundle 决定。 */
+const name = "dsh-chatgpt-subscription-progress-updates";
+/**
+* 这一行不为任何服务等待。
+*
+* `installProgressUpdates` 逐个用 `ctx.get()` 探可选服务（tools、systemPrompt、
+* sessions、sessionProjections、webServer），缺哪个就退化成更弱的实现；把它们的
+* 名字写进 `inject` 反而会让没装 agent-loop 的宿主整行挂不上——那是这一行原本的
+* 独立性所要避免的事。
+*/
+const inject = [];
+/**
+* 设置是怎么到这一行的。
+*
+* 字段声明在核心入口（见文件头的理由）。行顺序不归这一行管，所以两种顺序都要成立：
+* 核心先挂上就直接递交；这一行先挂上就把读取器寄存下来，核心一调用就取走。
+*/
+let attachedSettings;
+let waitingForSettings;
+/**
+* 由核心入口在挂载时调用，把它的 `volatile` 设置读面交给这一行。
+*
+* 幂等：重复递交以最后一次为准（核心重挂时设置引用会换一份新的）。
+* @param read - 每次调用都重读活引用，返回当前的开关、阈值与语言。
+*/
+function attachProgressSettings(read) {
+	attachedSettings = read;
+	const waiting = waitingForSettings;
+	waitingForSettings = void 0;
+	waiting?.(read);
+}
+/**
+* 还没有设置就不挂。
+*
+* 用一个写死的默认值假装在跑，会让「设置显示打开」与「实际没挂」同时成立——那正是
+* 这一行第一版的样子。等核心把它交过来，再挂。
+* @returns 一个读完引用就返回当前设置的函数。
+*/
+async function readSettings() {
+	if (attachedSettings !== void 0) return attachedSettings;
+	return await new Promise((resolve) => {
+		waitingForSettings = resolve;
+	});
+}
+async function apply(ctx) {
+	const read = await readSettings();
+	ctx.effect(() => installProgressUpdates(ctx, { settings: read }), "dsh-progress-updates: host half");
+}
+//#endregion
+export { resolveProgressUpdatesSettings as a, name as i, attachProgressSettings as n, inject as r, apply as t };