@askjo/pi-reflect 1.0.0 → 1.1.0

package/extensions/index.ts

@@ -82,8 +82,10 @@ export default function (pi: ExtensionAPI) {
 						"Which target?",
 						config.targets.map((t) => path.basename(t.path)),
 					);
-					if (choice === undefined) return;
-					target = config.targets[choice];
+					if (choice === undefined || choice === null) return;
+					const chosenTarget = config.targets.find((t) => path.basename(t.path) === choice);
+					if (!chosenTarget) return;
+					target = chosenTarget;
 				} else {
 					target = config.targets[0];
 				}
@@ -93,7 +95,21 @@ export default function (pi: ExtensionAPI) {
 				? (msg, level) => ctx.ui.notify(msg, level)
 				: (msg, level) => console.log(`[reflect] [${level}] ${msg}`);
 
-			const run = await runReflection(target, modelRegistryRef, notify);
+			// Use the current session model if available
+			let currentModel: any;
+			let currentModelApiKey: string | undefined;
+			if (ctx.model) {
+				const key = await ctx.modelRegistry.getApiKey(ctx.model);
+				if (key) {
+					currentModel = ctx.model;
+					currentModelApiKey = key;
+				}
+			}
+
+			const run = await runReflection(target, modelRegistryRef, notify, undefined, {
+				currentModel,
+				currentModelApiKey,
+			});
 
 			if (run) {
 				const history = loadHistory();

package/extensions/reflect.ts

@@ -101,6 +101,8 @@ export interface TranscriptResult {
 	transcripts: string;
 	sessionCount: number;
 	includedCount: number;
+	/** Individual sessions for chunked processing when transcripts exceed context budget */
+	sessions?: SessionData[];
 }
 
 export interface EditResult {
@@ -122,6 +124,9 @@ export interface ReflectionOptions {
 	sourceDateOverride?: string;
 	transcriptsOverride?: TranscriptResult;
 	dryRun?: boolean;
+	/** Override model — use the current session model instead of target.model */
+	currentModel?: any;
+	currentModelApiKey?: string;
 }
 
 export type NotifyFn = (msg: string, level: "info" | "warning" | "error") => void;
@@ -395,7 +400,7 @@ async function collectSessionsForDates(
 	}
 
 	if (allSessions.length === 0) {
-		return { transcripts: "", sessionCount: totalScanned, includedCount: 0 };
+		return { transcripts: "", sessionCount: totalScanned, includedCount: 0, sessions: [] };
 	}
 
 	allSessions.sort((a, b) => {
@@ -426,6 +431,7 @@ async function collectSessionsForDates(
 		transcripts: header + parts.join(""),
 		sessionCount: totalScanned,
 		includedCount: included,
+		sessions: allSessions,
 	};
 }
 
@@ -726,6 +732,144 @@ export function applyEdits(content: string, edits: AnalysisEdit[]): EditResult {
 	return { result, applied, skipped };
 }
 
+// --- Batch helpers ---
+
+/** Split sessions into batches that each fit within maxBytes */
+export function buildTranscriptBatches(sessions: SessionData[], maxBytes: number): string[][] {
+	const batches: string[][] = [];
+	let currentBatch: string[] = [];
+	let currentSize = 0;
+
+	for (const sd of sessions) {
+		const entry = sd.transcript + "\n---\n\n";
+		if (currentSize + entry.length > maxBytes && currentBatch.length > 0) {
+			batches.push(currentBatch);
+			currentBatch = [];
+			currentSize = 0;
+		}
+		currentBatch.push(entry);
+		currentSize += entry.length;
+	}
+	if (currentBatch.length > 0) {
+		batches.push(currentBatch);
+	}
+	return batches;
+}
+
+function formatBatchTranscripts(parts: string[], batchIndex: number, totalBatches: number, totalSessions: number): string {
+	const header =
+		`# Session Transcripts (batch ${batchIndex + 1}/${totalBatches})\n` +
+		`# ${parts.length} sessions in this batch, ${totalSessions} total\n\n`;
+	return header + parts.join("");
+}
+
+interface AnalysisResult {
+	edits: AnalysisEdit[];
+	correctionsFound: number;
+	sessionsWithCorrections: number;
+	summary: string;
+	patternsNotAdded?: any[];
+}
+
+/** Run a single LLM analysis call on one batch of transcripts */
+async function analyzeTranscriptBatch(
+	target: ReflectTarget,
+	targetPath: string,
+	targetContent: string,
+	transcripts: string,
+	context: string,
+	model: any,
+	apiKey: string,
+	modelLabel: string,
+	notify: NotifyFn,
+	completeFn: (model: any, request: any, options: any) => Promise<any>,
+): Promise<AnalysisResult | null> {
+	const prompt = buildPromptForTarget(target, targetPath, targetContent, transcripts, context);
+
+	const reflectAnalysisTool = {
+		name: "submit_analysis",
+		description: "Submit the reflection analysis results",
+		parameters: {
+			type: "object" as const,
+			properties: {
+				corrections_found: { type: "number", description: "Number of facts/rules added, updated, or removed" },
+				sessions_with_corrections: { type: "number", description: "Number of conversations containing new facts or corrections" },
+				edits: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							type: { type: "string", enum: ["strengthen", "add"], description: "strengthen = update existing text, add = insert new text" },
+							section: { type: "string", description: "Which section of the file" },
+							old_text: { type: ["string", "null"], description: "Exact text to find (for strengthen) or null (for add)" },
+							new_text: { type: "string", description: "Replacement text (for strengthen) or new text to insert (for add)" },
+							after_text: { type: ["string", "null"], description: "Text after which to insert (for add) or null (for strengthen)" },
+							reason: { type: "string", description: "What fact/rule this captures and where in the conversations it appeared" },
+						},
+						required: ["type", "new_text"],
+					},
+				},
+				patterns_not_added: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							pattern: { type: "string" },
+							reason: { type: "string" },
+						},
+					},
+				},
+				summary: { type: "string", description: "2-3 sentence summary of what was added/updated" },
+			},
+			required: ["corrections_found", "sessions_with_corrections", "edits", "summary"],
+		},
+	};
+
+	const response = await completeFn(model, {
+		systemPrompt: "You are a behavioral analysis tool. Analyze the session transcripts and call the submit_analysis tool with your results. Always call the tool — never respond with plain text.",
+		messages: [
+			{
+				role: "user" as const,
+				content: [{ type: "text" as const, text: prompt }],
+				timestamp: Date.now(),
+			},
+		],
+		tools: [reflectAnalysisTool],
+	}, { apiKey, maxTokens: 16384 });
+
+	if (response.stopReason === "error") {
+		notify(`LLM error: ${response.errorMessage ?? 'unknown'}`, "error");
+		return null;
+	}
+
+	let analysis: any;
+	const toolCall = response.content.find((c: any) => c.type === "toolCall" && c.name === "submit_analysis");
+	if (toolCall && (toolCall as any).arguments) {
+		analysis = (toolCall as any).arguments;
+	} else {
+		const responseText = response.content
+			.filter((c: any) => c.type === "text")
+			.map((c: any) => c.text)
+			.join("")
+			.trim();
+		try {
+			const jsonStr = responseText.replace(/^```json?\s*\n?/m, "").replace(/\n?```\s*$/m, "");
+			analysis = JSON.parse(jsonStr);
+		} catch {
+			notify(`Failed to parse LLM response as JSON. Raw response:\n${responseText.slice(0, 500)}`, "error");
+			return null;
+		}
+	}
+
+	return {
+		edits: analysis.edits ?? [],
+		correctionsFound: analysis.corrections_found ?? 0,
+		sessionsWithCorrections: analysis.sessions_with_corrections ?? 0,
+		summary: analysis.summary ?? "",
+		patternsNotAdded: analysis.patterns_not_added,
+	};
+}
+
 // --- Main reflection logic ---
 
 export interface RunReflectionDeps {
@@ -759,9 +903,11 @@ export async function runReflection(
 	let transcripts: string;
 	let sessionCount = 0;
 	let includedCount = 0;
+	let allSessions: SessionData[] | undefined;
 
 	if (options?.transcriptsOverride) {
 		({ transcripts, sessionCount, includedCount } = options.transcriptsOverride);
+		allSessions = options.transcriptsOverride.sessions;
 	} else if (target.transcripts && target.transcripts.length > 0) {
 		// New array-based transcript sources
 		notify(`Extracting transcripts from ${target.transcripts.length} source(s) (last ${target.lookbackDays} day(s))...`, "info");
@@ -779,6 +925,7 @@ export async function runReflection(
 			target.maxSessionBytes,
 		);
 		({ transcripts, sessionCount, includedCount } = result);
+		allSessions = result.sessions;
 	} else {
 		notify(`Extracting transcripts (last ${target.lookbackDays} day(s))...`, "info");
 		const fn = deps?.collectTranscriptsFn ?? collectTranscripts;
@@ -787,6 +934,7 @@ export async function runReflection(
 			target.maxSessionBytes,
 		);
 		({ transcripts, sessionCount, includedCount } = result);
+		allSessions = result.sessions;
 	}
 
 	if (!transcripts || includedCount === 0) {
@@ -794,25 +942,39 @@ export async function runReflection(
 		return null;
 	}
 
-	notify(`Extracted ${includedCount} sessions (${sessionCount} scanned, ${(transcripts.length / 1024).toFixed(0)}KB)`, "info");
+	// Use total session count from allSessions if available (includes sessions that didn't fit the budget)
+	const totalSessionCount = allSessions ? allSessions.length : includedCount;
+	const totalBytes = allSessions ? allSessions.reduce((sum, s) => sum + s.size, 0) : transcripts.length;
+	notify(`Extracted ${totalSessionCount} sessions (${sessionCount} scanned, ${(totalBytes / 1024).toFixed(0)}KB)`, "info");
 
-	// Resolve model
-	const getModelFn = deps?.getModel ?? (await import("@mariozechner/pi-ai")).getModel;
-	const [provider, modelId] = target.model.split("/", 2);
-	let model = getModelFn(provider as any, modelId as any);
+	// Resolve model — prefer current session model over target.model config
+	let model: any;
+	let apiKey: string | undefined;
+	let modelLabel: string;
 
-	if (!model) {
-		model = modelRegistry?.find(provider, modelId);
-	}
-	if (!model) {
-		notify(`Model not found: ${target.model}`, "error");
-		return null;
-	}
+	if (options?.currentModel && options?.currentModelApiKey) {
+		model = options.currentModel;
+		apiKey = options.currentModelApiKey;
+		modelLabel = `${model.provider}/${model.id}`;
+	} else {
+		const getModelFn = deps?.getModel ?? (await import("@mariozechner/pi-ai")).getModel;
+		const [provider, modelId] = target.model.split("/", 2);
+		model = getModelFn(provider as any, modelId as any);
 
-	const apiKey = await modelRegistry?.getApiKey(model);
-	if (!apiKey) {
-		notify(`No API key for model: ${target.model}`, "error");
-		return null;
+		if (!model) {
+			model = modelRegistry?.find(provider, modelId);
+		}
+		if (!model) {
+			notify(`Model not found: ${target.model}`, "error");
+			return null;
+		}
+
+		apiKey = await modelRegistry?.getApiKey(model);
+		if (!apiKey) {
+			notify(`No API key for model: ${target.model}`, "error");
+			return null;
+		}
+		modelLabel = target.model;
 	}
 
 	// Collect additional context
@@ -825,41 +987,71 @@ export async function runReflection(
 		}
 	}
 
-	// Build prompt and call LLM
-	notify(`Analyzing with ${target.model}...`, "info");
-	const prompt = buildPromptForTarget(target, targetPath, targetContent, transcripts, context);
-
+	// Build batches and call LLM
 	const completeFn = deps?.completeSimple ?? (await import("@mariozechner/pi-ai")).completeSimple;
-	const response = await completeFn(model, {
-		systemPrompt: "You are a behavioral analysis tool. You analyze agent session transcripts and output ONLY valid JSON. Never output markdown, explanations, or any text outside the JSON object.",
-		messages: [
-			{
-				role: "user" as const,
-				content: [{ type: "text" as const, text: prompt }],
-				timestamp: Date.now(),
-			},
-		],
-	}, { apiKey, maxTokens: 16384 });
 
-	const responseText = response.content
-		.filter((c: any) => c.type === "text")
-		.map((c: any) => c.text)
-		.join("")
-		.trim();
-
-	// Parse JSON response
-	let analysis: any;
-	try {
-		const jsonStr = responseText.replace(/^```json?\s*\n?/m, "").replace(/\n?```\s*$/m, "");
-		analysis = JSON.parse(jsonStr);
-	} catch {
-		notify(`Failed to parse LLM response as JSON. Raw response:\n${responseText.slice(0, 500)}`, "error");
-		return null;
+	// Determine if we need multiple batches
+	// Reserve space for target file, system prompt, tool schema, and context
+	const overhead = targetContent.length + (context?.length ?? 0) + 20_000; // 20KB for prompt/tool schema
+	const batchBudget = Math.max(target.maxSessionBytes - overhead, 100_000); // at least 100KB per batch
+	const needsBatching = allSessions && allSessions.length > 0 && totalBytes > batchBudget;
+	let allEdits: AnalysisEdit[] = [];
+	let totalCorrectionsFound = 0;
+	let allSummaries: string[] = [];
+
+	if (needsBatching) {
+		const batches = buildTranscriptBatches(allSessions!, batchBudget);
+		notify(`Sessions exceed context budget — splitting into ${batches.length} batches`, "info");
+
+		for (let i = 0; i < batches.length; i++) {
+			const batchTranscripts = formatBatchTranscripts(batches[i], i, batches.length, totalSessionCount);
+			// Re-read target content for each batch so later batches see earlier edits
+			const currentContent = i === 0 ? targetContent : fs.readFileSync(targetPath, "utf-8");
+			notify(`Analyzing batch ${i + 1}/${batches.length} (${batches[i].length} sessions, ${(batchTranscripts.length / 1024).toFixed(0)}KB) with ${modelLabel}...`, "info");
+
+			const result = await analyzeTranscriptBatch(
+				target, targetPath, currentContent, batchTranscripts, context,
+				model, apiKey!, modelLabel, notify, completeFn,
+			);
+
+			if (!result) continue;
+
+			allEdits.push(...result.edits);
+			totalCorrectionsFound += result.correctionsFound;
+			if (result.summary) allSummaries.push(result.summary);
+
+			// Apply this batch's edits immediately so the next batch sees the updated file
+			if (result.edits.length > 0) {
+				const currentForApply = fs.readFileSync(targetPath, "utf-8");
+				const { result: updated, applied } = applyEdits(currentForApply, result.edits);
+				if (applied > 0) {
+					// Backup before first edit
+					if (i === 0) {
+						const bkDir = resolvePath(target.backupDir);
+						fs.mkdirSync(bkDir, { recursive: true });
+						const bkPath = path.join(bkDir, `${path.basename(targetPath, ".md")}_${formatTimestamp()}.md`);
+						fs.copyFileSync(targetPath, bkPath);
+					}
+					fs.writeFileSync(targetPath, updated, "utf-8");
+					notify(`Batch ${i + 1}: applied ${applied} edit(s)`, "info");
+				}
+			}
+		}
+	} else {
+		notify(`Analyzing with ${modelLabel}...`, "info");
+		const result = await analyzeTranscriptBatch(
+			target, targetPath, targetContent, transcripts, context,
+			model, apiKey!, modelLabel, notify, completeFn,
+		);
+		if (!result) return null;
+		allEdits = result.edits;
+		totalCorrectionsFound = result.correctionsFound;
+		if (result.summary) allSummaries.push(result.summary);
 	}
 
-	const edits: AnalysisEdit[] = analysis.edits ?? [];
-	const correctionsFound = analysis.corrections_found ?? 0;
-	const correctionRate = includedCount > 0 ? correctionsFound / includedCount : 0;
+	const edits = allEdits;
+	const correctionsFound = totalCorrectionsFound;
+	const correctionRate = totalSessionCount > 0 ? correctionsFound / totalSessionCount : 0;
 
 	// sourceDate = the date of sessions being analyzed, not when reflect ran
 	let sourceDateStr: string;
@@ -871,15 +1063,17 @@ export async function runReflection(
 		sourceDateStr = sourceDate.toISOString().slice(0, 10);
 	}
 
+	const combinedSummary = allSummaries.join(" ") || `${edits.length} edits from ${totalSessionCount} sessions.`;
+
 	if (edits.length === 0) {
-		notify(`No edits needed. ${analysis.summary ?? ""}`, "info");
+		notify(`No edits needed. ${combinedSummary}`, "info");
 		return {
 			timestamp: new Date().toISOString(),
 			targetPath,
-			sessionsAnalyzed: includedCount,
+			sessionsAnalyzed: totalSessionCount,
 			correctionsFound,
 			editsApplied: 0,
-			summary: analysis.summary ?? "No edits needed.",
+			summary: combinedSummary,
 			diffLines: 0,
 			correctionRate,
 			edits: [],
@@ -897,16 +1091,15 @@ export async function runReflection(
 				reason: e.reason,
 			}));
 
-		const summary = analysis.summary ?? `${edits.length} edits proposed (dry run).`;
-		notify(`[dry run] ${summary}`, "info");
+		notify(`[dry run] ${combinedSummary}`, "info");
 
 		return {
 			timestamp: new Date().toISOString(),
 			targetPath,
-			sessionsAnalyzed: includedCount,
+			sessionsAnalyzed: totalSessionCount,
 			correctionsFound,
 			editsApplied: 0,
-			summary,
+			summary: combinedSummary,
 			diffLines: 0,
 			correctionRate,
 			edits: editRecords,
@@ -914,77 +1107,85 @@ export async function runReflection(
 		};
 	}
 
-	// Backup before editing
+	// Apply edits
 	const backupDir = resolvePath(target.backupDir);
-	fs.mkdirSync(backupDir, { recursive: true });
-	const backupPath = path.join(backupDir, `${path.basename(targetPath, ".md")}_${formatTimestamp()}.md`);
-	fs.copyFileSync(targetPath, backupPath);
+	let totalApplied = 0;
+
+	if (needsBatching) {
+		// Batched: edits were already applied inline in the loop above.
+		// Count total applied from the diff.
+		const finalContent = fs.readFileSync(targetPath, "utf-8");
+		const origLines = targetContent.split("\n");
+		const finalLines = finalContent.split("\n");
+		for (let i = 0; i < Math.max(origLines.length, finalLines.length); i++) {
+			if (origLines[i] !== finalLines[i]) totalApplied++;
+		}
+		// Use edit count as applied since we tracked them per-batch
+		totalApplied = edits.length; // best estimate — individual batch applied counts were logged
+	} else {
+		// Single batch — backup and apply
+		fs.mkdirSync(backupDir, { recursive: true });
+		const backupPath = path.join(backupDir, `${path.basename(targetPath, ".md")}_${formatTimestamp()}.md`);
+		fs.copyFileSync(targetPath, backupPath);
 
-	// Apply edits with safety checks
-	const { result, applied, skipped } = applyEdits(targetContent, edits);
+		const { result, applied, skipped } = applyEdits(targetContent, edits);
 
-	if (applied === 0) {
-		notify(`All ${edits.length} edits failed to apply. Skipped: ${skipped.join("; ")}`, "warning");
-		try { fs.unlinkSync(backupPath); } catch {}
-		return null;
-	}
+		if (applied === 0) {
+			notify(`All ${edits.length} edits failed to apply. Skipped: ${skipped.join("; ")}`, "warning");
+			try { fs.unlinkSync(backupPath); } catch {}
+			return null;
+		}
 
-	// Size sanity check — reject if result lost more than half the content
-	if (result.length < targetContent.length * 0.5) {
-		notify(`Result is suspiciously small (${result.length} vs ${targetContent.length} bytes). Aborting.`, "error");
-		return null;
-	}
+		if (result.length < targetContent.length * 0.5) {
+			notify(`Result is suspiciously small (${result.length} vs ${targetContent.length} bytes). Aborting.`, "error");
+			return null;
+		}
+
+		fs.writeFileSync(targetPath, result, "utf-8");
+		totalApplied = applied;
 
-	fs.writeFileSync(targetPath, result, "utf-8");
+		if (skipped.length > 0) {
+			notify(`Applied ${applied}/${edits.length} edits (${skipped.length} skipped). Backup: ${backupPath}`, "warning");
+		} else {
+			notify(`Applied ${applied} edit(s). Backup: ${backupPath}`, "info");
+		}
+	}
 
-	// Count changed lines
+	// Compute final diff
+	const finalContent = fs.readFileSync(targetPath, "utf-8");
 	const originalLines = targetContent.split("\n");
-	const resultLines = result.split("\n");
+	const resultLines = finalContent.split("\n");
 	let diffLines = 0;
 	const maxLen = Math.max(originalLines.length, resultLines.length);
 	for (let i = 0; i < maxLen; i++) {
 		if (originalLines[i] !== resultLines[i]) diffLines++;
 	}
 
-	if (skipped.length > 0) {
-		notify(`Applied ${applied}/${edits.length} edits (${skipped.length} skipped). Backup: ${backupPath}`, "warning");
-	} else {
-		notify(`Applied ${applied} edit(s). Backup: ${backupPath}`, "info");
-	}
-
-	const summary = analysis.summary ?? `${applied} edits applied from ${includedCount} sessions.`;
-	notify(summary, "info");
+	notify(combinedSummary, "info");
 
-	// If target is in a git repo, commit the change
+	// Git commit
 	try {
 		const realPath = fs.realpathSync(targetPath);
 		const repoDir = path.dirname(realPath);
 		if (fs.existsSync(path.join(repoDir, ".git"))) {
 			const { execFileSync } = require("node:child_process");
 			execFileSync("git", ["add", "-A"], { cwd: repoDir, stdio: "ignore", timeout: 5000 });
-			execFileSync("git", ["commit", "-m", `reflect: ${path.basename(realPath)} — ${applied} edits from ${includedCount} sessions`, "--no-verify"], { cwd: repoDir, stdio: "ignore", timeout: 5000 });
+			execFileSync("git", ["commit", "-m", `reflect: ${path.basename(realPath)} — ${totalApplied} edits from ${totalSessionCount} sessions`, "--no-verify"], { cwd: repoDir, stdio: "ignore", timeout: 5000 });
 			notify(`Committed to ${path.basename(repoDir)}`, "info");
 		}
-	} catch {
-		// Not in a git repo or commit failed — that's fine
-	}
+	} catch {}
 
-	// Extract per-edit detail for recidivism tracking
 	const editRecords: EditRecord[] = edits
 		.filter((e: any) => e.section && e.reason)
-		.map((e: any) => ({
-			type: e.type ?? "add",
-			section: e.section,
-			reason: e.reason,
-		}));
+		.map((e: any) => ({ type: e.type ?? "add", section: e.section, reason: e.reason }));
 
 	return {
 		timestamp: new Date().toISOString(),
 		targetPath,
-		sessionsAnalyzed: includedCount,
+		sessionsAnalyzed: totalSessionCount,
 		correctionsFound,
-		editsApplied: applied,
-		summary,
+		editsApplied: totalApplied,
+		summary: combinedSummary,
 		diffLines,
 		correctionRate,
 		edits: editRecords,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/pi-reflect",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Self-improving behavioral files for pi coding agents. Analyzes session transcripts for correction patterns and makes surgical edits to prevent recurrence.",
   "keywords": [
     "pi-package",

package/tests/batching.test.ts

@@ -0,0 +1,642 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	buildTranscriptBatches,
+	runReflection,
+	type ReflectTarget,
+	type RunReflectionDeps,
+	type NotifyFn,
+	type SessionData,
+	type TranscriptResult,
+	DEFAULT_TARGET,
+} from "../extensions/reflect.js";
+import { makeTempDir, cleanup, SAMPLE_AGENTS_MD } from "./helpers.js";
+
+// --- buildTranscriptBatches tests ---
+
+function makeSession(id: string, sizeBytes: number): SessionData {
+	const transcript = "x".repeat(sizeBytes);
+	return {
+		transcript,
+		project: "test-project",
+		sessionId: id,
+		date: "2026-02-20",
+		size: sizeBytes,
+	};
+}
+
+describe("buildTranscriptBatches", () => {
+	it("puts all sessions in one batch when they fit", () => {
+		const sessions = [makeSession("a", 100), makeSession("b", 100), makeSession("c", 100)];
+		const batches = buildTranscriptBatches(sessions, 1000);
+		assert.equal(batches.length, 1);
+		assert.equal(batches[0].length, 3);
+	});
+
+	it("splits sessions across batches when they exceed maxBytes", () => {
+		const sessions = [makeSession("a", 500), makeSession("b", 500), makeSession("c", 500)];
+		// Each entry is transcript + "\n---\n\n" = 506 bytes
+		const batches = buildTranscriptBatches(sessions, 600);
+		assert.equal(batches.length, 3);
+		assert.equal(batches[0].length, 1);
+		assert.equal(batches[1].length, 1);
+		assert.equal(batches[2].length, 1);
+	});
+
+	it("groups multiple small sessions into one batch", () => {
+		const sessions = [
+			makeSession("a", 100),
+			makeSession("b", 100),
+			makeSession("c", 100),
+			makeSession("d", 100),
+		];
+		// Each entry ~106 bytes, 4 × 106 = 424 bytes
+		const batches = buildTranscriptBatches(sessions, 250);
+		assert.equal(batches.length, 2);
+		assert.equal(batches[0].length, 2);
+		assert.equal(batches[1].length, 2);
+	});
+
+	it("returns empty array for empty sessions", () => {
+		const batches = buildTranscriptBatches([], 1000);
+		assert.equal(batches.length, 0);
+	});
+
+	it("handles a single session larger than maxBytes", () => {
+		const sessions = [makeSession("a", 2000)];
+		const batches = buildTranscriptBatches(sessions, 500);
+		// Single session still gets its own batch even if it exceeds budget
+		assert.equal(batches.length, 1);
+		assert.equal(batches[0].length, 1);
+	});
+
+	it("preserves session order across batches", () => {
+		const sessions = [
+			{ ...makeSession("1st", 300), transcript: "FIRST_SESSION_CONTENT" + "x".repeat(279) },
+			{ ...makeSession("2nd", 300), transcript: "SECOND_SESSION_CONTENT" + "x".repeat(278) },
+			{ ...makeSession("3rd", 300), transcript: "THIRD_SESSION_CONTENT" + "x".repeat(279) },
+		];
+		const batches = buildTranscriptBatches(sessions, 400);
+		assert.equal(batches.length, 3);
+		assert.ok(batches[0][0].includes("FIRST_SESSION"));
+		assert.ok(batches[1][0].includes("SECOND_SESSION"));
+		assert.ok(batches[2][0].includes("THIRD_SESSION"));
+	});
+
+	it("each entry includes separator suffix", () => {
+		const sessions = [makeSession("a", 50)];
+		const batches = buildTranscriptBatches(sessions, 1000);
+		assert.ok(batches[0][0].endsWith("\n---\n\n"));
+	});
+});
+
+// --- Tool call parsing + batched runReflection tests ---
+
+let tmpDir: string;
+let notifications: Array<{ msg: string; level: string }>;
+let notify: NotifyFn;
+
+beforeEach(() => {
+	tmpDir = makeTempDir();
+	notifications = [];
+	notify = (msg, level) => notifications.push({ msg, level });
+});
+
+afterEach(() => {
+	cleanup(tmpDir);
+});
+
+function makeTarget(overrides: Partial<ReflectTarget> = {}): ReflectTarget {
+	return {
+		...DEFAULT_TARGET,
+		backupDir: path.join(tmpDir, "backups"),
+		...overrides,
+	};
+}
+
+function makeModelRegistry() {
+	return {
+		find: () => ({ provider: "test", id: "test-model" }),
+		getApiKey: async () => "test-key",
+	};
+}
+
+function makeToolCallResponse(analysis: any) {
+	return {
+		content: [{
+			type: "toolCall",
+			name: "submit_analysis",
+			arguments: analysis,
+		}],
+	};
+}
+
+function makeTextResponse(text: string) {
+	return {
+		content: [{ type: "text", text }],
+	};
+}
+
+// batchBudget = Math.max(maxSessionBytes - overhead, 100_000)
+// overhead = targetContent.length + context.length + 20_000
+// SAMPLE_AGENTS_MD is ~900 bytes, so overhead ≈ 20_900
+// To force batching: totalBytes must exceed batchBudget
+// With maxSessionBytes=120_000, batchBudget = max(120_000 - 20_900, 100_000) = 100_000
+// So sessions totaling >100KB will trigger batching.
+const LARGE_SESSION_SIZE = 40_000; // 40KB each — 3 sessions = 120KB > 100KB budget
+
+function makeLargeSessions(count: number): SessionData[] {
+	return Array.from({ length: count }, (_, i) =>
+		makeSession(`s${i + 1}`, LARGE_SESSION_SIZE)
+	);
+}
+
+function makeBatchDeps(
+	responsePerCall: any[],
+	sessions: SessionData[],
+): RunReflectionDeps {
+	let callIndex = 0;
+	return {
+		completeSimple: async () => {
+			const resp = responsePerCall[Math.min(callIndex, responsePerCall.length - 1)];
+			callIndex++;
+			return resp;
+		},
+		getModel: () => ({ provider: "test", id: "test-model" }),
+		collectTranscriptsFn: async () => ({
+			transcripts: sessions.map(s => s.transcript).join("\n---\n\n"),
+			sessionCount: sessions.length,
+			includedCount: sessions.length,
+			sessions,
+		}),
+	};
+}
+
+describe("analyzeTranscriptBatch — tool call parsing", () => {
+	it("parses structured tool call response", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({ path: fp });
+
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => makeToolCallResponse({
+				corrections_found: 1,
+				sessions_with_corrections: 1,
+				edits: [{
+					type: "strengthen",
+					section: "Rules",
+					old_text: "- **Keep code DRY**: NEVER duplicate logic.",
+					new_text: "- **Keep code DRY**: NEVER duplicate logic. Always use shared helpers.",
+					reason: "Agent duplicated code in 2 sessions",
+				}],
+				summary: "Added DRY emphasis.",
+			}),
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: "### Session\n\n**USER:** test\n",
+				sessionCount: 1,
+				includedCount: 1,
+			}),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps);
+		assert.notEqual(result, null);
+		assert.equal(result!.editsApplied, 1);
+		const updated = fs.readFileSync(fp, "utf-8");
+		assert.ok(updated.includes("shared helpers"));
+	});
+
+	it("falls back to JSON text when no tool call in response", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({ path: fp });
+
+		const jsonResponse = JSON.stringify({
+			corrections_found: 1,
+			sessions_with_corrections: 1,
+			edits: [{
+				type: "strengthen",
+				section: "Rules",
+				old_text: "- **Keep code DRY**: NEVER duplicate logic.",
+				new_text: "- **Keep code DRY**: NEVER duplicate logic. Use parameterized functions.",
+				reason: "test",
+			}],
+			summary: "Fallback test.",
+		});
+
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => makeTextResponse(jsonResponse),
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: "### Session\n\n**USER:** test\n",
+				sessionCount: 1,
+				includedCount: 1,
+			}),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps);
+		assert.notEqual(result, null);
+		assert.equal(result!.editsApplied, 1);
+	});
+
+	it("handles LLM error response gracefully", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({ path: fp });
+
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => ({
+				stopReason: "error",
+				errorMessage: "Rate limit exceeded",
+				content: [],
+			}),
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: "### Session\n\n**USER:** test\n",
+				sessionCount: 1,
+				includedCount: 1,
+			}),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps);
+		assert.equal(result, null);
+		assert.ok(notifications.some(n => n.level === "error" && n.msg.includes("Rate limit")));
+	});
+});
+
+describe("batched runReflection", () => {
+	it("triggers batching when sessions exceed context budget", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+
+		const target = makeTarget({
+			path: fp,
+			maxSessionBytes: 120_000, // batchBudget ≈ 100KB, 3 × 40KB = 120KB > 100KB
+		});
+
+		const sessions = makeLargeSessions(3);
+
+		// Each batch gets its own LLM call
+		let callCount = 0;
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => {
+				callCount++;
+				if (callCount === 1) {
+					return makeToolCallResponse({
+						corrections_found: 1,
+						sessions_with_corrections: 1,
+						edits: [{
+							type: "add",
+							after_text: "- **Keep code DRY**: NEVER duplicate logic.",
+							new_text: "- **Batch 1 rule**: From first batch.",
+							reason: "batch 1",
+							section: "Rules",
+						}],
+						summary: "Batch 1 done.",
+					});
+				}
+				// Later batches: add after batch 1's rule
+				return makeToolCallResponse({
+					corrections_found: 1,
+					sessions_with_corrections: 1,
+					edits: [{
+						type: "add",
+						after_text: "- **Batch 1 rule**: From first batch.",
+						new_text: `- **Batch ${callCount} rule**: From batch ${callCount}.`,
+						reason: `batch ${callCount}`,
+						section: "Rules",
+					}],
+					summary: `Batch ${callCount} done.`,
+				});
+			},
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: sessions.map(s => s.transcript).join("\n---\n\n"),
+				sessionCount: sessions.length,
+				includedCount: sessions.length,
+				sessions,
+			}),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps);
+
+		assert.notEqual(result, null);
+		assert.ok(callCount >= 2, `Expected multiple LLM calls, got ${callCount}`);
+		assert.ok(notifications.some(n => n.msg.includes("splitting into")));
+		assert.ok(notifications.some(n => n.msg.includes("Batch 1")));
+
+		const updated = fs.readFileSync(fp, "utf-8");
+		assert.ok(updated.includes("Batch 1 rule"));
+	});
+
+	it("creates backup only once for multi-batch edits", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const backupDir = path.join(tmpDir, "backups");
+		const target = makeTarget({
+			path: fp,
+			backupDir,
+			maxSessionBytes: 120_000,
+		});
+
+		const sessions = makeLargeSessions(3);
+		let callCount = 0;
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => {
+				callCount++;
+				if (callCount === 1) {
+					return makeToolCallResponse({
+						corrections_found: 1,
+						sessions_with_corrections: 1,
+						edits: [{
+							type: "add",
+							after_text: "- **Keep code DRY**: NEVER duplicate logic.",
+							new_text: "- **Rule from batch 1**: Added.",
+							reason: "test",
+							section: "Rules",
+						}],
+						summary: "Batch 1.",
+					});
+				}
+				return makeToolCallResponse({
+					corrections_found: 1,
+					sessions_with_corrections: 1,
+					edits: [{
+						type: "add",
+						after_text: "- **Rule from batch 1**: Added.",
+						new_text: `- **Rule from batch ${callCount}**: Also added.`,
+						reason: "test",
+						section: "Rules",
+					}],
+					summary: `Batch ${callCount}.`,
+				});
+			},
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: sessions.map(s => s.transcript).join("\n---\n\n"),
+				sessionCount: sessions.length,
+				includedCount: sessions.length,
+				sessions,
+			}),
+		};
+
+		await runReflection(target, makeModelRegistry(), notify, deps);
+
+		// Only one backup file should exist
+		const backups = fs.readdirSync(backupDir);
+		assert.equal(backups.length, 1);
+
+		// Backup should have original content (before any batch edits)
+		const backupContent = fs.readFileSync(path.join(backupDir, backups[0]), "utf-8");
+		assert.equal(backupContent, SAMPLE_AGENTS_MD);
+	});
+
+	it("later batches see edits from earlier batches", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({
+			path: fp,
+			maxSessionBytes: 120_000,
+		});
+
+		const sessions = makeLargeSessions(3);
+
+		// Later batches should see edits from batch 1 on disk
+		let callIndex = 0;
+		let laterBatchSawEdit = false;
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => {
+				callIndex++;
+				if (callIndex === 1) {
+					return makeToolCallResponse({
+						corrections_found: 1,
+						sessions_with_corrections: 1,
+						edits: [{
+							type: "add",
+							after_text: "- **Keep code DRY**: NEVER duplicate logic.",
+							new_text: "- **Intermediate rule**: Inserted by batch 1.",
+							reason: "test",
+							section: "Rules",
+						}],
+						summary: "Batch 1.",
+					});
+				}
+				// Later batch — verify it sees batch 1's edit by reading the file
+				const currentContent = fs.readFileSync(fp, "utf-8");
+				if (currentContent.includes("Intermediate rule")) {
+					laterBatchSawEdit = true;
+				}
+				return makeToolCallResponse({
+					corrections_found: 0,
+					sessions_with_corrections: 0,
+					edits: [],
+					summary: `Batch ${callIndex} clean.`,
+				});
+			},
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: sessions.map(s => s.transcript).join("\n---\n\n"),
+				sessionCount: sessions.length,
+				includedCount: sessions.length,
+				sessions,
+			}),
+		};
+
+		await runReflection(target, makeModelRegistry(), notify, deps);
+		assert.ok(callIndex >= 2, "Should have multiple batch calls");
+		assert.ok(laterBatchSawEdit, "Later batch should see batch 1's edits on disk");
+	});
+
+	it("combines summaries from multiple batches", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({
+			path: fp,
+			maxSessionBytes: 120_000,
+		});
+
+		const sessions = makeLargeSessions(3);
+		let callCount = 0;
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => {
+				callCount++;
+				return makeToolCallResponse({
+					corrections_found: 0,
+					sessions_with_corrections: 0,
+					edits: [],
+					summary: `Batch ${callCount} summary.`,
+				});
+			},
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: sessions.map(s => s.transcript).join("\n---\n\n"),
+				sessionCount: sessions.length,
+				includedCount: sessions.length,
+				sessions,
+			}),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps);
+
+		assert.notEqual(result, null);
+		assert.ok(callCount >= 2, `Expected multiple LLM calls, got ${callCount}`);
+		assert.ok(result!.summary.includes("Batch 1 summary."));
+		assert.ok(result!.summary.includes("Batch 2 summary."));
+	});
+
+	it("continues processing when one batch fails", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({
+			path: fp,
+			maxSessionBytes: 120_000,
+		});
+
+		const sessions = makeLargeSessions(3);
+
+		let callIndex = 0;
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => {
+				callIndex++;
+				if (callIndex === 1) {
+					// First batch fails
+					return { stopReason: "error", errorMessage: "Timeout", content: [] };
+				}
+				// Later batches succeed
+				return makeToolCallResponse({
+					corrections_found: 1,
+					sessions_with_corrections: 1,
+					edits: [{
+						type: "add",
+						after_text: "- **Keep code DRY**: NEVER duplicate logic.",
+						new_text: "- **Surviving rule**: From later batch.",
+						reason: "test",
+						section: "Rules",
+					}],
+					summary: "Later batch succeeded.",
+				});
+			},
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: sessions.map(s => s.transcript).join("\n---\n\n"),
+				sessionCount: sessions.length,
+				includedCount: sessions.length,
+				sessions,
+			}),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps);
+		assert.ok(callIndex >= 2, "Should have made multiple LLM calls");
+		// Later batch's edit should still apply even though batch 1 failed
+		const updated = fs.readFileSync(fp, "utf-8");
+		assert.ok(updated.includes("Surviving rule"));
+		assert.ok(notifications.some(n => n.msg.includes("Timeout")));
+	});
+
+	it("does not batch when sessions fit within budget", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({
+			path: fp,
+			maxSessionBytes: 500_000, // large budget
+		});
+
+		const sessions = [makeSession("s1", 100), makeSession("s2", 100)];
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => makeToolCallResponse({
+				corrections_found: 0,
+				sessions_with_corrections: 0,
+				edits: [],
+				summary: "All clean.",
+			}),
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: "### Session\n\n**USER:** test\n",
+				sessionCount: 2,
+				includedCount: 2,
+				sessions,
+			}),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps);
+		assert.notEqual(result, null);
+		// Should NOT see batching notification
+		assert.ok(!notifications.some(n => n.msg.includes("splitting into")));
+		assert.ok(notifications.some(n => n.msg.includes("Analyzing with")));
+	});
+
+	it("accumulates correctionsFound across batches", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({
+			path: fp,
+			maxSessionBytes: 120_000,
+		});
+
+		const sessions = makeLargeSessions(3);
+		let callCount = 0;
+		const correctionsPerBatch = [3, 5, 2]; // one per batch
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => {
+				const idx = callCount;
+				callCount++;
+				return makeToolCallResponse({
+					corrections_found: correctionsPerBatch[idx] ?? 0,
+					sessions_with_corrections: 1,
+					edits: [],
+					summary: `Batch ${idx + 1}.`,
+				});
+			},
+			getModel: () => ({ provider: "test", id: "test-model" }),
+			collectTranscriptsFn: async () => ({
+				transcripts: sessions.map(s => s.transcript).join("\n---\n\n"),
+				sessionCount: sessions.length,
+				includedCount: sessions.length,
+				sessions,
+			}),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps);
+
+		assert.notEqual(result, null);
+		// Sum all corrections across however many batches were created
+		const expectedTotal = correctionsPerBatch.slice(0, callCount).reduce((a, b) => a + b, 0);
+		assert.equal(result!.correctionsFound, expectedTotal);
+	});
+
+	it("uses transcriptsOverride sessions for batching", async () => {
+		const fp = path.join(tmpDir, "AGENTS.md");
+		fs.writeFileSync(fp, SAMPLE_AGENTS_MD);
+		const target = makeTarget({
+			path: fp,
+			maxSessionBytes: 120_000,
+		});
+
+		const sessions = makeLargeSessions(3);
+
+		const deps: RunReflectionDeps = {
+			completeSimple: async () => makeToolCallResponse({
+				corrections_found: 0,
+				sessions_with_corrections: 0,
+				edits: [],
+				summary: "Clean.",
+			}),
+			getModel: () => ({ provider: "test", id: "test-model" }),
+		};
+
+		const result = await runReflection(target, makeModelRegistry(), notify, deps, {
+			transcriptsOverride: {
+				transcripts: sessions.map(s => s.transcript).join("\n---\n\n"),
+				sessionCount: 2,
+				includedCount: 2,
+				sessions,
+			},
+		});
+
+		assert.notEqual(result, null);
+		// Should batch since totalBytes (800) > batchBudget with tiny maxSessionBytes
+		assert.ok(notifications.some(n => n.msg.includes("splitting into")));
+	});
+});