pi-agent-flow 1.2.0 → 1.2.3

package/src/batch.ts

@@ -84,6 +84,14 @@ interface FileOpInput {
 	l?: number;
 }
 
+interface ContextMapEntry {
+	kind: string;
+	name: string;
+	startLine: number;
+	endLine: number;
+	parent?: string;
+}
+
 interface OpResult {
 	op: "read" | "write" | "edit" | "delete";
 	path: string;
@@ -92,6 +100,11 @@ interface OpResult {
 	bytes?: number;
 	blocksChanged?: number;
 	totalLines?: number;
+	contextMap?: boolean;
+	language?: string;
+	symbols?: ContextMapEntry[];
+	symbolsTruncated?: boolean;
+	warning?: string;
 	truncated?: boolean;
 	nextOffset?: number;
 	error?: string;
@@ -107,8 +120,9 @@ interface ReadTruncationResult {
 
 interface ReadOptions {
 	/**
-	 * When false, read operations ignore MAX_LINES and total MAX_BYTES caps.
-	 * A single selected line that exceeds MAX_BYTES still fails with a targeted error.
+	 * When false, readWithOffsetLimit ignores regular batch MAX_LINES and total
+	 * MAX_BYTES caps. batch_read applies its own safe full-file and targeted-read
+	 * guards before calling this helper.
 	 */
 	truncate?: boolean;
 	toolName?: "batch" | "batch_read";
@@ -125,6 +139,9 @@ interface ExecuteOptions {
 
 const MAX_LINES = 2000;
 const MAX_BYTES = 50 * 1024; // 50KB
+const SAFE_FULL_READ_LIMIT = 300;
+const TARGETED_READ_LINE_LIMIT = 1000;
+const MAX_CONTEXT_MAP_ENTRIES = 100;
 
 function normalizeToLF(text: string): string {
 	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
@@ -148,6 +165,355 @@ function stripBom(content: string): { bom: string; text: string } {
 		: { bom: "", text: content };
 }
 
+type ContextLanguage =
+	| "typescript"
+	| "javascript"
+	| "python"
+	| "terraform"
+	| "hcl"
+	| "yaml"
+	| "dockerfile"
+	| "plain";
+
+interface FileContextMap {
+	language: ContextLanguage;
+	symbols: ContextMapEntry[];
+	symbolsTruncated?: boolean;
+}
+
+function isBatchRead(options: ExecuteOptions): boolean {
+	return options.readOptions?.toolName === "batch_read";
+}
+
+function isFullFileRead(op: FileOpInput, totalLines: number): boolean {
+	const start = op.s ?? 1;
+	if (start !== 1) return false;
+	return op.l === undefined || op.l >= totalLines;
+}
+
+function buildBatchReadSafetyWarning(): string {
+	return `[batch_read safety] Raw content truncated at ${TARGETED_READ_LINE_LIMIT} lines to preserve context. Adjust your 's' and 'l' parameters to read further.`;
+}
+
+function detectContextLanguage(filePath: string): ContextLanguage {
+	const base = path.basename(filePath);
+	const lowerBase = base.toLowerCase();
+	const ext = path.extname(lowerBase);
+
+	if (
+		lowerBase === "dockerfile" ||
+		lowerBase.startsWith("dockerfile.") ||
+		lowerBase === ".dockerfile" ||
+		lowerBase.endsWith(".dockerfile")
+	) {
+		return "dockerfile";
+	}
+
+	if ([".ts", ".tsx", ".mts", ".cts"].includes(ext)) return "typescript";
+	if ([".js", ".jsx", ".mjs", ".cjs"].includes(ext)) return "javascript";
+	if ([".py", ".pyw"].includes(ext)) return "python";
+	if ([".tf", ".tfvars"].includes(ext)) return "terraform";
+	if (ext === ".hcl") return "hcl";
+	if ([".yml", ".yaml"].includes(ext)) return "yaml";
+	return "plain";
+}
+
+function buildFileContextMap(filePath: string, lines: string[]): FileContextMap {
+	const language = detectContextLanguage(filePath);
+	let symbols: ContextMapEntry[] = [];
+
+	try {
+		switch (language) {
+			case "typescript":
+			case "javascript":
+				symbols = extractTsJsSymbols(lines);
+				break;
+			case "python":
+				symbols = extractPythonSymbols(lines);
+				break;
+			case "terraform":
+			case "hcl":
+				symbols = extractTerraformSymbols(lines);
+				break;
+			case "yaml":
+				symbols = extractYamlSymbols(lines);
+				break;
+			case "dockerfile":
+				symbols = extractDockerfileSymbols(lines);
+				break;
+			default:
+				symbols = [];
+		}
+	} catch {
+		symbols = [];
+	}
+
+	const sorted = symbols
+		.filter((entry) => entry.startLine > 0 && entry.endLine >= entry.startLine)
+		.sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine);
+
+	return {
+		language,
+		symbols: sorted.slice(0, MAX_CONTEXT_MAP_ENTRIES),
+		symbolsTruncated: sorted.length > MAX_CONTEXT_MAP_ENTRIES || undefined,
+	};
+}
+
+function countLeadingWhitespace(line: string): number {
+	return line.match(/^\s*/)?.[0].length ?? 0;
+}
+
+function findBraceBlockEnd(lines: string[], startIndex: number): number {
+	let depth = 0;
+	let sawOpenBrace = false;
+
+	for (let i = startIndex; i < lines.length; i++) {
+		for (const char of lines[i]) {
+			if (char === "{") {
+				depth++;
+				sawOpenBrace = true;
+			} else if (char === "}") {
+				depth--;
+			}
+		}
+		if (sawOpenBrace && depth <= 0) return i + 1;
+	}
+
+	return sawOpenBrace ? lines.length : startIndex + 1;
+}
+
+function findStatementEnd(lines: string[], startIndex: number): number {
+	for (let i = startIndex; i < lines.length; i++) {
+		if (lines[i].includes(";")) return i + 1;
+	}
+	return startIndex + 1;
+}
+
+function findIndentedBlockEnd(lines: string[], startIndex: number, indent: number): number {
+	for (let i = startIndex + 1; i < lines.length; i++) {
+		const trimmed = lines[i].trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		if (countLeadingWhitespace(lines[i]) <= indent) return i;
+	}
+	return lines.length;
+}
+
+function findYamlBlockEnd(lines: string[], startIndex: number, indent: number): number {
+	for (let i = startIndex + 1; i < lines.length; i++) {
+		const trimmed = lines[i].trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		if (trimmed === "---" || countLeadingWhitespace(lines[i]) <= indent) return i;
+	}
+	return lines.length;
+}
+
+function extractTsJsSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+	const classes: ContextMapEntry[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		let match = line.match(/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/);
+		if (match) {
+			entries.push({ kind: "function", name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?(?:default\s+)?class\s+([A-Za-z_$][\w$]*)\b/);
+		if (match) {
+			const entry = { kind: "class", name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) };
+			entries.push(entry);
+			classes.push(entry);
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)\b/);
+		if (match) {
+			entries.push({ kind: "interface", name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\b/);
+		if (match) {
+			entries.push({ kind: "type", name: match[1], startLine: i + 1, endLine: line.includes("{") ? findBraceBlockEnd(lines, i) : findStatementEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?enum\s+([A-Za-z_$][\w$]*)\b/);
+		if (match) {
+			entries.push({ kind: "enum", name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:function\b|(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>)/);
+		if (match) {
+			entries.push({ kind: "function", name: match[1], startLine: i + 1, endLine: line.includes("{") ? findBraceBlockEnd(lines, i) : findStatementEnd(lines, i) });
+		}
+	}
+
+	const methodNameBlacklist = new Set(["if", "for", "while", "switch", "catch", "function"]);
+	for (const classEntry of classes) {
+		for (let i = classEntry.startLine; i < classEntry.endLine - 1 && i < lines.length; i++) {
+			const match = lines[i].match(/^\s*(?:(?:public|private|protected|static|async|override|readonly)\s+)*([A-Za-z_$][\w$]*)\s*(?:<[^>]+>)?\s*\([^)]*\)\s*(?::\s*[^={]+)?\s*\{/);
+			if (!match || methodNameBlacklist.has(match[1])) continue;
+			entries.push({
+				kind: "method",
+				name: `${classEntry.name}.${match[1]}`,
+				parent: classEntry.name,
+				startLine: i + 1,
+				endLine: findBraceBlockEnd(lines, i),
+			});
+		}
+	}
+
+	return entries;
+}
+
+function extractPythonSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+	const classes: Array<ContextMapEntry & { indent: number }> = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(/^(\s*)class\s+([A-Za-z_]\w*)\b/);
+		if (!match) continue;
+		const indent = match[1].length;
+		const entry = { kind: "class", name: match[2], startLine: i + 1, endLine: findIndentedBlockEnd(lines, i, indent), indent };
+		classes.push(entry);
+		entries.push(entry);
+	}
+
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(/^(\s*)(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/);
+		if (!match) continue;
+		const indent = match[1].length;
+		const parent = classes.find((cls) => i + 1 > cls.startLine && i + 1 < cls.endLine && indent > cls.indent);
+		entries.push({
+			kind: parent ? "method" : "function",
+			name: parent ? `${parent.name}.${match[2]}` : match[2],
+			parent: parent?.name,
+			startLine: i + 1,
+			endLine: findIndentedBlockEnd(lines, i, indent),
+		});
+	}
+
+	return entries;
+}
+
+function extractTerraformSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		let match = line.match(/^\s*(resource|data)\s+"([^"]+)"\s+"([^"]+)"\s*\{/);
+		if (match) {
+			entries.push({ kind: match[1], name: `${match[2]}.${match[3]}`, startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(module|variable|output|provider)\s+"([^"]+)"\s*\{/);
+		if (match) {
+			entries.push({ kind: match[1], name: match[2], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^\s*(locals|terraform)\s*\{/);
+		if (match) {
+			entries.push({ kind: match[1], name: match[1], startLine: i + 1, endLine: findBraceBlockEnd(lines, i) });
+			continue;
+		}
+
+		match = line.match(/^([A-Za-z_][\w-]*)\s*=/);
+		if (match) {
+			entries.push({ kind: "assignment", name: match[1], startLine: i + 1, endLine: i + 1 });
+		}
+	}
+
+	return entries;
+}
+
+function extractYamlSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+
+	let docStart = 0;
+	for (let i = 0; i <= lines.length; i++) {
+		if (i < lines.length && lines[i].trim() !== "---") continue;
+		const docEnd = i === lines.length ? lines.length : i;
+		const docLines = lines.slice(docStart, docEnd);
+		const kindLine = docLines.findIndex((line) => /^kind:\s*\S+/.test(line));
+		const nameLine = docLines.findIndex((line) => /^\s{2}name:\s*\S+/.test(line));
+		if (kindLine >= 0 && nameLine >= 0) {
+			const kind = docLines[kindLine].replace(/^kind:\s*/, "").trim();
+			const name = docLines[nameLine].replace(/^\s{2}name:\s*/, "").trim();
+			entries.push({ kind, name, startLine: docStart + 1, endLine: Math.max(docStart + 1, docEnd) });
+		}
+		docStart = i + 1;
+	}
+
+	for (let i = 0; i < lines.length; i++) {
+		const topLevel = lines[i].match(/^([A-Za-z_][\w.-]*):\s*/);
+		if (topLevel) {
+			const key = topLevel[1];
+			entries.push({ kind: "section", name: key, startLine: i + 1, endLine: findYamlBlockEnd(lines, i, 0) });
+
+			if (["jobs", "services", "volumes", "networks"].includes(key)) {
+				for (let j = i + 1; j < lines.length; j++) {
+					const trimmed = lines[j].trim();
+					if (!trimmed || trimmed.startsWith("#")) continue;
+					const indent = countLeadingWhitespace(lines[j]);
+					if (indent <= 0) break;
+					const child = lines[j].match(/^\s{2}([A-Za-z0-9_.-]+):\s*/);
+					if (!child) continue;
+					const childKind = key === "jobs" ? "job" : key.slice(0, -1);
+					entries.push({ kind: childKind, name: child[1], startLine: j + 1, endLine: findYamlBlockEnd(lines, j, 2) });
+				}
+			}
+		}
+
+		const step = lines[i].match(/^\s*-\s+(?:name:\s*(.+)|uses:\s*(.+)|run:\s*(.+))/);
+		if (step) {
+			const name = (step[1] ?? step[2] ?? step[3] ?? "step").trim();
+			entries.push({ kind: "step", name: name.slice(0, 120), startLine: i + 1, endLine: i + 1 });
+		}
+	}
+
+	return entries;
+}
+
+function findDockerInstructionEnd(lines: string[], startIndex: number): number {
+	let endIndex = startIndex;
+	while (endIndex + 1 < lines.length && lines[endIndex].trimEnd().endsWith("\\")) {
+		endIndex++;
+	}
+	return endIndex + 1;
+}
+
+function extractDockerfileSymbols(lines: string[]): ContextMapEntry[] {
+	const entries: ContextMapEntry[] = [];
+	const fromLines: number[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		if (/^\s*FROM\s+/i.test(lines[i])) fromLines.push(i);
+	}
+
+	for (let idx = 0; idx < fromLines.length; idx++) {
+		const i = fromLines[idx];
+		const nextFrom = fromLines[idx + 1] ?? lines.length;
+		const match = lines[i].match(/^\s*FROM\s+(\S+)(?:\s+AS\s+(\S+))?/i);
+		const image = match?.[1] ?? "unknown";
+		const alias = match?.[2];
+		entries.push({ kind: "stage", name: alias ? `${alias} FROM ${image}` : image, startLine: i + 1, endLine: nextFrom });
+	}
+
+	const important = /^(RUN|COPY|ADD|ENTRYPOINT|CMD|EXPOSE|ENV|ARG|WORKDIR)\b\s*(.*)/i;
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].trim().match(important);
+		if (!match) continue;
+		entries.push({ kind: match[1].toUpperCase(), name: (match[2] || match[1]).slice(0, 120), startLine: i + 1, endLine: findDockerInstructionEnd(lines, i) });
+	}
+
+	return entries;
+}
+
 function readWithOffsetLimit(
 	content: string,
 	offset?: number,
@@ -180,9 +546,8 @@ function readWithOffsetLimit(
 	let truncated = false;
 	let nextOffset: number | undefined;
 
-	// Apply max-lines cap for regular batch reads. batch_read intentionally
-	// bypasses this cap so each read operation can return the full requested file
-	// or range.
+	// Apply max-lines cap for regular batch reads. batch_read clamps oversized
+	// targeted reads before this helper and context-maps large full-file reads.
 	if (shouldTruncate && selectedLines.length > MAX_LINES) {
 		selectedLines = selectedLines.slice(0, MAX_LINES);
 		truncated = true;
@@ -202,8 +567,8 @@ function readWithOffsetLimit(
 	// Join and check byte size
 	let result = selectedLines.join("\n");
 
-	// Truncate by total bytes for regular batch reads only. batch_read keeps the
-	// complete selected multi-line content unless an individual line is too long.
+	// Truncate by total bytes for regular batch reads only. batch_read relies on
+	// its line-oriented safety guards and still rejects an individual huge line.
 	if (shouldTruncate && Buffer.byteLength(result, "utf-8") > MAX_BYTES) {
 		let byteAccum = 0;
 		let keepLines = 0;
@@ -732,11 +1097,42 @@ async function executeOperations(
 					const allLines = text.split("\n");
 					const totalFileLines = allLines.length;
 
-					const { content: readContent, truncated, nextOffset, linesRead } =
-						readWithOffsetLimit(text, op.s, op.l, op.p, options.readOptions);
+					if (isBatchRead(options) && isFullFileRead(op, totalFileLines) && totalFileLines > SAFE_FULL_READ_LIMIT) {
+						const context = buildFileContextMap(op.p, allLines);
+						results.push({
+							op: "read",
+							path: op.p,
+							status: "ok",
+							totalLines: totalFileLines,
+							contextMap: true,
+							language: context.language !== "plain" ? context.language : undefined,
+							symbols: context.symbols.length > 0 ? context.symbols : undefined,
+							symbolsTruncated: context.symbolsTruncated,
+						});
+						counts.read++;
+						break;
+					}
+
+					let effectiveLimit = op.l;
+					let safetyTruncated = false;
+					let safetyWarning: string | undefined;
+					if (isBatchRead(options) && !isFullFileRead(op, totalFileLines)) {
+						if (effectiveLimit === undefined || effectiveLimit > TARGETED_READ_LINE_LIMIT) {
+							effectiveLimit = TARGETED_READ_LINE_LIMIT;
+							safetyTruncated = true;
+							safetyWarning = buildBatchReadSafetyWarning();
+						}
+					}
 
-					if (truncated || (includeLimitWarnings && op.l !== undefined && (op.s ?? 1) - 1 + op.l < totalFileLines)) {
-						const shownLines = truncated ? linesRead : op.l!;
+					const { content: readContent, truncated, nextOffset, linesRead } =
+						readWithOffsetLimit(text, op.s, effectiveLimit, op.p, options.readOptions);
+					const finalContent = safetyWarning
+						? `${readContent}\n\n${safetyWarning}`
+						: readContent;
+					const finalTruncated = truncated || safetyTruncated;
+
+					if (finalTruncated || (includeLimitWarnings && effectiveLimit !== undefined && (op.s ?? 1) - 1 + effectiveLimit < totalFileLines)) {
+						const shownLines = finalTruncated ? linesRead : effectiveLimit!;
 						truncatedFiles.push({
 							path: op.p,
 							shown: shownLines,
@@ -749,9 +1145,10 @@ async function executeOperations(
 						op: "read",
 						path: op.p,
 						status: "ok",
-						content: readContent,
+						content: finalContent,
 						totalLines: totalFileLines,
-						truncated: truncated || undefined,
+						warning: safetyWarning,
+						truncated: finalTruncated || undefined,
 						nextOffset,
 					});
 					counts.read++;
@@ -990,11 +1387,40 @@ function renderBatchResult(
 	return new Text(fullText, 0, 0);
 }
 
+function buildContextMapText(result: OpResult): string {
+	const title = result.language || result.symbols ? "context map" : "file summary";
+	const lines: string[] = [`\n--- ${result.path} ${title} ---`];
+	lines.push(`Total lines: ${result.totalLines ?? 0}`);
+	if (result.language) lines.push(`Language: ${result.language}`);
+	lines.push("");
+	lines.push(`Full-file content omitted because file exceeds SAFE_FULL_READ_LIMIT=${SAFE_FULL_READ_LIMIT} lines.`);
+	lines.push("Use targeted reads with s/l, for example:");
+	lines.push(`{ "o": "read", "p": "${result.path}", "s": <startLine>, "l": <lineCount> }`);
+
+	if (result.symbols && result.symbols.length > 0) {
+		lines.push("");
+		lines.push("Context map:");
+		for (const entry of result.symbols) {
+			lines.push(`- ${entry.kind} ${entry.name} ${entry.startLine}-${entry.endLine}`);
+		}
+		if (result.symbolsTruncated) {
+			lines.push(`... [Context map truncated. Over ${MAX_CONTEXT_MAP_ENTRIES} entries detected. Use targeted reads to explore further.]`);
+		}
+	} else if (result.language) {
+		lines.push("");
+		lines.push("No context map entries detected for this structured file.");
+	}
+
+	return lines.join("\n");
+}
+
 function buildContentText(summary: string, results: OpResult[]): string {
 	const sections: string[] = [summary];
 
 	for (const r of results) {
-		if (r.op === "read" && r.status === "ok" && r.content) {
+		if (r.op === "read" && r.status === "ok" && r.contextMap) {
+			sections.push(buildContextMapText(r));
+		} else if (r.op === "read" && r.status === "ok" && r.content) {
 			const lineInfo = r.totalLines !== undefined ? ` (${r.totalLines} lines)` : "";
 			sections.push(`\n--- ${r.path}${lineInfo} ---\n${r.content}`);
 		} else if (r.op === "edit" && r.status === "ok") {
@@ -1071,7 +1497,8 @@ export function createBatchReadTool() {
 		description: [
 			"Batch read-only file operations — run multiple read ops in a single call.",
 			"Each operation is independent and executes sequentially in array order; on failure, remaining operations are skipped.",
-			"Reads are not truncated by the batch MAX_LINES or total MAX_BYTES caps; a single line over the byte limit still errors.",
+			`Full-file reads up to ${SAFE_FULL_READ_LIMIT} lines return raw content; larger full-file reads return a context map for code/infra files or total lines for plain text.`,
+			`Targeted reads with l over ${TARGETED_READ_LINE_LIMIT} are clamped with a continuation warning; a single line over the byte limit still errors.`,
 			"Use `o: \"read\"` with `s` (offset) and `l` (limit) for targeted reading. Prefer this over bash sed/head/tail.",
 			"Best for reading multiple files or sections in one call.",
 		].join("\n"),
@@ -1079,8 +1506,9 @@ export function createBatchReadTool() {
 		promptGuidelines: [
 			"Use batch_read to perform multiple file reads in a single call rather than separate tool calls.",
 			"Prefer batch_read when reading 2+ files or multiple sections of the same file.",
-			"batch_read returns the full requested content except when an individual line exceeds the byte limit.",
-			"For single-file reads, the read tool is fine; batch_read shines for multi-file reading.",
+			`Small full-file reads (<=${SAFE_FULL_READ_LIMIT} lines) return raw content; larger full-file reads return navigable context maps or line counts.`,
+			`Use targeted reads with s/l around context-map entries; targeted reads are capped at ${TARGETED_READ_LINE_LIMIT} lines.`,
+			"Do not retry the same full-file read when a context map is returned.",
 		],
 		parameters: BatchReadParams,
 		prepareArguments: prepareBatchReadArguments,

package/src/config.ts

@@ -27,6 +27,8 @@ export interface LoadedFlowModelConfigs {
 
 export interface FlowSettings {
 	toolOptimize?: boolean;
+	/** Whether to inject structured JSON output instructions into flow prompts. Default: true. */
+	structuredOutput?: boolean;
 }
 
 const BUILTIN_FLOW_MODEL_CONFIGS: FlowModelConfigs = {
@@ -171,6 +173,9 @@ function extractFlowSettings(settings: Record<string, unknown> | null): FlowSett
 	if (typeof obj.toolOptimize === "boolean") {
 		result.toolOptimize = obj.toolOptimize;
 	}
+	if (typeof obj.structuredOutput === "boolean") {
+		result.structuredOutput = obj.structuredOutput;
+	}
 	return result;
 }
 

package/src/flow.ts

@@ -20,6 +20,7 @@ import {
 	getFlowOutput,
 	normalizeFlowResult,
 } from "./types.js";
+import { extractStructuredOutput } from "./structured-output.js";
 
 const isWindows = process.platform === "win32";
 const SIGKILL_TIMEOUT_MS = 5000;
@@ -132,6 +133,7 @@ function buildFlowArgs(
 	parentDepth: number = 0,
 	maxDepth: number = 0,
 	toolOptimize: boolean = false,
+	structuredOutput: boolean = true,
 ): string[] {
 	const args: string[] = [
 		"--mode",
@@ -210,8 +212,42 @@ function buildFlowArgs(
 		`</activation>`;
 
 	// Phase 3: Directive — the flow's system prompt (renamed from <system-directive>)
-	const directive = flow.systemPrompt.trim()
-		? `\n\n<directive>\n${flow.systemPrompt.trim()}\n</directive>`
+	let directiveBody = flow.systemPrompt.trim();
+
+	// Append structured output instructions when enabled
+	if (structuredOutput && directiveBody) {
+		directiveBody +=
+			`\n\n## Structured Output\n\n` +
+			`End your response with a JSON code block containing:\n` +
+			`\n` +
+			`\`\`\`json\n` +
+			`{\n` +
+			`  "version": "1.0",\n` +
+			`  "status": "complete",\n` +
+			`  "summary": "2-3 sentence summary of what was accomplished",\n` +
+			`  "files": [\n` +
+			`    { "path": "relative/path", "role": "read", "description": "why it matters", "snippet": "short excerpt", "ranges": [{ "start": 10, "end": 25, "label": "bug" }] }\n` +
+			`  ],\n` +
+			`  "actions": [\n` +
+			`    { "type": "read", "description": "what was done", "target": "file.ts", "result": "success", "evidence": "output or proof" }\n` +
+			`  ],\n` +
+			`  "commands": [\n` +
+			`    { "command": "npm test", "tool": "bash", "target": ".", "result": "success", "output": "12 passing, 2 failing", "purpose": "Run test suite to verify fix" }\n` +
+			`  ],\n` +
+			`  "notDone": [\n` +
+			`    { "item": "unfinished work", "reason": "why it was not completed", "blocker": "blocking issue if any", "nextStep": "specific follow-up" }\n` +
+			`  ],\n` +
+			`  "nextSteps": ["recommended follow-up action"],\n` +
+			`  "reasoning": ["key hypothesis or inference"],\n` +
+			`  "notes": ["observation or warning"]\n` +
+			`}\n` +
+			`\`\`\`\n` +
+			`\n` +
+			`Only include fields that have data. Omit empty arrays; missing array fields are acceptable. Keep snippets under 300 characters. List at most 10 files, 10 actions, 10 commands, and 10 notDone items. If you cannot produce valid structured output, omit the JSON block entirely.`;
+	}
+
+	const directive = directiveBody
+		? `\n\n<directive>\n${directiveBody}\n</directive>`
 		: "";
 
 	// Phase 4: Mission — the intent wrapped with execution contract
@@ -256,6 +292,8 @@ export interface RunFlowOptions {
 	preventCycles: boolean;
 	/** Whether to transform tool lists to use batch. */
 	toolOptimize?: boolean;
+	/** Whether to inject structured JSON output instructions. Default: true. */
+	structuredOutput?: boolean;
 	/** Explicit model to use for this flow execution. */
 	model?: string;
 	/** Abort signal for cancellation. */
@@ -287,6 +325,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		maxDepth,
 		preventCycles,
 		toolOptimize = false,
+		structuredOutput = true,
 		model,
 		signal,
 		onUpdate,
@@ -367,6 +406,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			parentDepth,
 			maxDepth,
 			toolOptimize,
+			structuredOutput,
 		);
 		let wasAborted = false;
 
@@ -532,7 +572,18 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			result.usage.smoothedTps = finalSmoothedTps;
 		}
 
-		return normalizeFlowResult(result, wasAborted);
+		const normalized = normalizeFlowResult(result, wasAborted);
+
+		// Extract structured JSON output from the final assistant text
+		if (structuredOutput) {
+			const flowText = getFlowOutput(normalized.messages);
+			const extracted = extractStructuredOutput(flowText);
+			if (extracted) {
+				normalized.structuredOutput = extracted;
+			}
+		}
+
+		return normalized;
 	} finally {
 		cleanupFlowTempDir(forkSessionTmpDir);
 	}