pi-firecode 0.8.0 → 1.0.0

package/config.ts

@@ -14,25 +14,27 @@ export type ThinkingLevelValue =
 	| "xhigh"
 	| "max";
 
+/**
+ * 模型原子：配置里一律写作 "provider/model/thinking"，解析后拆成运行时模型 id 与思考档。
+ * 全仓库指定模型与思考档的唯一形状。
+ */
+export interface ModelAtom {
+	model: string;
+	thinking: ThinkingLevelValue;
+}
+
 export interface Preset {
-	provider?: string;
-	model?: string;
-	thinkingLevel?: ThinkingLevelValue;
+	model?: ModelAtom;
 	tools?: string[];
 	instructions?: string;
 	/** 一键切换，如 alt+1；不填则无快捷键 */
 	key?: string;
 }
 
-export interface ReviewModel {
-	model: string;
-	thinking: ThinkingLevelValue;
-}
-
 /** /fire-review 配置：审查者 / 顾问模型 + 循环限制。见 config.jsonc 的 review 节注释。 */
 export interface ReviewConfig {
-	advisor: ReviewModel;
-	reviewers: ReviewModel[];
+	advisor: ModelAtom;
+	reviewers: ModelAtom[];
 	/** 审查轮数硬上限。 */
 	maxRounds: number;
 	/** 连续几轮失败触发顾问仲裁。 */
@@ -44,19 +46,10 @@ export interface ReviewConfig {
 	language: Language;
 }
 
-/** Master 角色表条目：原子模型已拆成运行时模型与思考档。 */
-export interface MasterModelAtom {
-	model: string;
-	thinking: ThinkingLevelValue;
-}
-
-export const MASTER_ROLES = ["调研员", "工程师", "全栈", "架构师", "设计师", "哨兵"] as const;
-export type MasterRoleName = (typeof MASTER_ROLES)[number];
-
-export interface MasterRole extends MasterModelAtom {
-	role: MasterRoleName;
+export interface MasterRole extends ModelAtom {
+	role: string;
 	use: string;
-	fallback: MasterModelAtom[];
+	fallback: ModelAtom[];
 }
 
 export interface MasterConfig {
@@ -68,14 +61,13 @@ export interface MasterConfig {
 /** 观察员喂给观察会话的增量粒度：minimal 省略 reasoning 与 diff 正文。 */
 export type WatcherContext = "minimal" | "full";
 
-/** Watcher 观察员配置：模型与 thinking 必须显式配置，绝不回退默认模型。 */
-export interface WatcherConfig {
+/** Watcher 观察员配置：模型原子必须显式配置，绝不回退默认模型。 */
+export interface WatcherConfig extends ModelAtom {
 	enabled: boolean;
-	model: string;
-	thinking: ThinkingLevelValue;
 	context: WatcherContext;
 }
 
+
 export const FEATURES = [
 	"header",
 	"statusbar",
@@ -85,8 +77,6 @@ export const FEATURES = [
 	"stats",
 	"claudeSub",
 	"openaiNative",
-	"workingFlame",
-	"bark",
 	"review",
 	"master",
 	"watcher",
@@ -94,15 +84,16 @@ export const FEATURES = [
 
 export type Feature = (typeof FEATURES)[number];
 
+/** 顶层只认这些节；openai 节由 provider/openai-native 自己解析。 */
+const SECTIONS = ["features", "keys", "openai", "presets", "review", "master", "watcher"];
+
 export const DEFAULT_KEYS = {
 	rename: "ctrl+r",
-	cyclePreset: "ctrl+shift+u",
 	fast: "ctrl+f",
 } as const;
 
 export type FireCodeKeys = {
 	rename: string;
-	cyclePreset: string;
 	fast: string;
 };
 
@@ -115,9 +106,18 @@ export interface FireCodeConfig {
 	watcher: WatcherConfig;
 }
 
+/** 一节能否启动的唯一判定：要么交出可用配置，要么给出拒绝启动的原因。 */
+export type Section<T> = { config: T } | { error: string };
+
 export type LoadedConfig = {
 	config: FireCodeConfig;
+	/** 需要在 session_start 全局警告的问题；关闭的功能那一节的问题不在其中。 */
 	problems: string[];
+	review: Section<ReviewConfig>;
+	master: Section<MasterConfig>;
+	watcher: Section<WatcherConfig>;
+	/** features 整节类型错误：已安全回退成全关，但那是配置坏而非用户关闭。 */
+	featuresBroken: boolean;
 };
 
 export const CONFIG_PATH = join(getAgentDir(), "extensions", "firecode", "config.jsonc");
@@ -153,6 +153,39 @@ function asRecord(value: unknown): Record<string, unknown> {
 		: {};
 }
 
+/** 嵌套对象也做键白名单：拼写错误必须报出来，不能静默回退默认值。 */
+function rejectUnknownKeys(
+	record: Record<string, unknown>,
+	allowed: readonly string[],
+	field: string,
+	problems: string[],
+) {
+	for (const key of Object.keys(record))
+		if (!allowed.includes(key)) problems.push(`未知字段 ${field}.${key}`);
+}
+
+function booleanValue(value: unknown, field: string, fallback: boolean, problems: string[]): boolean {
+	if (value === undefined) return fallback;
+	if (typeof value === "boolean") return value;
+	problems.push(`${field} 必须是 true 或 false`);
+	return fallback;
+}
+
+function stringValue(value: unknown, field: string, problems: string[]): string | undefined {
+	if (typeof value === "string" && value) return value;
+	problems.push(`${field} 必须是非空字符串`);
+	return undefined;
+}
+
+function stringArray(value: unknown, field: string, problems: string[]): string[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item)) {
+		problems.push(`${field} 必须是非空字符串数组`);
+		return [];
+	}
+	return [...new Set(value)];
+}
+
 function checkFeatures(features: Record<string, unknown>, problems: string[]): void {
 	for (const [key, value] of Object.entries(features)) {
 		if (!FEATURES.includes(key as Feature)) {
@@ -169,7 +202,6 @@ function checkFeatures(features: Record<string, unknown>, problems: string[]): v
 function checkKeys(keys: FireCodeKeys, presets: Record<string, Preset>, problems: string[]): void {
 	const owners = new Map<string, string>([
 		[keys.rename, "keys.rename"],
-		[keys.cyclePreset, "keys.cyclePreset"],
 		[keys.fast, "keys.fast"],
 	]);
 	const declared = Object.entries(keys);
@@ -195,46 +227,135 @@ let cached: LoadedConfig | undefined;
 export function loadConfig(): LoadedConfig {
 	if (cached) return cached;
 
-	const problems: string[] = [];
-	const raw = readFile(problems);
+	// 文件级与开关级问题阻断所有付费功能：开关写成字符串 "false" 时 `!== false` 仍会启用。
+	const blocking: string[] = [];
+	const raw = readFile(blocking);
 	// features 省略表示沿用默认全开；只要显式写了，就必须是对象。
 	// 非对象不能回退成 {}，因为 {} 在入口语义里正是「全部启用」。
-	const invalidFeatures = raw.features !== undefined && !isPlainObject(raw.features);
-	if (invalidFeatures) problems.push("features 必须是对象");
-	const features: Partial<Record<Feature, boolean>> = invalidFeatures
+	const featuresBroken = raw.features !== undefined && !isPlainObject(raw.features);
+	if (featuresBroken) blocking.push("features 必须是对象");
+	const features: Partial<Record<Feature, boolean>> = featuresBroken
 		? Object.fromEntries(FEATURES.map((feature) => [feature, false]))
 		: asRecord(raw.features);
+	checkFeatures(features, blocking);
+
+	const problems = [...blocking];
+	for (const key of Object.keys(raw)) if (!SECTIONS.includes(key)) problems.push(`未知配置节 ${key}`);
 	const rawKeys = asRecord(raw.keys);
-	const presets = asRecord(raw.presets) as Record<string, Preset>;
+	rejectUnknownKeys(rawKeys, Object.keys(DEFAULT_KEYS), "keys", problems);
+	const presets = parsePresets(raw.presets, problems);
 	const keys: FireCodeKeys = {
 		rename: typeof rawKeys.rename === "string" ? rawKeys.rename : DEFAULT_KEYS.rename,
-		cyclePreset:
-			typeof rawKeys.cyclePreset === "string" ? rawKeys.cyclePreset : DEFAULT_KEYS.cyclePreset,
 		fast: typeof rawKeys.fast === "string" ? rawKeys.fast : DEFAULT_KEYS.fast,
 	};
-	checkFeatures(features, problems);
 	checkKeys(keys, presets, problems);
-	// review 写成字符串/数组/null 或缺字段时不能静默补齐：会拿用户未选择的模型真实发起审查。
-	const reviewProblems: string[] = [];
-	if (raw.review !== undefined && !isPlainObject(raw.review))
-		reviewProblems.push("review 必须是对象");
-	const review = parseReviewConfig(asRecord(raw.review), reviewProblems);
-	if (raw.review !== undefined || features.review !== false) problems.push(...reviewProblems);
-	// master 同理：角色表错误会拿错模型真实发起 Worker，不能静默当空对象。
-	if (raw.master !== undefined && !isPlainObject(raw.master))
-		problems.push("master 必须是对象");
-	const master = parseMasterConfig(asRecord(raw.master), problems);
-	// watcher 同理：缺节或模型有误时功能拒绝启动，静默回退会拿用户没配的模型真实发起观察。
-	const watcherProblems: string[] = [];
-	if (raw.watcher !== undefined && !isPlainObject(raw.watcher))
-		watcherProblems.push("watcher 必须是对象");
-	const watcher = parseWatcherConfig(asRecord(raw.watcher), watcherProblems);
-	if (raw.watcher !== undefined || features.watcher !== false) problems.push(...watcherProblems);
-
-	cached = { config: { features, keys, presets, review, master, watcher }, problems };
+
+	// review / master / watcher 有问题时对应功能拒绝启动：静默补齐会拿用户没选的模型真实发起调用。
+	// 节内问题只在功能开启时进全局警告。
+	const section = <T>(
+		name: "review" | "master" | "watcher",
+		label: string,
+		parse: (record: Record<string, unknown>, problems: string[]) => T,
+		incomplete: (config: T) => string | undefined,
+	): { config: T; verdict: Section<T> } => {
+		const own: string[] = [];
+		if (raw[name] !== undefined && !isPlainObject(raw[name])) own.push(`${name} 必须是对象`);
+		const config = parse(asRecord(raw[name]), own);
+		if (features[name] !== false) problems.push(...own);
+		const reasons = [...blocking, ...own];
+		const missing = reasons.length ? undefined : incomplete(config);
+		if (missing) reasons.push(missing);
+		return { config, verdict: reasons.length ? { error: `${label}配置有问题，已停止：${reasons.join("；")}` } : { config } };
+	};
+	const review = section("review", "fire-review ", parseReviewConfig, (config) =>
+		config.advisor.model && config.reviewers.length ? undefined : "请显式完整配置 review");
+	const master = section("master", "Master ", parseMasterConfig, (config) =>
+		config.roles.length ? undefined : "请在 master.roles 至少配置一个角色");
+	const watcher = section("watcher", "观察员", parseWatcherConfig, () => undefined);
+
+	cached = {
+		config: { features, keys, presets, review: review.config, master: master.config, watcher: watcher.config },
+		problems,
+		review: review.verdict,
+		master: master.verdict,
+		watcher: watcher.verdict,
+		featuresBroken,
+	};
 	return cached;
 }
 
+// ---- 模型原子 ----
+
+const THINKING_LEVELS = new Set<ThinkingLevelValue>([
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+]);
+const FALLBACK_THINKING: ThinkingLevelValue = "medium";
+
+/**
+ * 解析 "provider/model/thinking"：按最后一个斜杠切出思考档，前半必须仍是 provider/model。
+ * 任何位置的模型配置都走这里，解析失败只记录问题并留空模型，让上层拒绝启动。
+ * 每个字段只报一条问题，且必带目标形状——两段式旧写法会同时踩中两项校验，逐项报错说不出该改成什么。
+ * 旧的分字段与两段式写法一律拒绝、不做兼容：兼容层会把三种写法固化成三套事实源。
+ */
+export function parseModelAtom(value: unknown, field: string, problems: string[]): ModelAtom {
+	const shape = `${field} 必须是“provider/model/thinking”字符串`;
+	if (typeof value !== "string" || !value) {
+		problems.push(shape);
+		return { model: "", thinking: FALLBACK_THINKING };
+	}
+	const slash = value.lastIndexOf("/");
+	const model = slash > 0 ? value.slice(0, slash) : "";
+	const thinking = slash > 0 ? value.slice(slash + 1) : value;
+	const providerSlash = model.indexOf("/");
+	const valid = THINKING_LEVELS.has(thinking as ThinkingLevelValue);
+	const faults: string[] = [];
+	if (providerSlash <= 0 || providerSlash === model.length - 1)
+		faults.push(`模型段不是 provider/model：${model || value}`);
+	if (!valid) faults.push(`思考档无效：${thinking}`);
+	if (faults.length) problems.push(`${shape}（${faults.join("；")}）`);
+	return { model, thinking: valid ? (thinking as ThinkingLevelValue) : FALLBACK_THINKING };
+}
+
+// ---- presets 节 ----
+
+const PRESET_KEYS = ["model", "tools", "instructions", "key"] as const;
+
+function parsePresets(value: unknown, problems: string[]): Record<string, Preset> {
+	if (value === undefined) return {};
+	if (!isPlainObject(value)) {
+		problems.push("presets 必须是对象");
+		return {};
+	}
+	return Object.fromEntries(
+		Object.entries(value).map(([name, raw]) => [name, parsePreset(raw, `presets.${name}`, problems)]),
+	);
+}
+
+/** preset 只在写了 model 时切模型；其余字段与模型原子互不依赖。 */
+function parsePreset(value: unknown, field: string, problems: string[]): Preset {
+	if (!isPlainObject(value)) {
+		problems.push(`${field} 必须是对象`);
+		return {};
+	}
+	rejectUnknownKeys(value, PRESET_KEYS, field, problems);
+	return {
+		...(value.model === undefined
+			? {}
+			: { model: parseModelAtom(value.model, `${field}.model`, problems) }),
+		...(value.tools === undefined ? {} : { tools: stringArray(value.tools, `${field}.tools`, problems) }),
+		...(value.instructions === undefined
+			? {}
+			: { instructions: stringValue(value.instructions, `${field}.instructions`, problems) }),
+		...(value.key === undefined ? {} : { key: stringValue(value.key, `${field}.key`, problems) }),
+	};
+}
+
 // ---- review 节 ----
 
 const REVIEW_KEYS = new Set([
@@ -247,16 +368,6 @@ const REVIEW_KEYS = new Set([
 	"language",
 ]);
 const DEFAULT_TOOLS = ["read", "grep", "find", "ls", "bash"];
-const EMPTY_REVIEW_MODEL: ReviewModel = { model: "", thinking: "medium" };
-const THINKING_LEVELS = new Set<ThinkingLevelValue>([
-	"off",
-	"minimal",
-	"low",
-	"medium",
-	"high",
-	"xhigh",
-	"max",
-]);
 const LANGUAGES = new Set<Language>(["zh", "en"]);
 
 /** 导出供测试：严格拒绝未知字段（含嵌套），类型错误一律记录而非静默回退。 */
@@ -267,9 +378,11 @@ export function parseReviewConfig(raw: Record<string, unknown>, problems: string
 			? "review.background 已随审查子进程层删除，请直接移除该键"
 			: `未知字段 review.${key}`);
 	}
+	// advisor 与 reviewers 缺失由模型原子解析自己报形状，不再叠一条泛化的“必须显式配置”。
 	for (const key of REVIEW_KEYS)
-		if (!(key in raw)) problems.push(`review.${key} 必须显式配置`);
-	const advisor = reviewModel(raw.advisor, "review.advisor", EMPTY_REVIEW_MODEL, problems);
+		if (key !== "advisor" && key !== "reviewers" && !(key in raw))
+			problems.push(`review.${key} 必须显式配置`);
+	const advisor = parseModelAtom(raw.advisor, "review.advisor", problems);
 	const reviewers = reviewModels(raw.reviewers, problems);
 	return {
 		advisor,
@@ -282,46 +395,12 @@ export function parseReviewConfig(raw: Record<string, unknown>, problems: string
 	};
 }
 
-/** 嵌套对象也做键白名单：拼写错误必须报出来，不能静默回退默认值。 */
-function rejectUnknownKeys(
-	record: Record<string, unknown>,
-	allowed: readonly string[],
-	field: string,
-	problems: string[],
-) {
-	for (const key of Object.keys(record))
-		if (!allowed.includes(key)) problems.push(`未知字段 ${field}.${key}`);
-}
-
-function reviewModel(
-	value: unknown,
-	field: string,
-	fallback: ReviewModel,
-	problems: string[],
-): ReviewModel {
-	if (value === undefined) return fallback;
-	const record = asRecord(value);
-	rejectUnknownKeys(record, ["model", "thinking"], field, problems);
-	if (!record.model || typeof record.model !== "string") {
-		problems.push(`${field}.model 必须是非空字符串`);
-		return fallback;
-	}
-	const thinking =
-		typeof record.thinking === "string" && THINKING_LEVELS.has(record.thinking as ThinkingLevelValue)
-			? (record.thinking as ThinkingLevelValue)
-			: fallback.thinking;
-	if (thinking !== record.thinking) problems.push(`${field}.thinking 值无效`);
-	return { model: record.model, thinking };
-}
-
-function reviewModels(value: unknown, problems: string[]): ReviewModel[] {
+function reviewModels(value: unknown, problems: string[]): ModelAtom[] {
 	if (!Array.isArray(value) || value.length === 0 || value.length > 5) {
-		if (value !== undefined) problems.push("review.reviewers 必须包含 1–5 个模型");
+		problems.push("review.reviewers 必须包含 1–5 个模型原子");
 		return [];
 	}
-	return value.map((item, index) =>
-		reviewModel(item, `review.reviewers[${index}]`, EMPTY_REVIEW_MODEL, problems),
-	);
+	return value.map((item, index) => parseModelAtom(item, `review.reviewers[${index}]`, problems));
 }
 
 function reviewInt(
@@ -364,104 +443,51 @@ export function parseMasterConfig(raw: Record<string, unknown>, problems: string
 	if (raw.roles === undefined)
 		return { roles: [], workerExcludeExtensions: exclusions, autoActivate };
 	if (!isPlainObject(raw.roles) || Object.keys(raw.roles).length === 0) {
-		problems.push("master.roles 必须是至少包含一个固定角色的对象");
+		problems.push("master.roles 必须是至少包含一个角色的对象");
 		return { roles: [], workerExcludeExtensions: exclusions, autoActivate };
 	}
-	const configured = raw.roles;
-	for (const role of Object.keys(configured))
-		if (!MASTER_ROLES.includes(role as MasterRoleName))
-			problems.push(`未知角色 master.roles.${role}，可用：${MASTER_ROLES.join(" / ")}`);
-	const roles = MASTER_ROLES.flatMap((role) =>
-		Object.hasOwn(configured, role)
-			? [masterRole(configured[role], `master.roles.${role}`, role, problems)]
-			: []);
+	const roles = Object.entries(raw.roles).map(([role, value]) =>
+		masterRole(value, `master.roles.${role}`, role, problems));
 	return { roles, workerExcludeExtensions: exclusions, autoActivate };
 }
 
-function booleanValue(value: unknown, field: string, fallback: boolean, problems: string[]): boolean {
-	if (value === undefined) return fallback;
-	if (typeof value === "boolean") return value;
-	problems.push(`${field} 必须是 true 或 false`);
-	return fallback;
-}
-
-function stringArray(value: unknown, field: string, problems: string[]): string[] {
-	if (value === undefined) return [];
-	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item)) {
-		problems.push(`${field} 必须是非空字符串数组`);
-		return [];
-	}
-	return [...new Set(value)];
-}
-
-function masterRole(
-	value: unknown,
-	field: string,
-	role: MasterRoleName,
-	problems: string[],
-): MasterRole {
+function masterRole(value: unknown, field: string, role: string, problems: string[]): MasterRole {
 	const record = asRecord(value);
 	rejectUnknownKeys(record, ["model", "use", "fallback"], field, problems);
-	const atom = masterModelAtom(record.model, `${field}.model`, problems);
+	const atom = parseModelAtom(record.model, `${field}.model`, problems);
 	const use = typeof record.use === "string" && record.use ? record.use : "";
 	if (!use) problems.push(`${field}.use 必须是非空字符串`);
 	const fallback = masterFallback(record.fallback, `${field}.fallback`, problems);
 	return { role, ...atom, use, fallback };
 }
 
-function masterFallback(value: unknown, field: string, problems: string[]): MasterModelAtom[] {
+function masterFallback(value: unknown, field: string, problems: string[]): ModelAtom[] {
 	if (value === undefined) return [];
 	if (!Array.isArray(value) || value.length > 2) {
 		problems.push(`${field} 必须是至多 2 项的数组`);
 		return [];
 	}
-	return value.map((item, index) => masterModelAtom(item, `${field}[${index}]`, problems));
-}
-
-function masterModelAtom(value: unknown, field: string, problems: string[]): MasterModelAtom {
-	if (typeof value !== "string" || !value) {
-		problems.push(`${field} 必须是“供应商/模型/思考档”字符串`);
-		return { model: "", thinking: "medium" };
-	}
-	const slash = value.lastIndexOf("/");
-	const model = slash > 0 ? value.slice(0, slash) : "";
-	const thinking = slash > 0 ? value.slice(slash + 1) : value;
-	if (!THINKING_LEVELS.has(thinking as ThinkingLevelValue))
-		problems.push(`${field} 思考档无效：${thinking}`);
-	const providerSlash = model.indexOf("/");
-	if (providerSlash <= 0 || providerSlash === model.length - 1)
-		problems.push(`${field} 模型无效：必须是 provider/model`);
-	return {
-		model,
-		thinking: THINKING_LEVELS.has(thinking as ThinkingLevelValue)
-			? thinking as ThinkingLevelValue
-			: "medium",
-	};
+	return value.map((item, index) => parseModelAtom(item, `${field}[${index}]`, problems));
 }
 
 // ---- watcher 节 ----
 
-const WATCHER_KEYS = ["enabled", "model", "thinking", "context"] as const;
+const WATCHER_KEYS = ["enabled", "model", "context"] as const;
 const WATCHER_CONTEXTS = new Set<WatcherContext>(["minimal", "full"]);
 
-/** 导出供测试：model/thinking 必填，enabled 默认 true、context 默认 minimal。 */
+/** 导出供测试：model 必填（含思考档），enabled 默认 true、context 默认 minimal。 */
 export function parseWatcherConfig(raw: Record<string, unknown>, problems: string[]): WatcherConfig {
 	rejectUnknownKeys(raw, WATCHER_KEYS, "watcher", problems);
 	const enabled = booleanValue(raw.enabled, "watcher.enabled", true, problems);
-	const model = typeof raw.model === "string" && raw.model ? raw.model : "";
-	if (!model) problems.push("watcher.model 必须显式配置为非空字符串");
-	let thinking: ThinkingLevelValue | undefined;
-	if (raw.thinking === undefined) problems.push("watcher.thinking 必须显式配置");
-	else if (typeof raw.thinking === "string" && THINKING_LEVELS.has(raw.thinking as ThinkingLevelValue))
-		thinking = raw.thinking as ThinkingLevelValue;
-	else problems.push("watcher.thinking 值无效");
+	// 模型原子必填：缺失或写错时留空模型并记录问题，观察员据此拒绝启动。
+	const atom = parseModelAtom(raw.model, "watcher.model", problems);
 	let context: WatcherContext = "minimal";
 	if (raw.context !== undefined) {
 		if (typeof raw.context === "string" && WATCHER_CONTEXTS.has(raw.context as WatcherContext))
 			context = raw.context as WatcherContext;
 		else problems.push("watcher.context 必须是 minimal 或 full");
 	}
-	return { enabled, model, thinking: thinking ?? "low", context };
+	return { enabled, ...atom, context };
 }
 
 function reviewLanguage(value: unknown, problems: string[]): Language {

package/deliver.ts

@@ -1,32 +1,119 @@
 /**
  * 统一投递入口（Master 事件与观察员发言共用）：宿主流式中投自定义卡片、经
- * steer 队列在句缝送达；会话歇透时改走 sendUserMessage 前门唤起——宿主的
- * triggerTurn 唤醒会跳过 before_agent_start（上游缺陷，#33），前门唤醒自带
- * 完整开跑仪式，系统提示注入不随回合抖动。
+ * steer 队列在句缝送达；会话歇透时改走 sendUserMessage 前门唤起（只告知不唤醒的
+ * 结果改走 inform，歇透时直接追加）。唤醒走前门而非 triggerTurn 的原因（#33）与回合中不得立即追加（#28）见根 AGENTS.md 硬约束。
+ * 宿主的扩展 sendUserMessage 返回 void、不等回合：以宿主记录这条消息为送达，没进回合就改走 steer 补投（tests/delivery-contract.test.ts 钉住）。
  *
  * 忙闲判断与发送必须在同一事件循环节拍内完成，两者之间禁止 await：会话落定
  * 是下一节拍的事件，同节拍读到的忙闲不会骑墙；宿主在回合结束前清空 steer
  * 队列，忙时入队的消息以同回合续跑送达，不会沦为唤醒者。
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { textOf } from "./format.js";
 
-export interface Envelope<T> {
+/**
+ * 机器消息的信封是唯一事实源：模型上下文里的来源标记、卡片与折叠界面的识别都从这里来。
+ * 一条消息可含多个信封（并发落定的事件各占一个）；整条文本恰好由信封构成才算机器消息。
+ */
+export const ENVELOPE_TAGS = ["firecode_master_event", "firecode_watcher", "firecode_review"] as const;
+export type EnvelopeTag = (typeof ENVELOPE_TAGS)[number];
+
+export interface ParsedEnvelope {
+	tag: EnvelopeTag;
+	body: string;
+}
+
+export function wrapEnvelope(tag: EnvelopeTag, body: string): string {
+	return `<${tag}>\n${body}\n</${tag}>`;
+}
+
+const ENVELOPE = new RegExp(`<(${ENVELOPE_TAGS.join("|")})>\\n([\\s\\S]*?)\\n</\\1>\\s*`, "uy");
+
+export function parseEnvelopes(text: string): ParsedEnvelope[] | undefined {
+	const source = text.trim();
+	const found: ParsedEnvelope[] = [];
+	let end = 0;
+	for (;;) {
+		ENVELOPE.lastIndex = end;
+		const match = ENVELOPE.exec(source);
+		if (!match) break;
+		found.push({ tag: match[1] as EnvelopeTag, body: match[2] });
+		end = ENVELOPE.lastIndex;
+	}
+	return found.length && end === source.length ? found : undefined;
+}
+
+export interface Delivery {
 	customType: string;
+	/** 已按信封格式包好的正文，同时是卡片渲染的唯一数据源。 */
 	content: string;
-	details?: T;
 }
 
-export async function deliver<T>(
+/**
+ * 统一投递，resolve 即“已交给指挥官”：
+ * - 主回合在跑：卡片进 steer 队列，入队即交付；
+ * - 主回合歇透：前门 sendUserMessage 唤起，见 wake。
+ */
+export async function deliver(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
-	envelope: Envelope<T>,
+	envelope: Delivery,
 ): Promise<void> {
-	if (ctx.isIdle?.() === true) {
-		await pi.sendUserMessage(envelope.content);
-		return;
-	}
-	pi.sendMessage<T>(
-		{ customType: envelope.customType, content: envelope.content, display: true, details: envelope.details },
+	if (ctx.isIdle()) return wake(pi, envelope);
+	steer(pi, envelope);
+}
+
+/**
+ * 告知不唤醒：指挥官没在等的结果（用户在子代理视图里直接派的运行）。主回合在跑时与 deliver 相同，经 steer 队列句缝送达；
+ * 主会话歇透时以不带 triggerTurn 的 sendMessage 追加为会话记录，下一回合自然进上下文，resolve 即已写入。
+ * 歇透时追加是安全的（核对宿主 AgentSession.sendCustomMessage）：不在流式中且不触发回合时，宿主当场写会话树并刷新
+ * 上下文，追加在最后一条消息之后，不夹进工具调用与结果之间，已有前缀不变、提示词缓存不重写。#28 的快照分叉只发生在
+ * 回合进行中立即追加；这里也不经 triggerTurn，与 #33 无关。
+ */
+export async function inform(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	envelope: Delivery,
+): Promise<void> {
+	if (!ctx.isIdle()) return steer(pi, envelope);
+	pi.sendMessage({ customType: envelope.customType, content: envelope.content, display: true });
+}
+
+function steer(pi: ExtensionAPI, envelope: Delivery): void {
+	pi.sendMessage(
+		{ customType: envelope.customType, content: envelope.content, display: true },
 		{ deliverAs: "steer" },
 	);
 }
+
+/**
+ * 前门唤起按事实确认送达。宿主的扩展 sendUserMessage 返回 void、不等回合；开回合前被拒时只走宿主
+ * emitError，扩展订阅不到。所以等下一个回合的第一条消息：
+ * - 正是这条信封（role=user、正文原样）：它开启了这一回合，送达；
+ * - 是别的（用户自己发的话、其他扩展唤起的消息）：这条没进来，会话此刻正忙，同一节拍改走 steer 补投，句缝送达。
+ * 两种情况下 resolve 时指挥官回合都已在跑，Master 扣在飞数不会让 busy.ts 误报歇下。
+ * 之后再没有任何回合时投递保持未完成：宁可不歇下，也不误报歇下；没有计时器。
+ * 不以任意 agent_start 为送达（宿主拒绝后用户自己开的回合会被误认，事件被 ack 却没进上下文）；不加超时（超时后仍判断不了是否送达）。
+ */
+function wake(pi: ExtensionAPI, envelope: Delivery): Promise<void> {
+	const delivered = Promise.withResolvers<void>();
+	let running = false;
+	const unsubscribe = [
+		pi.on("agent_start", () => {
+			running = true;
+		}),
+		pi.on("message_start", ({ message }) => {
+			if (!running) return;
+			for (const off of unsubscribe) off();
+			if (message.role !== "user" || textOf(message.content) !== envelope.content) steer(pi, envelope);
+			delivered.resolve();
+		}),
+	];
+	try {
+		pi.sendUserMessage(envelope.content);
+	} catch (error) {
+		for (const off of unsubscribe) off();
+		throw error;
+	}
+	return delivered.promise;
+}