pi-agent-flow 1.1.0 → 1.2.2

package/src/structured-output.ts

@@ -0,0 +1,97 @@
+/**
+ * Structured JSON output extraction from flow responses.
+ *
+ * Parses a JSON code block from the end of the flow's final assistant text
+ * and validates it against the FlowStructuredOutput schema.
+ */
+
+import type { Action, CommandEntry, FileEntry, FlowStructuredOutput, NotDoneItem } from "./types.js";
+
+type FlowStatus = FlowStructuredOutput["status"];
+
+type StructuredOutputRecord = {
+	version: string;
+	status: FlowStatus;
+	summary: string;
+	files?: FileEntry[];
+	actions?: Action[];
+	commands?: CommandEntry[];
+	notDone?: NotDoneItem[];
+	nextSteps?: string[];
+	reasoning?: string[];
+	notes?: string[];
+	extensions?: Record<string, unknown>;
+};
+
+const VALID_STATUSES: FlowStatus[] = ["complete", "partial", "blocked", "failed"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isOptionalArray(record: Record<string, unknown>, key: string): boolean {
+	return record[key] === undefined || Array.isArray(record[key]);
+}
+
+/** Minimum required fields to consider parsed JSON a valid structured output. */
+function isValidStructuredOutput(obj: unknown): obj is StructuredOutputRecord {
+	if (!isRecord(obj)) return false;
+	return (
+		typeof obj.version === "string" &&
+		typeof obj.status === "string" &&
+		VALID_STATUSES.includes(obj.status as FlowStatus) &&
+		typeof obj.summary === "string" &&
+		isOptionalArray(obj, "files") &&
+		isOptionalArray(obj, "actions") &&
+		isOptionalArray(obj, "commands") &&
+		isOptionalArray(obj, "notDone") &&
+		isOptionalArray(obj, "nextSteps") &&
+		isOptionalArray(obj, "reasoning") &&
+		isOptionalArray(obj, "notes")
+	);
+}
+
+/**
+ * Extract a structured JSON output block from the end of an assistant's text.
+ *
+ * Looks for a final ```json ... ``` code block, parses it, and validates
+ * against the FlowStructuredOutput schema. Returns undefined when the block
+ * is missing, malformed, or fails validation.
+ */
+export function extractStructuredOutput(text: string): FlowStructuredOutput | undefined {
+	if (!text) return undefined;
+
+	// Find the last ```json ... ``` block in the text.
+	// Scan backward from the end to handle multiple blocks.
+	const allMatches = [...text.matchAll(/```json\s*([\s\S]*?)\s*```/g)];
+	const match = allMatches.length > 0 ? allMatches[allMatches.length - 1] : null;
+	if (!match || !match[1]) return undefined;
+
+	const jsonStr = match[1].trim();
+	if (!jsonStr) return undefined;
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(jsonStr);
+	} catch {
+		return undefined;
+	}
+
+	if (!isValidStructuredOutput(parsed)) return undefined;
+
+	// Sanitize: trim string fields and normalize omitted arrays to [] for
+	// backward compatibility with earlier structured-output prompts.
+	return {
+		version: parsed.version.trim(),
+		status: parsed.status,
+		summary: parsed.summary.trim(),
+		files: parsed.files ?? [],
+		actions: parsed.actions ?? [],
+		commands: parsed.commands ?? [],
+		notDone: parsed.notDone ?? [],
+		nextSteps: parsed.nextSteps ?? [],
+		reasoning: parsed.reasoning ?? [],
+		notes: parsed.notes ?? [],
+		...(parsed.extensions !== undefined ? { extensions: parsed.extensions } : {}),
+	};
+}

package/{types.ts → src/types.ts}

@@ -18,6 +18,102 @@ export interface UsageStats {
 	smoothedTps?: number;
 }
 
+/** Structured file entry in a flow's output. */
+export interface FileEntry {
+	/** Path to the file, relative or absolute. */
+	path: string;
+	/** Semantic role of this file in the flow's work. */
+	role?: "reference" | "read" | "modified" | "created" | "deleted" | "test";
+	/** Why this file matters (1 sentence). */
+	description?: string;
+	/** Short excerpt or snippet (not full content). */
+	snippet?: string;
+	/** Specific line ranges of interest. */
+	ranges?: Array<{
+		start: number;
+		end: number;
+		/** Free-form label like "bug", "fix", "ref", "added". */
+		label?: string;
+	}>;
+}
+
+/** Structured command/tool invocation entry in a flow's output. */
+export interface CommandEntry {
+	/** The command string or tool call representation. */
+	command: string;
+	/** Tool used: bash, grep, find, ls, batch, read, write, edit, flow, web. */
+	tool?: string;
+	/** Working directory or target scope (file path, URL, etc.). */
+	target?: string;
+	/** Whether it succeeded, failed, or was aborted. */
+	result?: "success" | "failure" | "partial" | "aborted";
+	/** High-level output or error excerpt (not full stdout). */
+	output?: string;
+	/** Why this command was run (1 sentence). */
+	purpose?: string;
+}
+
+/** Compressed representation of a flow result for child context inheritance. */
+export interface CompressedFlowResult {
+	/** Flow type (scout, build, debug, etc.). */
+	type: string;
+	/** Execution outcome. */
+	status: "accomplished" | "failed" | "aborted";
+	/** Files touched, read, or referenced. */
+	files?: FileEntry[];
+	/** Commands or tool calls executed. */
+	commands?: CommandEntry[];
+	/** Error message for failed/aborted flows. */
+	error?: string;
+}
+
+/** Action performed or attempted by a flow. */
+export interface Action {
+	type: string;
+	description: string;
+	target?: string;
+	result?: "success" | "failure" | "partial" | "skipped";
+	evidence?: string;
+}
+
+/** Incomplete, skipped, blocked, or deferred work reported by a flow. */
+export interface NotDoneItem {
+	/** The unfinished item. */
+	item: string;
+	/** Why the item was not completed. */
+	reason?: string;
+	/** Concrete blocker preventing completion, when applicable. */
+	blocker?: string;
+	/** Suggested follow-up for this item. */
+	nextStep?: string;
+}
+
+/** Structured JSON output from a flow run. */
+export interface FlowStructuredOutput {
+	/** Schema version for forward compatibility. */
+	version: string;
+	/** Overall completion status. */
+	status: "complete" | "partial" | "blocked" | "failed";
+	/** 1–3 sentence summary of what was accomplished. */
+	summary: string;
+	/** Files touched, read, or referenced. */
+	files: FileEntry[];
+	/** Actions performed or attempted. */
+	actions: Action[];
+	/** Commands or tool calls executed during the flow. */
+	commands: CommandEntry[];
+	/** Incomplete, skipped, blocked, or deferred work. */
+	notDone: NotDoneItem[];
+	/** Recommended next steps or follow-up flows. */
+	nextSteps: string[];
+	/** Reasoning chains, hypotheses, inferences made during the flow. */
+	reasoning: string[];
+	/** Observations, warnings, caveats, side notes. */
+	notes: string[];
+	/** Escape hatch for flow-specific data (audit findings, debug root cause, etc.). */
+	extensions?: Record<string, unknown>;
+}
+
 /** Result of a single flow invocation. */
 export interface SingleResult {
 	type: string;
@@ -32,6 +128,10 @@ export interface SingleResult {
 	stopReason?: string;
 	errorMessage?: string;
 	sawAgentEnd?: boolean;
+	/** Live in-progress text for status rendering; not part of the final flow report. */
+	streamingText?: string;
+	/** Structured JSON output parsed from the flow's final response. */
+	structuredOutput?: FlowStructuredOutput;
 }
 
 /** Metadata attached to every tool result for rendering. */

package/config.ts

@@ -1,102 +0,0 @@
-/**
- * Load flow tier model configuration from Pi settings files.
- *
- * Reads global (~/.pi/agent/settings.json) and project (.pi/settings.json)
- * settings, with project overriding global for flowModels.
- */
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-export interface FlowModelConfig {
-	lite?: string;
-	flash?: string;
-	full?: string;
-}
-
-export interface FlowSettings {
-	toolOptimize?: boolean;
-}
-
-function readSettingsJson(filePath: string): Record<string, unknown> | null {
-	try {
-		const content = fs.readFileSync(filePath, "utf-8");
-		return JSON.parse(content) as Record<string, unknown>;
-	} catch {
-		return null;
-	}
-}
-
-function extractFlowModels(settings: Record<string, unknown> | null): FlowModelConfig {
-	if (!settings) return {};
-	const flowModels = settings.flowModels;
-	if (!flowModels || typeof flowModels !== "object" || Array.isArray(flowModels)) {
-		return {};
-	}
-	const obj = flowModels as Record<string, unknown>;
-	const result: FlowModelConfig = {};
-	for (const key of ["lite", "flash", "full"] as const) {
-		if (typeof obj[key] === "string") {
-			result[key] = obj[key] as string;
-		}
-	}
-	return result;
-}
-
-function extractFlowSettings(settings: Record<string, unknown> | null): FlowSettings {
-	if (!settings) return {};
-	const flowSettings = settings.flowSettings;
-	if (!flowSettings || typeof flowSettings !== "object" || Array.isArray(flowSettings)) {
-		return {};
-	}
-	const obj = flowSettings as Record<string, unknown>;
-	const result: FlowSettings = {};
-	if (typeof obj.toolOptimize === "boolean") {
-		result.toolOptimize = obj.toolOptimize;
-	}
-	return result;
-}
-
-function getGlobalSettingsPath(): string {
-	const agentDir = process.env["PI_CODING_AGENT_DIR"]?.trim() || path.join(os.homedir(), ".pi", "agent");
-	return path.join(agentDir, "settings.json");
-}
-
-function getProjectSettingsPath(cwd: string): string {
-	return path.join(cwd, ".pi", "settings.json");
-}
-
-/**
- * Load flowModels from global and project settings.json.
- * Project overrides global (shallow merge per key).
- */
-export function loadFlowModels(cwd: string): FlowModelConfig {
-	const globalSettings = readSettingsJson(getGlobalSettingsPath());
-	const globalModels = extractFlowModels(globalSettings);
-
-	const projectSettings = readSettingsJson(getProjectSettingsPath(cwd));
-	const projectModels = extractFlowModels(projectSettings);
-
-	return {
-		...globalModels,
-		...projectModels,
-	};
-}
-
-/**
- * Load flowSettings from global and project settings.json.
- * Project overrides global (shallow merge per key).
- */
-export function loadFlowSettings(cwd: string): FlowSettings {
-	const globalSettings = readSettingsJson(getGlobalSettingsPath());
-	const globalFlowSettings = extractFlowSettings(globalSettings);
-
-	const projectSettings = readSettingsJson(getProjectSettingsPath(cwd));
-	const projectFlowSettings = extractFlowSettings(projectSettings);
-
-	return {
-		...globalFlowSettings,
-		...projectFlowSettings,
-	};
-}

package/runner-cli.js

@@ -1,254 +0,0 @@
-/**
- * Helpers for inheriting selected parent CLI flags in child flow processes.
- */
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-function looksLikeExplicitRelativePath(value) {
-  return (
-    value.startsWith("./") ||
-    value.startsWith("../") ||
-    value.startsWith(".\\") ||
-    value.startsWith("..\\")
-  );
-}
-
-function resolvePathArg(value, options = {}) {
-  const { allowPackageSource = false, alwaysResolveRelative = false } = options;
-  if (!value) return value;
-  if (allowPackageSource && (value.startsWith("npm:") || value.startsWith("git:"))) return value;
-  if (value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
-  if (path.isAbsolute(value)) return value;
-
-  const resolved = path.resolve(process.cwd(), value);
-  if (
-    alwaysResolveRelative ||
-    looksLikeExplicitRelativePath(value) ||
-    path.extname(value) !== "" ||
-    fs.existsSync(resolved)
-  ) {
-    return resolved;
-  }
-  return value;
-}
-
-/**
- * Parse process.argv into groups used for child flow invocations.
- *
- * - extensionArgs: forwarded with path resolution
- * - alwaysProxy: forwarded verbatim to every child
- * - fallbackModel/thinking/tools: used only when the flow file does not set them
- */
-export function parseFlowCliArgs(argv) {
-  const extensionArgs = [];
-  const alwaysProxy = [];
-  let fallbackModel;
-  let fallbackThinking;
-  let fallbackTools;
-  let fallbackNoTools = false;
-  let tieredLiteModel;
-  let tieredFlashModel;
-  let tieredFullModel;
-
-  let i = 2; // skip executable + script name
-  while (i < argv.length) {
-    const raw = argv[i];
-    if (!raw.startsWith("-")) {
-      i++;
-      continue;
-    }
-
-    const eqIdx = raw.indexOf("=");
-    const flagName = eqIdx !== -1 ? raw.slice(0, eqIdx) : raw;
-    const inlineValue = eqIdx !== -1 ? raw.slice(eqIdx + 1) : undefined;
-
-    const nextToken = argv[i + 1];
-    const nextIsValue = nextToken !== undefined && !nextToken.startsWith("-");
-
-    const getValue = () => {
-      if (inlineValue !== undefined) return [inlineValue, 1];
-      if (nextIsValue) return [nextToken, 2];
-      return [undefined, 1];
-    };
-
-    if (
-      [
-        "--mode",
-        "--session",
-        "--append-system-prompt",
-        "--export",
-        "--flow-max-depth",
-      ].includes(flagName)
-    ) {
-      const [, skip] = getValue();
-      i += skip;
-      continue;
-    }
-
-    if (["--flow-prevent-cycles", "--list-models"].includes(flagName)) {
-      const [, skip] = getValue();
-      i += skip;
-      continue;
-    }
-
-    if (
-      [
-        "--print",
-        "-p",
-        "--no-session",
-        "--continue",
-        "-c",
-        "--resume",
-        "-r",
-        "--offline",
-        "--help",
-        "-h",
-        "--version",
-        "-v",
-        "--no-flow-prevent-cycles",
-      ].includes(flagName)
-    ) {
-      i++;
-      continue;
-    }
-
-    if (flagName === "--no-extensions" || flagName === "-ne") {
-      extensionArgs.push(flagName);
-      i++;
-      continue;
-    }
-
-    if (flagName === "--extension" || flagName === "-e") {
-      const [value, skip] = getValue();
-      if (value !== undefined) {
-        extensionArgs.push(flagName, resolvePathArg(value, { allowPackageSource: true }));
-      }
-      i += skip;
-      continue;
-    }
-
-    if (["--skill", "--prompt-template", "--theme"].includes(flagName)) {
-      const [value, skip] = getValue();
-      if (value !== undefined) alwaysProxy.push(flagName, resolvePathArg(value));
-      i += skip;
-      continue;
-    }
-
-    if (flagName === "--session-dir") {
-      const [value, skip] = getValue();
-      if (value !== undefined) {
-        alwaysProxy.push(flagName, resolvePathArg(value, { alwaysResolveRelative: true }));
-      }
-      i += skip;
-      continue;
-    }
-
-    if (
-      [
-        "--provider",
-        "--api-key",
-        "--system-prompt",
-        "--models",
-      ].includes(flagName)
-    ) {
-      const [value, skip] = getValue();
-      if (value !== undefined) alwaysProxy.push(flagName, value);
-      i += skip;
-      continue;
-    }
-
-    if (
-      [
-        "--no-skills",
-        "-ns",
-        "--no-prompt-templates",
-        "-np",
-        "--no-themes",
-        "--verbose",
-      ].includes(flagName)
-    ) {
-      alwaysProxy.push(flagName);
-      i++;
-      continue;
-    }
-
-    if (flagName === "--model") {
-      const [value, skip] = getValue();
-      if (value !== undefined) fallbackModel = value;
-      i += skip;
-      continue;
-    }
-
-    if (flagName === "--thinking") {
-      const [value, skip] = getValue();
-      if (value !== undefined) fallbackThinking = value;
-      i += skip;
-      continue;
-    }
-
-    if (flagName === "--tools") {
-      const [value, skip] = getValue();
-      if (value !== undefined) fallbackTools = value;
-      i += skip;
-      continue;
-    }
-
-    if (flagName === "--no-tools") {
-      fallbackNoTools = true;
-      i++;
-      continue;
-    }
-
-    if (flagName === "--flow-lite-model") {
-      const [value, skip] = getValue();
-      if (value !== undefined) tieredLiteModel = value;
-      i += skip;
-      continue;
-    }
-
-    if (flagName === "--flow-flash-model") {
-      const [value, skip] = getValue();
-      if (value !== undefined) tieredFlashModel = value;
-      i += skip;
-      continue;
-    }
-
-    if (flagName === "--flow-full-model") {
-      const [value, skip] = getValue();
-      if (value !== undefined) tieredFullModel = value;
-      i += skip;
-      continue;
-    }
-
-    if (inlineValue !== undefined) {
-      alwaysProxy.push(flagName, inlineValue);
-      i++;
-      continue;
-    }
-
-    if (nextIsValue) {
-      alwaysProxy.push(flagName, nextToken);
-      i += 2;
-      continue;
-    }
-
-    alwaysProxy.push(flagName);
-    i++;
-  }
-
-  return {
-    extensionArgs,
-    alwaysProxy,
-    fallbackModel,
-    fallbackThinking,
-    fallbackTools,
-    fallbackNoTools,
-    tieredModels: {
-      lite: tieredLiteModel,
-      flash: tieredFlashModel,
-      full: tieredFullModel,
-    },
-  };
-}