@ghyper9023/pi-dev-workflow 0.6.2 → 0.7.0

package/extensions/grill-me-agent.ts

@@ -1,21 +1,22 @@
 /**
- * grill-me-agent.ts — 设计 (Grill) 和 PRD 生成的独立管理器
+ * grill-me-agent.ts — 设计 (Grill) 和 PRD 生成的管理器（运行在当前代理中）
  *
  * 职责：
- *   1. runGrillPhase()  — 启动 sub-agent 生成评审问题，TUI 逐题呈现（选项 + 自定义输入）
- *   2. runPRDPhase()    — 启动 sub-agent 生成 PRD，保存到 .pi-dev-output/pi-prd/
+ *   1. runGrillPhase()  — 由当前代理生成评审问题，TUI 逐题呈现（选项 + 自定义输入）
+ *   2. runPRDPhase()    — 由当前代理生成 PRD，保存到 .pi-dev-output/pi-prd/
  *
- * 关键设计决策（修复 #2）：
- *   sub-agent 通过 `write` 工具将评审问题写入临时文件，主进程事后读取。
- *   不依赖从 NDJSON 响应文本中解析 JSON（多轮 tool-calling 场景不可靠）。
+ * 与旧版的区别：不再创建隔离的子代理进程，而是把追问/PRD 任务交给当前代理执行。
+ * 当前模型普遍具备 >=1M 上下文窗口，无需通过子代理隔离上下文。
+ *
+ * 关键设计：
+ *   当前代理通过 `write` 工具将结果写入临时文件，主进程事后读取。
+ *   不依赖从响应文本中解析 JSON（多轮 tool-calling 场景不可靠）。
  */
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { BorderedLoader, DynamicBorder } from "@earendil-works/pi-coding-agent";
-import { spawnSubagent, extractFinalOutput, discoverAgents, type AgentDef } from "./sub-agents";
-export type { AgentDef };
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import {
 	Container,
 	SelectList,
@@ -28,10 +29,11 @@ import {
 	type SelectItem,
 } from "@earendil-works/pi-tui";
 import { uiSelect, uiConfirm, uiInput } from "./ui-helpers";
+import { pollFor, getLastAssistantTextAfter } from "./session-utils";
 
 // ── Types ────────────────────────────────────────────────────
 
-/** A single grill question returned by the sub-agent. */
+/** A single grill question returned by the agent. */
 export interface GrillQuestion {
 	id: number;
 	question: string;
@@ -104,7 +106,6 @@ export function saveAnswerFile(cwd: string, content: string): string {
 /**
  * Find the most recent answer backup file and read its content.
  * Returns undefined if no backup exists or read fails.
- * Now reads from pi-grill/answers/ subdirectory.
  */
 export function recoverFromBackup(cwd: string): string | undefined {
 	const dir = path.join(cwd, DEV_OUTPUT_DIR, GRILL_DIRNAME, GRILL_ANSWERS_DIRNAME);
@@ -132,10 +133,10 @@ function generatePrdFilename(moduleSuggestion: string): string {
 	return `${safe || "feature"}-${ts}.md`;
 }
 
-// ── Sub-agent definitions ────────────────────────────────────
+// ── File-based result extraction ─────────────────────────────
 
 /**
- * Helper: build the system prompt suffix that tells the sub-agent to
+ * Helper: build the system prompt suffix that tells the agent to
  * write results to a file via the `write` tool instead of putting JSON
  * in its chat response.
  */
@@ -176,15 +177,15 @@ function writeToolPromptSuffix(outputFilePath: string): string {
 		'}',
 		"```",
 		"",
-		"### \u26a0\ufe0f CRITICAL: String escaping rules",
+		"### ⚠️ CRITICAL: String escaping rules",
 		"",
 		"Every string value (question text, option text) MUST be valid JSON-escaped:",
 		"- Double quotes inside text \u2192 \\\"",
-		"- Newlines \u2192 \\n",
-		"- Backslashes \u2192 \\\\",
-		"- Tabs \u2192 \\t",
+		"- Newlines → \\n",
+		"- Backslashes → \\\\",
+		"- Tabs → \\t",
 		"",
-		"### \u2705 Self-review before writing",
+		"### ✅ Self-review before writing",
 		"",
 		"Before calling the `write` tool, mentally validate your JSON.",
 		"Check that all strings are properly escaped and the structure matches the schema above.",
@@ -204,7 +205,7 @@ function writeToolPromptSuffix(outputFilePath: string): string {
 		'    },',
 		'    {',
 		'      "id": 2,',
-		'      "question": "\\u4ed6\\u8bf4\\u201c\\u8fd9\\u4e2a\\u4e0d\\u884c\\u201d\\uff0c\\u8be5\\u5982\\u4f55\\u5904\\u7406\\uff1f",',
+		'      "question": "\\u4ed6\\u8bf4\\u201c\\u8fd9\\u4e2a\\u4e88\\u884c\\u201d\\uff0c\\u8be5\\u5982\\u4f55\\u5904\\u7406\\uff1f",',
 		'      "options": [',
 		'        "\\u5ffd\\u7565",',
 		'        "\\u4fee\\u590d"',
@@ -219,15 +220,8 @@ function writeToolPromptSuffix(outputFilePath: string): string {
 	].join("\n");
 }
 
-// ── Default agent definitions (loaded from agents/ directory) ────
-
-const _defaultGrillAgent = discoverAgents().find(a => a.name === "dev-grill-agent")!;
-const _defaultPrdAgent = discoverAgents().find(a => a.name === "dev-prd-agent")!;
-
-// ── File-based question extraction ───────────────────────────
-
 /**
- * Try to read and parse questions from the output file that the sub-agent
+ * Try to read and parse questions from the output file that the agent
  * was instructed to write via the `write` tool.
  */
 function readQuestionsFromFile(filePath: string): GrillQuestion[] {
@@ -258,7 +252,7 @@ function readQuestionsFromFile(filePath: string): GrillQuestion[] {
 }
 
 /**
- * Parse sub-agent output into a list of GrillQuestions.
+ * Parse agent output into a list of GrillQuestions.
  * Used as fallback when the file-based approach didn't produce results.
  */
 export function parseGrillQuestions(raw: string): GrillQuestion[] {
@@ -344,17 +338,15 @@ function extractQuestionArray(raw: string): Array<{ question: string; options: s
  * Options for customizing the grill phase.
  */
 export interface GrillOptions {
-	agentDef?: AgentDef;
 	title?: string;
 	description?: string;
 	questionTitle?: string;
-	loaderLabel?: string;
 }
 
 /**
  * Run the grill phase:
  * 1. Confirm with user
- * 2. Call sub-agent → sub-agent writes questions to a file via `write` tool
+ * 2. Send task to current agent → agent writes questions to a file via `write` tool
  * 3. Read questions from the file
  * 4. Show each question as TUI SelectList + custom input option
  * 5. Collect all Q&A pairs
@@ -363,6 +355,7 @@ export interface GrillOptions {
 export async function runGrillPhase(
 	assembledPrompt: string,
 	ctx: ExtensionCommandContext,
+	pi: ExtensionAPI,
 	options?: GrillOptions,
 ): Promise<GrillResult> {
 	const defaultResult: GrillResult = {
@@ -371,11 +364,9 @@ export async function runGrillPhase(
 		enhancedPrompt: assembledPrompt,
 	};
 
-	const agentDef = options?.agentDef ?? _defaultGrillAgent;
 	const confirmTitle = options?.title ?? "🔍 设计方案追问完善";
 	const confirmDesc = options?.description ?? "AI 会通过系统性追问帮你打磨方案：从术语精确化到边界条件验证，确保架构决策的每个分支都经过推敲。";
 	const qTitlePrefix = options?.questionTitle ?? "设计方案追问完善";
-	const loaderLabel = options?.loaderLabel ?? "🧠 AI 子代理正在分析代码并生成追问问题...";
 
 	// ── Step 1: Confirm entering grill mode ──────────────────
 	const enterGrill = await uiConfirm(ctx, confirmTitle, confirmDesc);
@@ -391,37 +382,17 @@ export async function runGrillPhase(
 		writeToolPromptSuffix(outputFilePath),
 	].join("\n\n");
 
-	// ── Step 3: Call sub-agent with BorderedLoader ───────────
-	const questions = await ctx.ui.custom<GrillQuestion[]>((tui, theme, _kb, done) => {
-		const loader = new BorderedLoader(tui, theme, loaderLabel);
-		loader.onAbort = () => done([]);
-
-		spawnSubagent(
-			agentDef,
-			enhancedPrompt,
-			ctx.cwd,
-			loader.signal,
-			undefined,
-			(progress) => {
-					const inner = (loader as unknown as { loader?: { setText?: (t: string) => void } }).loader;
-					inner?.setText?.(`🧠 ${progress.slice(0, 60)}`);
-				},
-		)
-			.then((result) => {
-				let qs = readQuestionsFromFile(outputFilePath);
-				if (qs.length === 0) {
-					const output = extractFinalOutput(result.output);
-					qs = parseGrillQuestions(output);
-				}
-				done(qs);
-			})
-			.catch(() => {
-				const qs = readQuestionsFromFile(outputFilePath);
-				done(qs);
-			});
-
-		return loader;
-	});
+	// ── Step 3: Ask current agent to generate questions ──────
+	ctx.ui.notify("🧠 已提交给当前代理生成追问问题，请稍候...", "info");
+	const sentAt = Date.now();
+	pi.sendUserMessage(enhancedPrompt, { deliverAs: "followUp" });
+
+	const questions = (await pollFor(() => {
+		const qs = readQuestionsFromFile(outputFilePath);
+		if (qs.length) return qs;
+		const parsed = parseGrillQuestions(getLastAssistantTextAfter(ctx, sentAt));
+		return parsed.length ? parsed : undefined;
+	}, 5 * 60_000)) || [];
 
 	// ── Step 4: Retry dialog if no questions generated ──────
 	if (questions.length === 0) {
@@ -449,43 +420,41 @@ export async function runGrillPhase(
 		switch (choice) {
 			case "🔄 重新尝试生成追问问题": {
 				const retryPath = grillOutputPath(ctx.cwd);
-				const errorFeedback = parseErrorMsg
-					? [
-						"",
-						"### ⚠️ Previous attempt had JSON errors — fix them now",
-						"",
-						`The previous attempt wrote to \`${outputFilePath}\` but the JSON was invalid.`,
-						"",
-						`JSON parse error: ${parseErrorMsg}`,
-						"",
-						"Invalid file content (first 2000 chars):",
-						"```",
-						failedFileContent.slice(0, 1000),
-						"```",
-						"",
-						"Please write valid JSON to the new path below. Make sure all strings are properly JSON-escaped.",
-					].join("\n")
-					: "";
 				const retryPrompt = [
 					assembledPrompt,
 					writeToolPromptSuffix(retryPath),
-					errorFeedback,
+					parseErrorMsg
+						? [
+								"",
+								"### ⚠️ Previous attempt had JSON errors — fix them now",
+								"",
+								`The previous attempt wrote to \`${outputFilePath}\` but the JSON was invalid.`,
+								"",
+								`JSON parse error: ${parseErrorMsg}`,
+								"",
+								"Invalid file content (first 2000 chars):",
+								"```",
+								failedFileContent.slice(0, 1000),
+								"```",
+								"",
+								"Please write valid JSON to the new path below. Make sure all strings are properly JSON-escaped.",
+							].join("\n")
+						: "",
 				].filter(Boolean).join("\n\n");
-				const retryQuestions = await ctx.ui.custom<GrillQuestion[]>((tui, theme, _kb, done) => {
-					const loader = new BorderedLoader(tui, theme, loaderLabel);
-					loader.onAbort = () => done([]);
-					spawnSubagent(agentDef, retryPrompt, ctx.cwd, loader.signal, undefined)
-						.then((r) => {
-							let qs = readQuestionsFromFile(retryPath);
-							if (qs.length === 0) qs = parseGrillQuestions(extractFinalOutput(r.output));
-							done(qs);
-						})
-						.catch(() => done([]));
-					return loader;
-				});
+
+				const retrySentAt = Date.now();
+				pi.sendUserMessage(retryPrompt, { deliverAs: "followUp" });
+
+				const retryQuestions = (await pollFor(() => {
+					const qs = readQuestionsFromFile(retryPath);
+					if (qs.length) return qs;
+					const parsed = parseGrillQuestions(getLastAssistantTextAfter(ctx, retrySentAt));
+					return parsed.length ? parsed : undefined;
+				}, 5 * 60_000)) || [];
 				if (retryQuestions.length === 0) {
 					return defaultResult;
 				}
+
 				// Replace questions with retry results (with back support)
 				const pairs: Array<{ question: string; answer: string }> = [];
 				let rIdx = 0;
@@ -504,7 +473,6 @@ export async function runGrillPhase(
 						}
 						return { ...defaultResult, cancelled: true, pairs };
 					}
-					// Overwrite if re-answering, otherwise append
 					if (rIdx < pairs.length) {
 						pairs[rIdx] = { question: q.question, answer };
 					} else {
@@ -561,7 +529,6 @@ export async function runGrillPhase(
 			return { ...defaultResult, cancelled: true, pairs };
 		}
 
-		// Overwrite if re-answering (back then forward), otherwise append
 		if (qIdx < pairs.length) {
 			pairs[qIdx] = { question: q.question, answer };
 		} else {
@@ -600,15 +567,6 @@ export async function runGrillPhase(
  *   - ↑↓ 选择, Enter 确认, Esc 取消全部评审
  *   - Ctrl+Shift+← 返回上一题（仅当 backable=true 且 currentIndex > 1 时生效）
  *   - 选择 "✏️ 自定义输入" 进入文本输入模式
- *
- * @param ctx - Extension command context for TUI rendering
- * @param q - The grill question to display
- * @param currentIndex - 1-based index of current question
- * @param totalCount - Total number of questions
- * @param titlePrefix - Prefix for the question title bar
- * @param backable - Whether navigating back to previous question is allowed
- * @param previousAnswer - Previous answer to pre-fill as "上次选择" marker
- * @returns Selected option text, "__BACK__" for back navigation, or null for cancel
  */
 async function showQuestionTUI(
 	ctx: ExtensionCommandContext,
@@ -631,7 +589,6 @@ async function showQuestionTUI(
 		return {
 			value: `opt-${i}`,
 			label: truncated,
-			// 完整文本由下方的预览面板展示（支持换行），description 列无法换行故移除
 		};
 	});
 
@@ -683,7 +640,6 @@ async function showQuestionTUI(
 		container.addChild(new Spacer(1));
 		container.addChild(previewText);
 
-		// 初始化预览为第一个选项
 		if (q.options.length > 0) {
 			const initialWrapped = wrapTextWithAnsi(q.options[0], previewWidth);
 			previewText.setText(
@@ -718,7 +674,6 @@ async function showQuestionTUI(
 			render: (w) => container.render(w),
 			invalidate: () => container.invalidate(),
 			handleInput: (data) => {
-				// Ctrl+Shift+← → 返回上一题（SelectList 不处理该键，需自行拦截）
 				if (backable && currentIndex > 1 && matchesKey(data, Key.ctrlShift("left"))) {
 					done("__BACK__");
 					return;
@@ -753,7 +708,7 @@ async function showQuestionTUI(
 /**
  * Run the PRD phase:
  * 1. Ask user if they want to create a PRD
- * 2. Call sub-agent → gets PRD Markdown
+ * 2. Call current agent → gets PRD Markdown
  * 3. Save to .pi-dev-output/pi-prd/<name>.md
  * 4. Ask if user wants to start development
  */
@@ -770,37 +725,44 @@ export async function runPRDPhase(
 	);
 	if (!wantPrd) return null;
 
-	const prdContent = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
-		const loader = new BorderedLoader(tui, theme, "📝 AI 正在生成 PRD 文档...");
-		loader.onAbort = () => done(null);
-
-		const prdTask = [
-			"请根据以下上下文生成一份 PRD（产品需求文档）。",
-			"输出格式必须是完整的 Markdown 文档。",
-			"",
-			"=== 上下文 ===",
-			context,
-		].join("\n");
-
-		spawnSubagent(_defaultPrdAgent, prdTask, ctx.cwd, loader.signal)
-			.then((result) => {
-				const output = extractFinalOutput(result.output);
-				done(output && output.length >= 50 ? output : null);
-			})
-			.catch(() => done(null));
-
-		return loader;
-	});
-
-	if (!prdContent) {
-		return null;
-	}
-
 	const prdDir = ensureOutputDir(ctx.cwd, PRD_DIRNAME);
 	const filename = generatePrdFilename(moduleHint);
 	const filePath = path.join(DEV_OUTPUT_DIR, PRD_DIRNAME, filename);
 	const fullPath = path.join(prdDir, filename);
-	fs.writeFileSync(fullPath, prdContent, "utf-8");
+
+	const prdTask = [
+		"请根据以下上下文生成一份 PRD（产品需求文档）。",
+		"输出格式必须是完整的 Markdown 文档。",
+		"",
+		"=== 上下文 ===",
+		context,
+		"",
+		`请使用 write 工具将完整 PRD 写入以下路径: ${fullPath}`,
+		"不要在聊天中输出全文，只需确认写入完成。",
+	].join("\n");
+
+	ctx.ui.notify("📝 已提交给当前代理生成 PRD，请稍候...", "info");
+	const sentAt = Date.now();
+	pi.sendUserMessage(prdTask, { deliverAs: "followUp" });
+
+	const prdContent = (await pollFor(() => {
+		let c = "";
+		try {
+			c = fs.readFileSync(fullPath, "utf-8").trim();
+		} catch { /* file not written yet */ }
+		if (c) return c;
+		return getLastAssistantTextAfter(ctx, sentAt) || undefined;
+	}, 5 * 60_000)) || "";
+
+	if (!prdContent || prdContent.length < 50) {
+		ctx.ui.notify("❌ PRD 生成失败：未获取到有效 PRD 内容，请查看当前代理的回复后重试。", "error");
+		return null;
+	}
+
+	// Fallback: if the agent chatted the PRD instead of writing it, persist it ourselves.
+	if (!fs.existsSync(fullPath)) {
+		fs.writeFileSync(fullPath, prdContent, "utf-8");
+	}
 
 	await askDevelopmentStart(pi, ctx, prdContent, filePath);
 	return { content: prdContent, filePath };
@@ -876,5 +838,4 @@ async function askDevelopmentStart(
 //
 export default function (_pi: ExtensionAPI) {
 	// grill-me-agent is a helper module, not a standalone extension.
-	// It is imported by dev-prompts.ts to provide grill + PRD phases.
 }

package/extensions/session-utils.ts

@@ -0,0 +1,169 @@
+/**
+ * session-utils.ts — 跨扩展共享的会话与等待工具
+ *
+ * 职责：
+ *   1. pollFor() — 轮询等待当前代理的产物（文件/文本）出现，带超时
+ *   2. getLastAssistantTextAfter() — 提取指定时间点之后最后一条 assistant 文本
+ *
+ * 供 git-commands.ts / grill-me-agent.ts / dev-prompts.ts 等扩展共享使用。
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** 项目基础信息，用于生成默认验收标准与默认字段。 */
+export interface ProjectDefaults {
+	language: string;
+	testCmd: string;
+	lintCmd: string;
+	packageManager: string;
+	hasPreCommit: boolean;
+	hasCI: boolean;
+}
+
+function safeReaddir(dir: string): string[] {
+	try {
+		return fs.readdirSync(dir);
+	} catch {
+		return [];
+	}
+}
+
+const SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", "coverage", ".pi-dev-output"]);
+
+/** 浅层递归收集文件扩展名（深度 2），用于语言推断。 */
+function scanExtensions(cwd: string, depth: number): string[] {
+	const exts = new Set<string>();
+	const walk = (dir: string, d: number): void => {
+		if (d > depth) return;
+		for (const name of safeReaddir(dir)) {
+			const full = path.join(dir, name);
+			let stat: fs.Stats | undefined;
+			try {
+				stat = fs.statSync(full);
+			} catch {
+				continue;
+			}
+			if (stat.isDirectory()) {
+				if (!SKIP_DIRS.has(name)) walk(full, d + 1);
+			} else {
+				const m = name.match(/\.([a-z0-9]+)$/i);
+				if (m) exts.add(m[1]!.toLowerCase());
+			}
+		}
+	};
+	walk(cwd, depth);
+	return [...exts];
+}
+
+/** 探测当前项目的语言/测试/lint 命令与工程规范（pre-commit、CI）。 */
+export function detectProjectDefaults(cwd: string): ProjectDefaults {
+	const d: ProjectDefaults = {
+		language: "",
+		testCmd: "",
+		lintCmd: "",
+		packageManager: "npm",
+		hasPreCommit: false,
+		hasCI: false,
+	};
+		try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
+		const scripts = pkg.scripts ?? {};
+		const rawTest = scripts.test ?? "";
+		d.testCmd = /no test specified/.test(rawTest) ? "" : rawTest;
+		d.lintCmd = scripts.lint ?? scripts["lint:fix"] ?? scripts.format ?? "";
+		const pm = pkg.packageManager ?? "";
+		d.packageManager = /pnpm/.test(pm) ? "pnpm" : /yarn/.test(pm) ? "yarn" : "npm";
+		const meta = [pkg.name ?? "", Object.keys(pkg.dependencies ?? {}), Object.keys(pkg.devDependencies ?? {})].flat().join(" ").toLowerCase();
+		if (fs.existsSync(path.join(cwd, "tsconfig.json")) || /typescript|tsx/.test(meta)) d.language = "TypeScript";
+		else if (/javascript|next|react|vue|node|nest/.test(meta)) d.language = "JavaScript";
+	} catch { /* 非 Node 项目 */ }
+	if (!d.language) {
+		const files = safeReaddir(cwd);
+		const exts = scanExtensions(cwd, 2);
+		if (fs.existsSync(path.join(cwd, "Cargo.toml"))) d.language = "Rust";
+		else if (fs.existsSync(path.join(cwd, "go.mod"))) d.language = "Go";
+		else if (fs.existsSync(path.join(cwd, "pyproject.toml")) || fs.existsSync(path.join(cwd, "requirements.txt"))) d.language = "Python";
+		else if (fs.existsSync(path.join(cwd, "pom.xml")) || fs.existsSync(path.join(cwd, "build.gradle"))) d.language = "Java";
+		else if (files.some((f) => f.endsWith(".csproj"))) d.language = "C#";
+		else if (exts.includes("rs")) d.language = "Rust";
+		else if (exts.includes("go")) d.language = "Go";
+		else if (exts.includes("py")) d.language = "Python";
+		else if (exts.includes("ts") || exts.includes("tsx")) d.language = "TypeScript";
+		else if (exts.some((e) => ["js", "mjs", "cjs", "jsx"].includes(e))) d.language = "JavaScript";
+	}
+	d.hasPreCommit = fs.existsSync(path.join(cwd, ".pre-commit-config.yaml")) || fs.existsSync(path.join(cwd, ".pre-commit-config.yml"));
+	d.hasCI = safeReaddir(path.join(cwd, ".github", "workflows")).some((f) => /\.ya?ml$/.test(f));
+	return d;
+}
+
+/** 根据项目探测结果生成常规验收标准（测试 + lint + pre-commit + CI）。 */
+export function defaultAcceptance(d: ProjectDefaults): string {
+	const parts: string[] = [];
+	if (d.testCmd) parts.push(`运行 ${d.testCmd} 确认全部测试通过、无回归`);
+	else parts.push(`按 ${d.language || "项目"} 的常规测试方式编写并运行测试，确认核心逻辑正确、无回归`);
+	if (d.lintCmd) parts.push(`运行 ${d.lintCmd} 符合代码规范`);
+	if (d.hasPreCommit) parts.push("通过本地 pre-commit 钩子检查");
+	if (d.hasCI) parts.push("通过 CI 检查");
+	if (parts.length === 0) parts.push("核心逻辑正确、边界情况处理完善、无行为回归");
+	return parts.join("；");
+}
+
+/**
+ * 轮询直到回调返回非空/非 undefined，或超时。
+ * 用于替代 "sendUserMessage 后再 waitForIdle" 的不可靠时序：
+ * waitForIdle 可能在消息触发的新 turn 开始前立即返回，导致误判完成。
+ */
+export async function pollFor<T>(poll: () => T | undefined | null, timeoutMs: number, intervalMs = 2_000): Promise<T | undefined> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const value = poll();
+		if (value !== undefined && value !== null && value !== "") return value;
+		await new Promise((r) => setTimeout(r, intervalMs));
+	}
+	return undefined;
+}
+
+/**
+ * Extract the most recent assistant message text that arrived after a given moment.
+ * Used as fallback when the agent did not write the expected file.
+ */
+export function getLastAssistantTextAfter(ctx: ExtensionCommandContext, afterMs: number): string {
+	try {
+		const entries = ctx.sessionManager.getEntries();
+		let text = "";
+		for (const entry of entries) {
+			if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+			const ts = new Date(entry.timestamp).getTime();
+			if (ts > afterMs) {
+				text = extractMessageText(entry.message.content) || text;
+			}
+		}
+		return text;
+	} catch {
+		return "";
+	}
+}
+
+function extractMessageText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content
+			.map((part) => {
+				if (typeof part === "string") return part;
+				if (part && typeof part === "object" && "type" in part && part.type === "text") {
+					return (part as { text: string }).text;
+				}
+				return "";
+			})
+			.join("\n");
+	}
+	return "";
+}
+
+// ── Extension factory (required by pi extension loader) ─────
+
+export default function (_pi: ExtensionAPI) {
+	// session-utils is a helper module, imported by other extensions.
+}