@inkeep/agents-cli 0.50.6 → 0.52.0

package/dist/commands/pull-v4/credential-generator.js

@@ -0,0 +1,30 @@
+import { addValueToObject, createFactoryDefinition, toCamelCase } from "./utils.js";
+import { z } from "zod";
+
+//#region src/commands/pull-v4/credential-generator.ts
+const CredentialSchema = z.object({
+	credentialId: z.string().nonempty(),
+	name: z.string().nonempty(),
+	type: z.string().nonempty(),
+	credentialStoreId: z.string().nonempty(),
+	description: z.string().optional(),
+	retrievalParams: z.unknown().optional()
+});
+function generateCredentialDefinition(data) {
+	const result = CredentialSchema.safeParse(data);
+	if (!result.success) throw new Error(`Validation failed for credential:\n${z.prettifyError(result.error)}`);
+	const parsed = result.data;
+	const { sourceFile, configObject } = createFactoryDefinition({
+		importName: "credential",
+		variableName: toCamelCase(parsed.credentialId)
+	});
+	const { credentialId, ...rest } = parsed;
+	for (const [k, v] of Object.entries({
+		id: credentialId,
+		...rest
+	})) addValueToObject(configObject, k, v);
+	return sourceFile;
+}
+
+//#endregion
+export { generateCredentialDefinition };

package/dist/commands/pull-v4/data-component-generator.js

@@ -0,0 +1,50 @@
+import { addStringProperty, addValueToObject, convertJsonSchemaToZodSafe, createFactoryDefinition, toCamelCase } from "./utils.js";
+import { z } from "zod";
+
+//#region src/commands/pull-v4/data-component-generator.ts
+const DataComponentSchema = z.object({
+	dataComponentId: z.string().nonempty(),
+	name: z.string().nonempty(),
+	description: z.string().nullable().optional(),
+	props: z.unknown().optional(),
+	schema: z.unknown().optional(),
+	render: z.looseObject({
+		component: z.string().optional(),
+		mockData: z.looseObject({}).optional()
+	}).nullable().optional()
+});
+function generateDataComponentDefinition(data) {
+	const result = DataComponentSchema.safeParse(data);
+	if (!result.success) throw new Error(`Validation failed for data component:\n${z.prettifyError(result.error)}`);
+	const parsed = result.data;
+	const props = parsed.props !== void 0 ? parsed.props : parsed.schema;
+	const { sourceFile, configObject } = createFactoryDefinition({
+		importName: "dataComponent",
+		variableName: toCamelCase(parsed.dataComponentId)
+	});
+	if (props !== void 0) sourceFile.addImportDeclaration({
+		namedImports: ["z"],
+		moduleSpecifier: "zod"
+	});
+	writeDataComponentConfig(configObject, parsed, props);
+	return sourceFile;
+}
+function writeDataComponentConfig(configObject, data, props) {
+	addStringProperty(configObject, "id", data.dataComponentId);
+	addStringProperty(configObject, "name", data.name);
+	if (typeof data.description === "string") addStringProperty(configObject, "description", data.description);
+	if (props !== void 0) configObject.addPropertyAssignment({
+		name: "props",
+		initializer: convertJsonSchemaToZodSafe(props)
+	});
+	if (data.render) addRenderProperty(configObject, data.render);
+}
+function addRenderProperty(configObject, render) {
+	if (render.component) addValueToObject(configObject, "render", {
+		component: render.component,
+		mockData: render.mockData
+	});
+}
+
+//#endregion
+export { generateDataComponentDefinition };

package/dist/commands/pull-v4/environment-generator.js

@@ -0,0 +1,123 @@
+import { addStringProperty, createFactoryDefinition, formatInlineLiteral, formatPropertyName, isPlainObject } from "./utils.js";
+import { z } from "zod";
+import { SyntaxKind } from "ts-morph";
+
+//#region src/commands/pull-v4/environment-generator.ts
+const EnvironmentSettingsSchema = z.looseObject({ credentials: z.record(z.string(), z.unknown()).nullable().optional() });
+const EnvironmentIndexSchema = z.array(z.string());
+function generateEnvironmentSettingsImports(environmentData) {
+	const imports = [`import { registerEnvironmentSettings } from '@inkeep/agents-sdk';`];
+	if (needsCredentialStoreType(environmentData)) imports.push(`import { CredentialStoreType } from '@inkeep/agents-core';`);
+	return imports;
+}
+function generateEnvironmentIndexImports(environments) {
+	const result = EnvironmentIndexSchema.safeParse(environments);
+	if (!result.success) throw new Error(`Validation failed for environments index:\n${z.prettifyError(result.error)}`);
+	const imports = [`import { createEnvironmentSettings } from '@inkeep/agents-sdk';`];
+	for (const environmentName of result.data) imports.push(`import { ${environmentName} } from './${environmentName}.env';`);
+	return imports;
+}
+function generateEnvironmentSettingsDefinition(environmentName, environmentData) {
+	const environmentNameResult = z.string().nonempty().safeParse(environmentName);
+	if (!environmentNameResult.success) throw new Error(`Validation failed for environment name:\n${z.prettifyError(environmentNameResult.error)}`);
+	const result = EnvironmentSettingsSchema.safeParse(environmentData);
+	if (!result.success) throw new Error(`Validation failed for environment settings:\n${z.prettifyError(result.error)}`);
+	const parsed = result.data;
+	const { sourceFile, configObject } = createFactoryDefinition({
+		importName: "registerEnvironmentSettings",
+		variableName: environmentNameResult.data
+	});
+	const hasCredentialStoreType = needsCredentialStoreType(parsed);
+	if (hasCredentialStoreType) sourceFile.addImportDeclaration({
+		namedImports: ["CredentialStoreType"],
+		moduleSpecifier: "@inkeep/agents-core"
+	});
+	addCredentialsProperty(configObject, parsed.credentials, hasCredentialStoreType);
+	return sourceFile;
+}
+function generateEnvironmentIndexDefinition(environments) {
+	const result = EnvironmentIndexSchema.safeParse(environments);
+	if (!result.success) throw new Error(`Validation failed for environments index:\n${z.prettifyError(result.error)}`);
+	const { sourceFile, configObject } = createFactoryDefinition({
+		importName: "createEnvironmentSettings",
+		variableName: "envSettings"
+	});
+	for (const environmentName of result.data) sourceFile.addImportDeclaration({
+		namedImports: [environmentName],
+		moduleSpecifier: `./${environmentName}.env`
+	});
+	for (const environmentName of result.data) configObject.addShorthandPropertyAssignment({ name: environmentName });
+	return sourceFile;
+}
+function generateEnvironmentSettingsFile(environmentName, environmentData) {
+	return generateEnvironmentSettingsDefinition(environmentName, environmentData);
+}
+function generateEnvironmentIndexFile(environments) {
+	return generateEnvironmentIndexDefinition(environments);
+}
+function needsCredentialStoreType(environmentData) {
+	if (!isPlainObject(environmentData.credentials)) return false;
+	return Object.values(environmentData.credentials).some((credential) => isPlainObject(credential) && typeof credential.type === "string" && [
+		"memory",
+		"env",
+		"keychain"
+	].includes(credential.type));
+}
+function addCredentialsProperty(configObject, credentials, hasCredentialStoreType) {
+	if (!isPlainObject(credentials) || !Object.keys(credentials).length) {
+		configObject.addPropertyAssignment({
+			name: "credentials",
+			initializer: "{}"
+		});
+		return;
+	}
+	const credentialsObject = configObject.addPropertyAssignment({
+		name: "credentials",
+		initializer: "{}"
+	}).getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+	for (const [credentialKey, credentialValue] of Object.entries(credentials)) {
+		if (!isPlainObject(credentialValue)) continue;
+		writeCredential(credentialsObject.addPropertyAssignment({
+			name: formatPropertyName(credentialKey),
+			initializer: "{}"
+		}).getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression), credentialValue, hasCredentialStoreType);
+	}
+}
+function writeCredential(credentialObject, credentialData, hasCredentialStoreType) {
+	if (credentialData.id !== void 0) addStringProperty(credentialObject, "id", credentialData.id);
+	if (credentialData.name !== void 0 && credentialData.name !== null) addStringProperty(credentialObject, "name", credentialData.name);
+	if (credentialData.type !== void 0) if (hasCredentialStoreType && typeof credentialData.type === "string" && [
+		"memory",
+		"env",
+		"keychain"
+	].includes(credentialData.type)) credentialObject.addPropertyAssignment({
+		name: "type",
+		initializer: `CredentialStoreType.${credentialData.type}`
+	});
+	else credentialObject.addPropertyAssignment({
+		name: "type",
+		initializer: formatInlineLiteral(credentialData.type)
+	});
+	if (credentialData.credentialStoreId !== void 0) addStringProperty(credentialObject, "credentialStoreId", credentialData.credentialStoreId);
+	if (credentialData.description !== void 0 && credentialData.description !== null) addStringProperty(credentialObject, "description", credentialData.description);
+	addRetrievalParams(credentialObject, credentialData.retrievalParams);
+}
+function addRetrievalParams(credentialObject, retrievalParams) {
+	if (!isPlainObject(retrievalParams)) return;
+	const retrievalParamsProperty = credentialObject.addPropertyAssignment({
+		name: "retrievalParams",
+		initializer: "{}"
+	});
+	const retrievalParamsObject = retrievalParamsProperty.getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+	for (const [key, value] of Object.entries(retrievalParams)) {
+		if (value === void 0 || value === null) continue;
+		retrievalParamsObject.addPropertyAssignment({
+			name: formatPropertyName(key),
+			initializer: formatInlineLiteral(value)
+		});
+	}
+	if (!retrievalParamsObject.getProperties().length) retrievalParamsProperty.remove();
+}
+
+//#endregion
+export { generateEnvironmentIndexDefinition, generateEnvironmentIndexFile, generateEnvironmentIndexImports, generateEnvironmentSettingsDefinition, generateEnvironmentSettingsFile, generateEnvironmentSettingsImports };

package/dist/commands/pull-v4/external-agent-generator.js

@@ -0,0 +1,56 @@
+import { addStringProperty, createFactoryDefinition, toCamelCase } from "./utils.js";
+import { z } from "zod";
+import { SyntaxKind } from "ts-morph";
+
+//#region src/commands/pull-v4/external-agent-generator.ts
+const ExternalAgentSchema = z.looseObject({
+	externalAgentId: z.string().nonempty(),
+	name: z.string().nonempty(),
+	description: z.string().nullable().optional(),
+	baseUrl: z.string().nonempty(),
+	credentialReference: z.union([z.string(), z.looseObject({
+		id: z.string().optional(),
+		name: z.string().optional(),
+		description: z.string().optional()
+	})]).optional()
+});
+function generateExternalAgentDefinition(data) {
+	const result = ExternalAgentSchema.safeParse(data);
+	if (!result.success) throw new Error(`Validation failed for external agent:\n${z.prettifyError(result.error)}`);
+	const parsed = result.data;
+	const { sourceFile, configObject } = createFactoryDefinition({
+		importName: "externalAgent",
+		variableName: toCamelCase(parsed.externalAgentId)
+	});
+	if (typeof parsed.credentialReference === "string") sourceFile.addImportDeclaration({
+		namedImports: [toCamelCase(parsed.credentialReference)],
+		moduleSpecifier: `../credentials/${parsed.credentialReference}`
+	});
+	writeExternalAgentConfig(configObject, parsed);
+	return sourceFile;
+}
+function writeExternalAgentConfig(configObject, data) {
+	addStringProperty(configObject, "id", data.externalAgentId);
+	addStringProperty(configObject, "name", data.name);
+	if (data.description !== null && data.description !== void 0) addStringProperty(configObject, "description", data.description);
+	else addStringProperty(configObject, "description", `External agent ${data.externalAgentId}`);
+	addStringProperty(configObject, "baseUrl", data.baseUrl);
+	if (typeof data.credentialReference === "string") {
+		configObject.addPropertyAssignment({
+			name: "credentialReference",
+			initializer: toCamelCase(data.credentialReference)
+		});
+		return;
+	}
+	if (!data.credentialReference) return;
+	const credentialReferenceObject = configObject.addPropertyAssignment({
+		name: "credentialReference",
+		initializer: "{}"
+	}).getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression);
+	if (data.credentialReference.id !== void 0) addStringProperty(credentialReferenceObject, "id", data.credentialReference.id);
+	if (data.credentialReference.name !== void 0) addStringProperty(credentialReferenceObject, "name", data.credentialReference.name);
+	if (data.credentialReference.description !== void 0) addStringProperty(credentialReferenceObject, "description", data.credentialReference.description);
+}
+
+//#endregion
+export { generateExternalAgentDefinition };

package/dist/commands/pull-v4/function-tool-generator.js

@@ -0,0 +1,48 @@
+import { addValueToObject, createFactoryDefinition, toCamelCase } from "./utils.js";
+import { z } from "zod";
+
+//#region src/commands/pull-v4/function-tool-generator.ts
+const FunctionToolSchema = z.looseObject({
+	functionToolId: z.string().nonempty(),
+	name: z.string().nonempty(),
+	description: z.string().optional(),
+	inputSchema: z.unknown().optional(),
+	schema: z.unknown().optional(),
+	executeCode: z.string().optional(),
+	execute: z.string().optional()
+}).superRefine((value, context) => {
+	if (value.inputSchema === void 0 && value.schema === void 0) context.addIssue({
+		code: "custom",
+		message: "inputSchema is required",
+		path: ["inputSchema"]
+	});
+	if (value.executeCode === void 0 && value.execute === void 0) context.addIssue({
+		code: "custom",
+		message: "executeCode is required",
+		path: ["executeCode"]
+	});
+});
+function generateFunctionToolDefinition(data) {
+	const result = FunctionToolSchema.safeParse(data);
+	if (!result.success) throw new Error(`Validation failed for function tool:\n${z.prettifyError(result.error)}`);
+	const parsed = result.data;
+	const { sourceFile, configObject } = createFactoryDefinition({
+		importName: "functionTool",
+		variableName: toCamelCase(parsed.functionToolId)
+	});
+	writeFunctionToolConfig(configObject, parsed);
+	return sourceFile;
+}
+function writeFunctionToolConfig(configObject, { functionToolId, executeCode, inputSchema, schema, ...rest }) {
+	for (const [k, v] of Object.entries({
+		...rest,
+		inputSchema: inputSchema ?? schema
+	})) addValueToObject(configObject, k, v);
+	if (executeCode) configObject.addPropertyAssignment({
+		name: "execute",
+		initializer: executeCode
+	});
+}
+
+//#endregion
+export { generateFunctionToolDefinition };

package/dist/commands/pull-v4/introspect/index.js

@@ -0,0 +1,365 @@
+import { ManagementApiClient } from "../../../api.js";
+import { initializeCommand } from "../../../utils/cli-pipeline.js";
+import { performBackgroundVersionCheck } from "../../../utils/background-version-check.js";
+import { loadProject } from "../../../utils/project-loader.js";
+import { extractSubAgents } from "../../pull-v3/utils/component-registry.js";
+import { introspectGenerate } from "../introspect-generator.js";
+import { join, resolve } from "node:path";
+import * as p from "@clack/prompts";
+import { existsSync, mkdirSync } from "node:fs";
+import { EventEmitter } from "node:events";
+import { styleText } from "node:util";
+
+//#region src/commands/pull-v4/introspect/index.ts
+/**
+* Pull v3 - Clean, efficient project generation
+*
+* Step 1: Validate and compile existing code
+* Step 2: Compare project with DB to detect ALL changes
+* Step 3: Classify changes as new vs modified components
+* Step 4: Generate new components deterministically
+* Step 5: Use LLM to correct modified components
+*/
+EventEmitter.defaultMaxListeners = 20;
+/**
+* Create project directory structure
+*/
+function createProjectStructure(projectRoot) {
+	mkdirSync(projectRoot, { recursive: true });
+	return {
+		projectRoot,
+		agentsDir: join(projectRoot, "agents"),
+		toolsDir: join(projectRoot, "tools"),
+		dataComponentsDir: join(projectRoot, "data-components"),
+		artifactComponentsDir: join(projectRoot, "artifact-components"),
+		statusComponentsDir: join(projectRoot, "status-components"),
+		environmentsDir: join(projectRoot, "environments"),
+		credentialsDir: join(projectRoot, "credentials"),
+		contextConfigsDir: join(projectRoot, "context-configs"),
+		externalAgentsDir: join(projectRoot, "external-agents"),
+		skillsDir: join(projectRoot, "skills")
+	};
+}
+/**
+* Enrich canDelegateTo references with component type information
+*/
+function enrichCanDelegateToWithTypes(project) {
+	const agentsIdSet = new Set(project.agents ? Object.keys(project.agents) : []);
+	const subAgentsIdSet = new Set(Object.keys(extractSubAgents(project)));
+	const externalAgentsIdSet = new Set(project.externalAgents ? Object.keys(project.externalAgents) : []);
+	function enrichCanDelegateToArray(canDelegateTo) {
+		return canDelegateTo.map((item) => {
+			if (typeof item !== "string") return item;
+			if (agentsIdSet.has(item)) return { agentId: item };
+			if (subAgentsIdSet.has(item)) return { subAgentId: item };
+			if (externalAgentsIdSet.has(item)) return { externalAgentId: item };
+			return item;
+		});
+	}
+	if (project.agents) {
+		for (const agentData of Object.values(project.agents)) if (agentData.subAgents) {
+			for (const subAgentData of Object.values(agentData.subAgents)) if (subAgentData.canDelegateTo) subAgentData.canDelegateTo = enrichCanDelegateToArray(subAgentData.canDelegateTo);
+		}
+	}
+}
+/**
+* Main pull-v3 command
+* @returns PullResult when in batch mode, otherwise void (exits process)
+*/
+async function pullV4Command(options) {
+	if (options.all) {
+		await pullAllProjects(options);
+		return;
+	}
+	const batchMode = options._batchMode ?? false;
+	const originalLogLevel = process.env.LOG_LEVEL;
+	process.env.LOG_LEVEL = "silent";
+	const restoreLogLevel = () => {
+		if (originalLogLevel !== void 0) process.env.LOG_LEVEL = originalLogLevel;
+		else delete process.env.LOG_LEVEL;
+	};
+	if (!batchMode) performBackgroundVersionCheck();
+	console.log(styleText("blue", "\nInkeep Pull:"));
+	if (options.introspect) console.log(styleText("gray", "  Introspect mode • Complete regeneration • No comparison needed"));
+	else console.log(styleText("gray", "  Smart comparison • Detect all changes • Targeted updates"));
+	const s = p.spinner();
+	try {
+		const { config, isCI } = await initializeCommand({
+			configPath: options.config,
+			profileName: options.profile,
+			tag: options.tag,
+			showSpinner: true,
+			spinnerText: "Loading configuration...",
+			logConfig: true,
+			quiet: options.quiet
+		});
+		s.start("Detecting project...");
+		let projectDir;
+		let projectId;
+		let localProjectForId = null;
+		const currentDir = process.cwd();
+		if (existsSync(join(currentDir, "index.ts"))) {
+			projectDir = currentDir;
+			s.start("Loading local project...");
+			try {
+				localProjectForId = await loadProject(projectDir);
+				const localProjectId = localProjectForId.getId();
+				if (options.project) {
+					if (localProjectId !== options.project) {
+						s.stop("Project ID mismatch");
+						console.error(styleText("red", `Local project ID "${localProjectId}" doesn't match --project "${options.project}"`));
+						console.error(styleText("yellow", "Either remove --project flag or ensure it matches the local project ID"));
+						if (batchMode) return {
+							success: false,
+							error: "Project ID mismatch"
+						};
+						process.exit(1);
+					}
+				}
+				projectId = localProjectId;
+				s.stop(`Using local project: ${projectId}`);
+			} catch (error) {
+				s.stop("Failed to load local project");
+				throw new Error(`Could not load local project: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		} else {
+			if (!options.project) {
+				s.stop("No index.ts found in current directory");
+				console.error(styleText("yellow", "Please run this command from a directory containing index.ts or use --project <project-id>"));
+				if (batchMode) return {
+					success: false,
+					error: "No index.ts found and no --project specified"
+				};
+				process.exit(1);
+			}
+			const projectPath = resolve(currentDir, options.project);
+			if (existsSync(join(projectPath, "index.ts"))) {
+				projectDir = projectPath;
+				s.start("Loading project from specified path...");
+				try {
+					localProjectForId = await loadProject(projectDir);
+					projectId = localProjectForId.getId();
+					s.stop(`Using project from path: ${projectId}`);
+				} catch (error) {
+					s.stop("Failed to load project from path");
+					throw new Error(`Could not load project from ${projectPath}: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			} else {
+				projectId = options.project;
+				projectDir = join(currentDir, projectId);
+				s.stop(`Creating new project directory: ${projectDir}`);
+			}
+		}
+		s.start(`Fetching project: ${projectId}`);
+		const remoteProject = await (await ManagementApiClient.create(config.agentsApiUrl, options.config, config.tenantId, projectId, isCI, config.agentsApiKey)).getFullProject(projectId);
+		if (options.debug && remoteProject.functions) {
+			console.log(styleText("gray", "   📋 Project-level functions from API:"), Object.keys(remoteProject.functions));
+			Object.entries(remoteProject.functions).forEach(([id, data]) => {
+				console.log(styleText("gray", `      ${id}: has name=${!!data.name}, has description=${!!data.description}`));
+			});
+		}
+		if (remoteProject.agents) for (const [agentId, agentData] of Object.entries(remoteProject.agents)) {
+			if (agentData.functionTools) {
+				remoteProject.functionTools = remoteProject.functionTools || {};
+				Object.assign(remoteProject.functionTools, agentData.functionTools);
+				if (options.debug) console.log(styleText("gray", `   Hoisted functionTools from agent ${agentId}: ${Object.keys(agentData.functionTools).join(", ")}`));
+			}
+			if (agentData.functions) {
+				remoteProject.functions = remoteProject.functions || {};
+				Object.entries(agentData.functions).forEach(([funcId, funcData]) => {
+					if (!remoteProject.functions[funcId]) remoteProject.functions[funcId] = {
+						id: funcData.id,
+						inputSchema: funcData.inputSchema,
+						executeCode: funcData.executeCode,
+						dependencies: funcData.dependencies
+					};
+				});
+			}
+		}
+		if (remoteProject.agents && remoteProject.tools) {
+			const projectToolIds = Object.keys(remoteProject.tools);
+			for (const agentData of Object.values(remoteProject.agents)) if (agentData.tools) {
+				const agentSpecificTools = Object.fromEntries(Object.entries(agentData.tools).filter(([toolId]) => !projectToolIds.includes(toolId)));
+				if (Object.keys(agentSpecificTools).length > 0) agentData.tools = agentSpecificTools;
+				else delete agentData.tools;
+			}
+		}
+		enrichCanDelegateToWithTypes(remoteProject);
+		s.message("Project data fetched");
+		if (options.json) {
+			console.log(JSON.stringify(remoteProject, null, 2));
+			restoreLogLevel();
+			return;
+		}
+		const paths = createProjectStructure(projectDir);
+		if (remoteProject.skills && Object.keys(remoteProject.skills).length) {
+			const { generateSkills } = await import("../../pull-v3/components/skill-generator.js");
+			await generateSkills(remoteProject.skills, paths.skillsDir);
+		}
+		s.start("Starting generating files...");
+		await introspectGenerate({
+			project: remoteProject,
+			paths,
+			debug: options.debug
+		});
+		s.stop("All files generated");
+		console.log(styleText("green", "\nProject synced successfully!"));
+		console.log(styleText("gray", `   Location: ${paths.projectRoot}`));
+		console.log(styleText("gray", `   Environment: ${options.env || "development"}`));
+		console.log(styleText("yellow", "⚠️  If you encounter broken code after running `inkeep pull`, please report it at https://github.com/inkeep/agents/issues."));
+		restoreLogLevel();
+		if (batchMode) return { success: true };
+		process.exit(0);
+	} catch (error) {
+		const message = error instanceof Error ? error.stack : String(error);
+		s.stop();
+		console.error(styleText("red", `\nError: ${message}`));
+		if (options.debug && error instanceof Error) console.error(styleText("red", error.stack || ""));
+		restoreLogLevel();
+		if (batchMode) return {
+			success: false,
+			error: message
+		};
+		process.exit(1);
+	}
+}
+/**
+* Pull all projects for the current tenant
+* Uses smart comparison with LLM merging for existing projects, introspect for new projects
+*/
+async function pullAllProjects(options) {
+	console.log(styleText("blue", "\n🔄 Batch Pull: Sequential processing with smart comparison\n"));
+	console.log(styleText("gray", "  • Existing projects: Smart comparison + LLM merging + confirmation prompts"));
+	console.log(styleText("gray", "  • New projects: Fresh generation with introspect mode\n"));
+	performBackgroundVersionCheck();
+	const { config, isCI } = await initializeCommand({
+		configPath: options.config,
+		profileName: options.profile,
+		tag: options.tag,
+		showSpinner: true,
+		spinnerText: "Loading configuration...",
+		logConfig: true,
+		quiet: options.quiet
+	});
+	const s = p.spinner();
+	try {
+		s.start("Fetching project list from API...");
+		const projects = await (await ManagementApiClient.create(config.agentsApiUrl, options.config, config.tenantId, void 0, isCI, config.agentsApiKey)).listAllProjects();
+		s.stop(`Found ${projects.length} project(s)`);
+		if (!projects.length) {
+			console.log(styleText("yellow", "No projects found for this tenant."));
+			process.exit(0);
+		}
+		const existingProjects = [];
+		const newProjects = [];
+		for (const project of projects) if (existsSync(join(join(process.cwd(), project.id), "index.ts"))) existingProjects.push(project);
+		else newProjects.push(project);
+		console.log(styleText("gray", "\nProjects to pull:\n"));
+		if (existingProjects.length > 0) {
+			console.log(styleText("cyan", "  Existing (smart comparison):"));
+			for (const project of existingProjects) console.log(styleText("gray", `    • ${project.name || project.id} (${project.id})`));
+		}
+		if (newProjects.length > 0) {
+			console.log(styleText("cyan", "  New (introspect):"));
+			for (const project of newProjects) console.log(styleText("gray", `    • ${project.name || project.id} (${project.id})`));
+		}
+		console.log();
+		const results = [];
+		const total = projects.length;
+		for (let i = 0; i < projects.length; i++) {
+			const project = projects[i];
+			const progress = `[${i + 1}/${total}]`;
+			console.log(styleText("cyan", `\n${"─".repeat(60)}`));
+			console.log(styleText("cyan", `${progress} Pulling ${project.name || project.id}...`));
+			const result = await pullSingleProject(project.id, project.name, options, config, isCI);
+			results.push(result);
+			if (result.success) console.log(styleText("green", `\n  ✓ ${result.projectName || result.projectId} → ${result.targetDir}`));
+			else console.log(styleText("red", `\n  ✗ ${result.projectName || result.projectId}: ${result.error}`));
+		}
+		const succeeded = results.filter((r) => r.success).length;
+		const failed = results.filter((r) => !r.success).length;
+		console.log(styleText("cyan", `\n${"═".repeat(60)}`));
+		console.log(styleText("cyan", "📊 Batch Pull Summary:"));
+		console.log(styleText("green", `  ✓ Succeeded: ${succeeded}`));
+		if (failed > 0) {
+			console.log(styleText("red", `  ✗ Failed: ${failed}`));
+			console.log(styleText("red", "\nFailed projects:"));
+			for (const result of results) if (!result.success) console.log(styleText("red", `  • ${result.projectId}: ${result.error}`));
+		}
+		process.exit(failed > 0 ? 1 : 0);
+	} catch (error) {
+		s.stop();
+		console.error(styleText("red", `\nError: ${error instanceof Error ? error.message : String(error)}`));
+		process.exit(1);
+	}
+}
+/**
+* Pull a single project (used by batch operations)
+* Uses smart comparison flow for existing projects, introspect for new projects
+*/
+async function pullSingleProject(projectId, projectName, options, config, isCI) {
+	const targetDir = join(process.cwd(), projectId);
+	const hasExistingProject = existsSync(join(targetDir, "index.ts"));
+	try {
+		if (hasExistingProject) {
+			console.log(styleText("gray", `   📂 Existing project found - using smart comparison mode`));
+			const originalDir = process.cwd();
+			process.chdir(targetDir);
+			try {
+				const result = await pullV4Command({
+					...options,
+					project: projectId,
+					all: false,
+					_batchMode: true
+				});
+				process.chdir(originalDir);
+				if (result && typeof result === "object") return {
+					projectId,
+					projectName,
+					targetDir,
+					success: result.success,
+					error: result.error
+				};
+				return {
+					projectId,
+					projectName,
+					targetDir,
+					success: true
+				};
+			} catch (error) {
+				process.chdir(originalDir);
+				throw error;
+			}
+		}
+		console.log(styleText("gray", `   🆕 New project - using introspect mode`));
+		const originalLogLevel = process.env.LOG_LEVEL;
+		process.env.LOG_LEVEL = "silent";
+		const restoreLogLevel = () => {
+			if (originalLogLevel !== void 0) process.env.LOG_LEVEL = originalLogLevel;
+			else delete process.env.LOG_LEVEL;
+		};
+		const remoteProject = await (await ManagementApiClient.create(config.agentsApiUrl, options.config, config.tenantId, projectId, isCI, config.agentsApiKey)).getFullProject(projectId);
+		await introspectGenerate({
+			project: remoteProject,
+			paths: createProjectStructure(targetDir)
+		});
+		restoreLogLevel();
+		return {
+			projectId,
+			projectName: projectName || remoteProject.name,
+			targetDir,
+			success: true
+		};
+	} catch (error) {
+		return {
+			projectId,
+			projectName,
+			targetDir,
+			success: false,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+
+//#endregion
+export { createProjectStructure, enrichCanDelegateToWithTypes, pullV4Command };