@agentuity/cli 0.0.101 → 0.0.103

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

@@ -23,45 +23,48 @@ 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}/src/generated/app.ts`;
-
 	// Set PORT env var so the generated app uses the correct port
 	process.env.PORT = String(port);
 
-	await import(appPath);
+	// Import the generated app with cache-busting query parameter.
+	// Bun's module cache is keyed by the full specifier including query string,
+	// so adding a unique timestamp forces a fresh import on each reload.
+	const cacheBuster = `?t=${Date.now()}`;
+	try {
+		await import(appPath + cacheBuster);
+	} 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/metadata-generator.ts

@@ -25,6 +25,7 @@ interface AssetInfo {
 	kind: string;
 	contentType: string;
 	size: number;
+	contentEncoding?: string;
 }
 
 function getContentType(filename: string): string {
@@ -65,6 +66,59 @@ function getContentType(filename: string): string {
 	}
 }
 
+/**
+ * Determine if an asset should be compressed with gzip.
+ * The result is included in asset metadata so the API can generate
+ * presigned URLs with matching Content-Encoding.
+ */
+function shouldCompressAsset(asset: {
+	filename: string;
+	contentType: string;
+	kind: string;
+}): boolean {
+	const ct = asset.contentType.toLowerCase();
+	const filename = asset.filename.toLowerCase();
+
+	if (ct.startsWith('image/') && ct !== 'image/svg+xml') {
+		return false;
+	}
+	if (ct.startsWith('video/') || ct.startsWith('audio/')) {
+		return false;
+	}
+	if (ct === 'font/woff' || ct === 'font/woff2') {
+		return false;
+	}
+	if (/\.(zip|gz|tgz|tar|bz2|br)$/.test(filename)) {
+		return false;
+	}
+
+	if (
+		ct.startsWith('text/') ||
+		ct === 'application/javascript' ||
+		ct === 'application/json' ||
+		ct === 'application/xml' ||
+		ct === 'application/xhtml+xml' ||
+		ct === 'image/svg+xml'
+	) {
+		return true;
+	}
+
+	if (ct === 'font/ttf' || ct === 'application/vnd.ms-fontobject') {
+		return true;
+	}
+
+	if (
+		asset.kind === 'entry-point' ||
+		asset.kind === 'script' ||
+		asset.kind === 'stylesheet' ||
+		asset.kind === 'sourcemap'
+	) {
+		return true;
+	}
+
+	return false;
+}
+
 function getAssetKind(filename: string, isEntry: boolean = false): string {
 	const ext = filename.split('.').pop()?.toLowerCase();
 
@@ -220,12 +274,18 @@ export async function generateMetadata(options: MetadataGeneratorOptions): Promi
 			}
 
 			seenAssets.add(assetPath);
-			assets.push({
+			const kind = getAssetKind(relativePath, isEntry);
+			const contentType = getContentType(relativePath);
+			const assetInfo: AssetInfo = {
 				filename: assetPath,
-				kind: getAssetKind(relativePath, isEntry),
-				contentType: getContentType(relativePath),
+				kind,
+				contentType,
 				size: stats.size,
-			});
+			};
+			if (shouldCompressAsset(assetInfo)) {
+				assetInfo.contentEncoding = 'gzip';
+			}
+			assets.push(assetInfo);
 		}
 	};
 
@@ -328,12 +388,17 @@ export async function generateMetadata(options: MetadataGeneratorOptions): Promi
 						const assetPath = `public/${relativePath}`;
 						if (!seenAssets.has(assetPath)) {
 							seenAssets.add(assetPath);
-							assets.push({
+							const contentType = getContentType(entry.name);
+							const assetInfo: AssetInfo = {
 								filename: assetPath,
 								kind: 'static',
-								contentType: getContentType(entry.name),
+								contentType,
 								size: stats.size,
-							});
+							};
+							if (shouldCompressAsset(assetInfo)) {
+								assetInfo.contentEncoding = 'gzip';
+							}
+							assets.push(assetInfo);
 						}
 					}
 				}
@@ -668,6 +733,7 @@ function generateAgentsMd(metadata: BuildMetadata): string {
 	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('- Temp directory: `/home/agentuity/tmp`');
 	lines.push('');
 	lines.push('**Pre-installed Tools:**');
 	lines.push('- **Runtimes:** Node.js 24, Bun 1.x');

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

@@ -0,0 +1,169 @@
+/**
+ * Prompt Generator
+ *
+ * Generates AGENTS.md prompt files in .agents/agentuity/sdk/[type]/ directories.
+ * Also creates reference files in src/[type]/AGENTS.md (write-once, only if missing).
+ *
+ * Uses hash tracking to detect template changes in .agents/ folder.
+ * Reference files in src/ are never overwritten once created.
+ *
+ * Only runs in dev mode.
+ */
+
+import { join, dirname } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import type { Logger } from '../../../types';
+import { needsUpdate } from '../../ai/prompt/version';
+import {
+	generateLLMPrompt as generateAgentPrompt,
+	getPromptContent as getAgentContent,
+} from '../../ai/prompt/agent';
+import {
+	generateLLMPrompt as generateApiPrompt,
+	getPromptContent as getApiContent,
+} from '../../ai/prompt/api';
+import {
+	generateLLMPrompt as generateWebPrompt,
+	getPromptContent as getWebContent,
+} from '../../ai/prompt/web';
+
+interface PromptConfig {
+	name: string;
+	srcFolder: string;
+	generate: () => string;
+	getContent: () => string;
+}
+
+const PROMPTS: PromptConfig[] = [
+	{
+		name: 'agent',
+		srcFolder: 'agent',
+		generate: generateAgentPrompt,
+		getContent: getAgentContent,
+	},
+	{
+		name: 'api',
+		srcFolder: 'api',
+		generate: generateApiPrompt,
+		getContent: getApiContent,
+	},
+	{
+		name: 'web',
+		srcFolder: 'web',
+		generate: generateWebPrompt,
+		getContent: getWebContent,
+	},
+];
+
+/**
+ * Generate the reference file content that points to .agents/
+ */
+function generateReferenceContent(name: string): string {
+	return `See [.agents/agentuity/sdk/${name}/AGENTS.md](../../.agents/agentuity/sdk/${name}/AGENTS.md) for Agentuity ${name} development guidelines.
+`;
+}
+
+/**
+ * Generate or update prompt files.
+ *
+ * - .agents/agentuity/sdk/[type]/AGENTS.md: Full content, updated when hash differs
+ * - src/[type]/AGENTS.md: Reference file, only created if missing
+ *
+ * @param srcDir - The src/ directory path
+ * @param logger - Logger for output
+ */
+export async function generatePromptFiles(srcDir: string, logger: Logger): Promise<void> {
+	const projectRoot = dirname(srcDir);
+
+	for (const prompt of PROMPTS) {
+		await generatePromptFile(projectRoot, srcDir, prompt, logger);
+	}
+}
+
+async function generatePromptFile(
+	projectRoot: string,
+	srcDir: string,
+	config: PromptConfig,
+	logger: Logger
+): Promise<void> {
+	const srcFolderPath = join(srcDir, config.srcFolder);
+
+	// Check if the src folder exists (e.g., src/agent/)
+	try {
+		const stat = await Bun.$`test -d ${srcFolderPath}`.nothrow();
+		if (stat.exitCode !== 0) {
+			logger.trace(`Skipping ${config.name} prompt - src/${config.srcFolder}/ does not exist`);
+			return;
+		}
+	} catch {
+		logger.trace(`Skipping ${config.name} prompt - src/${config.srcFolder}/ does not exist`);
+		return;
+	}
+
+	// Generate files
+	await generateAgentsFile(projectRoot, config, logger);
+	await generateReferenceFile(srcFolderPath, config, logger);
+}
+
+/**
+ * Generate/update the .agents/agentuity/sdk/[type]/AGENTS.md file.
+ * Overwrites if hash differs from source template.
+ */
+async function generateAgentsFile(
+	projectRoot: string,
+	config: PromptConfig,
+	logger: Logger
+): Promise<void> {
+	const agentsDir = join(projectRoot, '.agents', 'agentuity', 'sdk', config.name);
+	const filePath = join(agentsDir, 'AGENTS.md');
+
+	const file = Bun.file(filePath);
+	const fileExists = await file.exists();
+
+	if (!fileExists) {
+		// File doesn't exist - create it
+		await mkdir(agentsDir, { recursive: true });
+		const content = config.generate();
+		await Bun.write(filePath, content);
+		logger.debug(`Generated .agents/agentuity/sdk/${config.name}/AGENTS.md`);
+		return;
+	}
+
+	// File exists - check if it needs to be updated
+	const existingContent = await file.text();
+	const sourceContent = config.getContent();
+
+	if (needsUpdate(existingContent, sourceContent)) {
+		const content = config.generate();
+		await Bun.write(filePath, content);
+		logger.debug(`Updated .agents/agentuity/sdk/${config.name}/AGENTS.md`);
+		return;
+	}
+
+	logger.trace(`Skipping ${config.name} prompt - already up to date`);
+}
+
+/**
+ * Generate the src/[type]/AGENTS.md reference file.
+ * Only creates if missing (write-once).
+ */
+async function generateReferenceFile(
+	srcFolderPath: string,
+	config: PromptConfig,
+	logger: Logger
+): Promise<void> {
+	const filePath = join(srcFolderPath, 'AGENTS.md');
+
+	const file = Bun.file(filePath);
+	const fileExists = await file.exists();
+
+	if (fileExists) {
+		logger.trace(`Skipping src/${config.srcFolder}/AGENTS.md - already exists`);
+		return;
+	}
+
+	// Create the reference file
+	const content = generateReferenceContent(config.name);
+	await Bun.write(filePath, content);
+	logger.debug(`Generated src/${config.srcFolder}/AGENTS.md (reference)`);
+}

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

@@ -13,6 +13,22 @@ import type { RouteInfo } from './route-discovery';
 
 const AgentIdentifierCollisionError = StructuredError('AgentIdentifierCollisionError');
 
+/**
+ * Regex to strip route parameter characters that produce invalid TypeScript property names:
+ * - Leading : (path parameters, e.g., :id)
+ * - Leading * (wildcard routes, e.g., *path)
+ * - Trailing ?, +, * (optional/one-or-more/wildcard modifiers, e.g., :userId?)
+ */
+const ROUTE_PARAM_CHARS = /^[:*]|[?+*]$/g;
+
+/**
+ * Sanitize a route path segment for use as a TypeScript property name.
+ * Strips route parameter characters and converts to camelCase.
+ */
+function sanitizePathSegment(segment: string): string {
+	return toCamelCase(segment.replace(ROUTE_PARAM_CHARS, ''));
+}
+
 /**
  * Generate src/generated/registry.ts with agent registry and types
  */
@@ -244,9 +260,9 @@ function generateRPCRegistryType(
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		let current: any = tree;
 
-		// Add path segments (all parts) - convert to camelCase for safe property access
+		// Add path segments - sanitize for valid TypeScript property names
 		for (let i = 0; i < pathParts.length; i++) {
-			const part = toCamelCase(pathParts[i]);
+			const part = sanitizePathSegment(pathParts[i]);
 			if (!current[part]) {
 				current[part] = {};
 			}
@@ -382,11 +398,11 @@ function generateRPCRuntimeMetadata(
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		let current: any = tree;
 
-		// Convert path segments to camelCase for safe property access
+		// Sanitize path segments for valid property names (must match type generation)
 		for (const part of pathParts) {
-			const camelPart = toCamelCase(part);
-			if (!current[camelPart]) current[camelPart] = {};
-			current = current[camelPart];
+			const sanitized = sanitizePathSegment(part);
+			if (!current[sanitized]) current[sanitized] = {};
+			current = current[sanitized];
 		}
 
 		// Use terminal method name based on route type
@@ -478,7 +494,7 @@ export function generateRouteRegistry(
 	// Collect agent and schema imports from routes with validators or exported schemas
 	allRoutes.forEach((route) => {
 		const hasSchemaVars = !!route.inputSchemaVariable || !!route.outputSchemaVariable;
-		if (!route.hasValidator && !hasSchemaVars) return;
+		if (!route.hasValidator && !hasSchemaVars && !route.agentVariable) return;
 
 		// Collect agent imports (when using agent.validator())
 		if (
@@ -592,7 +608,7 @@ export function generateRouteRegistry(
 
 	// Add InferInput/InferOutput imports if we have any routes with schemas
 	const hasSchemas = allRoutes.some(
-		(r) => r.hasValidator || r.inputSchemaVariable || r.outputSchemaVariable
+		(r) => r.hasValidator || r.inputSchemaVariable || r.outputSchemaVariable || r.agentVariable
 	);
 	const typeImports = hasSchemas
 		? `import type { InferInput, InferOutput } from '@agentuity/core';\n`
@@ -600,7 +616,9 @@ export function generateRouteRegistry(
 
 	// Generate individual route schema types
 	const routeSchemaTypes = allRoutes
-		.filter((r) => r.hasValidator || r.inputSchemaVariable || r.outputSchemaVariable)
+		.filter(
+			(r) => r.hasValidator || r.inputSchemaVariable || r.outputSchemaVariable || r.agentVariable
+		)
 		.map((route) => {
 			const routeKey = route.method ? `${route.method.toUpperCase()} ${route.path}` : route.path;
 			const safeName = routeKey
@@ -707,7 +725,12 @@ export function generateRouteRegistry(
 			.replace(/_+/g, '_');
 		const pascalName = toPascalCase(safeName);
 
-		if (!route.hasValidator && !route.inputSchemaVariable && !route.outputSchemaVariable) {
+		if (
+			!route.hasValidator &&
+			!route.inputSchemaVariable &&
+			!route.outputSchemaVariable &&
+			!route.agentVariable
+		) {
 			const streamValue = route.stream === true ? 'true' : 'false';
 			return `\t'${routeKey}': {
 \t\tinputSchema: never;

package/src/cmd/build/vite/server-bundler.ts

@@ -9,6 +9,37 @@ import type { Logger } from '../../../types';
 import type { BunPlugin } from 'bun';
 import { generatePatches, applyPatch } from '../patch';
 
+/**
+ * Format a Bun build log (BuildMessage or ResolveMessage) into a readable string
+ */
+export function formatBuildLog(log: BuildMessage | ResolveMessage): string {
+	const parts: string[] = [];
+
+	// For ResolveMessage, format with specifier info
+	if (log.name === 'ResolveMessage') {
+		const resolveLog = log as ResolveMessage;
+		if (resolveLog.specifier) {
+			parts.push(`Could not resolve "${resolveLog.specifier}"`);
+			// Use referrer if available, otherwise fall back to position.file
+			const referrer = resolveLog.referrer || resolveLog.position?.file;
+			if (referrer) {
+				parts.push(`  imported from: ${referrer}`);
+			}
+		} else if (resolveLog.message) {
+			parts.push(resolveLog.message);
+		}
+	} else if (log.message) {
+		parts.push(log.message);
+	}
+
+	// Add position info if available (only if we haven't already shown referrer from position)
+	if (log.position && log.name !== 'ResolveMessage') {
+		parts.push(`  at ${log.position.file}:${log.position.line}:${log.position.column}`);
+	}
+
+	return parts.join('\n');
+}
+
 export interface ServerBundleOptions {
 	rootDir: string;
 	dev: boolean;
@@ -282,19 +313,29 @@ export async function installExternalsAndBuild(options: ServerBundleOptions): Pr
 		if (originalNodeEnv !== undefined) {
 			process.env.NODE_ENV = originalNodeEnv;
 		}
-		logger.error('Bun.build threw an exception');
 
 		// Handle AggregateError with build/resolve messages
 		if (error instanceof AggregateError && error.errors) {
-			for (const err of error.errors) {
-				const parts = [err.message || err.text || 'Unknown error'];
-				if (err.position) {
-					parts.push(`  at ${err.position.file}:${err.position.line}:${err.position.column}`);
-				}
-				logger.error(parts.join('\n'));
-			}
-		} else {
-			logger.error(`  ${error instanceof Error ? error.message : String(error)}`);
+			const formattedErrors = error.errors
+				.map((err) => {
+					// Try to use formatBuildLog if it looks like a BuildMessage/ResolveMessage
+					if (err && typeof err === 'object' && 'name' in err) {
+						const formatted = formatBuildLog(err as BuildMessage | ResolveMessage);
+						if (formatted) return formatted;
+					}
+					// Fallback for other error types
+					const parts = [err.message || err.text || 'Unknown error'];
+					if (err.position) {
+						parts.push(
+							`  at ${err.position.file}:${err.position.line}:${err.position.column}`
+						);
+					}
+					return parts.join('\n');
+				})
+				.filter(Boolean)
+				.join('\n');
+
+			throw new Error(formattedErrors || 'Build failed');
 		}
 
 		throw error;
@@ -306,19 +347,9 @@ export async function installExternalsAndBuild(options: ServerBundleOptions): Pr
 	}
 
 	if (!result.success) {
-		logger.error('Bun.build failed for server');
-		logger.error(
-			`Build result: success=${result.success}, outputs=${result.outputs.length}, logs=${result.logs.length}`
-		);
-
 		const errorMessages = result.logs
-			.map((log) => {
-				const parts = [log.message];
-				if (log.position) {
-					parts.push(`  at ${log.position.file}:${log.position.line}:${log.position.column}`);
-				}
-				return parts.join('\n');
-			})
+			.map((log) => formatBuildLog(log))
+			.filter(Boolean)
 			.join('\n');
 
 		throw new Error(errorMessages || 'Build failed with no error messages');

package/src/cmd/build/vite/vite-asset-server-config.ts

@@ -69,6 +69,11 @@ export async function generateAssetServerConfig(
 			dedupe: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
 		},
 
+		// Pre-bundle @agentuity/workbench to avoid React preamble issues with pre-built JSX
+		optimizeDeps: {
+			include: ['@agentuity/workbench', '@agentuity/core', '@agentuity/react'],
+		},
+
 		// Only allow frontend env vars (server uses process.env)
 		envPrefix: ['VITE_', 'AGENTUITY_PUBLIC_', 'PUBLIC_'],