@agentuity/cli 0.0.100 → 0.0.102

package/src/cmd/build/vite/agent-discovery.ts

@@ -306,7 +306,8 @@ function extractAgentMetadata(
 }
 
 /**
- * Extract evals from eval.ts file (READ-ONLY)
+ * Extract evals from a file (READ-ONLY)
+ * Finds createEval calls regardless of whether they're exported or not
  */
 async function extractEvalMetadata(
 	evalsPath: string,
@@ -322,72 +323,135 @@ async function extractEvalMetadata(
 
 	try {
 		const evalsSource = await evalsFile.text();
+		return extractEvalsFromSource(
+			evalsSource,
+			evalsPath,
+			agentId,
+			projectId,
+			deploymentId,
+			logger
+		);
+	} catch (error) {
+		logger.warn(`Failed to parse evals from ${evalsPath}: ${error}`);
+		return [];
+	}
+}
+
+/**
+ * Extract evals from source code (READ-ONLY)
+ * Finds all createEval calls in the source, exported or not
+ */
+function extractEvalsFromSource(
+	source: string,
+	filename: string,
+	agentId: string,
+	projectId: string,
+	deploymentId: string,
+	logger: Logger
+): EvalMetadata[] {
+	// Quick check - skip if no createEval in source
+	if (!source.includes('createEval')) {
+		return [];
+	}
+
+	try {
 		const transpiler = new Bun.Transpiler({ loader: 'ts', target: 'bun' });
-		const evalsContents = transpiler.transformSync(evalsSource);
-		const version = hash(evalsContents);
+		const contents = transpiler.transformSync(source);
+		const version = hash(contents);
 
-		const ast = acornLoose.parse(evalsContents, { ecmaVersion: 'latest', sourceType: 'module' });
+		const ast = acornLoose.parse(contents, { ecmaVersion: 'latest', sourceType: 'module' });
 		const evals: EvalMetadata[] = [];
 
-		// Find createEval calls
-		for (const node of (ast as { body: ASTNode[] }).body) {
-			if (node.type === 'ExportNamedDeclaration') {
-				const declaration = (
-					node as unknown as { declaration: { declarations?: ASTVariableDeclarator[] } }
-				).declaration;
-
-				if (declaration?.declarations) {
-					for (const decl of declaration.declarations) {
-						if (decl.init && decl.init.type === 'CallExpression') {
-							const callExpr = decl.init as ASTCallExpression;
-
-							if (
-								callExpr.callee.type === 'Identifier' &&
-								(callExpr.callee as ASTNodeIdentifier).name === 'createEval' &&
-								callExpr.arguments.length >= 2
-							) {
-								const nameArg = callExpr.arguments[0] as ASTLiteral;
-								const evalName = String(nameArg.value);
-
-								const callargexp = callExpr.arguments[1] as ASTObjectExpression;
-								let description: string | undefined;
-
-								for (const prop of callargexp.properties) {
-									if (
-										prop.key.name === 'metadata' &&
-										prop.value.type === 'ObjectExpression'
-									) {
-										const metadataMap = parseObjectExpressionToMap(
-											prop.value as ASTObjectExpression
-										);
-										description = metadataMap.get('description');
-										break;
-									}
-								}
+		// Recursively find all createEval calls in the AST
+		function findCreateEvalCalls(node: unknown): void {
+			if (!node || typeof node !== 'object') return;
+
+			const n = node as Record<string, unknown>;
+
+			// Check if this is a createEval call (either direct or method call)
+			// Direct: createEval('name', {...})
+			// Method: agent.createEval('name', {...})
+			let isCreateEvalCall = false;
+
+			if (n.type === 'CallExpression' && n.callee && typeof n.callee === 'object') {
+				const callee = n.callee as ASTNode & { property?: ASTNodeIdentifier };
+
+				// Direct function call: createEval(...)
+				if (
+					callee.type === 'Identifier' &&
+					(callee as ASTNodeIdentifier).name === 'createEval'
+				) {
+					isCreateEvalCall = true;
+				}
+
+				// Method call: someAgent.createEval(...)
+				if (
+					callee.type === 'MemberExpression' &&
+					callee.property &&
+					callee.property.type === 'Identifier' &&
+					callee.property.name === 'createEval'
+				) {
+					isCreateEvalCall = true;
+				}
+			}
+
+			if (isCreateEvalCall) {
+				const callExpr = n as unknown as ASTCallExpression;
+				if (callExpr.arguments.length >= 2) {
+					const nameArg = callExpr.arguments[0] as ASTLiteral;
+					const evalName = String(nameArg.value);
 
-								const id = getEvalId(projectId, deploymentId, evalsPath, evalName, version);
-								const evalId = generateStableEvalId(projectId, agentId, evalName);
-
-								evals.push({
-									id,
-									evalId,
-									name: evalName,
-									filename: evalsPath,
-									version,
-									description,
-									agentIdentifier: agentId,
-									projectId,
-								});
+					const callargexp = callExpr.arguments[1] as ASTObjectExpression;
+					let description: string | undefined;
+
+					if (callargexp.properties) {
+						for (const prop of callargexp.properties) {
+							if (prop.key.name === 'metadata' && prop.value.type === 'ObjectExpression') {
+								const metadataMap = parseObjectExpressionToMap(
+									prop.value as ASTObjectExpression
+								);
+								description = metadataMap.get('description');
+								break;
 							}
 						}
 					}
+
+					const id = getEvalId(projectId, deploymentId, filename, evalName, version);
+					const evalId = generateStableEvalId(projectId, agentId, evalName);
+
+					logger.trace(`Found eval '${evalName}' in ${filename} (evalId: ${evalId})`);
+
+					evals.push({
+						id,
+						evalId,
+						name: evalName,
+						filename,
+						version,
+						description,
+						agentIdentifier: agentId,
+						projectId,
+					});
+				}
+			}
+
+			// Recursively search child nodes
+			for (const key of Object.keys(n)) {
+				const value = n[key];
+				if (Array.isArray(value)) {
+					for (const item of value) {
+						findCreateEvalCalls(item);
+					}
+				} else if (value && typeof value === 'object') {
+					findCreateEvalCalls(value);
 				}
 			}
 		}
 
+		findCreateEvalCalls(ast);
+
 		return evals;
 	} catch (error) {
-		logger.warn(`Failed to parse evals from ${evalsPath}: ${error}`);
+		logger.warn(`Failed to parse evals from ${filename}: ${error}`);
 		return [];
 	}
 }
@@ -439,20 +503,49 @@ export async function discoverAgents(
 			if (agentMetadata) {
 				logger.trace('Discovered agent: %s at %s', agentMetadata.name, relativeFilename);
 
-				// Check for evals in same directory
+				// Collect evals from multiple sources
+				const allEvals: EvalMetadata[] = [];
+
+				// 1. Extract evals from the agent file itself (agent.createEval() pattern)
+				const evalsInAgentFile = extractEvalsFromSource(
+					source,
+					relativeFilename,
+					agentMetadata.agentId,
+					projectId,
+					deploymentId,
+					logger
+				);
+				if (evalsInAgentFile.length > 0) {
+					logger.trace(
+						'Found %d eval(s) in agent file for %s',
+						evalsInAgentFile.length,
+						agentMetadata.name
+					);
+					allEvals.push(...evalsInAgentFile);
+				}
+
+				// 2. Check for evals in separate eval.ts file in same directory
 				const agentDir = dirname(filePath);
 				const evalsPath = join(agentDir, 'eval.ts');
-				const evals = await extractEvalMetadata(
+				const evalsInSeparateFile = await extractEvalMetadata(
 					evalsPath,
 					agentMetadata.agentId,
 					projectId,
 					deploymentId,
 					logger
 				);
+				if (evalsInSeparateFile.length > 0) {
+					logger.trace(
+						'Found %d eval(s) in eval.ts for agent %s',
+						evalsInSeparateFile.length,
+						agentMetadata.name
+					);
+					allEvals.push(...evalsInSeparateFile);
+				}
 
-				if (evals.length > 0) {
-					agentMetadata.evals = evals;
-					logger.trace('Found %d eval(s) for agent %s', evals.length, agentMetadata.name);
+				if (allEvals.length > 0) {
+					agentMetadata.evals = allEvals;
+					logger.trace('Total %d eval(s) for agent %s', allEvals.length, agentMetadata.name);
 				}
 
 				agents.push(agentMetadata);

package/src/cmd/build/vite/bun-dev-server.ts

@@ -23,45 +23,75 @@ export interface BunDevServerResult {
 
 /**
  * Start Bun dev server (Vite asset server must already be running)
- * Generates entry file with proxy routes pointing to Vite
+ *
+ * IMPORTANT: This function assumes that the dev bundle has already been built:
+ * - Entry file generated at src/generated/app.ts (with workbench config if enabled)
+ * - Bundled to .agentuity/app.js with LLM patches applied
+ *
+ * The bundle is loaded here to ensure AI Gateway routing patches are active.
+ * Vite port is read from process.env.VITE_PORT at runtime.
  */
 export async function startBunDevServer(options: BunDevServerOptions): Promise<BunDevServerResult> {
-	const { rootDir, port = 3500, projectId = '', deploymentId = '', logger, vitePort } = options;
+	const { rootDir, port = 3500, logger, vitePort } = options;
 
 	logger.debug('Starting Bun dev server (Vite already running on port %d)...', vitePort);
 
-	// Generate workbench source files if enabled (dev mode)
-	const { loadAgentuityConfig, getWorkbenchConfig } = await import('./config-loader');
-	const config = await loadAgentuityConfig(rootDir, logger);
-	const workbenchConfig = getWorkbenchConfig(config, true); // dev mode
+	// Load the bundled app - this will start Bun.serve() internally
+	// IMPORTANT: We must import the bundled .agentuity/app.js (NOT src/generated/app.ts)
+	// because the bundled version has LLM provider patches applied that enable AI Gateway routing.
+	// Importing the source file directly would bypass these patches.
+	logger.debug('📦 Loading bundled app (Bun server will start)...');
+	const appPath = `${rootDir}/.agentuity/app.js`;
 
-	if (workbenchConfig.enabled) {
-		logger.debug('Workbench enabled (dev mode), generating source files...');
-		const { generateWorkbenchFiles } = await import('./workbench-generator');
-		await generateWorkbenchFiles(rootDir, projectId, workbenchConfig, logger);
+	// Verify bundle exists before attempting to load
+	const appFile = Bun.file(appPath);
+	if (!(await appFile.exists())) {
+		throw new Error(
+			`Dev bundle not found at ${appPath}. The bundle must be generated before starting the dev server.`
+		);
 	}
 
-	// Step 2: Generate entry file with Vite port for asset proxying
-	logger.debug('📝 Generating entry file with asset proxy configuration...');
-	const { generateEntryFile } = await import('../entry-generator');
-	await generateEntryFile({
-		rootDir,
-		projectId: projectId || '',
-		deploymentId: deploymentId || '',
-		logger,
-		mode: 'dev',
-		workbench: workbenchConfig.enabled ? workbenchConfig : undefined,
-		vitePort, // Pass Vite port for proxy routes
-	});
-
-	// Step 3: Load the generated app - this will start Bun.serve() internally
-	logger.debug('📦 Loading generated app (Bun server will start)...');
-	const appPath = `${rootDir}/.agentuity/app.generated.ts`;
+	// Clear Bun's module cache for the bundled app to ensure fresh code is loaded.
+	// This is essential for hot reload to work - otherwise Bun returns the cached module
+	// and the server continues serving stale code.
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const bunAny = Bun as any;
+		// Try multiple possible locations for the loader registry
+		const loader = bunAny.loader ?? bunAny.Loader ?? bunAny.Main;
+		const registry = loader?.registry ?? loader?.Registry;
+		if (registry?.delete) {
+			logger.debug('Clearing Bun module cache for: %s', appPath);
+			registry.delete(appPath);
+		} else if (typeof loader?.clearModuleCache === 'function') {
+			// Alternative API that may exist in some Bun versions
+			logger.debug('Clearing Bun module cache via clearModuleCache: %s', appPath);
+			loader.clearModuleCache(appPath);
+		} else {
+			logger.debug(
+				'Bun module cache API not available - module may be cached. Available loader keys: %s',
+				loader ? Object.keys(loader).join(', ') : 'none'
+			);
+		}
+	} catch (err) {
+		logger.warn(
+			'Failed to clear Bun module cache for %s: %s. Server restart may serve stale code.',
+			appPath,
+			err instanceof Error ? err.message : String(err)
+		);
+	}
 
 	// Set PORT env var so the generated app uses the correct port
 	process.env.PORT = String(port);
 
-	await import(appPath);
+	// Import the generated app using the canonical file path
+	try {
+		await import(appPath);
+	} catch (err) {
+		const errorMessage = err instanceof Error ? err.message : String(err);
+		logger.error('Failed to import generated app from %s: %s', appPath, errorMessage);
+		throw new Error(`Failed to load generated app: ${errorMessage}`);
+	}
 
 	// Wait for server to actually start listening
 	// The generated app sets (globalThis as any).__AGENTUITY_SERVER__ when server starts

package/src/cmd/build/vite/docs-generator.ts

@@ -0,0 +1,87 @@
+/**
+ * Documentation Generator
+ *
+ * Generates README.md and AGENTS.md in src/generated/ directory
+ * Only writes files if they don't already exist (preserves user modifications)
+ */
+
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import type { Logger } from '../../../types';
+
+const README_CONTENT = `# Generated Files - DO NOT EDIT
+
+This directory contains auto-generated TypeScript files created by the Agentuity build system.
+
+**These files are regenerated on every build.** Any manual changes will be overwritten.
+
+## Generated Files
+
+- \`registry.ts\` - Agent registry from \`src/agent/**\`
+- \`routes.ts\` - Route registry from \`src/api/**\`
+- \`app.ts\` - Application entry point
+- \`state.ts\` - App state types (when setup() exists)
+- \`router.ts\` - Runtime wrapper (when setup() exists)
+
+## For Developers
+
+Do not modify these files. Instead:
+- Add/modify agents in \`src/agent/\`
+- Add/modify routes in \`src/api/\`
+- Configure app in \`app.ts\`
+
+These files ARE version controlled to enable better tooling and type checking.
+`;
+
+const AGENTS_MD_CONTENT = `# AI Agent Instructions
+
+**CRITICAL:** Files in this directory are AUTO-GENERATED by the Agentuity build system.
+
+## Rules for AI Agents
+
+1. ❌ NEVER edit files in \`src/generated/\`
+2. ❌ NEVER include \`src/generated/\` files in context when analyzing code
+3. ❌ NEVER suggest changes to generated files
+4. ✅ Ignore this directory when searching for user code
+5. ✅ Direct users to modify source files in \`src/agent/\`, \`src/api/\`, or \`app.ts\`
+
+## What Gets Generated
+
+- \`registry.ts\` - Built from agent discovery in \`src/agent/\`
+- \`routes.ts\` - Built from route discovery in \`src/api/\`
+- \`app.ts\` - Entry point assembled from project configuration
+- \`state.ts\` - App state type from \`setup()\` return value
+- \`router.ts\` - Runtime wrapper with type augmentation
+
+These files are regenerated on every \`bun run build\` or \`bun run dev\`.
+`;
+
+/**
+ * Generate documentation files in src/generated/ directory
+ * Only creates files if they don't already exist
+ */
+export async function generateDocumentation(srcDir: string, logger: Logger): Promise<void> {
+	const generatedDir = join(srcDir, 'generated');
+
+	// Ensure directory exists
+	await mkdir(generatedDir, { recursive: true });
+
+	const readmePath = join(generatedDir, 'README.md');
+	const agentsMdPath = join(generatedDir, 'AGENTS.md');
+
+	// Generate README.md if it doesn't exist
+	if (!(await Bun.file(readmePath).exists())) {
+		await Bun.write(readmePath, README_CONTENT);
+		logger.debug('Generated src/generated/README.md');
+	} else {
+		logger.trace('Skipping README.md - file already exists');
+	}
+
+	// Generate AGENTS.md if it doesn't exist
+	if (!(await Bun.file(agentsMdPath).exists())) {
+		await Bun.write(agentsMdPath, AGENTS_MD_CONTENT);
+		logger.debug('Generated src/generated/AGENTS.md');
+	} else {
+		logger.trace('Skipping AGENTS.md - file already exists');
+	}
+}

package/src/cmd/build/vite/index.ts

@@ -28,9 +28,9 @@ export interface AgentuityPluginOptions {
  * Responsibilities:
  * - Agent discovery via READ-ONLY AST analysis
  * - Route discovery via READ-ONLY AST analysis
- * - Registry generation (.agentuity/registry.generated.ts)
- * - Lifecycle types generation (.agentuity/lifecycle.generated.d.ts)
- * - Entry file generation (.agentuity/agentuity_app.generated.ts)
+ * - Registry generation (src/generated/registry.ts)
+ * - Lifecycle types generation (src/generated/lifecycle.d.ts)
+ * - Entry file generation (src/generated/app.ts)
  * - Virtual modules (virtual:agentuity/agents, virtual:agentuity/routes)
  * - Metadata generation (agentuity.metadata.json)
  */
@@ -85,12 +85,14 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 			}
 
 			if (routeInfoList.length > 0) {
-				generateRouteRegistry(srcDir, routeInfoList);
+				generateRouteRegistry(srcDir, routeInfoList, agents);
 				logger.trace('Generated route registry with %d route(s)', routeInfoList.length);
 			}
 
 			// Generate lifecycle types
-			await generateLifecycleTypes(rootDir, srcDir, logger);
+			logger.debug('[vite-plugin] About to call generateLifecycleTypes');
+			const lifecycleResult = await generateLifecycleTypes(rootDir, srcDir, logger);
+			logger.debug(`[vite-plugin] generateLifecycleTypes returned: ${lifecycleResult}`);
 
 			// Generate entry file (pass workbench config for route mounting)
 			await generateEntryFile({
@@ -126,11 +128,11 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 		load(id) {
 			if (id === '\0virtual:agentuity/agents') {
 				// Re-export from generated registry
-				return `export { agentRegistry } from '../.agentuity/registry.generated.js';`;
+				return `export { agentRegistry } from '../src/generated/registry.js';`;
 			}
 			if (id === '\0virtual:agentuity/routes') {
 				// Re-export from generated route registry
-				return `export { routeRegistry } from '../.agentuity/routes.generated.js';`;
+				return `export { routeRegistry } from '../src/generated/routes.js';`;
 			}
 			return null;
 		},

package/src/cmd/build/vite/lifecycle-generator.ts

@@ -1,7 +1,7 @@
 /**
  * Lifecycle Types Generator
  *
- * Generates .agentuity/lifecycle.generated.d.ts by analyzing app.ts for setup() function
+ * Generates src/generated/lifecycle.d.ts by analyzing app.ts for setup() function
  */
 
 import { join } from 'node:path';
@@ -16,7 +16,12 @@ export async function generateLifecycleTypes(
 	srcDir: string,
 	logger: Logger
 ): Promise<boolean> {
-	const outDir = join(rootDir, '.agentuity');
+	logger.debug('[lifecycle] Starting lifecycle type generation...');
+	logger.debug(`[lifecycle] rootDir: ${rootDir}`);
+	logger.debug(`[lifecycle] srcDir: ${srcDir}`);
+
+	const outDir = join(srcDir, 'generated');
+	logger.debug(`[lifecycle] outDir: ${outDir}`);
 
 	// Look for app.ts in both root and src directories
 	const rootAppFile = join(rootDir, 'app.ts');
@@ -25,19 +30,28 @@ export async function generateLifecycleTypes(
 	let appFile = '';
 	if (await Bun.file(rootAppFile).exists()) {
 		appFile = rootAppFile;
+		logger.debug(`[lifecycle] Found app.ts at root: ${rootAppFile}`);
 	} else if (await Bun.file(srcAppFile).exists()) {
 		appFile = srcAppFile;
+		logger.debug(`[lifecycle] Found app.ts in src: ${srcAppFile}`);
 	}
 
 	if (!appFile || !(await Bun.file(appFile).exists())) {
-		logger.trace('No app.ts found for lifecycle types generation');
+		logger.debug('[lifecycle] No app.ts found for lifecycle types generation');
 		return false;
 	}
 
 	try {
-		return await generateLifecycleTypesFromAST(rootDir, outDir, appFile);
+		logger.debug(`[lifecycle] Calling generateLifecycleTypesFromAST...`);
+		const result = await generateLifecycleTypesFromAST(rootDir, outDir, appFile);
+		if (result) {
+			logger.debug(`[lifecycle] Lifecycle types generated successfully in ${outDir}`);
+		} else {
+			logger.debug('[lifecycle] generateLifecycleTypesFromAST returned false (no setup found)');
+		}
+		return result;
 	} catch (error) {
-		logger.error('Failed to generate lifecycle types:', error);
+		logger.error('[lifecycle] Failed to generate lifecycle types:', error);
 		return false;
 	}
 }