pi-firecode 0.8.0 → 1.0.0

package/master/event-card.ts

@@ -1,24 +1,19 @@
 /**
  * Master 事件卡：默认紧凑（每事件一行标题行），ctrl+o 展开完整内容。
- * content 给模型（完整事实），details 给渲染——两者刻意不对齐（先例：review/card.ts）。
- * 提取与校验的格式契约在 event-format.ts；旧会话无 details 的消息与校验失败一律降级
- * 完整内容；渲染器永不抛异常。
+ * 数据只来自消息正文里的信封（deliver.ts 是格式的唯一事实源）；渲染器永不抛异常。
  */
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Box, type Component, Markdown, Text } from "@earendil-works/pi-tui";
-import { clip, oneLine } from "../format.js";
-import {
-	MASTER_EVENT_TYPE,
-	isValidMasterEventDetails,
-	type MasterEventDetails,
-} from "./event-format.js";
+import { clip, firstSentence, oneLine, textOf } from "../format.js";
+import { parseEnvelopes } from "../deliver.js";
+import { machineEntries } from "../tools/machine.js";
+import { MASTER_EVENT_TYPE } from "./event-format.js";
 
 export function registerMasterEventRenderer(pi: ExtensionAPI): void {
-	pi.registerMessageRenderer<MasterEventDetails>(
+	pi.registerMessageRenderer(
 		MASTER_EVENT_TYPE,
-		(message, options, theme) =>
-			new MasterEventCard(message.details, message.content, options.expanded, theme),
+		(message, options, theme) => new MasterEventCard(message.content, options.expanded, theme),
 	);
 }
 
@@ -26,19 +21,12 @@ class MasterEventCard implements Component {
 	private readonly card: Component;
 	private readonly fallback: Component;
 
-	constructor(
-		details: MasterEventDetails | undefined,
-		content: string | (string | unknown)[],
-		expanded: boolean,
-		theme: Theme,
-	) {
-		const text = plainContent(content);
+	constructor(content: string | (string | unknown)[], expanded: boolean, theme: Theme) {
+		const text = textOf(content);
 		this.fallback = new Text(text, 0, 0);
 		let card: Component | undefined;
 		try {
-			card = !expanded && isValidMasterEventDetails(details)
-				? compactCard(details, theme)
-				: fullCard(text, theme);
+			card = !expanded ? compactCard(text, theme) : fullCard(text, theme);
 		} catch {
 			card = undefined;
 		}
@@ -63,8 +51,12 @@ class MasterEventCard implements Component {
 	}
 }
 
-function compactCard(details: MasterEventDetails, theme: Theme): Component {
-	return card(theme, details.titles.map((title) => new CompactTitle(`◆ ${title}`)));
+/** 每个事件一行：标题 + 正文首句；不是信封的旧消息退化为完整内容。 */
+function compactCard(text: string, theme: Theme): Component {
+	const entries = machineEntries(text);
+	if (!entries) return fullCard(text, theme);
+	return card(theme, entries.map((entry) =>
+		new CompactTitle(`◆ ${entry.title}${entry.preview ? ` — ${firstSentence(entry.preview)}` : ""}`)));
 }
 
 /**
@@ -83,7 +75,8 @@ class CompactTitle implements Component {
 }
 
 function fullCard(text: string, theme: Theme): Component {
-	return card(theme, [new Markdown(text, 0, 0, getMarkdownTheme())]);
+	const bodies = parseEnvelopes(text)?.map((envelope) => envelope.body).join("\n\n") ?? text;
+	return card(theme, [new Markdown(bodies, 0, 0, getMarkdownTheme())]);
 }
 
 function card(theme: Theme, children: Component[]): Component {
@@ -92,15 +85,3 @@ function card(theme: Theme, children: Component[]): Component {
 	for (const child of children) box.addChild(child);
 	return box;
 }
-
-function plainContent(content: string | (string | unknown)[]): string {
-	if (typeof content === "string") return content;
-	if (!Array.isArray(content)) return "";
-	return content
-		.map((part) =>
-			typeof part === "object" && part !== null && "text" in part
-				? String((part as { text: unknown }).text)
-				: "")
-		.filter(Boolean)
-		.join("\n");
-}

package/master/event-format.ts

@@ -1,52 +1,83 @@
 /**
- * Master 事件文本与紧凑行的共享格式契约（纯函数、零宿主依赖，可被测试直接导入）。
- * 分节标记是事件产文与紧凑卡提取的单一事实源：改词两侧编译期同步，杜绝静默退化
- * （曾经的隐式跨文件耦合让"改文案→预览悄悄消失"且测试全绿）。
+ * Master 事件正文的唯一产文处：第一行是给人看的标题“<名字> <结果词>”（名字是第一个空格前的词），
+ * 给模型的指令放在后续正文。分节标记独占一行“<标记>：”；失败只由“错误：”分节表示——
+ * 红色、失败计数与活动列表失败组都从这一个事实来（失败、审查停止、审查未完成；被中断不是失败）。
+ * 折叠界面（tools/machine.ts）按标题、“错误：”分节与“耗时：本次运行 …”行投影，改格式两侧都要同步。
  */
+import { formatDuration } from "../format.js";
+import type { ReviewOutcome } from "../review/outcome.js";
+
 export const MASTER_EVENT_TYPE = "firecode-master-event";
 
-/** 正文分节标记：事件产文用它拼标记行，紧凑行提取用它识别正文首句。 */
-export const BODY_SECTIONS = {
-	reply: "回复",
-	error: "错误",
-	question: "问题",
-	finalReply: "最终回复",
-	lastOutput: "中断前最后输出",
+const SECTIONS = {
+	reply: "回复：",
+	error: "错误：",
+	finalReply: "最终回复：",
+	advice: "顾问意见：",
 } as const;
 
-/** 产文侧唯一入口：正文段一律以 `<标记>：` 独占一行开头。 */
-export function sectionLine(section: keyof typeof BODY_SECTIONS): string {
-	return `${BODY_SECTIONS[section]}：`;
-}
-
-const BODY_MARKER = new RegExp(`^(?:${Object.values(BODY_SECTIONS).join("|")})：$`, "u");
+const OBLIGATION = "此票有审查义务，请显式 review。";
 
-const VERSION = 1;
-
-export interface MasterEventDetails {
-	version: typeof VERSION;
-	titles: string[];
+/**
+ * 产出的事件：正文与是否落定类。落定类（已返回、失败、被中断、审查通过/停止/未完成）才带“本次运行”耗时，
+ * 界面据此触发到达高亮；其余事件（待续跑、已切换模型、补充说明未送达）只带当前任务耗时。
+ */
+export interface MasterEvent {
+	body: string;
+	settled: boolean;
 }
 
-/** 每个事件一行：首行标题句 + 正文首句预览（渲染时按宽度截断）。 */
-export function masterEventDetails(contents: string[]): MasterEventDetails {
-	return { version: VERSION, titles: contents.map(compactLine) };
-}
+const lines = (...parts: (string | undefined)[]) => parts.filter((part) => part !== undefined).join("\n");
+const settled = (...parts: (string | undefined)[]): MasterEvent => ({ body: lines(...parts), settled: true });
+const notice = (...parts: (string | undefined)[]): MasterEvent => ({ body: lines(...parts), settled: false });
 
-function compactLine(content: string): string {
-	const lines = content.split("\n");
-	const title = lines[0] ?? "";
-	const marker = lines.findIndex((line) => BODY_MARKER.test(line.trim()));
-	if (marker < 0) return title;
-	const preview = lines.slice(marker + 1).find((line) => line.trim());
-	return preview ? `${title} — ${preview.trim()}` : title;
-}
+/**
+ * 一次运行里用户在子代理全过程视图直接说的话（按顺序）。有就在标题结果词后注明来源、正文先列原话：
+ * 指挥官据此知道这次运行不是它派的，只记下不向用户复述；成败、发落、在飞数与普通 send 完全相同。
+ */
+export type ViewPrompts = readonly string[];
+const VIEW_MARK = "（你在子代理视图里直接派的）";
+const runTitle = (name: string, word: string, view: ViewPrompts) => `${name} ${word}${view.length ? VIEW_MARK : ""}`;
+const youSaid = (view: ViewPrompts) => view.map((prompt) => `你说：${prompt}`);
+
+export const masterEvent = {
+	returned: (name: string, reply: string, obligation = false, view: ViewPrompts = []) =>
+		settled(runTitle(name, "已返回", view), ...youSaid(view), SECTIONS.reply, reply, obligation ? OBLIGATION : undefined),
+	failed: (name: string, error: string, obligation = false, view: ViewPrompts = []) =>
+		settled(runTitle(name, "失败", view), ...youSaid(view), SECTIONS.error, error, obligation ? OBLIGATION : undefined),
+	interrupted: (name: string, obligation: boolean, view: ViewPrompts = []) =>
+		settled(runTitle(name, "被中断", view), ...youSaid(view), obligation ? "会话与审查义务均已保留，可 send 续派" : "会话已保留，可 send 续派"),
+	reviewIncomplete: (name: string, reason: string, reply?: string) =>
+		settled(`${name} 审查未完成`, SECTIONS.error, reason, ...(reply === undefined ? [] : [SECTIONS.finalReply, reply || "（无回复）"])),
+	/** 审查终态；reply 是 Worker 最后一条回复。停止与未完成是失败：原因进“错误：”分节，顾问意见在其后。 */
+	review(name: string, outcome: ReviewOutcome, reply: string): MasterEvent {
+		const final = [SECTIONS.finalReply, reply || "（无回复）"];
+		if (outcome.status === "passed") return settled(`${name} 审查通过（${outcome.rounds} 轮）`, ...final);
+		if (outcome.status === "stopped")
+			return settled(
+				`${name} 审查停止（${outcome.rounds} 轮）`,
+				SECTIONS.error,
+				outcome.advisorAdvice ? `审查 ${outcome.rounds} 轮未通过，顾问叫停` : `审查 ${outcome.rounds} 轮用尽仍未通过`,
+				...(outcome.advisorAdvice ? [SECTIONS.advice, outcome.advisorAdvice] : []),
+				...final,
+			);
+		if (outcome.status === "failed") return masterEvent.reviewIncomplete(name, outcome.reason, reply);
+		if (outcome.status === "error") return masterEvent.reviewIncomplete(name, `审查读取失败：${outcome.message}`);
+		return masterEvent.reviewIncomplete(name, `审查结束时没有终态：${outcome.status}`);
+	},
+	/** 只给会话重载打断的回合：指挥官自己发起的 interrupt 它知道现场，不提醒。 */
+	resumeReminder: (name: string) => notice(`${name} 待续跑`, "上次回合被会话重载打断，恢复后一直没有续派；请 send 续派或 kill 收口"),
+	stranded: (name: string, texts: string[]) =>
+		notice(`${name} 补充说明未送达`, `回合结束时有 ${texts.length} 条补充说明未送达，请重发：`, texts.join("\n---\n")),
+	modelSwitched: (name: string, from: string, to: string, reason: string) =>
+		notice(`${name} 已切换模型`, `已切换 ${from}→${to}（${reason}），正在同一会话自动续跑`),
+};
 
-export function isValidMasterEventDetails(value: unknown): value is MasterEventDetails {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const record = value as Record<string, unknown>;
-	if (Object.keys(record).length !== 2 || record.version !== VERSION) return false;
-	return Array.isArray(record.titles) &&
-		record.titles.length > 0 &&
-		record.titles.every((title) => typeof title === "string");
+/** 落定类正文末尾追加 Worker 本次运行耗时（子代理会话写下的轮记录给出）；没有记录或非落定事件不追加，不用别处的计时冒充。 */
+export function withElapsed(event: MasterEvent, { run, task }: { run?: number; task?: number }): string {
+	const parts = [
+		...(run === undefined || !event.settled ? [] : [`本次运行 ${formatDuration(run)}`]),
+		...(task === undefined ? [] : [`当前任务 ${formatDuration(task)}`]),
+	];
+	return parts.length ? `${event.body}\n耗时：${parts.join(" · ")}` : event.body;
 }

package/master/guard.ts

@@ -0,0 +1,46 @@
+/**
+ * Worker 会话里 Master 只注册这一件事：edit/write 只能落在当前 checkout 或系统临时目录内（按真实路径判断）。
+ * 临时目录放行是因为调研报告、评测产物这类交付物本来就写在那里；拦掉只会逼 Worker 改用 bash 绕过守卫。
+ */
+import { realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export function registerWorkerGuard(pi: ExtensionAPI): void {
+	pi.on("tool_call", async (event, ctx) => {
+		if (!isToolCallEventType("edit", event) && !isToolCallEventType("write", event)) return;
+		const reason = await outsideCheckoutReason(event.input.path, ctx.cwd);
+		if (reason) return { block: true, reason };
+	});
+}
+
+/** os.tmpdir() 在 macOS 是每用户的 /var/folders/…，/tmp 是另一处，两处都是临时目录。 */
+const TEMP_ROOTS = [tmpdir(), "/tmp"];
+
+async function outsideCheckoutReason(path: string, cwd: string): Promise<string | undefined> {
+	const target = await canonicalWritePath(resolve(cwd, path));
+	const roots = await Promise.all([cwd, ...TEMP_ROOTS].map(canonicalWritePath));
+	return roots.some((root) => within(root, target)) ? undefined : `子代理只能修改当前 checkout 或系统临时目录：${path}`;
+}
+
+function within(root: string, target: string): boolean {
+	const local = relative(root, target);
+	return local !== ".." && !local.startsWith(`..${sep}`) && !isAbsolute(local);
+}
+
+/** 目标可能还不存在：沿祖先找到第一个真实存在的目录取真实路径，再拼回缺失的部分。 */
+async function canonicalWritePath(path: string): Promise<string> {
+	let ancestor = path;
+	const missing: string[] = [];
+	while (true) {
+		try {
+			return resolve(await realpath(ancestor), ...missing.reverse());
+		} catch {
+			const parent = dirname(ancestor);
+			if (parent === ancestor) return path;
+			missing.push(basename(ancestor));
+			ancestor = parent;
+		}
+	}
+}