@agentuity/cli 0.0.109 → 0.0.111

package/src/cmd/build/typecheck.ts

@@ -1,5 +1,6 @@
 import { parse, type GrammarItem } from '../../tsc-output-parser';
 import { formatTypeScriptErrors, hasErrors } from '../../typescript-errors';
+import type { BuildReportCollector } from '../../build-report';
 
 interface TypeError {
 	success: false;
@@ -18,13 +19,20 @@ interface TypeSuccess {
 
 type TypeResult = TypeError | TypeSuccess | TypeUnknownError;
 
+export interface TypecheckOptions {
+	/** Optional collector for structured error reporting */
+	collector?: BuildReportCollector;
+}
+
 /**
  * run the typescript compiler and result formatted results
  *
  * @param dir the absolute path to the directory containing the project (must have tsconfig.json in this folder)
+ * @param options optional configuration including error collector
  * @returns
  */
-export async function typecheck(dir: string): Promise<TypeResult> {
+export async function typecheck(dir: string, options?: TypecheckOptions): Promise<TypeResult> {
+	const { collector } = options ?? {};
 	const result = await Bun.$`bunx tsc --noEmit --skipLibCheck --pretty false`
 		.cwd(dir)
 		.quiet()
@@ -38,6 +46,11 @@ export async function typecheck(dir: string): Promise<TypeResult> {
 			success: true,
 		};
 	} else if (errors && hasErrors(errors)) {
+		// Add errors to collector if provided
+		if (collector) {
+			collector.addTypeScriptErrors(errors);
+		}
+
 		const formattedErrors = await formatTypeScriptErrors(errors, {
 			projectDir: dir,
 		});
@@ -47,6 +60,11 @@ export async function typecheck(dir: string): Promise<TypeResult> {
 			output: formattedErrors,
 		};
 	} else {
+		// Unknown error - add to collector as general error
+		if (collector) {
+			collector.addGeneralError('typescript', output || result.stderr.toString());
+		}
+
 		return {
 			success: false,
 			output: output || result.stderr.toString(),

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

@@ -65,7 +65,7 @@ export interface AgentMetadata {
 
 export interface EvalMetadata {
 	id: string;
-	evalId: string;
+	identifier: string;
 	name: string;
 	filename: string;
 	version: string;
@@ -459,13 +459,13 @@ function extractEvalsFromSource(
 
 				if (evalName) {
 					const id = getEvalId(projectId, deploymentId, filename, evalName, version);
-					const evalId = generateStableEvalId(projectId, agentId, evalName);
+					const identifier = generateStableEvalId(projectId, agentId, evalName);
 
-					logger.trace(`Found eval '${evalName}' in ${filename} (evalId: ${evalId})`);
+					logger.trace(`Found eval '${evalName}' in ${filename} (identifier: ${identifier})`);
 
 					evals.push({
 						id,
-						evalId,
+						identifier,
 						name: evalName,
 						filename,
 						version,

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

@@ -1,7 +1,7 @@
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
 import { createLogger } from '@agentuity/server';
-import type { LogLevel } from '../../../types';
+import type { LogLevel, DeployOptions } from '../../../types';
 import { discoverAgents, type AgentMetadata } from './agent-discovery';
 import { discoverRoutes, type RouteMetadata, type RouteInfo } from './route-discovery';
 import { generateAgentRegistry, generateRouteRegistry } from './registry-generator';
@@ -20,6 +20,7 @@ export interface AgentuityPluginOptions {
 	orgId?: string;
 	deploymentId?: string;
 	logLevel?: LogLevel;
+	deploymentOptions?: DeployOptions;
 }
 
 /**
@@ -42,6 +43,7 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 		orgId = '',
 		deploymentId = '',
 		logLevel = 'info',
+		deploymentOptions,
 	} = options;
 	const logger = createLogger(logLevel);
 	const srcDir = join(rootDir, 'src');
@@ -85,7 +87,7 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 			}
 
 			if (routeInfoList.length > 0) {
-				generateRouteRegistry(srcDir, routeInfoList, agents);
+				await generateRouteRegistry(srcDir, routeInfoList, agents);
 				logger.trace('Generated route registry with %d route(s)', routeInfoList.length);
 			}
 
@@ -153,6 +155,7 @@ export function agentuityPlugin(options: AgentuityPluginOptions): Plugin {
 				routes,
 				dev,
 				logger,
+				deploymentOptions,
 			});
 
 			// Write metadata file

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

@@ -443,7 +443,7 @@ export async function generateMetadata(options: MetadataGeneratorOptions): Promi
 			evals: agent.evals?.map((evalItem) => ({
 				filename: evalItem.filename,
 				id: evalItem.id,
-				evalId: evalItem.evalId,
+				identifier: evalItem.identifier,
 				name: evalItem.name,
 				version: evalItem.version,
 				description: evalItem.description,
@@ -478,12 +478,10 @@ export async function generateMetadata(options: MetadataGeneratorOptions): Promi
 		if (options.deploymentOptions.pullRequestNumber) {
 			git.pull_request = {
 				number: options.deploymentOptions.pullRequestNumber,
-				commentId: options.deploymentOptions.pullRequestCommentId,
-				url: options.deploymentOptions.pullRequestURL,
+				url: options.deploymentOptions.pullRequestUrl,
 			};
-			delete git.pullRequestCommentId;
 			delete git.pullRequestNumber;
-			delete git.pullRequestURL;
+			delete git.pullRequestUrl;
 		}
 		metadata.deployment.git = git;
 	}
@@ -706,10 +704,10 @@ function generateAgentsMd(metadata: BuildMetadata): string {
 	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/'))) {
+	if (metadata.assets?.some((a: { filename: string }) => a.filename.startsWith('client/'))) {
 		lines.push('├── client/                # Frontend assets (fallback, CDN by default)');
 	}
-	if (metadata.assets?.some((a) => a.filename.startsWith('public/'))) {
+	if (metadata.assets?.some((a: { filename: string }) => a.filename.startsWith('public/'))) {
 		lines.push('├── public/                # Static assets');
 	}
 	lines.push('└── AGENTS.md                  # This file');

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

@@ -6,6 +6,7 @@
 
 import { join } from 'node:path';
 import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
 import { StructuredError } from '@agentuity/core';
 import { toCamelCase, toPascalCase } from '../../../utils/string';
 import type { AgentMetadata } from './agent-discovery';
@@ -29,6 +30,28 @@ function sanitizePathSegment(segment: string): string {
 	return toCamelCase(segment.replace(ROUTE_PARAM_CHARS, ''));
 }
 
+/**
+ * Generate TypeScript type for path parameters.
+ * Returns 'never' if no path params, or '{ param1: string; param2: string }' format.
+ */
+function generatePathParamsType(pathParams?: string[]): string {
+	if (!pathParams || pathParams.length === 0) {
+		return 'never';
+	}
+	return `{ ${pathParams.map((p) => `${p}: string`).join('; ')} }`;
+}
+
+/**
+ * Generate TypeScript tuple type for path parameters (for positional args).
+ * Returns '[]' if no path params, or '[string, string]' format.
+ */
+function generatePathParamsTupleType(pathParams?: string[]): string {
+	if (!pathParams || pathParams.length === 0) {
+		return '[]';
+	}
+	return `[${pathParams.map(() => 'string').join(', ')}]`;
+}
+
 /**
  * Generate src/generated/registry.ts with agent registry and types
  */
@@ -36,11 +59,14 @@ export function generateAgentRegistry(srcDir: string, agents: AgentMetadata[]):
 	const generatedDir = join(srcDir, 'generated');
 	const registryPath = join(generatedDir, 'registry.ts');
 
+	// Sort agents by name for deterministic output
+	const sortedAgents = [...agents].sort((a, b) => a.name.localeCompare(b.name));
+
 	// Detect naming collisions in generated identifiers
 	const generatedNames = new Set<string>();
 	const collisions: string[] = [];
 
-	for (const agent of agents) {
+	for (const agent of sortedAgents) {
 		const camelName = toCamelCase(agent.name);
 
 		if (generatedNames.has(camelName)) {
@@ -59,7 +85,7 @@ export function generateAgentRegistry(srcDir: string, agents: AgentMetadata[]):
 	}
 
 	// Generate imports for all agents
-	const imports = agents
+	const imports = sortedAgents
 		.map(({ name, filename }) => {
 			const camelName = toCamelCase(name);
 			// Handle both './agent/...' and 'src/agent/...' formats
@@ -80,7 +106,7 @@ export function generateAgentRegistry(srcDir: string, agents: AgentMetadata[]):
 		.join('\n');
 
 	// Generate schema type exports for all agents
-	const schemaTypeExports = agents
+	const schemaTypeExports = sortedAgents
 		.map(({ name, description }) => {
 			const camelName = toCamelCase(name);
 			const pascalName = toPascalCase(name);
@@ -122,7 +148,7 @@ export function generateAgentRegistry(srcDir: string, agents: AgentMetadata[]):
 		.join('\n');
 
 	// Generate flat registry structure with JSDoc
-	const registry = agents
+	const registry = sortedAgents
 		.map(({ name, description }) => {
 			const camelName = toCamelCase(name);
 			const pascalName = toPascalCase(name);
@@ -138,7 +164,7 @@ export function generateAgentRegistry(srcDir: string, agents: AgentMetadata[]):
 
 	// Generate flat agent type definitions for AgentRegistry interface augmentation
 	// Uses the exported Agent types defined above
-	const runtimeAgentTypes = agents
+	const runtimeAgentTypes = sortedAgents
 		.map(({ name }) => {
 			const camelName = toCamelCase(name);
 			const pascalName = toPascalCase(name);
@@ -231,7 +257,7 @@ function generateRPCRegistryType(
 	apiRoutes: RouteInfo[],
 	websocketRoutes: RouteInfo[],
 	sseRoutes: RouteInfo[],
-	_agentImports: Map<string, string>,
+	agentImports: Map<string, string>,
 	_schemaImportAliases: Map<string, Map<string, string>>,
 	agentMetadataMap: Map<string, AgentMetadata>
 ): string {
@@ -263,6 +289,10 @@ function generateRPCRegistryType(
 		// Add path segments - sanitize for valid TypeScript property names
 		for (let i = 0; i < pathParts.length; i++) {
 			const part = sanitizePathSegment(pathParts[i]);
+			// Skip empty segments (e.g., wildcards like '*' that sanitize to '')
+			if (!part) {
+				continue;
+			}
 			if (!current[part]) {
 				current[part] = {};
 			}
@@ -292,8 +322,12 @@ function generateRPCRegistryType(
 		// Only reference type names if route has actual schemas extracted, otherwise use 'never'
 		// Note: hasValidator may be true (e.g., zValidator('query', ...)) but no schemas extracted
 		// because only 'json' validators extract input schemas
+		// Also check if agentVariable exists but import wasn't added (missing agentImportPath)
+		const hasValidAgentImport = route.agentVariable
+			? !!agentImports.get(route.agentVariable)
+			: false;
 		const hasSchemas =
-			route.inputSchemaVariable || route.outputSchemaVariable || route.agentVariable;
+			route.inputSchemaVariable || route.outputSchemaVariable || hasValidAgentImport;
 
 		current[terminalMethod] = {
 			input: hasSchemas ? `${pascalName}Input` : 'never',
@@ -315,7 +349,9 @@ function generateRPCRegistryType(
 	function treeToTypeString(node: NestedNode, indent: string = '\t\t'): string {
 		const lines: string[] = [];
 
-		for (const [key, value] of Object.entries(node)) {
+		// Sort entries alphabetically for deterministic output
+		const sortedEntries = Object.entries(node).sort(([a], [b]) => a.localeCompare(b));
+		for (const [key, value] of sortedEntries) {
 			if (
 				value &&
 				typeof value === 'object' &&
@@ -349,8 +385,10 @@ function generateRPCRegistryType(
 				jsdoc.push(`${indent} */`);
 				lines.push(...jsdoc);
 
+				const pathParamsType = generatePathParamsType(routeInfo.pathParams);
+				const pathParamsTupleType = generatePathParamsTupleType(routeInfo.pathParams);
 				lines.push(
-					`${indent}${key}: { input: ${value.input}; output: ${value.output}; type: ${value.type} };`
+					`${indent}${key}: { input: ${value.input}; output: ${value.output}; type: ${value.type}; params: ${pathParamsType}; paramsTuple: ${pathParamsTupleType} };`
 				);
 			} else {
 				// Nested node
@@ -380,7 +418,7 @@ function generateRPCRuntimeMetadata(
 	sseRoutes: RouteInfo[]
 ): string {
 	interface MetadataNode {
-		[key: string]: MetadataNode | { type: string };
+		[key: string]: MetadataNode | { type: string; path: string; pathParams?: string[] };
 	}
 
 	const tree: MetadataNode = {};
@@ -400,6 +438,10 @@ function generateRPCRuntimeMetadata(
 		// Sanitize path segments for valid property names (must match type generation)
 		for (const part of pathParts) {
 			const sanitized = sanitizePathSegment(part);
+			// Skip empty segments (e.g., wildcards like '*' that sanitize to '')
+			if (!sanitized) {
+				continue;
+			}
 			if (!current[sanitized]) current[sanitized] = {};
 			current = current[sanitized];
 		}
@@ -414,14 +456,35 @@ function generateRPCRuntimeMetadata(
 						? 'stream'
 						: route.method.toLowerCase();
 
-		current[terminalMethod] = { type: routeType };
+		const metadata: { type: string; path: string; pathParams?: string[] } = {
+			type: routeType,
+			path: route.path,
+		};
+		if (route.pathParams && route.pathParams.length > 0) {
+			metadata.pathParams = route.pathParams;
+		}
+		current[terminalMethod] = metadata;
 	};
 
 	apiRoutes.forEach((r) => addRoute(r, r.routeType === 'stream' ? 'stream' : 'api'));
 	websocketRoutes.forEach((r) => addRoute(r, 'websocket'));
 	sseRoutes.forEach((r) => addRoute(r, 'sse'));
 
-	return JSON.stringify(tree, null, '\t\t');
+	// Sort object keys recursively for deterministic output
+	const sortObject = (obj: MetadataNode): MetadataNode => {
+		const sorted: MetadataNode = {};
+		for (const key of Object.keys(obj).sort()) {
+			const value = obj[key];
+			if (value && typeof value === 'object' && !('type' in value)) {
+				sorted[key] = sortObject(value as MetadataNode);
+			} else {
+				sorted[key] = value;
+			}
+		}
+		return sorted;
+	};
+
+	return JSON.stringify(sortObject(tree), null, '\t\t');
 }
 
 /**
@@ -430,15 +493,15 @@ function generateRPCRuntimeMetadata(
  * Creates a module augmentation for @agentuity/react that provides
  * strongly-typed route keys with input/output schema information.
  */
-export function generateRouteRegistry(
+export async function generateRouteRegistry(
 	srcDir: string,
 	routes: RouteInfo[],
 	agents: AgentMetadata[] = []
-): void {
-	// Check if project uses @agentuity/react
+): Promise<void> {
 	const projectRoot = join(srcDir, '..');
 	const packageJsonPath = join(projectRoot, 'package.json');
 	let hasReactDependency = false;
+	let hasFrontendDependency = false;
 
 	try {
 		const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
@@ -446,14 +509,32 @@ export function generateRouteRegistry(
 			packageJson.dependencies?.['@agentuity/react'] ||
 			packageJson.devDependencies?.['@agentuity/react']
 		);
+		hasFrontendDependency = !!(
+			packageJson.dependencies?.['@agentuity/frontend'] ||
+			packageJson.devDependencies?.['@agentuity/frontend']
+		);
+	} catch {
+		// If we can't read package.json, assume no frontend dependencies
+	}
+
+	const webDir = join(srcDir, 'web');
+	let hasWebDirectory = false;
+	try {
+		const webDirStat = await stat(webDir);
+		hasWebDirectory = webDirStat.isDirectory();
 	} catch {
-		// If we can't read package.json, assume no React dependency
+		// Directory doesn't exist
 	}
 
-	// Filter routes by type
-	const apiRoutes = routes.filter((r) => r.routeType === 'api' || r.routeType === 'stream');
-	const websocketRoutes = routes.filter((r) => r.routeType === 'websocket');
-	const sseRoutes = routes.filter((r) => r.routeType === 'sse');
+	const shouldEmitFrontendClient = hasFrontendDependency && !hasReactDependency && hasWebDirectory;
+
+	// Filter routes by type and sort by path for deterministic output
+	const sortByPath = (a: RouteInfo, b: RouteInfo) => a.path.localeCompare(b.path);
+	const apiRoutes = routes
+		.filter((r) => r.routeType === 'api' || r.routeType === 'stream')
+		.sort(sortByPath);
+	const websocketRoutes = routes.filter((r) => r.routeType === 'websocket').sort(sortByPath);
+	const sseRoutes = routes.filter((r) => r.routeType === 'sse').sort(sortByPath);
 
 	const allRoutes = [...apiRoutes, ...websocketRoutes, ...sseRoutes];
 
@@ -637,8 +718,10 @@ export function generateRouteRegistry(
 				agentMeta = agentMetadataMap.get(route.agentVariable);
 			}
 
-			if (route.agentVariable) {
-				const importName = agentImports.get(route.agentVariable)!;
+			// Only generate agent-based types if the import was successfully added
+			// (import is only added when hasValidator && agentVariable && agentImportPath are all present)
+			const importName = route.agentVariable ? agentImports.get(route.agentVariable) : undefined;
+			if (importName) {
 				inputType = `InferInput<typeof ${importName}['inputSchema']>`;
 				outputType = `InferOutput<typeof ${importName}['outputSchema']>`;
 				inputSchemaType = `typeof ${importName} extends { inputSchema?: infer I } ? I : never`;
@@ -724,20 +807,28 @@ export function generateRouteRegistry(
 			.replace(/_+/g, '_');
 		const pascalName = toPascalCase(safeName);
 
+		// Use the exported schema types we generated above
+		// Note: agentImports.get() may return undefined if import wasn't added
+		const importName = route.agentVariable ? agentImports.get(route.agentVariable) : null;
+
 		// Use 'never' types if no schemas were actually extracted
 		// Note: hasValidator may be true (e.g., zValidator('query', ...)) but no schemas extracted
 		// because only 'json' validators extract input schemas
-		if (!route.inputSchemaVariable && !route.outputSchemaVariable && !route.agentVariable) {
+		// Also check if agentVariable exists but import wasn't added (missing agentImportPath)
+		const hasValidAgentImport = route.agentVariable ? !!importName : false;
+
+		// Generate pathParams type
+		const pathParamsType = generatePathParamsType(route.pathParams);
+
+		if (!route.inputSchemaVariable && !route.outputSchemaVariable && !hasValidAgentImport) {
 			const streamValue = route.stream === true ? 'true' : 'false';
 			return `\t'${routeKey}': {
-\t\tinputSchema: never;
-\t\toutputSchema: never;
-\t\tstream: ${streamValue};
-\t};`;
+		\t\tinputSchema: never;
+		\t\toutputSchema: never;
+		\t\tstream: ${streamValue};
+		\t\tparams: ${pathParamsType};
+		\t};`;
 		}
-
-		// Use the exported schema types we generated above
-		const importName = route.agentVariable ? agentImports.get(route.agentVariable)! : null;
 		const streamValue = importName
 			? `typeof ${importName} extends { stream?: infer S } ? S : false`
 			: route.stream === true
@@ -745,10 +836,11 @@ export function generateRouteRegistry(
 				: 'false';
 
 		return `\t'${routeKey}': {
-\t\tinputSchema: ${pascalName}InputSchema;
-\t\toutputSchema: ${pascalName}OutputSchema;
-\t\tstream: ${streamValue};
-\t};`;
+		\t\tinputSchema: ${pascalName}InputSchema;
+		\t\toutputSchema: ${pascalName}OutputSchema;
+		\t\tstream: ${streamValue};
+		\t\tparams: ${pathParamsType};
+		\t};`;
 	};
 
 	// Generate route entries with METHOD prefix for API routes
@@ -778,7 +870,7 @@ export function generateRouteRegistry(
 	const generatedContent = `// @generated
 // Auto-generated by Agentuity - DO NOT EDIT
 ${importsStr}${typeImports}${
-		!hasReactDependency
+		shouldEmitFrontendClient
 			? `
 import { createClient } from '@agentuity/frontend';`
 			: ''
@@ -803,7 +895,7 @@ ${routeSchemaTypes}
  * Individual route Input/Output types are exported above for direct usage.
  */
 ${
-	!hasReactDependency
+	shouldEmitFrontendClient
 		? `
 /**
  * RPC Route Registry
@@ -868,13 +960,14 @@ if (typeof globalThis !== 'undefined') {
 	(globalThis as Record<string, unknown>).__rpcRouteMetadata = _rpcRouteMetadata;
 }
 ${
-	!hasReactDependency
+	shouldEmitFrontendClient
 		? `
 /**
  * Create a type-safe API client with optional configuration.
  *
- * This function is only generated when @agentuity/react is not installed.
- * If using React, import createAPIClient from '@agentuity/react' instead.
+ * This function is only generated when @agentuity/frontend is installed
+ * but @agentuity/react is not. For React apps, import createAPIClient
+ * from '@agentuity/react' instead.
  *
  * @example
  * \`\`\`typescript
@@ -893,7 +986,8 @@ export function createAPIClient(options?: Parameters<typeof createClient>[0]): i
 	return createClient(options || {}, _rpcRouteMetadata) as import('@agentuity/frontend').Client<RPCRouteRegistry>;
 }
 `
-		: `
+		: hasReactDependency
+			? `
 /**
  * Type-safe API client is available from @agentuity/react
  *
@@ -906,6 +1000,7 @@ export function createAPIClient(options?: Parameters<typeof createClient>[0]): i
  * \`\`\`
  */
 `
+			: ''
 }
 
 // FOUND AN ERROR IN THIS FILE?
@@ -916,9 +1011,7 @@ export function createAPIClient(options?: Parameters<typeof createClient>[0]): i
 	const generatedDir = join(srcDir, 'generated');
 	const registryPath = join(generatedDir, 'routes.ts');
 
-	if (!existsSync(generatedDir)) {
-		mkdirSync(generatedDir, { recursive: true });
-	}
+	mkdirSync(generatedDir, { recursive: true });
 
 	// Collapse 2+ consecutive empty lines into 1 empty line (3+ \n becomes 2 \n)
 	const cleanedContent = generatedContent.replace(/\n{3,}/g, '\n\n');

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

@@ -40,6 +40,24 @@ export interface RouteInfo {
 	inputSchemaCode?: string;
 	outputSchemaCode?: string;
 	stream?: boolean;
+	pathParams?: string[];
+}
+
+/**
+ * Extract path parameters from a route path.
+ * Matches patterns like :id, :userId, :id?, *path, etc.
+ */
+export function extractPathParams(path: string): string[] {
+	const params: string[] = [];
+	const parts = path.split('/');
+	for (const part of parts) {
+		if (part.startsWith(':')) {
+			params.push(part.replace(/^:|[?+*]$/g, ''));
+		} else if (part.startsWith('*') && part.length > 1) {
+			params.push(part.substring(1).replace(/[?+*]$/g, ''));
+		}
+	}
+	return params;
 }
 
 /**
@@ -90,6 +108,7 @@ export async function discoverRoutes(
 
 					// Convert to RouteInfo for registry
 					for (const route of parsedRoutes) {
+						const pathParams = extractPathParams(route.path);
 						routeInfoList.push({
 							method: route.method.toUpperCase(),
 							path: route.path,
@@ -106,6 +125,7 @@ export async function discoverRoutes(
 									: route.type === 'stream'
 										? true
 										: undefined,
+							pathParams: pathParams.length > 0 ? pathParams : undefined,
 						});
 					}
 				}

package/src/cmd/build/vite/vite-builder.ts

@@ -10,6 +10,7 @@ import { createRequire } from 'node:module';
 import type { InlineConfig, Plugin } from 'vite';
 import type { Logger, DeployOptions } from '../../../types';
 import { browserEnvPlugin } from './browser-env-plugin';
+import type { BuildReportCollector } from '../../../build-report';
 
 /**
  * Vite plugin to flatten the output structure for index.html
@@ -56,6 +57,8 @@ export interface ViteBuildOptions {
 	workbenchEnabled?: boolean;
 	logger: Logger;
 	deploymentOptions?: DeployOptions;
+	/** Optional collector for structured error reporting */
+	collector?: BuildReportCollector;
 }
 
 /**
@@ -256,7 +259,7 @@ interface BuildResult {
  * Run all builds in sequence: client -> workbench (if enabled) -> server
  */
 export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Promise<BuildResult> {
-	const { rootDir, projectId = '', dev = false, logger } = options;
+	const { rootDir, projectId = '', dev = false, logger, collector } = options;
 
 	if (!dev) {
 		rmSync(join(rootDir, '.agentuity'), { force: true, recursive: true });
@@ -302,7 +305,7 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 	// Generate agent and route registries for type augmentation BEFORE builds
 	// (TypeScript needs these files to exist during type checking)
 	generateAgentRegistry(srcDir, agentMetadata);
-	generateRouteRegistry(srcDir, routeInfoList);
+	await generateRouteRegistry(srcDir, routeInfoList);
 	logger.debug('Agent and route registries generated');
 
 	// Check if web frontend exists
@@ -311,6 +314,7 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 	// 2. Build client (only if web frontend exists)
 	if (hasWebFrontend) {
 		logger.debug('Building client assets...');
+		const endClientDiagnostic = collector?.startDiagnostic('client-build');
 		const started = Date.now();
 		await runViteBuild({
 			...options,
@@ -320,6 +324,7 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 		});
 		result.client.included = true;
 		result.client.duration = Date.now() - started;
+		endClientDiagnostic?.();
 	} else {
 		logger.debug('Skipping client build - no src/web/index.html found');
 	}
@@ -327,6 +332,7 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 	// 3. Build workbench (if enabled in config)
 	if (workbenchConfig.enabled) {
 		logger.debug('Building workbench assets...');
+		const endWorkbenchDiagnostic = collector?.startDiagnostic('workbench-build');
 		const started = Date.now();
 		await runViteBuild({
 			...options,
@@ -336,17 +342,21 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 		});
 		result.workbench.included = true;
 		result.workbench.duration = Date.now() - started;
+		endWorkbenchDiagnostic?.();
 	}
 
 	// 4. Build server
 	logger.debug('Building server...');
+	const endServerDiagnostic = collector?.startDiagnostic('server-build');
 	const serverStarted = Date.now();
 	await runViteBuild({ ...options, mode: 'server' });
 	result.server.included = true;
 	result.server.duration = Date.now() - serverStarted;
+	endServerDiagnostic?.();
 
 	// 5. Generate metadata (after all builds complete)
 	logger.debug('Generating metadata...');
+	const endMetadataDiagnostic = collector?.startDiagnostic('metadata-generation');
 	const { generateMetadata, writeMetadataFile } = await import('./metadata-generator');
 
 	// Generate metadata
@@ -363,6 +373,7 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 	});
 
 	writeMetadataFile(rootDir, metadata, dev, logger);
+	endMetadataDiagnostic?.();
 	logger.debug('Registry and metadata generation complete');
 
 	logger.debug('All builds complete');