@rexvane/piweb 0.3.15 → 0.3.16

package/src/lib/agent-manager.ts

@@ -33,9 +33,12 @@ import { TrajLedger, buildTrajectoryFromEntries, toTrajTokens } from "./trajecto
 import { startArchivedSessionRetention } from "./session-retention";
 import { sanitizeToolOutput } from "./text-sanitize";
 import { BoundaryError } from "./path-security";
+import { beginActivity } from "./runtime-activity";
 import { estimateTokensOf } from "./process-format";
 import { getPiSettings } from "./pi-settings";
 import { createManagedNiubashTools } from "./managed-niubash";
+import { createDelegationTool } from "./delegation";
+import { awaitingGoalMessage, isWorkflowMode, planCanRun, readWorkflow, saveWorkflow, workflowInstruction, type WorkflowState } from "./workflow";
 import { clampThinkingLevel, getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 import type {
 	AgentCommand,
@@ -66,6 +69,7 @@ interface Managed {
 	ledger: TrajLedger;
 	lastActive: number;
 	toolPreset: ToolPreset;
+	workflow: WorkflowState;
 	/** 显式逐项选择优先于 preset；保留失效名称以便资源重新启用后恢复用户选择。 */
 	customActiveTools?: string[];
 	resourceVersion: number;
@@ -527,6 +531,20 @@ function translate(m: Managed, evt: AgentSessionEvent): void {
 			break;
 		case "agent_settled":
 			m.runActive = false;
+			if (m.workflow.mode === "plan") {
+				if (m.workflow.planStatus === "planning") {
+					const answer = [...(m.session?.messages ?? [])].reverse().find((message) => message.role === "assistant");
+					const ready = answer?.role === "assistant" && answer.stopReason === "stop" && answer.content.some((part) => part.type === "text" && part.text.trim());
+					const entry = ready ? m.sm.getBranch().slice().reverse().find((item) => item.type === "message" && item.message.role === "assistant" && item.message.stopReason === "stop") : undefined;
+					setWorkflow(m, { ...m.workflow, planStatus: entry ? "ready" : "idle", planId: entry?.id });
+				} else if (m.workflow.planStatus === "executing") {
+					// 执行报错或被中止时方案仍待执行：以当前叶节点为新的批准锚点，可以直接再次执行。
+					const answer = [...(m.session?.messages ?? [])].reverse().find((message) => message.role === "assistant");
+					const failed = answer?.role === "assistant" && (answer.stopReason === "error" || answer.stopReason === "aborted");
+					const anchor = failed ? m.sm.getLeafId() : null;
+					setWorkflow(m, anchor ? { ...m.workflow, planStatus: "ready", planId: anchor } : { ...m.workflow, planStatus: "idle", planId: undefined });
+				}
+			}
 			publish(m, { type: "status", isStreaming: false, state: "idle", ts: now });
 			publishUsage(m);
 			if (m.resourceReloadPending) queueMicrotask(() => void reloadManagedResources(m));
@@ -636,6 +654,7 @@ function registerManaged(sessionPath: string, cwd: string, sm: SessionManager):
 		ledger: new TrajLedger(initialTrajectory),
 		lastActive: Date.now(),
 		toolPreset: "readonly",
+		workflow: readWorkflow(sm),
 		resourceVersion: 0,
 		resourceReloadPending: false,
 		resourceReloading: false,
@@ -784,12 +803,33 @@ function publishEnvironmentTrajectory(m: Managed, session: AgentSession): void {
 }
 
 export async function ensureSession(m: Managed): Promise<AgentSession> {
+	const release = beginActivity("session");
+	try { return await ensureSessionActive(m); }
+	finally { release(); }
+}
+
+async function ensureSessionActive(m: Managed): Promise<AgentSession> {
 	if (m.disposed) throw new Error("session is disposed");
 	if (m.creating) return m.creating;
 	if (m.session) return m.session;
 	m.creating = (async () => {
 		await resourceLoaderReady(m.cwd);
-		const loader = await createSessionResourceLoader(m.cwd);
+		const loader = await createSessionResourceLoader(m.cwd, [{
+			name: "piweb-workflow",
+			hidden: true,
+			factory: (pi) => {
+				pi.on("before_agent_start", (event) => {
+					const instruction = workflowInstruction(m.workflow);
+					if (instruction) {
+						if (event.systemPromptOptions.forceSystemPrompt !== undefined) event.systemPromptOptions.forceSystemPrompt += `\n\n${instruction}`;
+						else event.systemPromptOptions.sections.piweb_workflow = instruction;
+					} else delete event.systemPromptOptions.sections.piweb_workflow;
+					if (m.workflow.mode === "plan" && m.workflow.planStatus !== "executing") {
+						event.systemPromptOptions.selectedTools = event.systemPromptOptions.selectedTools.filter((name) => [...TOOL_PRESETS.readonly, "piweb_delegate"].includes(name));
+					}
+				});
+			},
+		}]);
 		let created: AgentSession | undefined;
 		try {
 			if (m.disposed) throw new Error("session is disposed");
@@ -801,7 +841,7 @@ export async function ensureSession(m: Managed): Promise<AgentSession> {
 				resourceLoader: loader,
 				settingsManager: getSettingsManager(m.cwd),
 				// Windows: 同名 bash 覆盖 SDK 内置工具，指向托管 niubash；其它平台返回 []，走 Pi 默认。
-				customTools: createManagedNiubashTools(m.cwd),
+				customTools: [...createManagedNiubashTools(m.cwd), createDelegationTool(m.cwd, () => m.session)],
 			});
 			created = session;
 			if (m.disposed) throw new Error("session is disposed");
@@ -848,7 +888,9 @@ function isManagedBusy(m: Managed): boolean {
 
 function allowedToolNames(m: Managed, session: AgentSession): string[] {
 	const allowed = m.customActiveTools ?? (m.toolPreset === "full" ? undefined : TOOL_PRESETS[m.toolPreset]);
-	return listAllToolNames(session).filter((name) => !allowed || allowed.includes(name));
+	const effective = allowed ? [...allowed, ...(m.customActiveTools || m.toolPreset === "readonly" ? [] : ["piweb_delegate"])] : undefined;
+	const planning = m.workflow.mode === "plan" && m.workflow.planStatus !== "executing";
+	return listAllToolNames(session).filter((name) => (!effective || effective.includes(name)) && (!planning || [...TOOL_PRESETS.readonly, "piweb_delegate"].includes(name)));
 }
 
 function applyToolPolicy(m: Managed, session: AgentSession): void {
@@ -859,6 +901,20 @@ 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() });
 }
 
+function setWorkflow(m: Managed, next: WorkflowState): void {
+	saveWorkflow(m.sm, next);
+	m.workflow = next;
+	publishWorkflow(m);
+}
+
+function publishWorkflow(m: Managed): void {
+	if (m.session && !m.disposed) {
+		applyToolPolicy(m, m.session);
+		publishTools(m, m.session);
+	}
+	publish(m, { type: "workflow", workflow: m.workflow, ts: Date.now() });
+}
+
 /** SDK reload 自动启用扩展工具，注册新工具也会刷新全集；统一在激活边界收敛到服务端选择。 */
 function installSessionPolicy(m: Managed, session: AgentSession): void {
 	const setActive = session.setActiveToolsByName.bind(session);
@@ -1174,12 +1230,12 @@ export async function buildSnapshot(m: Managed): Promise<WebSnapshot> {
 			}
 			for (let i = messages.length - 1; i >= 0 && !compactedSinceLastAssistant; i--) {
 				const msg = messages[i];
-				if (msg.role === "assistant" && msg.usage) {
-					lastTurnTokens =
+				if (msg.role === "assistant" && msg.usage && msg.stopReason !== "error" && msg.stopReason !== "aborted") {
+					lastTurnTokens = Number(msg.usage.totalTokens ?? 0) || (
 						Number(msg.usage.input ?? 0) +
 						Number(msg.usage.cacheRead ?? 0) +
 						Number(msg.usage.cacheWrite ?? 0) +
-						Number(msg.usage.output ?? 0);
+						Number(msg.usage.output ?? 0));
 					break;
 				}
 			}
@@ -1244,6 +1300,7 @@ export async function buildSnapshot(m: Managed): Promise<WebSnapshot> {
 		thinkingLevel,
 		thinkingLevels,
 		toolPreset: m.toolPreset,
+		workflow: m.workflow,
 		customActiveTools: m.customActiveTools ?? null,
 		extensionUiRequests: m.ui?.getPendingRequests() ?? [],
 		tools,
@@ -1297,12 +1354,52 @@ export interface CommandResult {
 }
 
 export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandResult> {
+	let release: (() => void) | undefined;
+	try {
+		if (!["abort", "clearQueue", "extensionUiResponse"].includes(cmd.cmd)) release = beginActivity("session");
+		return await executeCommand(m, cmd);
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+	} finally {
+		release?.();
+	}
+}
+
+function trackedPrompt(session: AgentSession, ...args: Parameters<AgentSession["prompt"]>): ReturnType<AgentSession["prompt"]> {
+	const release = beginActivity("session");
+	try { return session.prompt(...args).finally(release); }
+	catch (error) { release(); throw error; }
+}
+
+async function executeCommand(m: Managed, cmd: AgentCommand): Promise<CommandResult> {
 	touch(m);
 	try {
 		switch (cmd.cmd) {
 			case "prepare":
 				await ensureSession(m);
 				return { ok: true };
+			case "setWorkflowMode": {
+				if (!isWorkflowMode(cmd.mode)) return { ok: false, error: "invalid workflow mode" };
+				if (isManagedBusy(m)) return { ok: false, error: "cannot change workflow while the agent is running" };
+				// 重选当前模式不重置：否则会清掉 Goal 目标或待执行的方案，并多写一条记录。
+				if (cmd.mode === m.workflow.mode) return { ok: true };
+				setWorkflow(m, { mode: cmd.mode, planStatus: "idle", goal: "" });
+				return { ok: true };
+			}
+			case "approvePlan": {
+				if (!planCanRun(m.workflow)) return { ok: false, error: "there is no plan awaiting approval" };
+				if (isManagedBusy(m)) return { ok: false, error: "session is busy" };
+				const branch = m.sm.getBranch();
+				const planIndex = branch.findIndex((entry) => entry.id === m.workflow.planId);
+				if (planIndex < 0 || branch.slice(planIndex + 1).some((entry) => entry.type === "message")) {
+					return { ok: false, error: "the plan is no longer the latest conversation; request a new plan" };
+				}
+				const ready = m.workflow;
+				setWorkflow(m, { ...ready, planStatus: "executing" });
+				const result = await execute(m, { cmd: "prompt", text: "Execute the plan you just proposed. Verify the changes and report any unfinished work." });
+				if (!result.ok) setWorkflow(m, ready);
+				return result;
+			}
 			case "prompt": {
 				const text = (cmd.text ?? "").trim();
 				if (!text && !cmd.images?.length) return { ok: false, error: "empty prompt" };
@@ -1314,6 +1411,7 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 					if (m.disposed) throw new Error("session is disposed");
 					// 只有用户显式选择 steer/followUp 才排队；旧的普通提交不能悄悄成为 steering。
 					if ((session.isStreaming || m.runActive) && !cmd.behavior) return { ok: false, error: "session is busy; choose steer or followUp" };
+					if (m.workflow.mode === "plan" && (session.isStreaming || m.runActive)) return { ok: false, error: "wait for the current plan or execution to finish" };
 					if (!session.isStreaming) {
 						// 基线快照不能无限阻塞首条 prompt（git 不可用时每次探测至多 30s 超时）：
 						// 5s 内没完成就放行 prompt，快照后台补拍（工具结束后照常记步，外部修改兜底）。
@@ -1323,11 +1421,18 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 						]);
 					}
 					if (m.disposed) throw new Error("session is disposed");
-					return await new Promise<CommandResult>((resolve) => {
+					const previousWorkflow = m.workflow;
+					if (m.workflow.mode === "plan" && m.workflow.planStatus !== "executing") {
+						setWorkflow(m, { ...m.workflow, planStatus: "planning", planId: undefined });
+					} else if (m.workflow.mode === "goal" && !m.workflow.goal && text) {
+						setWorkflow(m, { ...m.workflow, goal: text.slice(0, 8_000) });
+					}
+					const result = await new Promise<CommandResult>((resolve) => {
 						let accepted = false;
-						const run = session.prompt(text, {
+						const run = trackedPrompt(session, text, {
 							images: cmd.images,
 							streamingBehavior: cmd.behavior,
+							expandPromptTemplates: m.workflow.mode !== "plan" || m.workflow.planStatus === "executing",
 							source: "rpc",
 							preflightResult: (success) => {
 								if (success) {
@@ -1344,7 +1449,9 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 							if (accepted) publish(m, { type: "error", message, ts: Date.now() });
 							else resolve({ ok: false, error: message });
 						});
-					});
+						});
+					if (!result.ok && m.workflow !== previousWorkflow) setWorkflow(m, previousWorkflow);
+					return result;
 				} finally {
 					m.promptSubmitting = false;
 					if (!m.disposed) publish(m, { type: "status", isStreaming: isManagedBusy(m), state: isManagedBusy(m) ? "running" : "idle", ts: Date.now() });
@@ -1353,6 +1460,7 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 			}
 			case "steer":
 			case "followUp": {
+				if (m.workflow.mode === "plan") return { ok: false, error: "Plan mode does not queue prompts" };
 				if (m.promptSubmitting || m.resourceReloading) return { ok: false, error: "session is busy accepting another command" };
 				const session = await ensureSession(m);
 				if (m.promptSubmitting || m.resourceReloading || !session.isStreaming) return { ok: false, error: "session is not accepting queued messages" };
@@ -1441,6 +1549,10 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 				const entryId = String((cmd as any).entryId ?? "");
 				if (!entryId) return { ok: false, error: "missing entryId" };
 				const r = await session.navigateTree(entryId);
+				if (!r?.cancelled) {
+					m.workflow = readWorkflow(m.sm);
+					publishWorkflow(m);
+				}
 				return { ok: !r?.cancelled, data: { cancelled: r?.cancelled === true, editorText: r?.editorText } };
 			}
 			case "editAndResend": {
@@ -1450,6 +1562,9 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 				const text = (cmd.text ?? "").trim();
 				if (!entryId) return { ok: false, error: "missing entryId" };
 				if (!text) return { ok: false, error: "empty prompt" };
+				const target = m.sm.getEntry(entryId);
+				if (target?.type !== "message" || target.message.role !== "user") return { ok: false, error: "message is not editable" };
+				const images = Array.isArray(target.message.content) ? target.message.content.filter((part) => part.type === "image") : [];
 				if (m.promptSubmitting || m.resourceReloading) return { ok: false, error: "session is busy accepting another command" };
 				m.promptSubmitting = true;
 				try {
@@ -1463,11 +1578,64 @@ export async function execute(m: Managed, cmd: AgentCommand): Promise<CommandRes
 						}
 					}
 					if (m.disposed) throw new Error("session is disposed");
-					const moved = await session.navigateTree(entryId);
+					// SDK 对当前叶节点直接返回 no-op；先移开叶节点，才能把最后一条用户消息也原位重发。
+					const originalLeafId = m.sm.getLeafId();
+					const leafWasTarget = originalLeafId === entryId;
+					if (leafWasTarget) {
+						if (target.parentId) m.sm.branch(target.parentId);
+						else m.sm.resetLeaf();
+					}
+					let moved;
+					try {
+						moved = await session.navigateTree(entryId);
+					} catch (error) {
+						if (leafWasTarget) m.sm.branch(entryId);
+						throw error;
+					}
+					if (moved?.cancelled && leafWasTarget) m.sm.branch(entryId);
 					if (moved?.cancelled) return { ok: false, error: "edit cancelled" };
+					m.workflow = readWorkflow(m.sm);
+					publishWorkflow(m);
 					await growthOf(m).prepare().catch(() => undefined);
-					await session.prompt(text);
-					return { ok: true };
+					const previousWorkflow = m.workflow;
+					if (m.workflow.mode === "plan") setWorkflow(m, { ...m.workflow, planStatus: "planning", planId: undefined });
+					// 编辑的正是定下目标的那条消息时，目标跟着改；旧目标记录是它的祖先，回退分支不会带走它。
+					else if (m.workflow.mode === "goal" && awaitingGoalMessage(m.sm) && m.workflow.goal !== text.slice(0, 8_000)) {
+						setWorkflow(m, { ...m.workflow, goal: text.slice(0, 8_000) });
+					}
+					const options = { images, expandPromptTemplates: m.workflow.mode !== "plan" };
+					return await new Promise<CommandResult>((resolve) => {
+						let accepted = false;
+						const run = trackedPrompt(session, text, {
+							...options,
+							preflightResult: (success) => {
+								if (success) {
+									accepted = true;
+									resolve({ ok: true, data: { accepted: true } });
+								}
+							},
+						});
+						void run.then(() => {
+							if (!accepted) resolve({ ok: true });
+						}, (error) => {
+							const message = String(error?.message ?? error);
+							if (accepted) {
+								publish(m, { type: "error", message, ts: Date.now() });
+								return;
+							}
+							// Rejected preflight never wrote the edited turn; restore the old branch before the client resyncs.
+							try {
+								if (originalLeafId) m.sm.branch(originalLeafId);
+								else m.sm.resetLeaf();
+								session.refreshContext();
+								m.workflow = readWorkflow(m.sm);
+								publishWorkflow(m);
+							} catch {
+								if (m.workflow !== previousWorkflow) setWorkflow(m, previousWorkflow);
+							}
+							resolve({ ok: false, error: message });
+						});
+					});
 				} finally {
 					m.promptSubmitting = false;
 				}

package/src/lib/command-validation.ts

@@ -1,4 +1,4 @@
-import type { AgentCommand, ImageAttachment, ToolPreset } from "./types";
+import type { AgentCommand, ImageAttachment, ToolPreset, WorkflowMode } from "./types";
 
 const COMMANDS = new Set<AgentCommand["cmd"]>([
 	"prepare",
@@ -10,6 +10,8 @@ const COMMANDS = new Set<AgentCommand["cmd"]>([
 	"setModel",
 	"setThinkingLevel",
 	"setToolPreset",
+	"setWorkflowMode",
+	"approvePlan",
 	"setActiveTools",
 	"rename",
 	"fork",
@@ -21,6 +23,7 @@ const COMMANDS = new Set<AgentCommand["cmd"]>([
 	"reload",
 ]);
 const TOOL_PRESETS = new Set<ToolPreset>(["readonly", "standard", "full"]);
+const WORKFLOW_MODES = new Set<WorkflowMode>(["agent", "plan", "goal"]);
 const STREAMING_BEHAVIORS = new Set(["steer", "followUp"]);
 const IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/webp", "image/gif"]);
 const MAX_TEXT = 1_000_000;
@@ -78,6 +81,10 @@ export function parseAgentCommand(value: unknown): CommandParseResult {
 			if (typeof raw.preset !== "string" || !TOOL_PRESETS.has(raw.preset as ToolPreset)) throw new Error("invalid tool preset");
 			command.preset = raw.preset as ToolPreset;
 		}
+		if (raw.mode !== undefined) {
+			if (typeof raw.mode !== "string" || !WORKFLOW_MODES.has(raw.mode as WorkflowMode)) throw new Error("invalid workflow mode");
+			command.mode = raw.mode as WorkflowMode;
+		}
 		if (raw.behavior !== undefined) {
 			if (typeof raw.behavior !== "string" || !STREAMING_BEHAVIORS.has(raw.behavior)) throw new Error("invalid streaming behavior");
 			command.behavior = raw.behavior as "steer" | "followUp";
@@ -108,6 +115,7 @@ export function parseAgentCommand(value: unknown): CommandParseResult {
 		if (command.cmd === "setModel" && (!command.provider || !command.modelId)) throw new Error("provider and modelId are required");
 		if (command.cmd === "setThinkingLevel" && !command.level) throw new Error("level is required");
 		if (command.cmd === "setToolPreset" && !command.preset) throw new Error("preset is required");
+		if (command.cmd === "setWorkflowMode" && !command.mode) throw new Error("mode is required");
 		if (command.cmd === "setActiveTools" && !command.names) throw new Error("names are required");
 		if (command.cmd === "navigate" && !command.entryId) throw new Error("entryId is required");
 		return { ok: true, command };

package/src/lib/delegation.ts

@@ -0,0 +1,93 @@
+import { DefaultResourceLoader, SessionManager, createAgentSession, defineTool, type AgentSession, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { getAgentDir, getModelRuntime, getSettingsManager, TOOL_PRESETS, withResourceLock } from "./pi";
+
+const MAX_TASKS = 3;
+const TASK_TIMEOUT_MS = 120_000;
+const MAX_REPORT_CHARS = 12_000;
+
+const parameters = Type.Object({
+	tasks: Type.Array(Type.Object({
+		title: Type.String({ minLength: 1, maxLength: 80 }),
+		instruction: Type.String({ minLength: 1, maxLength: 4_000 }),
+	}), { minItems: 1, maxItems: MAX_TASKS }),
+});
+
+function reportOf(session: AgentSession): string {
+	const answer = [...session.messages].reverse().find((message) => message.role === "assistant");
+	if (!answer || answer.role !== "assistant") return "The subagent returned no assistant answer.";
+	return answer.content.filter((part) => part.type === "text").map((part) => part.text).join("\n").slice(0, MAX_REPORT_CHARS) || "The subagent returned no text answer.";
+}
+
+async function runSubagent(cwd: string, parent: AgentSession, instruction: string, signal?: AbortSignal): Promise<string> {
+	if (signal?.aborted) throw new Error("Delegation cancelled");
+	const loader = new DefaultResourceLoader({
+		cwd,
+		agentDir: getAgentDir(),
+		settingsManager: getSettingsManager(cwd),
+		noExtensions: true,
+		noPromptTemplates: true,
+		noThemes: true,
+		appendSystemPrompt: ["You are a read-only PiWeb subagent. Investigate the assigned task and return a concise, evidence-based report. Do not modify files or run commands. Do not delegate further."],
+	});
+	let child: AgentSession | undefined;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let timedOut = false;
+	const abort = () => { void child?.abort().catch(() => undefined); };
+	try {
+		await withResourceLock(() => loader.reload());
+		if (signal?.aborted) throw new Error("Delegation cancelled");
+		const created = await createAgentSession({
+			cwd,
+			agentDir: getAgentDir(),
+			sessionManager: SessionManager.inMemory(cwd),
+			modelRuntime: await getModelRuntime(),
+			model: parent.model ?? undefined,
+			thinkingLevel: parent.thinkingLevel,
+			settingsManager: getSettingsManager(cwd),
+			resourceLoader: loader,
+			tools: TOOL_PRESETS.readonly,
+		});
+		child = created.session;
+		if (signal?.aborted) throw new Error("Delegation cancelled");
+		signal?.addEventListener("abort", abort, { once: true });
+		timer = setTimeout(() => { timedOut = true; abort(); }, TASK_TIMEOUT_MS);
+		await child.prompt(instruction, { source: "rpc", expandPromptTemplates: false });
+		if (timedOut) throw new Error("Subagent timed out after two minutes");
+		if (signal?.aborted) throw new Error("Delegation cancelled");
+		return reportOf(child);
+	} finally {
+		if (timer) clearTimeout(timer);
+		signal?.removeEventListener("abort", abort);
+		child?.dispose();
+		loader.getExtensions().runtime.invalidate();
+	}
+}
+
+export function createDelegationTool(cwd: string, parent: () => AgentSession | null): ToolDefinition {
+	return defineTool({
+		name: "piweb_delegate",
+		label: "Delegate research",
+		description: "Delegate one to three independent, read-only research or review tasks to temporary Pi subagents. They cannot edit files, run shell commands, or delegate further. Use only when parallel investigation is useful; summarize their findings yourself.",
+		promptSnippet: "Delegate bounded, read-only research tasks to temporary subagents.",
+		parameters,
+		executionMode: "sequential",
+		async execute(_id, { tasks }, signal, onUpdate) {
+			const leader = parent();
+			if (!leader) throw new Error("Parent session is unavailable");
+			const reports: string[] = new Array(tasks.length);
+			await Promise.all(tasks.map(async (task, index) => {
+				try {
+					const report = await runSubagent(cwd, leader, task.instruction, signal);
+					reports[index] = `## ${task.title}\n${report}`;
+				} catch (error) {
+					reports[index] = `## ${task.title}\nFailed: ${String((error as Error)?.message ?? error)}`;
+				}
+				onUpdate?.({ content: [{ type: "text", text: reports.filter(Boolean).join("\n\n") }], details: undefined });
+			}));
+			if (signal?.aborted) throw new Error("Delegation cancelled");
+			const text = reports.join("\n\n");
+			return { content: [{ type: "text", text }], details: undefined };
+		},
+	});
+}

package/src/lib/managed-niubash.ts

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
-import { createRequire } from "node:module";
+import * as nodeModule from "node:module";
 import path from "node:path";
 import { createBashToolDefinition, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { APP_ROOT } from "./app-root";
@@ -56,12 +56,16 @@ type LoadedPackage = { entryPath: string; value: unknown };
  * 这与平台包发布后的目录布局一一对应，不引入第二套解析规则。
  */
 export function resolveManagedNiubashPackageEntry(packageName: string, arch: SupportedArch, root = APP_ROOT): LoadedPackage {
-	const require = createRequire(path.join(root, "package.json"));
+	// 必须通过命名空间调用。webpack 会改写从 node:module 具名导入的 createRequire：
+	// 参数不是字符串字面量时把调用擦掉，运行时变成对 undefined 调用 resolve。
+	const loadPackage = nodeModule.createRequire(path.join(root, "package.json"));
+	const resolveEntry = loadPackage.resolve.bind(loadPackage);
 	try {
-		return { entryPath: require.resolve(packageName), value: require(packageName) };
+		const entryPath = resolveEntry(packageName);
+		return { entryPath, value: loadPackage(packageName) };
 	} catch (error) {
 		const checkoutEntry = path.join(root, "platform-packages", PACKAGE_BY_ARCH[arch].directory, "index.cjs");
-		if (fs.existsSync(checkoutEntry)) return { entryPath: checkoutEntry, value: require(checkoutEntry) };
+		if (fs.existsSync(checkoutEntry)) return { entryPath: checkoutEntry, value: loadPackage(checkoutEntry) };
 		throw error;
 	}
 }

package/src/lib/pi.ts

@@ -9,6 +9,7 @@ import {
 	type SettingsManager,
 	DefaultPackageManager,
 	DefaultResourceLoader,
+	type InlineExtension,
 	ModelRuntime,
 	ProjectTrustStore,
 	SessionManager,
@@ -157,10 +158,10 @@ function loaderKey(cwd: string): string {
 }
 
 /** 每个热会话必须拥有自己的扩展 runtime；这里只创建，不加入发现缓存。 */
-export async function createSessionResourceLoader(cwd: string): Promise<DefaultResourceLoader> {
+export async function createSessionResourceLoader(cwd: string, extensionFactories: InlineExtension[] = []): Promise<DefaultResourceLoader> {
 	const settingsManager = getSettingsManager(cwd);
 	settingsManager.setProjectTrusted(resolveProjectTrust(cwd).trusted);
-	const loader = new DefaultResourceLoader({ cwd: path.resolve(cwd), agentDir: getAgentDir(), settingsManager });
+	const loader = new DefaultResourceLoader({ cwd: path.resolve(cwd), agentDir: getAgentDir(), settingsManager, extensionFactories });
 	const reload = loader.reload.bind(loader);
 	loader.reload = async (options) => {
 		settingsManager.setProjectTrusted(resolveProjectTrust(cwd).trusted);

package/src/lib/runtime-activity.ts

@@ -0,0 +1,27 @@
+type ActivityKind = "session" | "swarm" | "tests";
+interface Registry { active: Map<symbol, ActivityKind>; maintenance: boolean }
+
+// Route bundles must share a process-wide gate, not separate module-local registries.
+const globals = globalThis as typeof globalThis & { __piwebRuntimeActivity?: Registry };
+const registry = globals.__piwebRuntimeActivity ??= { active: new Map(), maintenance: false };
+
+export class RuntimeBusyError extends Error {}
+
+export function beginActivity(kind: ActivityKind): () => void {
+  if (registry.maintenance) throw new RuntimeBusyError("update maintenance is active; wait for the release to finish");
+  const token = Symbol(kind);
+  registry.active.set(token, kind);
+  return () => { registry.active.delete(token); };
+}
+
+export function beginMaintenance(): () => void {
+  if (registry.maintenance || registry.active.size) {
+    throw new RuntimeBusyError("work is active; wait for sessions, swarms and tests to finish before entering the maintenance window");
+  }
+  registry.maintenance = true;
+  let released = false;
+  return () => {
+    if (!released) registry.maintenance = false;
+    released = true;
+  };
+}

package/src/lib/session-import/index.ts

@@ -18,6 +18,7 @@ import { dshSource } from "./dsh";
 import { zcodeSource } from "./zcode";
 import { opencodeSource } from "./opencode";
 import { importedKey, listImportedKeys, findImported, writeImportedSession } from "./writer";
+import { withImportLock } from "./lock";
 
 export const IMPORT_SOURCE_MODULES: Record<ImportSource, ImportSourceModule> = {
 	claude: claudeSource,
@@ -146,6 +147,10 @@ async function oversize(location: string): Promise<boolean> {
 }
 
 export async function importSessions(items: ImportSelection[], options: ImportOptions): Promise<ImportReport> {
+	return withImportLock(options.agentDir, () => importSessionsLocked(items, options));
+}
+
+async function importSessionsLocked(items: ImportSelection[], options: ImportOptions): Promise<ImportReport> {
 	const results: ImportOutcome[] = [];
 	const workspaces = new Set<string>();
 	const fallback = (await isDirectory(options.fallbackCwd)) ? path.resolve(options.fallbackCwd as string) : undefined;

package/src/lib/session-import/lock.ts

@@ -0,0 +1,25 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+
+const pending = new Map<string, Promise<void>>();
+
+export async function withImportLock<T>(agentDir: string, operation: () => Promise<T>): Promise<T> {
+  await fs.mkdir(agentDir, { recursive: true });
+  const real = await fs.realpath(agentDir);
+  const key = process.platform === "win32" ? real.toLowerCase() : real;
+  const previous = pending.get(key) ?? Promise.resolve();
+  const result = previous.then(async () => {
+    // Serialize the global provenance lookup and write, including across server processes.
+    const release = await lockfile.lock(path.join(real, "piweb-session-import"), {
+      realpath: false, stale: 120_000,
+      retries: { retries: 60, minTimeout: 100, maxTimeout: 500 },
+    });
+    try { return await operation(); }
+    finally { await release(); }
+  });
+  const settled = result.then(() => undefined, () => undefined);
+  pending.set(key, settled);
+  void settled.then(() => { if (pending.get(key) === settled) pending.delete(key); });
+  return result;
+}

package/src/lib/session-import/writer.ts

@@ -235,9 +235,14 @@ export async function writeImportedSession(session: ImportedSession, options: Wr
 	const dir = path.join(options.agentDir, "sessions", encodeSessionDir(options.cwd));
 	await fs.mkdir(dir, { recursive: true });
 	const target = path.join(dir, importedFileName(summary.source, summary.externalId, createdAt));
-	const temporary = `${target}.${process.pid}.tmp`;
-	await fs.writeFile(temporary, `${lines.join("\n")}\n`, "utf8");
-	await fs.rename(temporary, target);
+	const temporary = `${target}.${randomUUID()}.tmp`;
+	try {
+		await fs.writeFile(temporary, `${lines.join("\n")}\n`, { encoding: "utf8", flag: "wx" });
+		// Publish a complete file atomically without replacing an existing imported session.
+		await fs.link(temporary, target);
+	} finally {
+		await fs.rm(temporary, { force: true });
+	}
 	return { path: target, messageCount: messages.messages.length, skipped };
 }