pi-agent-flow 1.1.0 → 1.2.2

package/src/cli-args.ts

@@ -0,0 +1,283 @@
+/**
+ * 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: string): boolean {
+	return (
+		value.startsWith("./") ||
+		value.startsWith("../") ||
+		value.startsWith(".\\") ||
+		value.startsWith("..\\")
+	);
+}
+
+interface ResolvePathOptions {
+	allowPackageSource?: boolean;
+	alwaysResolveRelative?: boolean;
+}
+
+function resolvePathArg(value: string, options: ResolvePathOptions = {}): string {
+	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;
+}
+
+export interface ParsedFlowCliArgs {
+	extensionArgs: string[];
+	alwaysProxy: string[];
+	fallbackModel?: string;
+	fallbackThinking?: string;
+	fallbackTools?: string;
+	fallbackNoTools: boolean;
+	flowModelConfig?: string;
+	tieredModels: {
+		lite?: string;
+		flash?: string;
+		full?: string;
+	};
+}
+
+/**
+ * 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: string[]): ParsedFlowCliArgs {
+	const extensionArgs: string[] = [];
+	const alwaysProxy: string[] = [];
+	let fallbackModel: string | undefined;
+	let fallbackThinking: string | undefined;
+	let fallbackTools: string | undefined;
+	let fallbackNoTools = false;
+	let flowModelConfig: string | undefined;
+	let tieredLiteModel: string | undefined;
+	let tieredFlashModel: string | undefined;
+	let tieredFullModel: string | undefined;
+
+	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 = (): [string | undefined, number] => {
+			if (inlineValue !== undefined) return [inlineValue, 1];
+			if (nextIsValue) return [nextToken, 2];
+			return [undefined, 1];
+		};
+
+		if (flagName === "--flow-model-config") {
+			const [value, skip] = getValue();
+			if (value !== undefined) flowModelConfig = value;
+			i += skip;
+			continue;
+		}
+
+		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,
+		flowModelConfig,
+		tieredModels: {
+			lite: tieredLiteModel,
+			flash: tieredFlashModel,
+			full: tieredFullModel,
+		},
+	};
+}

package/src/config.ts

@@ -0,0 +1,310 @@
+/**
+ * Load flow model strategy configuration from Pi settings files.
+ *
+ * Reads global (~/.pi/agent/settings.json) and project (.pi/settings.json)
+ * settings, with project overriding global for flowModelConfigs.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type FlowTier = "lite" | "flash" | "full";
+
+export interface FlowModelTierConfig {
+	primary?: string;
+	failover?: string[];
+}
+
+export type FlowModelStrategy = Partial<Record<FlowTier, FlowModelTierConfig>>;
+export type FlowModelConfigs = Record<string, FlowModelStrategy>;
+
+export interface LoadedFlowModelConfigs {
+	selectedName: string;
+	configs: FlowModelConfigs;
+	strategy: FlowModelStrategy;
+}
+
+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 = {
+	default: {},
+};
+
+const FLOW_TIERS: FlowTier[] = ["lite", "flash", "full"];
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+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 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");
+}
+
+function extractSelectedFlowModelConfigName(settings: Record<string, unknown> | null): string | undefined {
+	if (!isPlainObject(settings)) return undefined;
+	const raw = settings.flowModelConfig;
+	if (typeof raw !== "string") return undefined;
+	const normalized = raw.trim();
+	return normalized.length > 0 ? normalized : undefined;
+}
+
+function normalizeFailoverList(
+	value: unknown,
+	sourceLabel: string,
+	strategyName: string,
+	tier: FlowTier,
+): string[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) {
+		console.warn(
+			`[pi-agent-flow] Ignoring invalid ${sourceLabel}.flowModelConfigs.${strategyName}.${tier}.failover. Expected an array of strings.`,
+		);
+		return undefined;
+	}
+
+	const result: string[] = [];
+	for (const item of value) {
+		if (typeof item !== "string") {
+			console.warn(
+				`[pi-agent-flow] Ignoring invalid failover entry in ${sourceLabel}.flowModelConfigs.${strategyName}.${tier}. Expected a string.`,
+			);
+			continue;
+		}
+		const normalized = item.trim();
+		if (!normalized) continue;
+		result.push(normalized);
+	}
+	return result;
+}
+
+function extractFlowModelConfigs(settings: Record<string, unknown> | null, sourceLabel: string): FlowModelConfigs {
+	if (!isPlainObject(settings)) return {};
+	const rawConfigs = settings.flowModelConfigs;
+	if (rawConfigs === undefined) return {};
+	if (!isPlainObject(rawConfigs)) {
+		console.warn(
+			`[pi-agent-flow] Ignoring invalid ${sourceLabel}.flowModelConfigs. Expected an object map of strategy names.`,
+		);
+		return {};
+	}
+
+	const result: FlowModelConfigs = {};
+	for (const [rawName, rawStrategy] of Object.entries(rawConfigs)) {
+		const name = rawName.trim();
+		if (!name) {
+			console.warn(
+				`[pi-agent-flow] Ignoring empty strategy name in ${sourceLabel}.flowModelConfigs.`,
+			);
+			continue;
+		}
+		if (!isPlainObject(rawStrategy)) {
+			console.warn(
+				`[pi-agent-flow] Ignoring invalid ${sourceLabel}.flowModelConfigs.${name}. Expected an object with lite/flash/full tiers.`,
+			);
+			continue;
+		}
+
+		const strategy: FlowModelStrategy = {};
+		for (const tier of FLOW_TIERS) {
+			const rawTier = rawStrategy[tier];
+			if (rawTier === undefined) continue;
+			if (!isPlainObject(rawTier)) {
+				console.warn(
+					`[pi-agent-flow] Ignoring invalid ${sourceLabel}.flowModelConfigs.${name}.${tier}. Expected { primary?: string, failover?: string[] }.`,
+				);
+				continue;
+			}
+
+			const tierConfig: FlowModelTierConfig = {};
+			if (typeof rawTier.primary === "string") {
+				const primary = rawTier.primary.trim();
+				if (primary) tierConfig.primary = primary;
+			} else if (rawTier.primary !== undefined) {
+				console.warn(
+					`[pi-agent-flow] Ignoring invalid ${sourceLabel}.flowModelConfigs.${name}.${tier}.primary. Expected a string.`,
+				);
+			}
+
+			const failover = normalizeFailoverList(rawTier.failover, sourceLabel, name, tier);
+			if (failover !== undefined) {
+				tierConfig.failover = failover;
+			}
+
+			if (tierConfig.primary !== undefined || tierConfig.failover !== undefined) {
+				strategy[tier] = tierConfig;
+			}
+		}
+
+		result[name] = strategy;
+	}
+
+	return result;
+}
+
+function extractFlowSettings(settings: Record<string, unknown> | null): FlowSettings {
+	if (!settings || typeof settings !== "object" || Array.isArray(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;
+	}
+	if (typeof obj.structuredOutput === "boolean") {
+		result.structuredOutput = obj.structuredOutput;
+	}
+	return result;
+}
+
+function mergeFlowModelTierConfigs(
+	base: FlowModelTierConfig | undefined,
+	override: FlowModelTierConfig | undefined,
+): FlowModelTierConfig | undefined {
+	if (!base && !override) return undefined;
+	return {
+		...(base?.primary !== undefined ? { primary: base.primary } : {}),
+		...(base?.failover !== undefined ? { failover: base.failover } : {}),
+		...(override?.primary !== undefined ? { primary: override.primary } : {}),
+		...(override?.failover !== undefined ? { failover: override.failover } : {}),
+	};
+}
+
+function mergeFlowModelStrategies(
+	base: FlowModelStrategy | undefined,
+	override: FlowModelStrategy | undefined,
+): FlowModelStrategy {
+	const result: FlowModelStrategy = {};
+	for (const tier of FLOW_TIERS) {
+		const merged = mergeFlowModelTierConfigs(base?.[tier], override?.[tier]);
+		if (merged) result[tier] = merged;
+	}
+	return result;
+}
+
+function mergeFlowModelConfigs(...configs: FlowModelConfigs[]): FlowModelConfigs {
+	const result: FlowModelConfigs = {};
+	for (const configSet of configs) {
+		for (const [name, strategy] of Object.entries(configSet)) {
+			result[name] = mergeFlowModelStrategies(result[name], strategy);
+		}
+	}
+	return result;
+}
+
+/**
+ * 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,
+	};
+}
+
+export function selectFlowModelStrategy(
+	configs: FlowModelConfigs,
+	requestedName?: string,
+): LoadedFlowModelConfigs {
+	const normalizedRequested = requestedName?.trim() || "default";
+	const strategy = configs[normalizedRequested];
+	if (strategy) {
+		return { selectedName: normalizedRequested, configs, strategy };
+	}
+
+	if (normalizedRequested !== "default") {
+		console.warn(
+			`[pi-agent-flow] Flow model config "${normalizedRequested}" not found. Falling back to "default".`,
+		);
+	}
+	return {
+		selectedName: "default",
+		configs,
+		strategy: configs.default ?? {},
+	};
+}
+
+/**
+ * Load flow model configs from global and project settings.json.
+ * Project overrides global (shallow merge per strategy/tier).
+ */
+export function loadFlowModelConfigs(cwd: string): LoadedFlowModelConfigs {
+	const globalSettings = readSettingsJson(getGlobalSettingsPath());
+	const globalConfigs = extractFlowModelConfigs(globalSettings, "global");
+
+	const projectSettings = readSettingsJson(getProjectSettingsPath(cwd));
+	const projectConfigs = extractFlowModelConfigs(projectSettings, "project");
+
+	const configs = mergeFlowModelConfigs(BUILTIN_FLOW_MODEL_CONFIGS, globalConfigs, projectConfigs);
+	const requestedName =
+		extractSelectedFlowModelConfigName(projectSettings) ??
+		extractSelectedFlowModelConfigName(globalSettings) ??
+		"default";
+
+	return selectFlowModelStrategy(configs, requestedName);
+}
+
+export function resolveFlowModelCandidates(opts: {
+	tier: FlowTier;
+	flowModel?: string;
+	cliTierOverride?: string;
+	strategy: FlowModelStrategy;
+	fallbackModel?: string;
+}): { primary: string | undefined; candidates: string[] } {
+	const unique = new Set<string>();
+	const candidates: string[] = [];
+
+	const add = (value: string | undefined) => {
+		if (!value) return;
+		const normalized = value.trim();
+		if (!normalized || unique.has(normalized)) return;
+		unique.add(normalized);
+		candidates.push(normalized);
+	};
+
+	if (opts.flowModel) {
+		add(opts.flowModel);
+		return { primary: candidates[0], candidates };
+	}
+
+	if (opts.cliTierOverride) {
+		add(opts.cliTierOverride);
+		return { primary: candidates[0], candidates };
+	}
+
+	const tierConfig = opts.strategy[opts.tier];
+	add(tierConfig?.primary);
+	for (const model of tierConfig?.failover ?? []) add(model);
+	add(opts.fallbackModel);
+
+	return { primary: candidates[0], candidates };
+}