@agentuity/cli 0.0.60 → 0.0.62

package/src/cmd/build/ast.ts

@@ -1,16 +1,26 @@
 import * as acornLoose from 'acorn-loose';
 import { basename, dirname, relative } from 'node:path';
+import { parse as parseCronExpression } from '@datasert/cronjs-parser';
 import { generate } from 'astring';
 import type { BuildMetadata } from '../../types';
 import { createLogger } from '@agentuity/server';
 import * as ts from 'typescript';
-import type { WorkbenchConfig } from '@agentuity/core';
+import { StructuredError, type WorkbenchConfig } from '@agentuity/core';
 import type { LogLevel } from '../../types';
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import JSON5 from 'json5';
 
 const logger = createLogger((process.env.AGENTUITY_LOG_LEVEL || 'info') as LogLevel);
 
+interface ASTProgram extends ASTNode {
+	body: ASTNode[];
+}
+
 interface ASTNode {
 	type: string;
+	start?: number;
+	end?: number;
 }
 
 interface ASTNodeIdentifier extends ASTNode {
@@ -166,6 +176,11 @@ function generateStableEvalId(projectId: string, agentId: string, name: string):
 
 type AcornParseResultType = ReturnType<typeof acornLoose.parse>;
 
+const MetadataError = StructuredError('MetatadataNameMissingError')<{
+	filename: string;
+	line?: number;
+}>();
+
 function augmentAgentMetadataNode(
 	projectId: string,
 	id: string,
@@ -178,17 +193,21 @@ function augmentAgentMetadataNode(
 ): [string, Map<string, string>] {
 	const metadata = parseObjectExpressionToMap(propvalue);
 	if (!metadata.has('name')) {
-		const location = ast.loc?.start ? ` on line ${ast.loc.start}` : '';
-		throw new Error(
-			`missing required metadata.name in ${filename}${location}. This Agent should have a unique and human readable name for this project.`
-		);
+		const location = ast.loc?.start?.line ? ` on line ${ast.loc.start.line}` : '';
+		throw new MetadataError({
+			filename,
+			line: ast.loc?.start?.line,
+			message: `missing required metadata.name in ${filename}${location}. This Agent should have a unique and human readable name for this project.`,
+		});
 	}
 	const name = metadata.get('name')!;
 	if (metadata.has('identifier') && identifier !== metadata.get('identifier')) {
-		const location = ast.loc?.start ? ` on line ${ast.loc.start}` : '';
-		throw new Error(
-			`metadata.identifier (${metadata.get('identifier')}) in ${filename}${location} is mismatched (${name}). This is an internal error.`
-		);
+		const location = ast.loc?.start?.line ? ` on line ${ast.loc.start.line}` : '';
+		throw new MetadataError({
+			filename,
+			line: ast.loc?.start?.line,
+			message: `metadata.identifier (${metadata.get('identifier')}) in ${filename}${location} is mismatched (${name}). This is an internal error.`,
+		});
 	}
 	const descriptionNode = propvalue.properties.find((x) => x.key.name === 'description')?.value;
 	const description = descriptionNode ? (descriptionNode as ASTLiteral).value : '';
@@ -244,7 +263,7 @@ function createAgentMetadataNode(
 function camelToKebab(str: string): string {
 	return str
 		.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-		.replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
 		.toLowerCase();
 }
 
@@ -367,6 +386,8 @@ function augmentEvalMetadataNode(
 	}
 }
 
+const DuplicateNameError = StructuredError('DuplicateNameError')<{ filename: string }>();
+
 export function parseEvalMetadata(
 	rootDir: string,
 	filename: string,
@@ -394,7 +415,11 @@ export function parseEvalMetadata(
 		| 'error';
 	const logger = createLogger(logLevel);
 	logger.trace(`Parsing evals from ${filename}`);
-	const ast = acornLoose.parse(contents, { ecmaVersion: 'latest', sourceType: 'module' });
+	const ast = acornLoose.parse(contents, {
+		locations: true,
+		ecmaVersion: 'latest',
+		sourceType: 'module',
+	});
 	const rel = relative(rootDir, filename);
 	const version = hash(contents);
 	const evals: Array<{
@@ -484,9 +509,12 @@ export function parseEvalMetadata(
 									} else if (variableName) {
 										finalName = camelToKebab(variableName);
 									} else {
-										throw new Error(
-											'Eval is missing a name. Please provide metadata.name or use a named export.'
-										);
+										throw new MetadataError({
+											filename,
+											line: body.loc?.start?.line,
+											message:
+												'Eval is missing a name. Please provide metadata.name or use a named export.',
+										});
 									}
 
 									logger.trace(
@@ -563,10 +591,12 @@ export function parseEvalMetadata(
 	}
 
 	if (duplicates.length > 0) {
-		throw new Error(
-			`Duplicate eval names found in ${rel}: ${duplicates.join(', ')}. ` +
-				'Eval names must be unique within the same file to prevent ID collisions.'
-		);
+		throw new DuplicateNameError({
+			filename,
+			message:
+				`Duplicate eval names found in ${rel}: ${duplicates.join(', ')}. ` +
+				'Eval names must be unique within the same file to prevent ID collisions.',
+		});
 	}
 
 	const newsource = generate(ast);
@@ -574,6 +604,9 @@ export function parseEvalMetadata(
 	return [newsource, evals];
 }
 
+const InvalidExportError = StructuredError('InvalidExportError')<{ filename: string }>();
+const InvalidCreateAgentError = StructuredError('InvalidCreateAgentError')<{ filename: string }>();
+
 export async function parseAgentMetadata(
 	rootDir: string,
 	filename: string,
@@ -581,7 +614,11 @@ export async function parseAgentMetadata(
 	projectId: string,
 	deploymentId: string
 ): Promise<[string, Map<string, string>]> {
-	const ast = acornLoose.parse(contents, { ecmaVersion: 'latest', sourceType: 'module' });
+	const ast = acornLoose.parse(contents, {
+		locations: true,
+		ecmaVersion: 'latest',
+		sourceType: 'module',
+	});
 	let exportName: string | undefined;
 	const rel = relative(rootDir, filename);
 	const name = basename(dirname(filename));
@@ -635,7 +672,10 @@ export async function parseAgentMetadata(
 		}
 	}
 	if (!result && !exportName) {
-		throw new Error(`could not find default export for ${filename} using ${rootDir}`);
+		throw new InvalidExportError({
+			filename,
+			message: `could not find default export for ${filename} using ${rootDir}`,
+		});
 	}
 	if (!result) {
 		for (const body of ast.body) {
@@ -689,9 +729,10 @@ export async function parseAgentMetadata(
 		}
 	}
 	if (!result) {
-		throw new Error(
-			`error parsing: ${filename}. could not find an proper createAgent defined in this file`
-		);
+		throw new InvalidCreateAgentError({
+			filename,
+			message: `error parsing: ${filename}. could not find an proper createAgent defined in this file`,
+		});
 	}
 
 	// Parse evals from eval.ts file in the same directory
@@ -735,6 +776,15 @@ export async function parseAgentMetadata(
 
 type RouteDefinition = BuildMetadata['routes'];
 
+const InvalidCreateRouterError = StructuredError('InvalidCreateRouterError')<{
+	filename: string;
+}>();
+
+const InvalidRouterConfigError = StructuredError('InvalidRouterConfigError')<{
+	filename: string;
+	line?: number;
+}>();
+
 export async function parseRoute(
 	rootDir: string,
 	filename: string,
@@ -743,7 +793,11 @@ export async function parseRoute(
 ): Promise<BuildMetadata['routes']> {
 	const contents = await Bun.file(filename).text();
 	const version = hash(contents);
-	const ast = acornLoose.parse(contents, { ecmaVersion: 'latest', sourceType: 'module' });
+	const ast = acornLoose.parse(contents, {
+		locations: true,
+		ecmaVersion: 'latest',
+		sourceType: 'module',
+	});
 	let exportName: string | undefined;
 	let variableName: string | undefined;
 	for (const body of ast.body) {
@@ -754,7 +808,10 @@ export async function parseRoute(
 		}
 	}
 	if (!exportName) {
-		throw new Error(`could not find default export for ${filename} using ${rootDir}`);
+		throw new InvalidExportError({
+			filename,
+			message: `could not find default export for ${filename} using ${rootDir}`,
+		});
 	}
 	for (const body of ast.body) {
 		if (body.type === 'VariableDeclaration') {
@@ -775,9 +832,10 @@ export async function parseRoute(
 		}
 	}
 	if (!variableName) {
-		throw new Error(
-			`error parsing: ${filename}. could not find an proper createRouter defined in this file`
-		);
+		throw new InvalidCreateRouterError({
+			filename,
+			message: `error parsing: ${filename}. could not find an proper createRouter defined in this file`,
+		});
 	}
 
 	const rel = relative(rootDir, filename);
@@ -831,9 +889,11 @@ export async function parseRoute(
 								if (action && (action as ASTLiteral).type === 'Literal') {
 									suffix = (action as ASTLiteral).value;
 								} else {
-									throw new Error(
-										`unsupported HTTP method ${method} in ${filename} at line ${body.start}`
-									);
+									throw new InvalidRouterConfigError({
+										filename,
+										line: body.loc?.start?.line,
+										message: `unsupported HTTP method ${method} in ${filename} at line ${body.loc?.start?.line}`,
+									});
 								}
 								break;
 							}
@@ -886,16 +946,29 @@ export async function parseRoute(
 								method = 'post';
 								const theaction = action as ASTLiteral;
 								if (theaction.type === 'Literal') {
-									const number = theaction.value;
-									suffix = hash(number);
+									const expression = theaction.value;
+									try {
+										parseCronExpression(expression, { hasSeconds: false });
+									} catch (ex) {
+										throw new InvalidRouterConfigError({
+											filename,
+											cause: ex,
+											line: body.loc?.start?.line,
+											message: `invalid cron expression "${expression}" in ${filename} at line ${body.loc?.start?.line}`,
+										});
+									}
+									suffix = hash(expression);
+									config = { expression };
 									break;
 								}
 								break;
 							}
 							default: {
-								throw new Error(
-									`unsupported router method ${method} in ${filename} at line ${body.start}`
-								);
+								throw new InvalidRouterConfigError({
+									filename,
+									line: body.loc?.start?.line,
+									message: `unsupported router method ${method} in ${filename} at line ${body.loc?.start?.line}`,
+								});
 							}
 						}
 						const thepath = `${routePrefix}/${routeName}/${suffix}`
@@ -924,8 +997,13 @@ export async function parseRoute(
 			}
 		}
 	} catch (error) {
-		const err = error instanceof Error ? error : new Error(String(error));
-		throw new Error(`Failed to parse route file ${filename}: ${err.message}`);
+		if (error instanceof InvalidRouterConfigError) {
+			throw error;
+		}
+		throw new InvalidRouterConfigError({
+			filename,
+			cause: error,
+		});
 	}
 	return routes;
 }
@@ -1019,6 +1097,431 @@ export function checkRouteConflicts(content: string, workbenchEndpoint: string):
 	}
 }
 
+/**
+ * Extract AppState type from setup() return value in createApp call
+ *
+ * @param content - The TypeScript source code from app.ts
+ * @returns Type definition string or null if no setup found
+ */
+export function extractAppStateType(content: string): string | null {
+	try {
+		const sourceFile = ts.createSourceFile('app.ts', content, ts.ScriptTarget.Latest, true);
+		let appStateType: string | null = null;
+		let foundCreateApp = false;
+		let foundSetup = false;
+
+		function visitNode(node: ts.Node): void {
+			// Look for createApp call expression (can be on await expression)
+			let callExpr: ts.CallExpression | undefined;
+
+			if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+				if (node.expression.text === 'createApp') {
+					foundCreateApp = true;
+					callExpr = node;
+				}
+			} else if (ts.isAwaitExpression(node) && ts.isCallExpression(node.expression)) {
+				const call = node.expression;
+				if (ts.isIdentifier(call.expression) && call.expression.text === 'createApp') {
+					foundCreateApp = true;
+					callExpr = call;
+				}
+			}
+
+			if (callExpr) {
+				// Check if it has a config object argument
+				if (callExpr.arguments.length > 0) {
+					const configArg = callExpr.arguments[0];
+					if (ts.isObjectLiteralExpression(configArg)) {
+						// Find setup property
+						for (const prop of configArg.properties) {
+							if (
+								ts.isPropertyAssignment(prop) &&
+								ts.isIdentifier(prop.name) &&
+								prop.name.text === 'setup'
+							) {
+								foundSetup = true;
+								// Found setup function - extract return type
+								const setupFunc = prop.initializer;
+								if (ts.isFunctionExpression(setupFunc) || ts.isArrowFunction(setupFunc)) {
+									// Find return statement
+									const returnObj = findReturnObject(setupFunc);
+									if (returnObj) {
+										appStateType = objectLiteralToTypeDefinition(returnObj, sourceFile);
+									} else {
+										logger.debug('No return object found in setup function');
+									}
+								} else {
+									logger.debug(
+										`Setup is not a function expression or arrow function, it's: ${ts.SyntaxKind[setupFunc.kind]}`
+									);
+								}
+							}
+						}
+					}
+				}
+			}
+
+			ts.forEachChild(node, visitNode);
+		}
+
+		function findReturnObject(
+			func: ts.FunctionExpression | ts.ArrowFunction
+		): ts.ObjectLiteralExpression | null {
+			let returnObject: ts.ObjectLiteralExpression | null = null;
+
+			function visitFuncNode(node: ts.Node): void {
+				if (ts.isReturnStatement(node) && node.expression) {
+					// Handle direct object literal
+					if (ts.isObjectLiteralExpression(node.expression)) {
+						returnObject = node.expression;
+					}
+					// Handle variable reference (const state = {...}; return state;)
+					else if (ts.isIdentifier(node.expression)) {
+						// Try to find the variable declaration
+						const varName = node.expression.text;
+						// Walk back through the function to find the declaration
+						findVariableDeclaration(func.body!, varName);
+					}
+				}
+				ts.forEachChild(node, visitFuncNode);
+			}
+
+			function findVariableDeclaration(body: ts.Node, varName: string): void {
+				function visitForVar(node: ts.Node): void {
+					if (ts.isVariableStatement(node)) {
+						for (const decl of node.declarationList.declarations) {
+							if (ts.isIdentifier(decl.name) && decl.name.text === varName) {
+								if (decl.initializer && ts.isObjectLiteralExpression(decl.initializer)) {
+									returnObject = decl.initializer;
+								}
+							}
+						}
+					}
+					ts.forEachChild(node, visitForVar);
+				}
+				visitForVar(body);
+			}
+
+			if (func.body) {
+				visitFuncNode(func.body);
+			}
+
+			return returnObject;
+		}
+
+		function objectLiteralToTypeDefinition(
+			obj: ts.ObjectLiteralExpression,
+			sourceFile: ts.SourceFile
+		): string {
+			const properties: string[] = [];
+
+			for (const prop of obj.properties) {
+				if (ts.isPropertyAssignment(prop)) {
+					const name = prop.name.getText(sourceFile);
+					const value = prop.initializer;
+					const typeStr = inferTypeFromValue(value, sourceFile);
+					properties.push(`\t${name}: ${typeStr};`);
+				} else if (ts.isShorthandPropertyAssignment(prop)) {
+					const name = prop.name.getText(sourceFile);
+					properties.push(`\t${name}: unknown;`);
+				}
+			}
+
+			return `{\n${properties.join('\n')}\n}`;
+		}
+
+		function inferTypeFromValue(value: ts.Expression, sourceFile: ts.SourceFile): string {
+			if (ts.isStringLiteral(value)) {
+				return 'string';
+			}
+			if (ts.isNumericLiteral(value)) {
+				return 'number';
+			}
+			if (
+				value.kind === ts.SyntaxKind.TrueKeyword ||
+				value.kind === ts.SyntaxKind.FalseKeyword
+			) {
+				return 'boolean';
+			}
+			if (ts.isNewExpression(value) && ts.isIdentifier(value.expression)) {
+				if (value.expression.text === 'Date') {
+					return 'Date';
+				}
+			}
+			if (ts.isObjectLiteralExpression(value)) {
+				return objectLiteralToTypeDefinition(value, sourceFile);
+			}
+			if (ts.isArrayLiteralExpression(value)) {
+				return 'unknown[]';
+			}
+			return 'unknown';
+		}
+
+		visitNode(sourceFile);
+
+		if (!foundCreateApp) {
+			logger.debug('Did not find createApp call in app.ts');
+		} else if (!foundSetup) {
+			logger.debug('Found createApp but no setup property');
+		} else if (!appStateType) {
+			logger.debug('Found createApp and setup but could not extract type');
+		}
+
+		return appStateType;
+	} catch (error) {
+		logger.warn('AppState type extraction failed:', error);
+		return null;
+	}
+}
+
+/**
+ * Update tsconfig.json to add path mapping for @agentuity/runtime
+ *
+ * @param rootDir - Root directory of the project
+ * @param shouldAdd - If true, add the mapping; if false, remove it
+ */
+async function updateTsconfigPathMapping(rootDir: string, shouldAdd: boolean): Promise<void> {
+	const tsconfigPath = join(rootDir, 'tsconfig.json');
+
+	if (!(await Bun.file(tsconfigPath).exists())) {
+		logger.debug('No tsconfig.json found, skipping path mapping update');
+		return;
+	}
+
+	try {
+		const tsconfigContent = await Bun.file(tsconfigPath).text();
+
+		// Use JSON5 to parse tsconfig.json (handles comments in input)
+		const tsconfig = JSON5.parse(tsconfigContent);
+		const _before = JSON.stringify(tsconfig);
+
+		// Initialize compilerOptions and paths if they don't exist
+		if (!tsconfig.compilerOptions) {
+			tsconfig.compilerOptions = {};
+		}
+		if (!tsconfig.compilerOptions.paths) {
+			tsconfig.compilerOptions.paths = {};
+		}
+
+		if (shouldAdd) {
+			// Add or update the path mapping
+			tsconfig.compilerOptions.paths['@agentuity/runtime'] = [
+				'./.agentuity/.agentuity_runtime.ts',
+			];
+
+			// Ensure .agentuity_types.ts is included so module augmentation works
+			if (!tsconfig.include) {
+				tsconfig.include = [];
+			}
+			if (!tsconfig.include.includes('.agentuity/.agentuity_types.ts')) {
+				tsconfig.include.push('.agentuity/.agentuity_types.ts');
+			}
+
+			logger.debug('Added @agentuity/runtime path mapping to tsconfig.json');
+		} else {
+			// Remove the path mapping if it exists
+			if (tsconfig.compilerOptions.paths['@agentuity/runtime']) {
+				delete tsconfig.compilerOptions.paths['@agentuity/runtime'];
+				logger.debug('Removed @agentuity/runtime path mapping from tsconfig.json');
+			}
+
+			// Clean up empty paths object
+			if (Object.keys(tsconfig.compilerOptions.paths).length === 0) {
+				delete tsconfig.compilerOptions.paths;
+			}
+		}
+
+		const _after = JSON.stringify(tsconfig);
+		if (_before === _after) {
+			return;
+		}
+
+		// Write back using standard JSON (TypeScript requires strict JSON format)
+		await Bun.write(tsconfigPath, JSON.stringify(tsconfig, null, '\t') + '\n');
+	} catch (error) {
+		logger.warn('Failed to update tsconfig.json:', error);
+	}
+}
+
+const RuntimePackageNotFound = StructuredError('RuntimePackageNotFound');
+
+/**
+ * Generate lifecycle type files (.agentuity/types.ts and .agentuity/.agentuity_runtime.ts)
+ *
+ * @param rootDir - Root directory of the project
+ * @param appFilePath - Path to app.ts file
+ * @returns true if files were generated, false if no setup found
+ */
+export async function generateLifecycleTypes(
+	rootDir: string,
+	outDir: string,
+	appFilePath: string
+): Promise<boolean> {
+	const appContent = await Bun.file(appFilePath).text();
+	if (typeof appContent !== 'string') {
+		return false;
+	}
+
+	const appStateType = extractAppStateType(appContent as string);
+
+	if (!appStateType) {
+		logger.debug('No setup() function found in app.ts, skipping lifecycle type generation');
+		// Remove path mapping if no setup found
+		await updateTsconfigPathMapping(rootDir, false);
+		return false;
+	}
+
+	const agentuityDir = join(rootDir, '.agentuity');
+
+	// Ensure .agentuity directory exists
+	if (!existsSync(agentuityDir)) {
+		mkdirSync(agentuityDir, { recursive: true });
+	}
+
+	// First, determine the runtime package location
+	// Try multiple locations: app-level node_modules, then monorepo root
+	const appLevelPath = join(rootDir, 'node_modules', '@agentuity', 'runtime');
+	// From apps/testing/auth-app to monorepo root is 3 levels up (../../..)
+	const rootLevelPath = join(rootDir, '..', '..', '..', 'node_modules', '@agentuity', 'runtime');
+
+	let runtimePkgPath: string;
+	if (existsSync(appLevelPath)) {
+		runtimePkgPath = appLevelPath;
+		logger.debug(`Found runtime package at app level: ${appLevelPath}`);
+	} else if (existsSync(rootLevelPath)) {
+		runtimePkgPath = rootLevelPath;
+		logger.debug(`Found runtime package at root level: ${rootLevelPath}`);
+	} else {
+		throw new RuntimePackageNotFound({
+			message:
+				`@agentuity/runtime package not found in:\n` +
+				`  - ${appLevelPath}\n` +
+				`  - ${rootLevelPath}\n` +
+				`Make sure dependencies are installed by running 'bun install' or 'npm install'`,
+		});
+	}
+
+	let runtimeImportPath: string | null = null;
+
+	// Calculate relative path from .agentuity/ to the package location
+	// Don't resolve symlinks - we want to use the symlink path so it works in both
+	// local dev (symlinked to packages/) and CI (actual node_modules)
+	if (existsSync(runtimePkgPath)) {
+		// Calculate relative path from .agentuity/ to node_modules package
+		const relPath = relative(agentuityDir, runtimePkgPath);
+		runtimeImportPath = relPath;
+		logger.debug(`Using relative path to runtime package: ${relPath}`);
+	} else {
+		throw new RuntimePackageNotFound({
+			message:
+				`Failed to access @agentuity/runtime package at ${runtimePkgPath}\n` +
+				`Make sure dependencies are installed`,
+		});
+	}
+
+	if (!runtimeImportPath) {
+		throw new RuntimePackageNotFound({
+			message: `Failed to determine import path for @agentuity/runtime`,
+		});
+	}
+
+	// Now generate .agentuity_types.ts
+	// NOTE: We can ONLY augment the package name, not relative paths
+	// TypeScript resolves @agentuity/runtime through path mapping -> wrapper -> actual package
+	const typesContent = `// AUTO-GENERATED from app.ts setup() return type
+// This file is auto-generated by the build tool - do not edit manually
+
+/**
+ * Application state type inferred from your createApp setup function.
+ * This type is automatically generated and available throughout your app via ctx.app.
+ *
+ * @example
+ * \`\`\`typescript
+ * // In your agents:
+ * const agent = createAgent({
+ *   handler: async (ctx, input) => {
+ *     // ctx.app is strongly typed as GeneratedAppState
+ *     const value = ctx.app; // All properties from your setup return value
+ *     return 'result';
+ *   }
+ * });
+ * \`\`\`
+ */
+export type GeneratedAppState = ${appStateType};
+
+// Augment the @agentuity/runtime module with AppState
+// This will be picked up when imported through the wrapper
+declare module '@agentuity/runtime' {
+	interface AppState extends GeneratedAppState {}
+}
+`;
+	const typesPath = join(outDir, '.agentuity_types.ts');
+	await Bun.write(typesPath, typesContent);
+	logger.debug(`Generated lifecycle types: ${typesPath}`);
+
+	const wrapperContent = `// AUTO-GENERATED runtime wrapper
+// This file is auto-generated by the build tool - do not edit manually
+
+// Import augmentations file (NOT type-only) to trigger module augmentation
+import type { GeneratedAppState } from './.agentuity_types';
+import './.agentuity_types';
+
+// Import from actual package location
+import { createRouter as baseCreateRouter, type Env } from '${runtimeImportPath}/src/index';
+import type { Hono } from 'hono';
+
+// Type aliases to avoid repeating the generic parameter
+type AppEnv = Env<GeneratedAppState>;
+type AppRouter = Hono<AppEnv>;
+
+/**
+ * Creates a Hono router with extended methods for Agentuity-specific routing patterns.
+ *
+ * In addition to standard HTTP methods (get, post, put, delete, patch), the router includes:
+ * - **stream()** - Stream responses with ReadableStream
+ * - **websocket()** - WebSocket connections
+ * - **sse()** - Server-Sent Events
+ * - **email()** - Email handler routing
+ * - **sms()** - SMS handler routing
+ * - **cron()** - Scheduled task routing
+ *
+ * @returns Extended Hono router with custom methods and app state typing
+ *
+ * @example
+ * \`\`\`typescript
+ * const router = createRouter();
+ *
+ * // Standard HTTP routes
+ * router.get('/hello', (c) => c.text('Hello!'));
+ * router.post('/data', async (c) => {
+ *   const body = await c.req.json();
+ *   return c.json({ received: body });
+ * });
+ *
+ * // Access app state (strongly typed!)
+ * router.get('/db', (c) => {
+ *   const db = c.var.app; // Your app state from createApp setup
+ *   return c.json({ connected: true });
+ * });
+ * \`\`\`
+ */
+export function createRouter(): AppRouter {
+	return baseCreateRouter() as any;
+}
+
+// Re-export everything else
+export * from '${runtimeImportPath}/src/index';
+`;
+	const wrapperPath = join(outDir, '.agentuity_runtime.ts');
+	await Bun.write(wrapperPath, wrapperContent);
+	logger.debug(`Generated lifecycle wrapper: ${wrapperPath}`);
+
+	// Update tsconfig.json with path mapping
+	await updateTsconfigPathMapping(rootDir, true);
+
+	return true;
+}
+
 /**
  * Analyze workbench usage and extract configuration
  *
@@ -1115,3 +1618,98 @@ function parseConfigObject(node: ts.Node): WorkbenchConfig | null {
 
 	return config;
 }
+
+/**
+ * Find the end position of createApp call statement in the source code
+ * Uses AST parsing to reliably find the complete statement including await/const assignment
+ *
+ * @param content - The source code content
+ * @returns The character position after the createApp statement, or -1 if not found
+ */
+export function findCreateAppEndPosition(content: string): number {
+	try {
+		const ast = acornLoose.parse(content, {
+			ecmaVersion: 'latest',
+			sourceType: 'module',
+		}) as ASTProgram;
+
+		// Walk through all top-level statements
+		for (const node of ast.body) {
+			let targetNode: ASTNode | undefined;
+
+			// Check for: const app = await createApp(...)
+			if (node.type === 'VariableDeclaration') {
+				const varDecl = node as unknown as { declarations: ASTVariableDeclarator[] };
+				for (const declarator of varDecl.declarations) {
+					if (declarator.init) {
+						// Handle await createApp(...)
+						if (declarator.init.type === 'AwaitExpression') {
+							const awaitExpr = declarator.init as unknown as {
+								argument: ASTCallExpression;
+							};
+							if (
+								awaitExpr.argument?.type === 'CallExpression' &&
+								isCreateAppCall(awaitExpr.argument)
+							) {
+								targetNode = node;
+								break;
+							}
+						}
+						// Handle createApp(...) without await
+						else if (declarator.init.type === 'CallExpression') {
+							if (isCreateAppCall(declarator.init as ASTCallExpression)) {
+								targetNode = node;
+								break;
+							}
+						}
+					}
+				}
+			}
+			// Check for: await createApp(...)
+			else if (node.type === 'ExpressionStatement') {
+				const exprStmt = node as ASTExpressionStatement;
+				if (exprStmt.expression.type === 'AwaitExpression') {
+					const awaitExpr = exprStmt.expression as unknown as { argument: ASTCallExpression };
+					if (
+						awaitExpr.argument?.type === 'CallExpression' &&
+						isCreateAppCall(awaitExpr.argument)
+					) {
+						targetNode = node;
+					}
+				} else if (exprStmt.expression.type === 'CallExpression') {
+					if (isCreateAppCall(exprStmt.expression as ASTCallExpression)) {
+						targetNode = node;
+					}
+				}
+			}
+
+			if (targetNode && targetNode.end !== undefined) {
+				// Find the semicolon after the statement (if it exists)
+				const afterStmt = content.slice(targetNode.end);
+				const semiMatch = afterStmt.match(/^\s*;/);
+				if (semiMatch) {
+					return targetNode.end + semiMatch[0].length;
+				}
+				// No semicolon, return end of statement
+				return targetNode.end;
+			}
+		}
+
+		return -1;
+	} catch (error) {
+		logger.warn('Failed to parse AST for createApp detection:', error);
+		return -1;
+	}
+}
+
+/**
+ * Check if a CallExpression is a call to createApp
+ */
+function isCreateAppCall(node: ASTCallExpression): boolean {
+	const callee = node.callee;
+	if (callee.type === 'Identifier') {
+		const id = callee as ASTNodeIdentifier;
+		return id.name === 'createApp';
+	}
+	return false;
+}