singularity-forge/packages/coding-agent/src/main.ts

/**
 * Main entry point for the coding agent CLI.
 *
 * This file handles CLI argument parsing and translates them into
 * createAgentSession() options. The SDK does the heavy lifting.
 */

import { createInterface } from "node:readline";
import {
	type ImageContent,
	modelsAreEqual,
	supportsXhigh,
} from "@singularity-forge/ai";
import chalk from "chalk";
import {
	type Args,
	type ExtensionFlagParseOptions,
	parseArgs,
	printHelp,
} from "./cli/args.js";
import { selectConfig } from "./cli/config-selector.js";
import { processFileArguments } from "./cli/file-processor.js";
import { discoverAndPrintModels, listModels } from "./cli/list-models.js";
import { selectSession } from "./cli/session-picker.js";
import { APP_NAME, getAgentDir, getModelsPath, VERSION } from "./config.js";
import { AuthStorage } from "./core/auth-storage.js";
import { exportFromFile } from "./core/export-html/index.js";
import type { LoadExtensionsResult } from "./core/extensions/index.js";
import { KeybindingsManager } from "./core/keybindings.js";
import { ModelRegistry } from "./core/model-registry.js";
import {
	resolveCliModel,
	resolveModelScope,
	type ScopedModel,
} from "./core/model-resolver.js";
import { runPackageCommand } from "./core/package-commands.js";
import { DefaultPackageManager } from "./core/package-manager.js";
import { DefaultResourceLoader } from "./core/resource-loader.js";
import {
	type CreateAgentSessionOptions,
	createAgentSession,
} from "./core/sdk.js";
import { SessionManager } from "./core/session-manager.js";
import { SettingsManager } from "./core/settings-manager.js";
import { printTimings, time } from "./core/timings.js";
import { allTools } from "./core/tools/index.js";
import { runMigrations, showDeprecationWarnings } from "./migrations.js";
import { InteractiveMode, runPrintMode, runRpcMode } from "./modes/index.js";
import {
	initTheme,
	stopThemeWatcher,
} from "./modes/interactive/theme/theme.js";

/**
 * Read all content from piped stdin.
 * Returns undefined if stdin is a TTY (interactive terminal).
 */
async function readPipedStdin(): Promise<string | undefined> {
	// If stdin is a TTY, we're running interactively - don't read stdin
	if (process.stdin.isTTY) {
		return undefined;
	}

	return new Promise((resolve) => {
		let data = "";
		process.stdin.setEncoding("utf8");
		process.stdin.on("data", (chunk) => {
			data += chunk;
		});
		process.stdin.on("end", () => {
			resolve(data.trim() || undefined);
		});
		process.stdin.resume();
	});
}

function reportSettingsErrors(
	settingsManager: SettingsManager,
	context: string,
): void {
	const errors = settingsManager.drainErrors();
	for (const { scope, error } of errors) {
		console.error(
			chalk.yellow(`Warning (${context}, ${scope} settings): ${error.message}`),
		);
		if (error.stack) {
			console.error(chalk.dim(error.stack));
		}
	}
}

function isTruthyEnvFlag(value: string | undefined): boolean {
	if (!value) return false;
	return (
		value === "1" ||
		value.toLowerCase() === "true" ||
		value.toLowerCase() === "yes"
	);
}

async function prepareInitialMessage(
	parsed: Args,
	autoResizeImages: boolean,
): Promise<{
	initialMessage?: string;
	initialImages?: ImageContent[];
}> {
	if (parsed.fileArgs.length === 0) {
		return {};
	}

	const { text, images } = await processFileArguments(parsed.fileArgs, {
		autoResizeImages,
	});

	let initialMessage: string;
	if (parsed.messages.length > 0) {
		initialMessage = text + parsed.messages[0];
		parsed.messages.shift();
	} else {
		initialMessage = text;
	}

	return {
		initialMessage,
		initialImages: images.length > 0 ? images : undefined,
	};
}

/** Result from resolving a session argument */
type ResolvedSession =
	| { type: "path"; path: string } // Direct file path
	| { type: "local"; path: string } // Found in current project
	| { type: "global"; path: string; cwd: string } // Found in different project
	| { type: "not_found"; arg: string }; // Not found anywhere

/**
 * Resolve a session argument to a file path.
 * If it looks like a path, use as-is. Otherwise try to match as session ID prefix.
 */
async function resolveSessionPath(
	sessionArg: string,
	cwd: string,
	sessionDir?: string,
): Promise<ResolvedSession> {
	// If it looks like a file path, use as-is
	if (
		sessionArg.includes("/") ||
		sessionArg.includes("\\") ||
		sessionArg.endsWith(".jsonl")
	) {
		return { type: "path", path: sessionArg };
	}

	// Try to match as session ID in current project first
	const localSessions = await SessionManager.list(cwd, sessionDir);
	const localMatches = localSessions.filter((s) => s.id.startsWith(sessionArg));

	if (localMatches.length >= 1) {
		return { type: "local", path: localMatches[0].path };
	}

	// Try global search across all projects
	const allSessions = await SessionManager.listAll();
	const globalMatches = allSessions.filter((s) => s.id.startsWith(sessionArg));

	if (globalMatches.length >= 1) {
		const match = globalMatches[0];
		return { type: "global", path: match.path, cwd: match.cwd };
	}

	// Not found anywhere
	return { type: "not_found", arg: sessionArg };
}

/** Prompt user for yes/no confirmation */
async function promptConfirm(message: string): Promise<boolean> {
	return new Promise((resolve) => {
		const rl = createInterface({
			input: process.stdin,
			output: process.stdout,
		});
		rl.question(`${message} [y/N] `, (answer) => {
			rl.close();
			resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
		});
	});
}

/** Helper to call CLI-only session_directory handlers before the initial session manager is created */
async function callSessionDirectoryHook(
	extensions: LoadExtensionsResult,
	cwd: string,
): Promise<string | undefined> {
	let customSessionDir: string | undefined;

	for (const ext of extensions.extensions) {
		const handlers = ext.handlers.get("session_directory");
		if (!handlers || handlers.length === 0) continue;

		for (const handler of handlers) {
			try {
				const event = { type: "session_directory" as const, cwd };
				const result = (await handler(event)) as
					| { sessionDir?: string }
					| undefined;

				if (result?.sessionDir) {
					customSessionDir = result.sessionDir;
				}
			} catch (err) {
				const message = err instanceof Error ? err.message : String(err);
				console.error(
					chalk.red(
						`Extension "${ext.path}" session_directory handler failed: ${message}`,
					),
				);
			}
		}
	}

	return customSessionDir;
}

async function createSessionManager(
	parsed: Args,
	cwd: string,
	extensions: LoadExtensionsResult,
): Promise<SessionManager | undefined> {
	if (parsed.noSession) {
		return SessionManager.inMemory();
	}

	// CLI flag takes precedence, otherwise ask extensions for custom session directory
	let effectiveSessionDir = parsed.sessionDir;
	if (!effectiveSessionDir) {
		effectiveSessionDir = await callSessionDirectoryHook(extensions, cwd);
	}

	if (parsed.session) {
		const resolved = await resolveSessionPath(
			parsed.session,
			cwd,
			effectiveSessionDir,
		);

		switch (resolved.type) {
			case "path":
			case "local":
				return SessionManager.open(resolved.path, effectiveSessionDir);

			case "global": {
				// Session found in different project - ask user if they want to fork
				console.log(
					chalk.yellow(`Session found in different project: ${resolved.cwd}`),
				);
				const shouldFork = await promptConfirm(
					"Fork this session into current directory?",
				);
				if (!shouldFork) {
					console.log(chalk.dim("Aborted."));
					process.exit(0);
				}
				return SessionManager.forkFrom(resolved.path, cwd, effectiveSessionDir);
			}

			case "not_found":
				console.error(chalk.red(`No session found matching '${resolved.arg}'`));
				process.exit(1);
		}
	}
	if (parsed.continue) {
		return SessionManager.continueRecent(cwd, effectiveSessionDir);
	}
	// --resume is handled separately (needs picker UI)
	// If effective session dir is set, create new session there
	if (effectiveSessionDir) {
		return SessionManager.create(cwd, effectiveSessionDir);
	}
	// Default case (new session) returns undefined, SDK will create one
	return undefined;
}

async function runStartupFlagHandlers(
	extensions: LoadExtensionsResult,
	parsed: Args,
	context: {
		cwd: string;
		agentDir: string;
		authStorage: AuthStorage;
		modelRegistry: ModelRegistry;
	},
): Promise<boolean> {
	let handledStartup = false;

	for (const extension of extensions.extensions) {
		for (const [flagName, flag] of extension.flags) {
			const flagValue = parsed.unknownFlags.get(flagName);
			if (flagValue === undefined || !flag.onStartup) {
				continue;
			}

			await flag.onStartup(flagValue, context);
			handledStartup = true;
		}
	}

	return handledStartup;
}

function buildSessionOptions(
	parsed: Args,
	scopedModels: ScopedModel[],
	sessionManager: SessionManager | undefined,
	modelRegistry: ModelRegistry,
	settingsManager: SettingsManager,
): { options: CreateAgentSessionOptions; cliThinkingFromModel: boolean } {
	const options: CreateAgentSessionOptions = {};
	let cliThinkingFromModel = false;

	if (sessionManager) {
		options.sessionManager = sessionManager;
	}

	// Model from CLI
	// - supports --provider <name> --model <pattern>
	// - supports --model <provider>/<pattern>
	if (parsed.model) {
		const resolved = resolveCliModel({
			cliProvider: parsed.provider,
			cliModel: parsed.model,
			modelRegistry,
		});
		if (resolved.warning) {
			console.warn(chalk.yellow(`Warning: ${resolved.warning}`));
		}
		if (resolved.error) {
			console.error(chalk.red(resolved.error));
			process.exit(1);
		}
		if (resolved.model) {
			options.model = resolved.model;
			// Allow "--model <pattern>:<thinking>" as a shorthand.
			// Explicit --thinking still takes precedence (applied later).
			if (!parsed.thinking && resolved.thinkingLevel) {
				options.thinkingLevel = resolved.thinkingLevel;
				cliThinkingFromModel = true;
			}
		}
	}

	if (
		!options.model &&
		scopedModels.length > 0 &&
		!parsed.continue &&
		!parsed.resume
	) {
		// Check if saved default is in scoped models - use it if so, otherwise first scoped model
		const savedProvider = settingsManager.getDefaultProvider();
		const savedModelId = settingsManager.getDefaultModel();
		const savedModel =
			savedProvider && savedModelId
				? modelRegistry.find(savedProvider, savedModelId)
				: undefined;
		const savedInScope = savedModel
			? scopedModels.find((sm) => modelsAreEqual(sm.model, savedModel))
			: undefined;

		if (savedInScope) {
			options.model = savedInScope.model;
			// Use thinking level from scoped model config if explicitly set
			if (!parsed.thinking && savedInScope.thinkingLevel) {
				options.thinkingLevel = savedInScope.thinkingLevel;
			}
		} else {
			options.model = scopedModels[0].model;
			// Use thinking level from first scoped model if explicitly set
			if (!parsed.thinking && scopedModels[0].thinkingLevel) {
				options.thinkingLevel = scopedModels[0].thinkingLevel;
			}
		}
	}

	// Thinking level from CLI (takes precedence over scoped model thinking levels set above)
	if (parsed.thinking) {
		options.thinkingLevel = parsed.thinking;
	}

	// Scoped models for Ctrl+P cycling
	// Keep thinking level undefined when not explicitly set in the model pattern.
	// Undefined means "inherit current session thinking level" during cycling.
	if (scopedModels.length > 0) {
		options.scopedModels = scopedModels.map((sm) => ({
			model: sm.model,
			thinkingLevel: sm.thinkingLevel,
		}));
	}

	// API key from CLI - set in authStorage
	// (handled by caller before createAgentSession)

	// Tools
	if (parsed.noTools) {
		// --no-tools: start with no built-in tools
		// --tools can still add specific ones back
		if (parsed.tools && parsed.tools.length > 0) {
			options.tools = parsed.tools.map((name) => allTools[name]);
		} else {
			options.tools = [];
		}
	} else if (parsed.tools) {
		options.tools = parsed.tools.map((name) => allTools[name]);
	}

	return { options, cliThinkingFromModel };
}

async function handleConfigCommand(args: string[]): Promise<boolean> {
	if (args[0] !== "config") {
		return false;
	}

	const cwd = process.cwd();
	const agentDir = getAgentDir();
	const settingsManager = SettingsManager.create(cwd, agentDir);
	reportSettingsErrors(settingsManager, "config command");
	const packageManager = new DefaultPackageManager({
		cwd,
		agentDir,
		settingsManager,
	});

	const resolvedPaths = await packageManager.resolve();

	await selectConfig({
		resolvedPaths,
		settingsManager,
		cwd,
		agentDir,
	});

	process.exit(0);
}

export async function main(args: string[]) {
	// Catch unhandled promise rejections so the process doesn't silently disappear
	process.on("unhandledRejection", (reason) => {
		const message =
			reason instanceof Error
				? (reason.stack ?? reason.message)
				: String(reason);
		console.error(`\nFatal: unhandled promise rejection\n${message}`);
		process.exitCode = 1;
	});

	const offlineMode =
		args.includes("--offline") || isTruthyEnvFlag(process.env.PI_OFFLINE);
	if (offlineMode) {
		process.env.PI_OFFLINE = "1";
		process.env.PI_SKIP_VERSION_CHECK = "1";
	}

	const packageCommand = await runPackageCommand({
		appName: APP_NAME,
		args,
		cwd: process.cwd(),
		agentDir: getAgentDir(),
		stdout: process.stdout,
		stderr: process.stderr,
	});
	if (packageCommand.handled) {
		process.exitCode = packageCommand.exitCode;
		return;
	}

	if (await handleConfigCommand(args)) {
		return;
	}

	// Run migrations (pass cwd for project-local migrations)
	const { migratedAuthProviders: migratedProviders, deprecationWarnings } =
		runMigrations(process.cwd());

	// First pass: parse args to get --extension paths
	const firstPass = parseArgs(args);

	// Early load extensions to discover their CLI flags
	const cwd = process.cwd();
	const agentDir = getAgentDir();
	const settingsManager = SettingsManager.create(cwd, agentDir);
	reportSettingsErrors(settingsManager, "startup");
	const authStorage = AuthStorage.create();
	const modelRegistry = new ModelRegistry(
		authStorage,
		getModelsPath(),
		settingsManager,
	);

	// Offline mode validation / auto-detection
	if (offlineMode) {
		// --offline flag: validate all models are local
		if (!modelRegistry.isAllLocalChain()) {
			const remoteModel = modelRegistry
				.getAll()
				.find((m) => !ModelRegistry.isLocalModel(m));
			if (remoteModel) {
				console.error(
					`Error: --offline requires all configured models to be local. Found remote model: ${remoteModel.name} (${remoteModel.baseUrl || "cloud API"})`,
				);
				process.exit(1);
			}
		}
	} else if (
		modelRegistry.isAllLocalChain() &&
		modelRegistry.getAll().length > 0
	) {
		// Auto-detect: all models are local, enable offline mode
		process.env.PI_OFFLINE = "1";
		process.env.PI_SKIP_VERSION_CHECK = "1";
		console.log(
			"[sf] All configured models are local \u2014 enabling offline mode automatically.",
		);
	}

	const resourceLoader = new DefaultResourceLoader({
		cwd,
		agentDir,
		settingsManager,
		additionalExtensionPaths: firstPass.extensions,
		additionalSkillPaths: firstPass.skills,
		additionalPromptTemplatePaths: firstPass.promptTemplates,
		additionalThemePaths: firstPass.themes,
		noExtensions: firstPass.noExtensions,
		noSkills: firstPass.noSkills || firstPass.bare,
		noPromptTemplates: firstPass.noPromptTemplates || firstPass.bare,
		noThemes: firstPass.noThemes || firstPass.bare,
		systemPrompt: firstPass.systemPrompt,
		appendSystemPrompt: firstPass.appendSystemPrompt,
		// --bare: suppress CLAUDE.md/AGENTS.md ancestor walk
		...(firstPass.bare
			? { agentsFilesOverride: () => ({ agentsFiles: [] }) }
			: {}),
	});
	await resourceLoader.reload();
	time("resourceLoader.reload");

	const extensionsResult: LoadExtensionsResult = resourceLoader.getExtensions();
	for (const { path, error } of extensionsResult.errors) {
		console.error(chalk.red(`Failed to load extension "${path}": ${error}`));
	}

	// Apply pending provider registrations from extensions immediately
	// so they're available for model resolution before AgentSession is created
	for (const { name, config } of extensionsResult.runtime
		.pendingProviderRegistrations) {
		modelRegistry.registerProvider(name, config);
	}
	extensionsResult.runtime.pendingProviderRegistrations = [];

	const extensionFlags = new Map<string, ExtensionFlagParseOptions>();
	for (const ext of extensionsResult.extensions) {
		for (const [name, flag] of ext.flags) {
			extensionFlags.set(name, {
				type: flag.type,
				allowNoValue: flag.allowNoValue,
			});
		}
	}

	// Second pass: parse args with extension flags
	const parsed = parseArgs(args, extensionFlags);

	// Pass flag values to extensions via runtime
	for (const [name, value] of parsed.unknownFlags) {
		extensionsResult.runtime.flagValues.set(name, value);
	}

	if (parsed.version) {
		console.log(VERSION);
		process.exit(0);
	}

	if (parsed.help) {
		printHelp();
		process.exit(0);
	}

	if (parsed.addProvider) {
		const { ModelsJsonWriter } = await import("./core/models-json-writer.js");
		const writer = new ModelsJsonWriter();
		writer.setProvider(parsed.addProvider, {
			baseUrl: parsed.addProviderBaseUrl,
			apiKey: parsed.apiKey,
		});
		console.log(`Provider "${parsed.addProvider}" added to models.json`);
		process.exit(0);
	}

	if (parsed.discoverModels !== undefined) {
		const provider =
			typeof parsed.discoverModels === "string"
				? parsed.discoverModels
				: undefined;
		await discoverAndPrintModels(modelRegistry, provider);
		process.exit(0);
	}

	if (parsed.listModels !== undefined) {
		const searchPattern =
			typeof parsed.listModels === "string" ? parsed.listModels : undefined;
		await listModels(modelRegistry, {
			searchPattern,
			discover: parsed.discover,
		});
		process.exit(0);
	}

	if (
		await runStartupFlagHandlers(extensionsResult, parsed, {
			cwd,
			agentDir,
			authStorage,
			modelRegistry,
		})
	) {
		return;
	}

	// Read piped stdin content (if any) - skip for RPC mode which uses stdin for JSON-RPC
	if (parsed.mode !== "rpc") {
		const stdinContent = await readPipedStdin();
		if (stdinContent !== undefined) {
			// Force print mode since interactive mode requires a TTY for keyboard input
			parsed.print = true;
			// Prepend stdin content to messages
			parsed.messages.unshift(stdinContent);
		}
	}

	if (parsed.export) {
		let result: string;
		try {
			const outputPath =
				parsed.messages.length > 0 ? parsed.messages[0] : undefined;
			result = await exportFromFile(parsed.export, outputPath);
		} catch (error: unknown) {
			const message =
				error instanceof Error ? error.message : "Failed to export session";
			console.error(chalk.red(`Error: ${message}`));
			process.exit(1);
		}
		console.log(`Exported to: ${result}`);
		process.exit(0);
	}

	if (parsed.mode === "rpc" && parsed.fileArgs.length > 0) {
		console.error(
			chalk.red("Error: @file arguments are not supported in RPC mode"),
		);
		process.exit(1);
	}

	const { initialMessage, initialImages } = await prepareInitialMessage(
		parsed,
		settingsManager.getImageAutoResize(),
	);
	const isInteractive = !parsed.print && parsed.mode === undefined;
	const mode = parsed.mode || "text";
	initTheme(settingsManager.getTheme(), isInteractive);

	// Show deprecation warnings in interactive mode
	if (isInteractive && deprecationWarnings.length > 0) {
		await showDeprecationWarnings(deprecationWarnings);
	}

	let scopedModels: ScopedModel[] = [];
	const modelPatterns = parsed.models ?? settingsManager.getEnabledModels();
	if (modelPatterns && modelPatterns.length > 0) {
		scopedModels = await resolveModelScope(modelPatterns, modelRegistry);
	}

	// Create session manager based on CLI flags
	let sessionManager = await createSessionManager(
		parsed,
		cwd,
		extensionsResult,
	);

	// Handle --resume: show session picker
	if (parsed.resume) {
		// Initialize keybindings so session picker respects user config
		KeybindingsManager.create();

		// Compute effective session dir for resume (same logic as createSessionManager)
		const effectiveSessionDir =
			parsed.sessionDir ||
			(await callSessionDirectoryHook(extensionsResult, cwd));

		const selectedPath = await selectSession(
			(onProgress) => SessionManager.list(cwd, effectiveSessionDir, onProgress),
			SessionManager.listAll,
		);
		if (!selectedPath) {
			console.log(chalk.dim("No session selected"));
			stopThemeWatcher();
			process.exit(0);
		}
		sessionManager = SessionManager.open(selectedPath, effectiveSessionDir);
	}

	const { options: sessionOptions, cliThinkingFromModel } = buildSessionOptions(
		parsed,
		scopedModels,
		sessionManager,
		modelRegistry,
		settingsManager,
	);
	sessionOptions.authStorage = authStorage;
	sessionOptions.modelRegistry = modelRegistry;
	sessionOptions.resourceLoader = resourceLoader;
	// Persistence of defaultProvider/defaultModel to settings.json is an
	// interactive-only opt-in. AgentSessionConfig.persistModelChanges defaults
	// to false (#4251) so SDK consumers and one-shot/print/rpc/mcp invocations
	// never silently mutate the global default. Interactive CLI launches
	// explicitly opt in so user model picks still persist.
	sessionOptions.persistModelChanges = isInteractive;

	// Handle CLI --api-key as runtime override (not persisted)
	if (parsed.apiKey) {
		if (!sessionOptions.model) {
			console.error(
				chalk.red(
					"--api-key requires a model to be specified via --model, --provider/--model, or --models",
				),
			);
			process.exit(1);
		}
		authStorage.setRuntimeApiKey(sessionOptions.model.provider, parsed.apiKey);
	}

	const { session, modelFallbackMessage } =
		await createAgentSession(sessionOptions);

	if (!isInteractive && !session.model) {
		console.error(chalk.red("No models available."));
		console.error(chalk.yellow("\nSet an API key environment variable:"));
		console.error(
			"  ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, etc.",
		);
		console.error(chalk.yellow(`\nOr create ${getModelsPath()}`));
		process.exit(1);
	}

	// Clamp thinking level to model capabilities for CLI-provided thinking levels.
	// This covers both --thinking <level> and --model <pattern>:<thinking>.
	const cliThinkingOverride =
		parsed.thinking !== undefined || cliThinkingFromModel;
	if (session.model && cliThinkingOverride) {
		let effectiveThinking = session.thinkingLevel;
		if (!session.model.reasoning) {
			effectiveThinking = "off";
		} else if (effectiveThinking === "xhigh" && !supportsXhigh(session.model)) {
			effectiveThinking = "high";
		}
		if (effectiveThinking !== session.thinkingLevel) {
			session.setThinkingLevel(effectiveThinking);
		}
	}

	if (mode === "rpc") {
		await runRpcMode(session);
	} else if (isInteractive) {
		if (
			scopedModels.length > 0 &&
			(parsed.verbose || !settingsManager.getQuietStartup())
		) {
			const modelList = scopedModels
				.map((sm) => {
					const thinkingStr = sm.thinkingLevel ? `:${sm.thinkingLevel}` : "";
					return `${sm.model.id}${thinkingStr}`;
				})
				.join(", ");
			console.log(
				chalk.dim(
					`Model scope: ${modelList} ${chalk.gray("(Ctrl+P to cycle)")}`,
				),
			);
		}

		printTimings();
		const mode = new InteractiveMode(session, {
			migratedProviders,
			modelFallbackMessage,
			initialMessage,
			initialImages,
			initialMessages: parsed.messages,
			verbose: parsed.verbose,
		});
		await mode.run();
	} else {
		await runPrintMode(session, {
			mode,
			messages: parsed.messages,
			initialMessage,
			initialImages,
		});
		stopThemeWatcher();
		if (process.stdout.writableLength > 0) {
			await new Promise<void>((resolve) =>
				process.stdout.once("drain", resolve),
			);
		}
		process.exit(0);
	}
}