@agentuity/cli 0.0.99 → 0.0.101

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

@@ -56,7 +56,7 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 
 	// 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`;
+	const appPath = `${rootDir}/src/generated/app.ts`;
 
 	// Set PORT env var so the generated app uses the correct port
 	process.env.PORT = String(port);

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

@@ -11,7 +11,6 @@ import { generateEntryFile } from '../entry-generator';
 import { loadAgentuityConfig, getWorkbenchConfig } from './config-loader';
 
 // Re-export plugins
-export { patchPlugin } from './patch-plugin';
 export { browserEnvPlugin } from './browser-env-plugin';
 
 export interface AgentuityPluginOptions {
@@ -29,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)
  */
@@ -86,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({
@@ -127,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;
 	}
 }

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

@@ -548,6 +548,175 @@ async function getGitInfo(
 	}
 }
 
+/**
+ * Generate AGENTS.md content for AI coding agents
+ */
+function generateAgentsMd(metadata: BuildMetadata): string {
+	const lines: string[] = [];
+
+	lines.push('# Compiled Agentuity Application');
+	lines.push('');
+	lines.push(
+		'This directory contains compiled and bundled source code from an Agentuity application.'
+	);
+	lines.push('');
+
+	// Add source repository info if available
+	if (metadata.deployment?.git?.repo) {
+		lines.push('## Source Repository');
+		lines.push('');
+		lines.push(`**Repository:** ${metadata.deployment.git.repo}`);
+
+		if (metadata.deployment.git.branch) {
+			lines.push(`**Branch:** ${metadata.deployment.git.branch}`);
+		}
+
+		if (metadata.deployment.git.commit) {
+			const shortCommit = metadata.deployment.git.commit.substring(0, 7);
+			const commitUrl = metadata.deployment.git.repo.endsWith('.git')
+				? metadata.deployment.git.repo.slice(0, -4)
+				: metadata.deployment.git.repo;
+			lines.push(
+				`**Commit:** [\`${shortCommit}\`](${commitUrl}/commit/${metadata.deployment.git.commit})`
+			);
+		}
+
+		if (metadata.deployment.git.message) {
+			lines.push(`**Message:** ${metadata.deployment.git.message}`);
+		}
+
+		lines.push('');
+	}
+
+	// Add build info
+	lines.push('## Build Information');
+	lines.push('');
+	if (metadata.project?.name) {
+		lines.push(
+			`**Project:** ${metadata.project.name}${metadata.project.version ? ` v${metadata.project.version}` : ''}`
+		);
+	}
+	if (metadata.project?.id) {
+		lines.push(`**Project ID:** ${metadata.project.id}`);
+	}
+	if (metadata.project?.orgId) {
+		lines.push(`**Org ID:** ${metadata.project.orgId}`);
+	}
+	if (metadata.deployment.id) {
+		lines.push(`**Deployment ID:** ${metadata.deployment.id}`);
+	}
+	if (metadata.deployment?.build) {
+		lines.push(
+			`**Built with:** Agentuity CLI v${metadata.deployment.build.agentuity}, Bun v${metadata.deployment.build.bun}`
+		);
+		lines.push(
+			`**Platform:** ${metadata.deployment.build.platform}-${metadata.deployment.build.arch}`
+		);
+	}
+	if (metadata.deployment?.date) {
+		lines.push(`**Build date:** ${metadata.deployment.date}`);
+	}
+	lines.push('');
+
+	// Add structure overview
+	lines.push('## Structure');
+	lines.push('');
+	lines.push('```');
+	lines.push('.agentuity/');
+	lines.push('├── app.js                     # Bundled server application');
+	lines.push('├── agentuity.metadata.json    # Build metadata and schemas');
+	if (metadata.assets?.some((a) => a.filename.startsWith('client/'))) {
+		lines.push('├── client/                # Frontend assets (fallback, CDN by default)');
+	}
+	if (metadata.assets?.some((a) => a.filename.startsWith('public/'))) {
+		lines.push('├── public/                # Static assets');
+	}
+	lines.push('└── AGENTS.md                  # This file');
+	lines.push('```');
+	lines.push('');
+
+	// Add agent/route details
+	if (metadata.agents && metadata.agents.length > 0) {
+		lines.push('## Agents');
+		lines.push('');
+		lines.push(`This application defines ${metadata.agents.length} agent(s):`);
+		lines.push('');
+		for (const agent of metadata.agents) {
+			lines.push(`- **${agent.name}** (ID: \`${agent.id}\`)`);
+		}
+		lines.push('');
+	}
+
+	if (metadata.routes && metadata.routes.length > 0) {
+		lines.push('## Routes');
+		lines.push('');
+		lines.push(`This application defines ${metadata.routes.length} route(s):`);
+		lines.push('');
+		for (const route of metadata.routes) {
+			lines.push(`- \`${route.method.toUpperCase()} ${route.path}\` (${route.type})`);
+		}
+		lines.push('');
+	}
+
+	// Add runtime environment info
+	lines.push('## Runtime Environment');
+	lines.push('');
+	lines.push('When deployed, this application runs in a managed runtime environment with:');
+	lines.push('');
+	lines.push('**User & Permissions:**');
+	lines.push('- User: `agentuity` (UID: 1022, GID: 1777)');
+	lines.push('- Home directory: `/home/agentuity`');
+	lines.push('- Working directory: `/home/agentuity/app` (application code deployed here)');
+	lines.push('- Logs directory: `/home/agentuity/logs`');
+	lines.push('');
+	lines.push('**Pre-installed Tools:**');
+	lines.push('- **Runtimes:** Node.js 24, Bun 1.x');
+	lines.push('- **AI Tools:** Amp, Opencode AI, Claude Code');
+	lines.push('- **Version Control:** git, GitHub CLI (gh)');
+	lines.push('- **Browser Automation:** Chromium, ChromeDriver, Xvfb (headless display)');
+	lines.push('- **Media Processing:** ffmpeg');
+	lines.push('- **Network Tools:** curl, wget, netcat, dnsutils');
+	lines.push('- **Other:** openssh-client, openssh-sftp-server, strace, unzip, fuse');
+	lines.push('');
+	lines.push('**Environment Variables:**');
+	lines.push('- `AGENTUITY_DATA_DIR=/home/agentuity/data` - Persistent data storage');
+	lines.push('- `AGENTUITY_LOG_DIR=/home/agentuity/logs` - Application logs');
+	lines.push('- `CHROME_BIN=/usr/bin/chromium` - Chromium browser path');
+	lines.push('- `DISPLAY=:99` - X11 display for headless browser');
+	lines.push(
+		'- `PATH` includes `/home/agentuity/.local/bin` and `/home/agentuity/.agentuity/bin`'
+	);
+	lines.push('');
+	lines.push('**Ports:**');
+	lines.push(
+		'- `3000: This default port that the project is running. Use PORT environment if not available'
+	);
+	lines.push('');
+
+	// Add note about metadata
+	lines.push('## For AI Coding Agents');
+	lines.push('');
+	lines.push(
+		'This is production-ready compiled code. For development and source code modifications:'
+	);
+	lines.push('');
+	if (metadata.deployment?.git?.repo) {
+		lines.push(`1. Clone the source repository: ${metadata.deployment.git.repo}`);
+		lines.push('2. Make changes to source files in `src/`');
+		lines.push('3. Run `agentuity build` to rebuild this bundle');
+	} else {
+		lines.push('1. Locate the original source repository');
+		lines.push('2. Make changes to source files in `src/`');
+		lines.push('3. Run `agentuity build` to rebuild this bundle');
+	}
+	lines.push('');
+	lines.push(
+		'See `agentuity.metadata.json` for detailed information about agents, routes, and schemas.'
+	);
+
+	return lines.join('\n');
+}
+
 /**
  * Write agentuity.metadata.json to .agentuity directory
  */
@@ -569,6 +738,15 @@ export function writeMetadataFile(
 
 	writeFileSync(metadataPath, metadataContent, 'utf-8');
 	logger.trace('Wrote agentuity.metadata.json');
+
+	// Write AGENTS.md for AI coding agents
+	if (!dev) {
+		const agentMdPath = join(agentuityDir, 'AGENTS.md');
+		const agentMdContent = generateAgentsMd(metadata);
+
+		writeFileSync(agentMdPath, agentMdContent, 'utf-8');
+		logger.trace('Wrote AGENTS.md');
+	}
 }
 
 /**