@rexvane/piweb 0.3.25 → 0.3.26

package/src/lib/agent-manager.ts

@@ -2,11 +2,11 @@
  * agent-manager：AgentSession 池 + pi 事件 → Web 事件翻译 + SSE 订阅管理。
  * 打开会话即惰性冷启动（createAgentSession），空闲回收，事件先快照后增量。
  */
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, readSync, 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 { formatSkillsForPrompt, generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
+import { ExtensionRunner, ModelRegistry, formatSkillsForPrompt, generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
 import {
 	getResourceLoader,
 	createSessionResourceLoader,
@@ -56,6 +56,8 @@ const IDLE_MS = 10 * 60 * 1000;
 const MAX_ACTIVE = 6;
 const BUFFER_CAP = 400;
 const SHUTDOWN_TIMEOUT_MS = 5_000;
+/** 外来写入重载后，这么久之内连上的快照都带着提示 */
+const EXTERNAL_RELOAD_NOTICE_MS = 60_000;
 
 interface Managed {
 	viewerAvailable?: () => boolean;
@@ -106,6 +108,12 @@ interface Managed {
 	ui: ExtensionUiBridge | null;
 	/** 项目生长：影子仓库快照的触发器（首个会话事件时创建，dispose 时释放） */
 	growth: GrowthTracker | null;
+	/** JSONL 已核对到的字节位置（总在整行末尾）；之后多出来的行要看是不是别的进程写的（见 externalEntryCount） */
+	diskSize: number;
+	/** 已发现、还没重载进来的外来条目数（终端 pi 同时在写这个会话） */
+	externalEntries: number;
+	/** 这一份是因外来写入从磁盘重载出来的：快照带上，前端提示一次 */
+	externalReload?: { entries: number; at: number };
 }
 
 const globalForAgentManager = globalThis as typeof globalThis & {
@@ -165,10 +173,95 @@ export function toWebMessage(m: any, entryId?: string): WebMessage {
 			encodingLoss: result.encodingLoss || undefined,
 			patch: patchOf(m.details),
 		}];
+	} else if (m.role === "compactionSummary" || m.role === "branchSummary") {
+		out.role = "summary";
+		out.summaryKind = m.role === "branchSummary" ? "branch" : "compaction";
+		out.summary = typeof m.summary === "string" ? m.summary : "";
+		if (typeof m.tokensBefore === "number" && Number.isFinite(m.tokensBefore)) out.tokensBefore = m.tokensBefore;
 	}
 	return out;
 }
 
+/** 会话条目 → 显示消息：消息照常投影，压缩 / 分支摘要投影成摘要卡，其余条目（切模型、自定义状态等）不显示 */
+function entryToWebMessage(entry: any): WebMessage | null {
+	if (entry?.type === "message" && entry.message) return toWebMessage(entry.message, entry.id);
+	if (entry?.type !== "compaction" && !(entry?.type === "branch_summary" && entry.summary)) return null;
+	const timestamp = Date.parse(entry.timestamp);
+	return toWebMessage({
+		role: entry.type === "compaction" ? "compactionSummary" : "branchSummary",
+		summary: entry.summary,
+		tokensBefore: entry.tokensBefore,
+		timestamp: Number.isFinite(timestamp) ? timestamp : undefined,
+	}, entry.id);
+}
+
+/**
+ * 被压缩掉的历史：当前分支上已不在模型上下文里的条目，按原顺序照常显示（可编辑、可分叉）。
+ * 每张压缩卡挪到它保留的第一条（firstKeptEntryId）前面，和上下文部分「摘要在前、保留消息在后」一致；
+ * 这样卡片以上就是模型只看得到摘要的内容。
+ */
+function compactedHistory(sm: Pick<SessionManager, "getBranch">, context: any[]): WebMessage[] {
+	if (context[0]?.type !== "compaction") return [];
+	const inContext = new Set(context.map((entry) => entry.id));
+	const entries = (sm.getBranch() as any[]).filter((entry) => !inContext.has(entry.id));
+	const position = new Map(entries.map((entry, index) => [entry.id, index]));
+	const markersBefore = new Map<string, WebMessage[]>();
+	const moved = new Set<string>();
+	entries.forEach((entry, index) => {
+		if (entry.type !== "compaction") return;
+		const at = position.get(entry.firstKeptEntryId);
+		if (at === undefined || at >= index) return;
+		const marker = entryToWebMessage(entry)!;
+		markersBefore.set(entry.firstKeptEntryId, [...(markersBefore.get(entry.firstKeptEntryId) ?? []), marker]);
+		moved.add(entry.id);
+	});
+	const out: WebMessage[] = [];
+	for (const entry of entries) {
+		out.push(...(markersBefore.get(entry.id) ?? []));
+		if (moved.has(entry.id)) continue;
+		const message = entryToWebMessage(entry);
+		if (message) out.push(message);
+	}
+	return out;
+}
+
+/** 冷会话 / 只读接口的消息列表：被压缩掉的历史 + 当前上下文（最新一次压缩投影成分隔卡） */
+export function sessionDisplayMessages(sm: Pick<SessionManager, "getBranch" | "buildContextEntries">): WebMessage[] {
+	const context = sm.buildContextEntries() as any[];
+	const current = context.flatMap((entry, index) => {
+		// 保留区里更早的压缩条目不进模型上下文（SDK 投影只取下标 0 的那次），这里同样跳过
+		if (entry.type === "compaction" && index > 0) return [];
+		const message = entryToWebMessage(entry);
+		return message ? [message] : [];
+	});
+	return [...compactedHistory(sm, context), ...current];
+}
+
+/**
+ * 压缩刚完成（SDK 先写条目再发 compaction_end）：分隔卡 + 它该插在哪条消息前。
+ * 取保留下来的第一条用户 / 助手消息，和快照里「卡片在保留消息之前」的位置一致；没有保留消息就追加。
+ */
+function compactionMarker(m: Managed): { marker?: WebMessage; beforeId?: string; beforeStreamId?: string } {
+	try {
+		const context = m.sm.buildContextEntries() as any[];
+		if (context[0]?.type !== "compaction") return {};
+		const kept = context.find((entry) => entry.type === "message" && (entry.message?.role === "user" || entry.message?.role === "assistant"));
+		return {
+			marker: entryToWebMessage(context[0]) ?? undefined,
+			beforeId: kept?.id,
+			beforeStreamId: kept ? m.messageIds?.get(kept.message) : undefined,
+		};
+	} catch {
+		return {};
+	}
+}
+
+/** 热会话里摘要消息（SDK 每次投影新建的对象）对应的条目 ID：压缩取上下文首条，分支摘要按 fromId + 时间匹配 */
+function summaryEntryId(context: any[], message: any): string | undefined {
+	if (message?.role === "compactionSummary") return context[0]?.type === "compaction" ? context[0].id : undefined;
+	return context.find((entry) => entry.type === "branch_summary" && entry.fromId === message?.fromId && Date.parse(entry.timestamp) === message?.timestamp)?.id;
+}
+
 /** 消息对象 → 持久化条目 ID 的索引；条目数一变就重建（会话只追加，改写分支时条目数也会变） */
 const entryIdIndexes = new WeakMap<SessionManager, { count: number; ids: WeakMap<object, string> }>();
 
@@ -346,11 +439,15 @@ function publishModelState(m: Managed, session: AgentSession): void {
 	});
 }
 
-/** 切模型后恢复用户显式选过的级别（按新模型钳制） */
+/**
+ * 切模型后恢复用户显式选过的级别（按新模型钳制）。
+ * 只记进本会话（SDK 会写 thinking_level_change 条目），不写全局默认：
+ * ~/.pi/agent/settings.json 与终端 pi 共用，在 PiWeb 里切一下档位不该改掉终端 pi 的默认值。
+ */
 function reapplyDesiredLevel(m: Managed, session: AgentSession): void {
 	if (!m.desiredThinkingLevel) return;
 	const target = clampThinkingLevel(session.model as any, m.desiredThinkingLevel as any);
-	if (target !== session.thinkingLevel) session.setThinkingLevel(target as never, { persist: true });
+	if (target !== session.thinkingLevel) session.setThinkingLevel(target as never);
 }
 
 /**
@@ -658,6 +755,7 @@ function translate(m: Managed, evt: AgentSessionEvent): void {
 				phase: "end",
 				reason: (evt as any).reason,
 				errorMessage: (evt as any).errorMessage,
+				...((evt as any).result && !(evt as any).errorMessage ? compactionMarker(m) : {}),
 				ts: now,
 			});
 			publishUsage(m, true);
@@ -760,7 +858,8 @@ export function warmSessionResources(cwds: string[]): void {
 
 export function getManaged(sessionPath: string): Managed {
 	let m = sessions.get(sessionPath);
-	if (!m) {
+	if (m) m = syncWithDisk(m);
+	else {
 		if (!existsSync(sessionPath)) throw new BoundaryError("session not found");
 		const sm = openSessionManager(sessionPath);
 		m = registerManaged(sessionPath, sm.getCwd() || process.cwd(), sm);
@@ -769,6 +868,115 @@ export function getManaged(sessionPath: string): Managed {
 	return m;
 }
 
+/**
+ * 数出 JSONL 里自上次核对以来、不是本进程写的新条目。
+ * 自己的条目在 SessionManager._appendEntry 里先进内存索引再落盘，所以索引里找不到 id 的行就是外来的
+ * （终端 pi 同时打开了这个会话）。只读新增的字节；文件变短（被整体重写）就从头核对；没写完的最后一行留到下次。
+ */
+function externalEntryCount(m: Managed): number {
+	let size: number;
+	try {
+		size = statSync(m.sessionPath).size;
+	} catch {
+		return 0; // 还没落盘
+	}
+	if (size === m.diskSize) return 0;
+	const from = size < m.diskSize ? 0 : m.diskSize;
+	let buf = Buffer.alloc(size - from);
+	let fd: number | undefined;
+	try {
+		fd = openSync(m.sessionPath, "r");
+		buf = buf.subarray(0, readSync(fd, buf, 0, buf.length, from));
+	} catch {
+		return 0;
+	} finally {
+		if (fd !== undefined) closeSync(fd);
+	}
+	const end = buf.lastIndexOf(0x0a);
+	m.diskSize = from + end + 1;
+	let count = 0;
+	for (const line of buf.subarray(0, Math.max(0, end)).toString("utf8").split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const entry = JSON.parse(line);
+			if (entry?.type !== "session" && typeof entry?.id === "string" && !m.sm.getEntry(entry.id)) count += 1;
+		} catch {
+			/* 从行中间读起的半行、写坏的行都不算 */
+		}
+	}
+	return count;
+}
+
+/**
+ * pi 终端和 PiWeb 共用同一份 JSONL，但各自在内存里记着会话树：一边写了，另一边不知道，
+ * 接着写就从自己的旧叶子分叉。打开会话、发消息都经过 getManaged，这里先核对磁盘：
+ * 有外来条目且本会话空闲，就丢掉内存里的旧副本从磁盘重开；正在跑就只提醒，空闲后的下一次核对再重载。
+ */
+function syncWithDisk(m: Managed): Managed {
+	const found = externalEntryCount(m);
+	if (!found && !m.externalEntries) return m;
+	m.externalEntries += found;
+	if (m.creating || isManagedBusy(m)) {
+		if (found) publish(m, { type: "external_write", entries: m.externalEntries, ts: Date.now() });
+		return m;
+	}
+	return reopenManaged(m);
+}
+
+/** 等同空闲回收后再打开：会话级的选择（工具档位、思考级别）带过去，正在看的浏览器立刻重连拿新快照 */
+function reopenManaged(m: Managed): Managed {
+	let sm: SessionManager;
+	try {
+		sm = openSessionManager(m.sessionPath);
+	} catch {
+		return m; // 读不出来（正被写坏？）就先沿用旧副本，下次再试
+	}
+	const at = Date.now();
+	const reload = { entries: m.externalEntries, at };
+	// 直接写给订阅者：publish 可能排在队列里，晚于 dispose 就送不到了
+	const frame = JSON.stringify({ type: "external_reload", ...reload, ts: at });
+	for (const send of m.subscribers) {
+		try {
+			send(m.seq, frame);
+		} catch {
+			/* ignore */
+		}
+	}
+	disposeSession(m);
+	const fresh = registerManaged(m.sessionPath, sm.getCwd() || m.cwd, sm);
+	// 核对位置沿用旧的（整行末尾）：打开时恰好没写完的那行，写完后还会被认作外来的
+	fresh.diskSize = m.diskSize;
+	fresh.toolPreset = m.toolPreset;
+	fresh.customActiveTools = m.customActiveTools;
+	fresh.desiredThinkingLevel = m.desiredThinkingLevel;
+	fresh.viewerGraceUntil = m.viewerGraceUntil;
+	fresh.externalReload = reload;
+	return fresh;
+}
+
+/**
+ * 侧栏每 3 秒拉一次会话列表，顺带核对所有开着的会话：终端写入几秒内就能提示 / 重载，
+ * 回合中途发现的外来写入也在回合结束后的下一次拉取时重载（不在 agent_settled 里做：
+ * SDK 收尾时还可能有延后的提问要开跑，那一刻回收会把它丢掉）。每个会话一次 stat，没变就不读文件。
+ */
+export function syncSessionsFromDisk(): void {
+	for (const m of [...sessions.values()]) {
+		try {
+			syncWithDisk(m);
+		} catch {
+			/* 核对失败只是晚一点发现，打开 / 发送时还会再查 */
+		}
+	}
+}
+
+function fileSize(file: string): number {
+	try {
+		return statSync(file).size;
+	} catch {
+		return 0;
+	}
+}
+
 function registerManaged(sessionPath: string, cwd: string, sm: SessionManager): Managed {
 	let initialTrajectory: TrajEntry[] = [];
 	try {
@@ -800,6 +1008,8 @@ function registerManaged(sessionPath: string, cwd: string, sm: SessionManager):
 		runActive: false,
 		disposed: false,
 		messageIds: new WeakMap(),
+		diskSize: fileSize(sessionPath),
+		externalEntries: 0,
 	};
 	sessions.set(sessionPath, m);
 	return m;
@@ -1232,7 +1442,22 @@ startArchivedSessionRetention({ isActive: isSessionInUse, log: (message) => cons
 
 type ResourceBundle = Pick<WebSnapshot, "skills" | "promptTemplates" | "extensionCommands" | "projectTrust" | "resourceDiagnostics">;
 
-function collectResources(m: Managed): ResourceBundle {
+/**
+ * 会话还不存在时也能发现命令：不绑定运行时、不发 session_start、不启动 MCP。
+ * 新会话页和冷会话的斜杠补全都靠它，等第一次提问才建会话。
+ */
+export async function loadWorkspaceResources(cwd: string): Promise<ResourceBundle> {
+	await refreshResourceLoaderIfStale(cwd);
+	const modelRegistry = new ModelRegistry(await getModelRuntime());
+	return withResourceLock(async () => {
+		const loader = getResourceLoader(cwd);
+		const { extensions, runtime } = loader.getExtensions();
+		const runner = new ExtensionRunner(extensions, runtime, cwd, SessionManager.inMemory(cwd), modelRegistry);
+		return collectResources({ cwd, session: null }, runner);
+	});
+}
+
+function collectResources(m: Pick<Managed, "cwd" | "session">, commandRunner?: ExtensionRunner): ResourceBundle {
 	const loader = m.session?.resourceLoader ?? peekResourceLoader(m.cwd) ?? getResourceLoader(m.cwd);
 	const diagnostics: WebSnapshot["resourceDiagnostics"] = [];
 	let skills: WebSnapshot["skills"] = [];
@@ -1257,9 +1482,9 @@ function collectResources(m: Managed): ResourceBundle {
 		/* ignore */
 	}
 	let extensionCommands: WebSnapshot["extensionCommands"] = [];
-	if (m.session) {
+	if (m.session || commandRunner) {
 		try {
-			const runner = (m.session as unknown as { extensionRunner?: { getRegisteredCommands(): Array<{ invocationName: string; description?: string; sourceInfo?: { path?: string } }>; getCommandDiagnostics(): Array<{ path?: string; message: string }> } }).extensionRunner;
+			const runner = commandRunner ?? m.session?.extensionRunner;
 			if (runner) {
 				extensionCommands = runner.getRegisteredCommands().map((c) => ({
 					name: c.invocationName,
@@ -1388,7 +1613,22 @@ export async function buildSnapshot(m: Managed): Promise<WebSnapshot> {
 
 	if (session) {
 		const hasInflightFinal = linkInflightFinal(m, session);
-		messages = session.messages.map((message) => projectMessage(m, message));
+		// session.messages 只是压缩后的模型上下文；前面补上被压缩掉的历史，压缩摘要投影成分隔卡
+		let context: any[] = [];
+		let history: WebMessage[] = [];
+		try {
+			context = m.sm.buildContextEntries() as any[];
+			history = compactedHistory(m.sm, context);
+		} catch {
+			/* 条目读不到时只显示上下文 */
+		}
+		messages = [
+			...history,
+			...session.messages.map((message: any) =>
+				message?.role === "compactionSummary" || message?.role === "branchSummary"
+					? toWebMessage(message, summaryEntryId(context, message))
+					: projectMessage(m, message)),
+		];
 		// final 已被 SDK push 时只投影一次；延后的 end 使用相同 streamId 继续更新权威内容。
 		if (!hasInflightFinal && m.inflight) {
 			const partial = projectMessage(m, m.inflight);
@@ -1405,12 +1645,9 @@ export async function buildSnapshot(m: Managed): Promise<WebSnapshot> {
 		}
 		isStreaming = isManagedBusy(m);
 	} else {
-		// 冷渲染：从 JSONL 还原上下文消息（不启动 agent）
+		// 冷渲染：从 JSONL 还原消息（不启动 agent），压缩掉的历史也照常显示
 		try {
-			const entries = m.sm.buildContextEntries();
-			messages = entries
-				.filter((e: any) => e.type === "message" && e.message)
-				.map((e: any) => toWebMessage(e.message, e.id));
+			messages = sessionDisplayMessages(m.sm);
 		} catch {
 			messages = [];
 		}
@@ -1481,7 +1718,8 @@ export async function buildSnapshot(m: Managed): Promise<WebSnapshot> {
 	}
 
 	// 斜杠命令数据源：技能 / 提示模板 / 扩展命令，加上项目信任与资源诊断
-	const resources = collectResources(m);
+	// 冷会话还没有 extensionRunner，但命令目录已经能发现；不要在第一次提问前推空列表。
+	const resources = session && !m.creating ? collectResources(m) : await loadWorkspaceResources(m.cwd);
 
 	const baseTrajectory = m.ledger.entries.length ? m.ledger.entries : coldTrajectory(m);
 	const trajectory = [...environmentTrajectory(m, session, contextResourcesLoaded ? contextResources : undefined), ...baseTrajectory];
@@ -1513,6 +1751,8 @@ export async function buildSnapshot(m: Managed): Promise<WebSnapshot> {
 		queue,
 		trajectory,
 		isStreaming,
+		// 重载时没人在看（打开会话那一刻才发现）：靠快照把提示带给随后连上的浏览器，前端按 at 去重
+		...(m.externalReload && Date.now() - m.externalReload.at < EXTERNAL_RELOAD_NOTICE_MS ? { externalReload: m.externalReload } : {}),
 	};
 }
 
@@ -1594,6 +1834,17 @@ async function prepareGrowthBriefly(m: Managed): Promise<void> {
 	]);
 }
 
+type PromptImages = NonNullable<NonNullable<Parameters<AgentSession["prompt"]>[1]>["images"]>;
+
+/** 被编辑的那条用户消息里的图片：编辑只改文字，图片原样带进重发（编辑框里也照样显示它们） */
+function userMessageImages(session: AgentSession, entryId: string): PromptImages {
+	const entry = session.sessionManager?.getEntry?.(entryId) as { type?: string; message?: { role?: string; content?: unknown } } | undefined;
+	if (entry?.type !== "message" || entry.message?.role !== "user" || !Array.isArray(entry.message.content)) return [];
+	return entry.message.content.filter(
+		(c): c is PromptImages[number] => c?.type === "image" && typeof c.data === "string" && typeof c.mimeType === "string",
+	);
+}
+
 /** 交给 SDK，并在「受理」那一刻返回，而不是等整轮跑完；受理之后的错误经 SSE 可见 */
 function submitPrompt(
 	m: Managed,
@@ -1615,7 +1866,10 @@ function submitPrompt(
 		});
 		// 同步挂好 rejection handler；接受后的错误仍经 SSE 可见，不能成为未处理拒绝。
 		void run.then(() => {
-			if (!accepted) resolve({ ok: false, error: "prompt completed without acceptance" });
+			// 上一轮的 agent_settled 还没发完时，SDK 不拒绝提问，而是把它挂进 deferredSettledActions，
+			// 立即返回并在稍后用同一份 options 重发；这条路径不会调用 preflightResult。
+			// 消息确实会发出去，不能报「未受理」——否则界面报错，消息随后照样出现。真正的拒绝只会是 rejection。
+			if (!accepted) resolve({ ok: true, data: { accepted: true } });
 		}, (error) => {
 			const message = String(error?.message ?? error);
 			if (accepted) publish(m, { type: "error", message, ts: Date.now() });
@@ -1699,7 +1953,8 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 				// 与 pi 终端一致：不支持的档位就近钳制而不是拒绝（非推理模型 → off），并把实际生效值回传
 				const effective = clampThinkingLevel(session.model as any, requested as any);
 				m.desiredThinkingLevel = requested;
-				session.setThinkingLevel(effective as never, { persist: true });
+				// 不传 persist：与终端 pi 一样，聊天里切档位只影响本会话；全局默认仍以 settings.json 为准（见 reapplyDesiredLevel）
+				session.setThinkingLevel(effective as never);
 				publishModelState(m, session);
 				return { ok: true, data: { requested, thinkingLevel: session.thinkingLevel, clamped: session.thinkingLevel !== requested } };
 			}
@@ -1777,13 +2032,15 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 						}
 					}
 					if (m.disposed) throw new Error("session is disposed");
+					// 回到消息之前先取它带的图片：客户端只发改过的文字，不取的话重发出去图就没了
+					const images = userMessageImages(session, entryId);
 					const moved = await session.navigateTree(entryId);
 					if (moved?.cancelled) return { ok: false, error: "edit cancelled" };
 					await prepareGrowthBriefly(m);
 					if (m.disposed) throw new Error("session is disposed");
 					// 与普通 prompt 一样在受理时就返回：等整轮跑完的话，这期间 promptSubmitting 一直为真，
 					// 插话 / 排队 / 新消息全被拒，HTTP 请求也一直挂着
-					return await submitPrompt(m, session, text);
+					return await submitPrompt(m, session, text, images.length ? { images } : {});
 				} finally {
 					m.promptSubmitting = false;
 					if (!m.disposed) publish(m, { type: "status", isStreaming: isManagedBusy(m), state: isManagedBusy(m) ? "running" : "idle", ts: Date.now() });

package/src/lib/chat/skill-expansion.ts

@@ -39,3 +39,13 @@ export function parseExpandedSkill(text: string): ExpandedSkill | null {
 	// 参数在闭合标签之后，与技能正文同属一条用户消息（pi 不单独发）
 	return { name, args: trimmed.slice(close + "</skill>".length).trim() };
 }
+
+/**
+ * 拿用户消息当标题 / 摘要时用的文本：技能展开还原成用户当初打的 `/skill:name 参数`，
+ * 别的原样返回。会话列表、窗口标题、增长树的轮次标题都走它，不再露出 `<skill name=…>` 和 SKILL.md 正文。
+ */
+export function promptTitleText(text: string): string {
+	const skill = parseExpandedSkill(text);
+	if (!skill) return text;
+	return skill.args ? `/skill:${skill.name} ${skill.args}` : `/skill:${skill.name}`;
+}

package/src/lib/extension-ui.ts

@@ -31,6 +31,28 @@ export interface ExtensionUiBridge {
 
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 
+const plainText = (text: unknown): string => (typeof text === "string" ? text : String(text ?? ""));
+/**
+ * 扩展常写 `ctx.ui.theme.fg("accent", text)` 给状态文字上色；pi 的 noOp 上下文也带 theme。
+ * 缺了它扩展一调就抛 TypeError。Web 不渲染 ANSI，所以给一个原样返回文字、不加任何转义序列的主题。
+ */
+const PLAIN_THEME = {
+	name: "piweb-plain",
+	style: (text: string) => plainText(text),
+	fg: (_color: string, text: string) => plainText(text),
+	bg: (_color: string, text: string) => plainText(text),
+	bold: plainText,
+	italic: plainText,
+	underline: plainText,
+	inverse: plainText,
+	strikethrough: plainText,
+	getFgAnsi: () => "",
+	getBgAnsi: () => "",
+	getColorMode: () => "truecolor",
+	getThinkingBorderColor: () => plainText,
+	getBashModeBorderColor: () => plainText,
+};
+
 export function createExtensionUiBridge(opts: {
 	publish: (evt: WebEvent) => void;
 	hasViewers: () => boolean;
@@ -106,9 +128,11 @@ export function createExtensionUiBridge(opts: {
 		addAutocompleteProvider: () => {},
 		setEditorComponent: () => {},
 		getEditorComponent: () => undefined,
+		theme: PLAIN_THEME,
 		getAllThemes: () => [],
 		getTheme: () => undefined,
-		setTheme: () => {},
+		// 与 pi 的 noOp 同一返回形状：扩展会读 result.success，返回 undefined 会让它们解构时出错
+		setTheme: () => ({ success: false, error: "UI not available" }),
 		getToolsExpanded: () => false,
 		setToolsExpanded: () => {},
 	};