pi-firecode 0.8.0 → 1.0.0

package/master/spawn.ts

@@ -3,17 +3,21 @@ import { basename, dirname } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import {
 	createAgentSession,
+	createCodemodeExtension,
 	DefaultResourceLoader,
 	getAgentDir,
 	ModelRuntime,
 	SessionManager,
 	type AgentSession,
+	type InlineExtension,
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { withSubsessionRole, type SubsessionRole } from "./role.js";
 import type { WorkerThinking } from "./state.js";
 
 export const IDLE_SESSION_TIMEOUT_MS = 10 * 60_000;
+/** 宿主只给 CLI 主会话注入内置扩展；子会话自带 codemode（按 builtin 名受 settings 开关），激活仍由 tools 决定。 */
+const BUILTIN_CODEMODE: InlineExtension = { name: "codemode", factory: createCodemodeExtension(), replaceable: true, builtin: true };
 
 export type SessionPersistence =
 	| { type: "memory" }
@@ -39,7 +43,8 @@ export interface SpawnedSession {
 	readonly session: AgentSession;
 	readonly sessionPath?: string;
 	prompt(text: string): Promise<void>;
-	dispose(): void;
+	/** 先让会话内扩展按宿主契约收口（session_shutdown），再释放；resolve 即收口完成。 */
+	dispose(): Promise<void>;
 }
 
 interface HeldSession {
@@ -47,21 +52,41 @@ interface HeldSession {
 	session: AgentSession;
 	sessionPath?: string;
 	timer?: NodeJS.Timeout;
-	unsubscribe?: () => void;
-	disposed: boolean;
+	releasing?: Promise<void>;
 }
 
-const SESSION_WRITERS = new Set<string>();
+// 单写者登记必须进程唯一：宿主按文件重新求值模块图（见 role.ts），模块级集合在副本间互不可见。
+const WRITERS_KEY = Symbol.for("firecode.session-writers");
+const SESSION_WRITERS = ((globalThis as Record<symbol, unknown>)[WRITERS_KEY] ??= new Set<string>()) as Set<string>;
 
-/** 全插件唯一的进程内子会话入口；池同时是 JSONL 单写者登记。 */
+export interface PoolEnvironment {
+	agentDir?: string;
+	modelRuntime?: ModelRuntime;
+	idleTimeoutMs?: number;
+	/** 模型原子 id（provider/model）解析；默认用池内缓存的一份 ModelRuntime。 */
+	resolveModel?: (id: string) => Promise<Model<any>>;
+}
+
+/** 全插件唯一的进程内子会话入口：模型解析、单写者登记与热会话生命周期都在这里。 */
 export class InProcessSessionPool {
 	private readonly held = new Map<string, HeldSession>();
-
-	constructor(private readonly environment: {
-		agentDir?: string;
-		modelRuntime?: ModelRuntime;
-		idleTimeoutMs?: number;
-	} = {}) {}
+	private runtime?: Promise<ModelRuntime>;
+	private readonly releaseListeners = new Set<(sessionPath: string) => void>();
+
+	constructor(private readonly environment: PoolEnvironment = {}) {}
+
+	/**
+	 * 把 "provider/model" 解析成模型。ModelRuntime 每个池只建一次（auth.json 与 models.json 只读一次），解析与建子会话共用；
+	 * 扩展注册的 provider 在这里不可见，只能用内置 provider 与 models.json 里的模型。
+	 */
+	async resolveModel(id: string): Promise<Model<any>> {
+		if (this.environment.resolveModel) return this.environment.resolveModel(id);
+		const runtime = await this.modelRuntime();
+		const slash = id.indexOf("/");
+		const model = slash > 0 ? runtime.getModel(id.slice(0, slash), id.slice(slash + 1)) : undefined;
+		if (!model) throw new Error(`找不到模型：${id}；子会话只能使用内置 provider 或 models.json 里的模型`);
+		return model;
+	}
 
 	async spawn(options: SpawnSessionOptions): Promise<SpawnedSession> {
 		const sessionPath = options.persistence.type === "file" ? options.persistence.sessionPath : undefined;
@@ -77,6 +102,7 @@ export class InProcessSessionPool {
 				cwd: options.cwd,
 				agentDir: this.environment.agentDir ?? getAgentDir(),
 				noContextFiles: !options.contextFiles,
+				extensionFactories: [BUILTIN_CODEMODE],
 				noExtensions: options.isolated,
 				noSkills: options.isolated,
 				noPromptTemplates: options.isolated,
@@ -96,7 +122,8 @@ export class InProcessSessionPool {
 			const result = await createAgentSession({
 				cwd: options.cwd,
 				agentDir: this.environment.agentDir,
-				modelRuntime: this.environment.modelRuntime,
+				// 与模型解析同一份：不传时宿主会为每个子会话重读一次 auth.json 与 models.json。
+				modelRuntime: await this.modelRuntime(),
 				model: options.model,
 				thinkingLevel: options.thinking,
 				tools: options.tools,
@@ -112,12 +139,8 @@ export class InProcessSessionPool {
 		}
 
 		const key = sessionPath ?? `memory:${crypto.randomUUID()}`;
-		const held: HeldSession = { key, session: created, sessionPath, disposed: false };
+		const held: HeldSession = { key, session: created, sessionPath };
 		this.held.set(key, held);
-		held.unsubscribe = created.subscribe((event) => {
-			if (event.type === "agent_start") this.clearTimer(held);
-			if (event.type === "agent_settled") this.armIdleDisposal(held);
-		});
 		return {
 			session: created,
 			sessionPath,
@@ -126,6 +149,20 @@ export class InProcessSessionPool {
 		};
 	}
 
+	/** 热会话被释放（空闲到期或 dispose）后通知持有方放掉对它的订阅与引用；返回退订函数。 */
+	onRelease(listener: (sessionPath: string) => void): () => void {
+		this.releaseListeners.add(listener);
+		return () => this.releaseListeners.delete(listener);
+	}
+
+	private modelRuntime(): Promise<ModelRuntime> {
+		const agentDir = this.environment.agentDir ?? getAgentDir();
+		this.runtime ??= this.environment.modelRuntime
+			? Promise.resolve(this.environment.modelRuntime)
+			: ModelRuntime.create({ authPath: `${agentDir}/auth.json`, modelsPath: `${agentDir}/models.json` });
+		return this.runtime;
+	}
+
 	has(sessionPath: string): boolean {
 		return this.held.has(sessionPath);
 	}
@@ -137,38 +174,42 @@ export class InProcessSessionPool {
 		return held.session;
 	}
 
+	/** 空闲只由调用方判定：池不订阅会话事件自判空闲；超时后释放热会话，档案与 JSONL 保留。 */
 	markIdle(sessionPath: string): void {
 		const held = this.held.get(sessionPath);
-		if (held) this.armIdleDisposal(held);
+		if (!held) return;
+		this.clearTimer(held);
+		held.timer = setTimeout(() => void this.release(held), this.environment.idleTimeoutMs ?? IDLE_SESSION_TIMEOUT_MS);
+		held.timer.unref?.();
 	}
 
-	dispose(sessionPath: string): boolean {
+	async dispose(sessionPath: string): Promise<boolean> {
 		const held = this.held.get(sessionPath);
 		if (!held) return false;
-		this.release(held);
+		await this.release(held);
 		return true;
 	}
 
-	disposeAll(): void {
-		for (const held of [...this.held.values()]) this.release(held);
+	async disposeAll(): Promise<void> {
+		await Promise.all([...this.held.values()].map((held) => this.release(held)));
 	}
 
-	private armIdleDisposal(held: HeldSession): void {
-		this.clearTimer(held);
-		held.timer = setTimeout(() => {
-			if (!held.session.isStreaming) this.release(held);
-		}, this.environment.idleTimeoutMs ?? IDLE_SESSION_TIMEOUT_MS);
-		held.timer.unref?.();
-	}
-
-	private release(held: HeldSession): void {
-		if (held.disposed) return;
-		held.disposed = true;
-		held.unsubscribe?.();
-		this.clearTimer(held);
-		held.session.dispose();
-		if (this.held.get(held.key) === held) this.held.delete(held.key);
-		if (held.sessionPath) SESSION_WRITERS.delete(held.sessionPath);
+	/** 镜像宿主替换会话的顺序：先 session_shutdown 让扩展收口，再 dispose 作废上下文。 */
+	private release(held: HeldSession): Promise<void> {
+		held.releasing ??= (async () => {
+			this.clearTimer(held);
+			if (this.held.get(held.key) === held) this.held.delete(held.key);
+			try {
+				await held.session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+			} finally {
+				held.session.dispose();
+				if (held.sessionPath) {
+					SESSION_WRITERS.delete(held.sessionPath);
+					for (const listener of this.releaseListeners) listener(held.sessionPath);
+				}
+			}
+		})();
+		return held.releasing;
 	}
 
 	private clearTimer(held: HeldSession): void {

package/master/state.ts

@@ -1,8 +1,7 @@
 import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
-const STATE_VERSION = 8;
+const STATE_VERSION = 9;
 
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type WorkerThinking = (typeof THINKING_LEVELS)[number];
@@ -18,6 +17,11 @@ export interface WorkerRef {
 	sessionPath: string;
 	cwd?: string;
 	interruptedAt?: number;
+	/**
+	 * 启动序：start 在同步段按到达先后取的单调序号，活动列表与全过程视图按它排。必须持久化：并行 start 越过
+	 * await 后落盘的先后（以及任何落盘时刻）与到达先后不一致，恢复后若靠别的字段排会换序。
+	 */
+	launch: number;
 	reviewNeeded?: boolean;
 	disposition?: WorkerDisposition;
 }
@@ -79,9 +83,10 @@ export class LegacyMasterStateError extends Error {
 	}
 }
 
-export function masterStatePath(sessionId: string): string {
+/** 子代理池档案：与运行配置同一个 Pi Agent 目录（含 PI_CODING_AGENT_DIR 覆写），按主会话 id 分文件。 */
+export function masterStatePath(agentDir: string, sessionId: string): string {
 	const safeId = sessionId.replace(/[^a-zA-Z0-9_-]/gu, "-");
-	return join(homedir(), ".pi", "agent", "tmp", `firecode-master-${safeId}.json`);
+	return join(agentDir, "tmp", `firecode-master-${safeId}.json`);
 }
 
 export function loadMasterState(path: string): MasterState | undefined {
@@ -99,8 +104,8 @@ export function loadMasterState(path: string): MasterState | undefined {
 		throw new Error(`Master Worker Pool 状态不是合法 JSON：${path}`);
 	}
 	const version = (data as { version?: unknown } | null)?.version;
-	if (typeof version === "number" && version !== STATE_VERSION) throw new LegacyMasterStateError(version);
-	const state = restoreMasterState(data);
+	if (typeof version === "number" && version !== STATE_VERSION && version !== 8) throw new LegacyMasterStateError(version);
+	const state = restoreMasterState(version === 8 ? migrateFromV8(data as { workers?: unknown }) : data);
 	if (!state) throw new Error(`Master Worker Pool 状态结构无效：${path}`);
 	return state;
 }
@@ -147,6 +152,24 @@ export class MasterStore {
 	}
 }
 
+/**
+ * v8 → v9 只差启动序：v8 的创建时间是同一先后的近似（并行 start 下可能有出入，从此以 launch 为准），没有创建时间的
+ * 是更早版本恢复来的、排最前。升级不丢池：池里是用户仍在用的子代理，丢弃会让指挥官失去它们的会话与审查义务。
+ */
+function migrateFromV8(data: { workers?: unknown }): unknown {
+	if (!Array.isArray(data.workers)) return data;
+	const workers = data.workers as Record<string, unknown>[];
+	const created = (index: number) => (typeof workers[index]?.createdAt === "number" ? workers[index].createdAt as number : -Infinity);
+	const order = workers.map((_, index) => index).sort((a, b) => created(a) - created(b) || a - b);
+	return {
+		version: STATE_VERSION,
+		workers: workers.map((worker, index) => {
+			const { createdAt: _createdAt, ...rest } = worker ?? {};
+			return { ...rest, launch: order.indexOf(index) + 1 };
+		}),
+	};
+}
+
 export function requireWorker(state: MasterState, name: string): WorkerRef {
 	const worker = state.workers.find((candidate) => candidate.name === name);
 	if (!worker) throw new Error(`子代理不存在：${name}`);
@@ -191,6 +214,7 @@ function isWorker(value: unknown): value is WorkerRef {
 	if (record.interruptedAt !== undefined && (typeof record.interruptedAt !== "number" || record.interruptedAt <= 0))
 		return false;
 	if (record.reviewNeeded !== undefined && typeof record.reviewNeeded !== "boolean") return false;
+	if (typeof record.launch !== "number" || !Number.isInteger(record.launch) || record.launch <= 0) return false;
 	if (record.disposition !== undefined && record.disposition !== "pending" && record.disposition !== "reminded")
 		return false;
 	return true;