@rexvane/piweb 0.3.20 → 0.3.21

package/src/lib/agent-manager.ts

@@ -6,7 +6,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
+import { formatSkillsForPrompt, generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
 import {
 	getResourceLoader,
 	createSessionResourceLoader,
@@ -63,6 +63,10 @@ interface Managed {
 	session: AgentSession | null;
 	creating: Promise<AgentSession> | null;
 	subscribers: Set<(seq: number, json: string) => void>;
+	/** 长轮询的浏览器在两次请求之间没有订阅，到这个时间点之前仍算有人在看（见 holdViewer） */
+	viewerGraceUntil?: number;
+	/** 本轮已排队推送上下文分项（publishContextBreakdown 合并同一轮的多次触发） */
+	breakdownQueued?: boolean;
 	buffer: { seq: number; json: string }[];
 	seq: number;
 	/**
@@ -579,6 +583,7 @@ function translate(m: Managed, evt: AgentSessionEvent): void {
 				ts: now,
 			});
 			publishUsage(m);
+			publishContextBreakdown(m);
 			if ((evt as any).reason === "manual") {
 				publish(m, { type: "status", isStreaming: isManagedBusy(m), state: isManagedBusy(m) ? "running" : "idle", ts: now });
 				if (m.resourceReloadPending) queueMicrotask(() => void reloadManagedResources(m));
@@ -733,45 +738,46 @@ function loadContextResources(cwd: string, loader: AgentSession["resourceLoader"
 	];
 }
 
+const SKILLS_SECTION_START = "The following skills provide specialized instructions";
+const SKILLS_SECTION_END = "</available_skills>";
+
 /**
  * 上下文占用的服务端估算分项。systemPrompt 是整段拼接（正文 + memory + skills + 工具列表），
  * 所以 Memory / Skills 从资源加载器与 systemPrompt 的资源段差分得出：
  * SDK 的拼接顺序固定为 正文 → context files → skills → 工具列表，按内容定位切块。
+ *
+ * 冷会话（只浏览历史、不冷启动 agent）拿不到组装后的 system prompt 和工具定义，这三项为 0、标 cold；
+ * Memory / Skills / Compacted / Buffer 不依赖 agent，照常从发现缓存、会话文件和设置里算，
+ * 不能因为没启动就整块归零（那样弹窗只剩消息几类）。
  */
-async function buildContextBreakdown(
-	cwd: string,
-	session: AgentSession | null,
-	resources: ContextResource[],
-): Promise<ContextBreakdown> {
+async function buildContextBreakdown(m: Managed, resources: ContextResource[]): Promise<ContextBreakdown> {
+	const session = m.session;
 	const breakdown: ContextBreakdown = {
 		systemPrompt: 0, systemTools: 0, customTools: 0, memory: 0, skills: 0, compacted: 0, autoCompactBuffer: 0,
+		...(session ? {} : { cold: true }),
 	};
-	if (!session) return breakdown;
-	try {
-		const prompt = session.systemPrompt ?? "";
-		// Memory：AGENTS.md 等注入文件（contextResources 的 project 部分）
-		const memoryText = resources.filter((r) => r.source === "project").map((r) => r.content).join("\n\n");
-		breakdown.memory = estimateTokensOf(memoryText);
-		// Skills：从资源加载器取技能清单，按 SDK 的 formatSkillsForPrompt 段落定位。
-		// 该段落没有 Markdown 标题（原文以 "The following skills provide specialized instructions…" 开头，
-		// 结尾是 </available_skills>），以前按 "## Skills" 找永远找不到，技能段一直是 0。
+	// Memory：AGENTS.md 等注入文件（contextResources 的 project 部分）
+	const memoryText = resources.filter((r) => r.source === "project").map((r) => r.content).join("\n\n");
+	breakdown.memory = estimateTokensOf(memoryText);
+	if (session) {
 		try {
-			const { skills } = session.resourceLoader.getSkills();
-			if (skills.length && prompt) {
-				const start = prompt.indexOf("The following skills provide specialized instructions");
-				const end = prompt.indexOf("</available_skills>");
-				if (start >= 0 && end > start) breakdown.skills = estimateTokensOf(prompt.slice(start, end + "</available_skills>".length));
+			const prompt = session.systemPrompt ?? "";
+			// Skills：按 SDK 的 formatSkillsForPrompt 段落定位。该段落没有 Markdown 标题（以
+			// "The following skills provide specialized instructions…" 开头、</available_skills> 结尾），
+			// 以前按 "## Skills" 找永远找不到，技能段一直是 0。
+			try {
+				if (session.resourceLoader.getSkills().skills.length && prompt) {
+					const start = prompt.indexOf(SKILLS_SECTION_START);
+					const end = prompt.indexOf(SKILLS_SECTION_END);
+					if (start >= 0 && end > start) breakdown.skills = estimateTokensOf(prompt.slice(start, end + SKILLS_SECTION_END.length));
+				}
+			} catch {
+				/* loader 不可用则跳过 */
 			}
-		} catch {
-			/* loader 不可用则跳过 */
-		}
-		// System Prompt 正文 = 全文减去资源段与 skills 段的近似差分，下限 0
-		const estimatedSections = breakdown.memory + breakdown.skills;
-		breakdown.systemPrompt = Math.max(0, estimateTokensOf(prompt) - estimatedSections);
-		// 工具：builtin 与扩展注册的分开统计（schema + description + guidelines 序列化估算）
-		try {
-			const tools = session.getAllTools();
-			for (const tool of tools) {
+			// System Prompt 正文 = 全文减去资源段与 skills 段的近似差分，下限 0
+			breakdown.systemPrompt = Math.max(0, estimateTokensOf(prompt) - breakdown.memory - breakdown.skills);
+			// 工具：builtin 与扩展注册的分开统计（schema + description + guidelines 序列化估算）
+			for (const tool of session.getAllTools()) {
 				const size = estimateTokensOf(JSON.stringify({
 					name: tool.name,
 					description: tool.description,
@@ -782,38 +788,61 @@ async function buildContextBreakdown(
 				else breakdown.customTools += size;
 			}
 		} catch {
-			/* getAllTools 不可用则跳过 */
+			/* systemPrompt / getAllTools 不可用则保持 0 */
 		}
-		// 最新一次压缩的摘要
+	} else {
+		// 冷会话：技能段用发现缓存里的清单按 SDK 同一个格式化函数估算（启动后改用实际 prompt 里的那段）
 		try {
-			const entries = m_smEntries(session);
-			for (let i = entries.length - 1; i >= 0; i -= 1) {
-				const entry = entries[i] as { type?: string; summary?: string };
-				if (entry?.type === "compaction" && typeof entry.summary === "string") {
-					breakdown.compacted = estimateTokensOf(entry.summary);
-					break;
-				}
-			}
+			const loader = peekResourceLoader(m.cwd) ?? getResourceLoader(m.cwd);
+			breakdown.skills = estimateTokensOf(formatSkillsForPrompt(loader.getSkills().skills).trim());
 		} catch {
-			/* entries 不可用则跳过 */
+			/* 发现缓存还没好则跳过 */
 		}
-		// auto-compact 预留 = compaction.reserveTokens（启用时）
-		try {
-			const settings = await getPiSettings();
-			if (settings.compaction.enabled) breakdown.autoCompactBuffer = settings.compaction.reserveTokens;
-		} catch {
-			/* 设置读取失败则保持 0 */
+	}
+	// 最新一次压缩的摘要（会话文件里就有，冷热都能算）
+	try {
+		const entries = m.sm.getEntries() as unknown as { type?: string; summary?: string }[];
+		for (let i = entries.length - 1; i >= 0; i -= 1) {
+			const entry = entries[i];
+			if (entry?.type === "compaction" && typeof entry.summary === "string") {
+				breakdown.compacted = estimateTokensOf(entry.summary);
+				break;
+			}
 		}
 	} catch {
-		/* systemPrompt 不可用则保持 0 */
+		/* entries 不可用则跳过 */
+	}
+	// auto-compact 预留 = compaction.reserveTokens（启用时）
+	try {
+		const settings = await getPiSettings();
+		if (settings.compaction.enabled) breakdown.autoCompactBuffer = settings.compaction.reserveTokens;
+	} catch {
+		/* 设置读取失败则保持 0 */
 	}
 	return breakdown;
 }
 
-/** SessionManager 的 getEntries 经由 session 暴露的形态（各版本字段名有差异，这里宽松取） */
-function m_smEntries(session: AgentSession): unknown[] {
-	const s = session as unknown as { sm?: { getEntries?: () => unknown[] }; sessionManager?: { getEntries?: () => unknown[] } };
-	return s.sm?.getEntries?.() ?? s.sessionManager?.getEntries?.() ?? [];
+/**
+ * 分项变了就推一次（会话启动、工具 / 资源重载、压缩之后）。分项以前只随快照下发：
+ * 打开冷会话时是 0，之后会话启动了弹窗也一直停在那份 0 上，直到刷新页面。
+ * 同一轮里多次触发（启动时 publishTools + publishResources）合并成一次。
+ */
+function publishContextBreakdown(m: Managed): void {
+	if (m.breakdownQueued || m.disposed) return;
+	m.breakdownQueued = true;
+	queueMicrotask(() => {
+		m.breakdownQueued = false;
+		if (m.disposed) return;
+		let resources: ContextResource[] = [];
+		try {
+			resources = loadContextResources(m.cwd, m.session?.resourceLoader);
+		} catch {
+			/* 读不到注入文件就按空算 Memory */
+		}
+		void buildContextBreakdown(m, resources).then((breakdown) => {
+			if (!m.disposed) publish(m, { type: "context_breakdown", breakdown, ts: Date.now() });
+		}, () => undefined);
+	});
 }
 
 /** resources 已经算过（快照）就传进来，免得资源发现结果再读一遍 */
@@ -877,7 +906,7 @@ export async function ensureSession(m: Managed): Promise<AgentSession> {
 			installSessionPolicy(m, session);
 			applyToolPolicy(m, session);
 			session.subscribe((evt) => { if (!m.disposed) translate(m, evt); });
-			const ui = createExtensionUiBridge({ publish: (evt) => publish(m, evt), hasViewers: () => !m.disposed && m.subscribers.size > 0 });
+			const ui = createExtensionUiBridge({ publish: (evt) => publish(m, evt), hasViewers: () => !m.disposed && hasViewers(m) });
 			m.ui = ui;
 			await session.bindExtensions({
 				mode: "rpc",
@@ -989,6 +1018,7 @@ function shutdownSession(session: AgentSession): Promise<void> {
 
 function publishTools(m: Managed, session: AgentSession): void {
 	publish(m, { type: "tools", active: listActiveTools(session), all: listAllToolNames(session), toolPreset: m.toolPreset, customActiveTools: m.customActiveTools ?? null, ts: Date.now() });
+	publishContextBreakdown(m);
 }
 
 /** SDK reload 自动启用扩展工具，注册新工具也会刷新全集；统一在激活边界收敛到服务端选择。 */
@@ -1086,13 +1116,13 @@ export async function disposeSessionPath(sessionPath: string): Promise<void> {
 export function reap(): void {
 	const now = Date.now();
 	for (const m of [...sessions.values()]) {
-		if (m.subscribers.size > 0 || now - m.lastActive <= IDLE_MS) continue;
+		if (hasViewers(m) || now - m.lastActive <= IDLE_MS) continue;
 		if (!m.creating && !isManagedBusy(m)) disposeSession(m);
 	}
 	const active = [...sessions.values()].filter((m) => m.session);
 	if (active.length > MAX_ACTIVE) {
 		const evictable = active
-			.filter((m) => !m.creating && !isManagedBusy(m) && m.subscribers.size === 0)
+			.filter((m) => !m.creating && !isManagedBusy(m) && !hasViewers(m))
 			.sort((a, b) => a.lastActive - b.lastActive);
 		for (const m of evictable.slice(0, active.length - MAX_ACTIVE)) disposeSession(m);
 	}
@@ -1166,6 +1196,7 @@ function collectResources(m: Managed): ResourceBundle {
 
 export function publishResources(m: Managed): void {
 	publish(m, { type: "resources", ...collectResources(m), ts: Date.now() });
+	publishContextBreakdown(m);
 }
 
 /**
@@ -1198,7 +1229,7 @@ export async function reloadSessionsForCwd(cwd?: string): Promise<number> {
 		if (cwd && key(m.cwd) !== key(cwd)) continue;
 		if (!m.session) {
 			// 冷会话没有扩展运行时可重建，但页面可能开着：把新清单（模板 / 技能 / 信任）推过去
-			if (m.subscribers.size > 0) publishResources(m);
+			if (hasViewers(m)) publishResources(m);
 			continue;
 		}
 		if (m.creating || isManagedBusy(m)) {
@@ -1359,7 +1390,7 @@ export async function buildSnapshot(m: Managed): Promise<WebSnapshot> {
 	// 服务端可得的上下文分项（估算；失败不影响快照）
 	let contextBreakdown: ContextBreakdown | undefined;
 	try {
-		contextBreakdown = await buildContextBreakdown(m.cwd, m.session, contextResources);
+		contextBreakdown = await buildContextBreakdown(m, contextResources);
 	} catch {
 		contextBreakdown = undefined;
 	}
@@ -1446,6 +1477,18 @@ export function unsubscribe(m: Managed, send: (seq: number, json: string) => voi
 	m.subscribers.delete(send);
 }
 
+/**
+ * 长轮询（快速隧道）的一次请求结束时调用：下一次请求到来前的这段空档仍算有人在看，
+ * 否则扩展弹窗会被当成无人值守直接取默认值，会话也可能被当成没人开着回收掉。
+ */
+export function holdViewer(m: Managed, ms: number): void {
+	m.viewerGraceUntil = Math.max(m.viewerGraceUntil ?? 0, Date.now() + ms);
+}
+
+function hasViewers(m: Managed): boolean {
+	return m.subscribers.size > 0 || (m.viewerGraceUntil ?? 0) > Date.now();
+}
+
 // ---------- 命令执行 ----------
 
 export interface CommandResult {

package/src/lib/chat/event-stream.ts

@@ -0,0 +1,113 @@
+/**
+ * 会话事件的长轮询通道（浏览器端）。
+ *
+ * Cloudflare 快速隧道（远程连接的公网入口）不支持 SSE：流式响应被攒成 128KB 一块才转发，
+ * 不满一块的尾巴一直卡着——打开会话等不到完整快照（一直转圈），聊天也不流式。
+ * 隧道下改成一次次短请求：服务端把这一批事件发完就结束响应（结束时隧道一定吐干净），
+ * 浏览器带着 Last-Event-ID 立刻再来一次，漏掉的事件由服务端从环形缓冲补发。
+ * 线上格式仍是 SSE 文本，服务端两种模式共用一套写法。
+ */
+
+/** 只有快速隧道需要轮询；局域网、本机、用户自己的反向代理都照旧走 SSE */
+export function usesEventPolling(hostname: string): boolean {
+	return hostname.toLowerCase().endsWith(".trycloudflare.com");
+}
+
+export interface SseFrame {
+	id?: string;
+	event?: string;
+	data: string;
+}
+
+/** 解析一段完整的 SSE 文本（只认本项目用到的 id / event / data，注释行跳过） */
+export function parseSseText(text: string): SseFrame[] {
+	const frames: SseFrame[] = [];
+	for (const block of text.split(/\r?\n\r?\n/)) {
+		const frame: SseFrame = { data: "" };
+		const data: string[] = [];
+		for (const line of block.split(/\r?\n/)) {
+			if (!line || line.startsWith(":")) continue;
+			const colon = line.indexOf(":");
+			const field = colon === -1 ? line : line.slice(0, colon);
+			let value = colon === -1 ? "" : line.slice(colon + 1);
+			if (value.startsWith(" ")) value = value.slice(1);
+			if (field === "data") data.push(value);
+			else if (field === "id") frame.id = value;
+			else if (field === "event") frame.event = value;
+		}
+		if (!data.length) continue;
+		frame.data = data.join("\n");
+		frames.push(frame);
+	}
+	return frames;
+}
+
+export interface EventPollHandlers {
+	/** 一次请求成功返回（断开后恢复时也会再调） */
+	onOpen(): void;
+	onMessage(data: string): void;
+	/** 一次请求失败；之后按退避自动重试 */
+	onError(): void;
+}
+
+export interface EventPollOptions {
+	fetch?: typeof fetch;
+	/** 第 n 次连续失败后等多久再试 */
+	backoffMs?: (failures: number) => number;
+}
+
+const defaultBackoff = (failures: number) => Math.min(2000 * 2 ** (failures - 1), 30_000);
+
+export function pollEventStream(url: string, handlers: EventPollHandlers, { fetch: fetchImpl = fetch, backoffMs = defaultBackoff }: EventPollOptions = {}): { close(): void } {
+	const controller = new AbortController();
+	let closed = false;
+	let lastEventId: string | undefined;
+	let open = false;
+	let failures = 0;
+	const pollUrl = `${url}${url.includes("?") ? "&" : "?"}poll=1`;
+
+	const sleep = (ms: number) => new Promise<void>((resolve) => {
+		const timer = setTimeout(resolve, ms);
+		controller.signal.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+	});
+
+	void (async () => {
+		while (!closed) {
+			let frames: SseFrame[];
+			try {
+				const response = await fetchImpl(pollUrl, {
+					headers: lastEventId ? { "Last-Event-ID": lastEventId } : {},
+					cache: "no-store",
+					signal: controller.signal,
+				});
+				if (!response.ok) throw new Error(`events poll failed (${response.status})`);
+				frames = parseSseText(await response.text());
+			} catch {
+				if (closed) return;
+				open = false;
+				handlers.onError();
+				failures += 1;
+				await sleep(backoffMs(failures));
+				continue;
+			}
+			if (closed) return;
+			failures = 0;
+			if (!open) {
+				open = true;
+				handlers.onOpen();
+			}
+			for (const frame of frames) {
+				if (closed) return;
+				handlers.onMessage(frame.data);
+				if (frame.id !== undefined) lastEventId = frame.id;
+			}
+		}
+	})();
+
+	return {
+		close() {
+			closed = true;
+			controller.abort();
+		},
+	};
+}

package/src/lib/chat/stream-settings.ts

@@ -0,0 +1,192 @@
+/**
+ * 流式文字输出偏好：显示样式 / 推进速度 / 打字光标。
+ *
+ * 存 localStorage（piweb.streamStyle / piweb.streamSpeed / piweb.streamCaret），
+ * 模块级订阅：设置面板一改，正在流的那条回答在下一帧就换样式，不必重开会话；
+ * 跨标签页由 storage 事件同步。
+ *
+ * 推进量是纯函数 nextRevealEnd(target, shownLength, settings)：给定目标文本、已显示长度和偏好，
+ * 算出这一帧该显示到哪。不变量是「显示内容始终是目标前缀、单调增长、最终追平」——
+ * 见 tests/stream-settings.test.ts。
+ */
+
+export type StreamStyle = "smooth" | "instant" | "typewriter" | "fade";
+
+export interface StreamSettings {
+	/** 文字出现的方式 */
+	style: StreamStyle;
+	/** 推进速度档位 1..5（3 = 标准） */
+	speed: number;
+	/** 打字光标：流式期间在文字末尾闪烁 */
+	caret: boolean;
+}
+
+/** 设置面板里的展示顺序（即时排在最后：它是「不要平滑」的退路） */
+export const STREAM_STYLES: readonly StreamStyle[] = ["smooth", "typewriter", "fade", "instant"];
+export const STREAM_SPEED_MIN = 1;
+export const STREAM_SPEED_MAX = 5;
+export const DEFAULT_STREAM_SETTINGS: StreamSettings = { style: "smooth", speed: 3, caret: false };
+
+const KEY = {
+	style: "piweb.streamStyle",
+	speed: "piweb.streamSpeed",
+	caret: "piweb.streamCaret",
+} as const;
+
+/** 每帧间隔（约 60fps 起步）：档位越高越密 */
+const STEP_MS = [24, 20, 16, 12, 8];
+/** 平滑 / 渐显：每帧推进「积压 / 该值」，值越大追赶越缓、手感越匀（突发不再狂奔） */
+const SMOOTH_DIVISOR = [14, 10, 7, 5, 3];
+/** 平滑 / 渐显：每帧至少推进的字符数，保证收尾时也能走完 */
+const SMOOTH_MIN_CHARS = [1, 1, 1, 2, 3];
+/** 平滑 / 渐显：每帧至多推进的字符数——大块突发被摊到更多帧里缓缓出现，不会一口吞掉 */
+const SMOOTH_MAX_CHARS = [140, 110, 90, 70, 50];
+/** 打字机：每帧固定敲出的字符数 */
+const TYPEWRITER_CHARS = [1, 2, 3, 5, 8];
+/** 打字机也要有底线：积压超过约 1.5 秒的量就跟着加速，不出现「回答完了字还在爬」 */
+const TYPEWRITER_CATCHUP_DIVISOR = 90;
+
+export function isStreamStyle(value: string | null | undefined): value is StreamStyle {
+	return value === "smooth" || value === "instant" || value === "typewriter" || value === "fade";
+}
+
+export function clampStreamSpeed(value: number): number {
+	if (!Number.isFinite(value)) return DEFAULT_STREAM_SETTINGS.speed;
+	return Math.max(STREAM_SPEED_MIN, Math.min(STREAM_SPEED_MAX, Math.round(value)));
+}
+
+/** 这一档速度下每帧的间隔（毫秒） */
+export function streamStepMs(speed: number): number {
+	return STEP_MS[clampStreamSpeed(speed) - 1];
+}
+
+function readStored(): StreamSettings {
+	try {
+		const style = localStorage.getItem(KEY.style);
+		const speed = Number.parseInt(localStorage.getItem(KEY.speed) ?? "", 10);
+		const caret = localStorage.getItem(KEY.caret);
+		return {
+			style: isStreamStyle(style) ? style : DEFAULT_STREAM_SETTINGS.style,
+			speed: Number.isFinite(speed) ? clampStreamSpeed(speed) : DEFAULT_STREAM_SETTINGS.speed,
+			caret: caret === null ? DEFAULT_STREAM_SETTINGS.caret : caret === "1" || caret === "true",
+		};
+	} catch {
+		// 隐私模式 / localStorage 不可用：这一份内存偏好照样生效
+		return DEFAULT_STREAM_SETTINGS;
+	}
+}
+
+export function loadStreamSettings(): StreamSettings {
+	if (typeof window === "undefined") return DEFAULT_STREAM_SETTINGS;
+	return readStored();
+}
+
+function persist(settings: StreamSettings): void {
+	if (typeof window === "undefined") return;
+	try {
+		localStorage.setItem(KEY.style, settings.style);
+		localStorage.setItem(KEY.speed, String(settings.speed));
+		localStorage.setItem(KEY.caret, settings.caret ? "1" : "0");
+	} catch {
+		/* 配额满 / 被禁用：内存里已经生效 */
+	}
+}
+
+let cached: StreamSettings | null = null;
+const listeners = new Set<() => void>();
+let storageBound = false;
+
+/** useSyncExternalStore 的 getSnapshot：同一份引用，只有真改了才换（否则会无限重渲染） */
+export function getStreamSettings(): StreamSettings {
+	if (!cached) cached = loadStreamSettings();
+	return cached;
+}
+
+/** 服务端 / 水合首帧没有 localStorage，给默认值 */
+export function getServerStreamSettings(): StreamSettings {
+	return DEFAULT_STREAM_SETTINGS;
+}
+
+function bindStorage(): void {
+	if (storageBound || typeof window === "undefined") return;
+	storageBound = true;
+	window.addEventListener("storage", (event) => {
+		if (event.key !== null && event.key !== KEY.style && event.key !== KEY.speed && event.key !== KEY.caret) return;
+		cached = loadStreamSettings();
+		for (const listener of listeners) listener();
+	});
+}
+
+export function subscribeStreamSettings(listener: () => void): () => void {
+	listeners.add(listener);
+	bindStorage();
+	return () => {
+		listeners.delete(listener);
+	};
+}
+
+/** 改一项并持久化，返回合并后的完整偏好；正在流的回答下帧就用新值 */
+export function setStreamSettings(patch: Partial<StreamSettings>): StreamSettings {
+	const current = getStreamSettings();
+	const next: StreamSettings = {
+		style: isStreamStyle(patch.style) ? patch.style : current.style,
+		speed: patch.speed === undefined ? current.speed : clampStreamSpeed(patch.speed),
+		caret: patch.caret === undefined ? current.caret : patch.caret === true,
+	};
+	cached = next;
+	persist(next);
+	for (const listener of listeners) listener();
+	return next;
+}
+
+/**
+ * 不在 UTF-16 代理对中间切：切在中间会渲染成一个替换字符（半个 emoji）。
+ * 端点越界时按文本长度收口。
+ */
+export function safeSliceEnd(text: string, end: number): number {
+	if (end <= 0) return 0;
+	if (end >= text.length) return text.length;
+	const high = text.charCodeAt(end - 1);
+	const low = text.charCodeAt(end);
+	if (high >= 0xd800 && high <= 0xdbff && low >= 0xdc00 && low <= 0xdfff) return Math.min(end + 1, text.length);
+	return end;
+}
+
+/**
+ * 渐显：只在整词处停 —— 从 end 往回找到最近的分隔符，切在它后面；
+ * 这一段里没有分隔符（正在敲的词）就照常长，否则会停在原地走不完。
+ */
+function snapToWordEnd(target: string, from: number, end: number): number {
+	if (end >= target.length) return target.length;
+	for (let i = end - 1; i >= from; i -= 1) {
+		if (/\s/.test(target[i])) return i + 1;
+	}
+	return end;
+}
+
+/**
+ * 这一帧显示到哪个下标（返回值 = 目标文本前缀长度）。
+ * - instant：不排队，直接追平；
+ * - smooth：自适应 —— 积压越多推得越快，但每帧有上限：大块突发被摊到多帧缓缓出现；
+ * - typewriter：固定节奏逐字，但积压过大时跟着加速（上限约 1.5 秒的落后量）；
+ * - fade：在 smooth 的基础上按整词推进。
+ */
+export function nextRevealEnd(target: string, shownLength: number, settings: StreamSettings): number {
+	const total = target.length;
+	if (settings.style === "instant") return total;
+	const backlog = total - shownLength;
+	if (backlog <= 0) return total;
+	const level = clampStreamSpeed(settings.speed) - 1;
+	let end: number;
+	if (settings.style === "typewriter") {
+		end = shownLength + Math.max(TYPEWRITER_CHARS[level], Math.ceil(backlog / TYPEWRITER_CATCHUP_DIVISOR));
+	} else {
+		end = shownLength + Math.min(
+			SMOOTH_MAX_CHARS[level],
+			Math.max(SMOOTH_MIN_CHARS[level], Math.ceil(backlog / SMOOTH_DIVISOR[level])),
+		);
+	}
+	if (end > total) end = total;
+	if (settings.style === "fade") end = snapToWordEnd(target, shownLength, end);
+	return safeSliceEnd(target, end);
+}

package/src/lib/types.ts

@@ -116,6 +116,8 @@ export type WebEvent =
 	| { type: "traj"; entry: TrajEntry; ts: number }
 	| { type: "name"; name: string; ts: number }
 	| { type: "tools"; active: string[]; all: string[]; toolPreset?: ToolPreset; customActiveTools?: string[] | null; ts: number }
+	/** 上下文分项变了（会话启动、工具 / 资源重载、压缩之后）：替换快照里的 contextBreakdown */
+	| { type: "context_breakdown"; breakdown: ContextBreakdown; ts: number }
 	| {
 			/** 资源（扩展/技能/模板/命令）重载后的新清单；前端据此刷新 / 菜单与设置面板 */
 			type: "resources";
@@ -248,6 +250,11 @@ export interface ContextBreakdown {
 	compacted: number;
 	/** auto-compact 预留（compaction.reserveTokens 设置值；未启用为 0） */
 	autoCompactBuffer: number;
+	/**
+	 * 会话还没启动（只浏览历史不冷启动 agent）：systemPrompt / systemTools / customTools 拿不到、为 0，
+	 * 其余几项照常统计。前端据此提示并提供「现在统计」（prepare 启动会话）。
+	 */
+	cold?: boolean;
 }
 
 /** SSE 连接建立时先发的完整快照 */