@agentuity/cli 0.0.100 → 0.0.102

package/dist/cmd/build/vite/registry-generator.js

@@ -1,20 +1,33 @@
 /**
  * Registry Generator
  *
- * Generates .agentuity/registry.generated.ts from discovered agents
+ * Generates src/generated/registry.ts from discovered agents
  */
 import { join } from 'node:path';
-import { writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
+import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync } from 'node:fs';
 import { StructuredError } from '@agentuity/core';
 import { toCamelCase, toPascalCase } from '../../../utils/string';
 const AgentIdentifierCollisionError = StructuredError('AgentIdentifierCollisionError');
 /**
- * Generate .agentuity/registry.generated.ts with agent registry and types
+ * 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) {
+    return toCamelCase(segment.replace(ROUTE_PARAM_CHARS, ''));
+}
+/**
+ * Generate src/generated/registry.ts with agent registry and types
  */
 export function generateAgentRegistry(srcDir, agents) {
-    const projectRoot = join(srcDir, '..');
-    const agentuityDir = join(projectRoot, '.agentuity');
-    const registryPath = join(agentuityDir, 'registry.generated.ts');
+    const generatedDir = join(srcDir, 'generated');
+    const registryPath = join(generatedDir, 'registry.ts');
     // Detect naming collisions in generated identifiers
     const generatedNames = new Set();
     const collisions = [];
@@ -39,57 +52,126 @@ export function generateAgentRegistry(srcDir, agents) {
         // Handle both './agent/...' and 'src/agent/...' formats
         let relativePath = filename;
         if (relativePath.startsWith('./agent/')) {
-            relativePath = relativePath.replace(/^\.\/agent\//, '../src/agent/');
+            // ./agent/foo.ts -> ../agent/foo.js (use .js extension for TypeScript)
+            relativePath = relativePath
+                .replace(/^\.\/agent\//, '../agent/')
+                .replace(/\.tsx?$/, '.js');
         }
         else if (relativePath.startsWith('src/agent/')) {
-            relativePath = '../' + relativePath;
+            // src/agent/foo.ts -> ../agent/foo.js (use .js extension for TypeScript)
+            relativePath = relativePath
+                .replace(/^src\/agent\//, '../agent/')
+                .replace(/\.tsx?$/, '.js');
         }
         return `import ${camelName} from '${relativePath}';`;
     })
         .join('\n');
-    // Generate flat registry structure
-    const registry = agents
-        .map(({ name }) => {
+    // Generate schema type exports for all agents
+    const schemaTypeExports = agents
+        .map(({ name, description }) => {
         const camelName = toCamelCase(name);
-        return `  ${camelName}: ${camelName},`;
+        const pascalName = toPascalCase(name);
+        const descComment = description ? `\n * ${description}` : '';
+        const parts = [
+            '',
+            `/**`,
+            ` * Input type for ${name} agent${descComment}`,
+            ` */`,
+            `export type ${pascalName}Input = InferInput<typeof ${camelName}['inputSchema']>;`,
+            '',
+            `/**`,
+            ` * Output type for ${name} agent${descComment}`,
+            ` */`,
+            `export type ${pascalName}Output = InferOutput<typeof ${camelName}['outputSchema']>;`,
+            '',
+            `/**`,
+            ` * Input schema type for ${name} agent${descComment}`,
+            ` */`,
+            `export type ${pascalName}InputSchema = typeof ${camelName}['inputSchema'];`,
+            '',
+            `/**`,
+            ` * Output schema type for ${name} agent${descComment}`,
+            ` */`,
+            `export type ${pascalName}OutputSchema = typeof ${camelName}['outputSchema'];`,
+            '',
+            `/**`,
+            ` * Agent type for ${name}${descComment}`,
+            ` */`,
+            `export type ${pascalName}Agent = AgentRunner<`,
+            `\t${pascalName}InputSchema,`,
+            `\t${pascalName}OutputSchema,`,
+            `\ttypeof ${camelName}['stream'] extends true ? true : false`,
+            `>;`,
+        ];
+        return parts.join('\n');
     })
         .join('\n');
-    // Generate type exports for all agents
-    const typeExports = agents
-        .map(({ name }) => {
+    // Generate flat registry structure with JSDoc
+    const registry = agents
+        .map(({ name, description }) => {
         const camelName = toCamelCase(name);
         const pascalName = toPascalCase(name);
-        return `export type ${pascalName}Runner = AgentRunner<typeof ${camelName}['inputSchema'], typeof ${camelName}['outputSchema'], typeof ${camelName}['stream'] extends true ? true : false>;`;
+        const descComment = description ? `\n\t * ${description}` : '';
+        return `\t/**
+\t * ${name}${descComment}
+\t * @type {${pascalName}Agent}
+\t */
+\t${camelName},`;
     })
         .join('\n');
     // Generate flat agent type definitions for AgentRegistry interface augmentation
+    // Uses the exported Agent types defined above
     const runtimeAgentTypes = agents
         .map(({ name }) => {
         const camelName = toCamelCase(name);
-        return `		${camelName}: AgentRunner<typeof ${camelName}['inputSchema'], typeof ${camelName}['outputSchema'], typeof ${camelName}['stream'] extends true ? true : false>;`;
+        const pascalName = toPascalCase(name);
+        return `		${camelName}: ${pascalName}Agent;`;
     })
         .join('\n');
-    const generatedContent = `/// <reference types="hono" />
-// Auto-generated by Agentuity - do not edit manually
+    const generatedContent = `// @generated
+// Auto-generated by Agentuity - DO NOT EDIT
 ${imports}
-import type { AgentRunner, Logger } from '@agentuity/runtime';
-import type { KeyValueStorage, StreamStorage, VectorStorage } from '@agentuity/core';
+import type { AgentRunner } from '@agentuity/runtime';
+import type { InferInput, InferOutput } from '@agentuity/core';
+
+// ============================================================================
+// Schema Type Exports
+// ============================================================================
+${schemaTypeExports}
+
+// ============================================================================
+// Agent Definitions
+// ============================================================================
 
 /**
+ * Agent Definitions
+ * 
  * Registry of all agents in this application.
  * Provides strongly-typed access to agent metadata and runner functions.
- * Auto-generated from your agent files during build.
+ * 
+ * @remarks
+ * This object is auto-generated from your agent files during build.
+ * Each agent has corresponding Input, Output, and Runner types exported above.
+ * 
+ * @example
+ * \`\`\`typescript
+ * import { AgentDefinitions, SessionBasicInput } from './generated/registry';
+ * 
+ * // Access agent definition
+ * const agent = AgentDefinitions.sessionBasic;
+ * 
+ * // Use typed schema types
+ * const input: SessionBasicInput = { ... };
+ * const result = await agent.run(input);
+ * \`\`\`
  */
-export const agentRegistry = {
+export const AgentDefinitions = {
 ${registry}
 } as const;
 
-// Local type aliases for Hono augmentation
-type LocalAgentName = keyof typeof agentRegistry;
-type LocalAgentRegistry = typeof agentRegistry;
-
-// Typed runners for each agent
-${typeExports}
+// ============================================================================
+// Module Augmentation
+// ============================================================================
 
 // Augment @agentuity/runtime types with strongly-typed agents from this project
 declare module "@agentuity/runtime" {
@@ -99,32 +181,220 @@ ${runtimeAgentTypes}
 	}
 }
 
-// NOTE: Hono Context properties are accessed via c.var (e.g., c.var.logger, c.var.kv)
-// The Variables interface in @agentuity/runtime defines all available context properties
+// FOUND AN ERROR IN THIS FILE?
+// Please file an issue at https://github.com/agentuity/sdk/issues
+// or if you know the fix please submit a PR!
 `;
     const agentsDir = join(srcDir, 'agent');
     const legacyTypesPath = join(agentsDir, 'types.generated.d.ts');
-    // Ensure .agentuity directory exists
-    if (!existsSync(agentuityDir)) {
-        mkdirSync(agentuityDir, { recursive: true });
+    // Ensure src/generated directory exists
+    if (!existsSync(generatedDir)) {
+        mkdirSync(generatedDir, { recursive: true });
     }
-    writeFileSync(registryPath, generatedContent, 'utf-8');
-    // Remove legacy types.generated.d.ts if it exists (now consolidated into registry.generated.ts)
+    // Collapse 2+ consecutive empty lines into 1 empty line (3+ \n becomes 2 \n)
+    const cleanedContent = generatedContent.replace(/\n{3,}/g, '\n\n');
+    writeFileSync(registryPath, cleanedContent, 'utf-8');
+    // Remove legacy types.generated.d.ts if it exists (legacy cleanup)
     if (existsSync(legacyTypesPath)) {
         unlinkSync(legacyTypesPath);
     }
 }
+/**
+ * Helper function to generate RPC-style nested registry type.
+ * Converts routes like "POST /api/hello" to nested structure: post.api.hello
+ */
+function generateRPCRegistryType(apiRoutes, websocketRoutes, sseRoutes, _agentImports, _schemaImportAliases, agentMetadataMap) {
+    const tree = {};
+    // Helper to add route to tree
+    const addRoute = (route, routeType) => {
+        const method = route.method.toLowerCase();
+        // Strip /api prefix from path
+        let cleanPath = route.path;
+        if (cleanPath.startsWith('/api/')) {
+            cleanPath = cleanPath.substring(4); // Remove '/api'
+        }
+        else if (cleanPath === '/api') {
+            cleanPath = '/';
+        }
+        const pathParts = cleanPath.split('/').filter(Boolean);
+        // Navigate/create tree structure: path segments first, then method
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let current = tree;
+        // Add path segments - sanitize for valid TypeScript property names
+        for (let i = 0; i < pathParts.length; i++) {
+            const part = sanitizePathSegment(pathParts[i]);
+            if (!current[part]) {
+                current[part] = {};
+            }
+            current = current[part];
+        }
+        // Determine terminal method name based on route type
+        // For stream types (websocket, sse, stream), use the type name as the method
+        // For regular API routes, use the HTTP method
+        const terminalMethod = routeType === 'websocket'
+            ? 'websocket'
+            : routeType === 'sse'
+                ? 'eventstream'
+                : routeType === 'stream'
+                    ? 'stream'
+                    : method;
+        // Add method as final level with schema types
+        const routeKey = `${route.method.toUpperCase()} ${route.path}`;
+        const safeName = routeKey
+            .replace(/[^a-zA-Z0-9]/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .replace(/_+/g, '_');
+        const pascalName = toPascalCase(safeName);
+        // Only reference type names if route has schemas, otherwise use 'never'
+        const hasSchemas = route.hasValidator ||
+            route.inputSchemaVariable ||
+            route.outputSchemaVariable ||
+            route.agentVariable;
+        current[terminalMethod] = {
+            input: hasSchemas ? `${pascalName}Input` : 'never',
+            output: hasSchemas ? `${pascalName}Output` : 'never',
+            type: `'${routeType}'`,
+            route,
+        };
+    };
+    // Add all routes with their types
+    apiRoutes.forEach((route) => {
+        const routeType = route.routeType === 'stream' ? 'stream' : 'api';
+        addRoute(route, routeType);
+    });
+    websocketRoutes.forEach((route) => addRoute(route, 'websocket'));
+    sseRoutes.forEach((route) => addRoute(route, 'sse'));
+    // Convert tree to TypeScript type string
+    function treeToTypeString(node, indent = '\t\t') {
+        const lines = [];
+        for (const [key, value] of Object.entries(node)) {
+            if (value &&
+                typeof value === 'object' &&
+                'input' in value &&
+                'output' in value &&
+                'type' in value &&
+                'route' in value) {
+                // Leaf node with schema and type - add JSDoc
+                const route = value.route;
+                const jsdoc = [];
+                // Access route info from value
+                const routeInfo = route;
+                // Look up agent metadata
+                let agentMeta;
+                if (routeInfo.agentVariable) {
+                    agentMeta = agentMetadataMap.get(routeInfo.agentVariable);
+                }
+                // Build JSDoc comment
+                jsdoc.push(`${indent}/**`);
+                jsdoc.push(`${indent} * Route: ${routeInfo.method.toUpperCase()} ${routeInfo.path}`);
+                if (agentMeta?.name) {
+                    jsdoc.push(`${indent} * @agent ${agentMeta.name}`);
+                }
+                if (agentMeta?.description) {
+                    jsdoc.push(`${indent} * @description ${agentMeta.description}`);
+                }
+                jsdoc.push(`${indent} */`);
+                lines.push(...jsdoc);
+                lines.push(`${indent}${key}: { input: ${value.input}; output: ${value.output}; type: ${value.type} };`);
+            }
+            else {
+                // Nested node
+                lines.push(`${indent}${key}: {`);
+                lines.push(treeToTypeString(value, indent + '\t'));
+                lines.push(`${indent}};`);
+            }
+        }
+        return lines.join('\n');
+    }
+    if (Object.keys(tree).length === 0) {
+        return '\t\t// No routes discovered';
+    }
+    return treeToTypeString(tree);
+}
+/**
+ * Generate runtime metadata object for RPC routes.
+ * This allows the client to know route types at runtime.
+ */
+function generateRPCRuntimeMetadata(apiRoutes, websocketRoutes, sseRoutes) {
+    const tree = {};
+    const addRoute = (route, routeType) => {
+        let cleanPath = route.path;
+        if (cleanPath.startsWith('/api/')) {
+            cleanPath = cleanPath.substring(4);
+        }
+        else if (cleanPath === '/api') {
+            cleanPath = '/';
+        }
+        const pathParts = cleanPath.split('/').filter(Boolean);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let current = tree;
+        // Sanitize path segments for valid property names (must match type generation)
+        for (const part of pathParts) {
+            const sanitized = sanitizePathSegment(part);
+            if (!current[sanitized])
+                current[sanitized] = {};
+            current = current[sanitized];
+        }
+        // Use terminal method name based on route type
+        const terminalMethod = routeType === 'websocket'
+            ? 'websocket'
+            : routeType === 'sse'
+                ? 'eventstream'
+                : routeType === 'stream'
+                    ? 'stream'
+                    : route.method.toLowerCase();
+        current[terminalMethod] = { type: routeType };
+    };
+    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');
+}
 /**
  * Generate RouteRegistry type definitions from discovered routes.
  *
  * Creates a module augmentation for @agentuity/react that provides
  * strongly-typed route keys with input/output schema information.
  */
-export function generateRouteRegistry(srcDir, routes) {
+export function generateRouteRegistry(srcDir, routes, agents = []) {
+    // Check if project uses @agentuity/react
+    const projectRoot = join(srcDir, '..');
+    const packageJsonPath = join(projectRoot, 'package.json');
+    let hasReactDependency = false;
+    try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        hasReactDependency = !!(packageJson.dependencies?.['@agentuity/react'] ||
+            packageJson.devDependencies?.['@agentuity/react']);
+    }
+    catch {
+        // If we can't read package.json, assume no React dependency
+    }
     // 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 allRoutes = [...apiRoutes, ...websocketRoutes, ...sseRoutes];
+    // Create maps for agent metadata lookup
+    const agentMetadataMap = new Map();
+    const agentNameMap = new Map();
+    // Map by agent name for easy lookup
+    agents.forEach((agent) => {
+        agentNameMap.set(agent.name, agent);
+    });
+    // Map agent import variables to metadata by extracting agent name from import path
+    allRoutes.forEach((route) => {
+        if (route.agentVariable && route.agentImportPath) {
+            // Extract agent name from import path (e.g., "@agent/hello" -> "hello")
+            const match = route.agentImportPath.match(/@agent[s]?\/([^/]+)/);
+            if (match) {
+                const agentName = match[1];
+                const metadata = agentNameMap.get(agentName);
+                if (metadata) {
+                    agentMetadataMap.set(route.agentVariable, metadata);
+                }
+            }
+        }
+    });
     if (apiRoutes.length === 0 && websocketRoutes.length === 0 && sseRoutes.length === 0) {
         return;
     }
@@ -132,31 +402,84 @@ export function generateRouteRegistry(srcDir, routes) {
     const imports = [];
     const agentImports = new Map();
     const routeFileImports = new Map();
-    const allRoutes = [...apiRoutes, ...websocketRoutes, ...sseRoutes];
-    // Collect agent imports
+    // Collect agent and schema imports from routes with validators or exported schemas
     allRoutes.forEach((route) => {
-        if (!route.hasValidator)
+        const hasSchemaVars = !!route.inputSchemaVariable || !!route.outputSchemaVariable;
+        if (!route.hasValidator && !hasSchemaVars && !route.agentVariable)
             return;
-        if (route.agentVariable && route.agentImportPath && !agentImports.has(route.agentVariable)) {
+        // Collect agent imports (when using agent.validator())
+        if (route.hasValidator &&
+            route.agentVariable &&
+            route.agentImportPath &&
+            !agentImports.has(route.agentVariable)) {
             let resolvedPath = route.agentImportPath;
-            if (resolvedPath.startsWith('@agent/')) {
-                resolvedPath = `../src/agent/${resolvedPath.substring('@agent/'.length)}`;
+            if (resolvedPath.startsWith('@agents/') || resolvedPath.startsWith('@agent/')) {
+                // Handle both @agents/ and @agent/ aliases -> ../agent/
+                const suffix = resolvedPath.startsWith('@agents/')
+                    ? resolvedPath.substring('@agents/'.length)
+                    : resolvedPath.substring('@agent/'.length);
+                // Convert @agent/hello -> ../agent/hello/index.js
+                // Convert @agent/hello/agent -> ../agent/hello/agent.js
+                if (!suffix.includes('/')) {
+                    // Bare module (e.g., @agent/hello) - add /index.js
+                    resolvedPath = `../agent/${suffix}/index.js`;
+                }
+                else {
+                    // File path (e.g., @agent/hello/agent) - add .js
+                    const finalPath = suffix.endsWith('.js')
+                        ? suffix
+                        : suffix.replace(/\.tsx?$/, '') + '.js';
+                    resolvedPath = `../agent/${finalPath}`;
+                }
             }
             else if (resolvedPath.startsWith('@api/')) {
-                resolvedPath = `../src/web/${resolvedPath.substring('@api/'.length)}`;
+                // src/generated/ -> src/api/ is ../api/
+                const suffix = resolvedPath.substring('@api/'.length);
+                const finalPath = suffix.endsWith('.js')
+                    ? suffix
+                    : suffix.replace(/\.tsx?$/, '') + '.js';
+                resolvedPath = `../api/${finalPath}`;
             }
             else if (resolvedPath.startsWith('./') || resolvedPath.startsWith('../')) {
+                // Resolve relative import from route file's directory
                 const routeDir = route.filename.substring(0, route.filename.lastIndexOf('/'));
-                resolvedPath = `../${routeDir}/${resolvedPath}`;
+                // Join and normalize the path
+                const joined = `${routeDir}/${resolvedPath}`;
+                // Normalize by resolving .. and . segments
+                const normalized = joined
+                    .split('/')
+                    .reduce((acc, segment) => {
+                    if (segment === '..') {
+                        acc.pop();
+                    }
+                    else if (segment !== '.' && segment !== '') {
+                        acc.push(segment);
+                    }
+                    return acc;
+                }, [])
+                    .join('/');
+                // Remove 'src/' prefix if present (routes are in src/, generated is in src/generated/)
+                const withoutSrc = normalized.startsWith('src/') ? normalized.substring(4) : normalized;
+                // Make it relative from src/generated/
+                resolvedPath = `../${withoutSrc}`;
+                // Add .js extension if not already present
+                if (!resolvedPath.endsWith('.js')) {
+                    resolvedPath = resolvedPath.replace(/\.tsx?$/, '') + '.js';
+                }
             }
-            const uniqueImportName = `agent_${route.agentVariable}`;
+            const uniqueImportName = route.agentVariable;
             imports.push(`import type ${uniqueImportName} from '${resolvedPath}';`);
             agentImports.set(route.agentVariable, uniqueImportName);
         }
         // Collect schema variable imports
         if (route.inputSchemaVariable || route.outputSchemaVariable) {
             const filename = route.filename.replace(/\\/g, '/');
-            const importPath = `../${filename.replace(/\.ts$/, '')}`;
+            // Remove 'src/' prefix if present (routes.filename might be './api/...' or 'src/api/...')
+            const withoutSrc = filename.startsWith('src/') ? filename.substring(4) : filename;
+            const withoutLeadingDot = withoutSrc.startsWith('./')
+                ? withoutSrc.substring(2)
+                : withoutSrc;
+            const importPath = `../${withoutLeadingDot.replace(/\.ts$/, '')}`;
             if (!routeFileImports.has(importPath)) {
                 routeFileImports.set(importPath, new Set());
             }
@@ -168,83 +491,301 @@ export function generateRouteRegistry(srcDir, routes) {
             }
         }
     });
-    // Generate schema imports
+    // Generate schema imports with unique aliases to avoid conflicts
+    const schemaImportAliases = new Map(); // importPath -> (schemaName -> alias)
+    let aliasCounter = 0;
     routeFileImports.forEach((schemas, importPath) => {
-        const schemaList = Array.from(schemas).join(', ');
-        imports.push(`import type { ${schemaList} } from '${importPath}';`);
+        const aliases = new Map();
+        const importParts = [];
+        for (const schemaName of Array.from(schemas)) {
+            // Create a unique alias for this schema to avoid collisions
+            const alias = `${schemaName}_${aliasCounter++}`;
+            aliases.set(schemaName, alias);
+            importParts.push(`${schemaName} as ${alias}`);
+        }
+        schemaImportAliases.set(importPath, aliases);
+        imports.push(`import type { ${importParts.join(', ')} } from '${importPath}';`);
     });
-    const importsStr = imports.join('\n');
-    // Helper to generate route entry
-    const generateRouteEntry = (route) => {
-        const routeKey = route.path;
-        if (!route.hasValidator) {
-            const streamValue = route.stream === true ? 'true' : 'false';
-            return `  '${routeKey}': {
-    inputSchema: never;
-    outputSchema: never;
-    stream: ${streamValue};
-  };`;
+    const importsStr = imports.length > 0 ? imports.join('\n') + '\n' : '';
+    // Add InferInput/InferOutput imports if we have any routes with schemas
+    const hasSchemas = allRoutes.some((r) => r.hasValidator || r.inputSchemaVariable || r.outputSchemaVariable || r.agentVariable);
+    const typeImports = hasSchemas
+        ? `import type { InferInput, InferOutput } from '@agentuity/core';\n`
+        : '';
+    // Generate individual route schema types
+    const routeSchemaTypes = allRoutes
+        .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
+            .replace(/[^a-zA-Z0-9]/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .replace(/_+/g, '_');
+        const pascalName = toPascalCase(safeName);
+        let inputType = 'never';
+        let outputType = 'never';
+        let inputSchemaType = 'never';
+        let outputSchemaType = 'never';
+        let agentMeta;
+        // Look up agent metadata if available
+        if (route.agentVariable) {
+            agentMeta = agentMetadataMap.get(route.agentVariable);
         }
         if (route.agentVariable) {
             const importName = agentImports.get(route.agentVariable);
-            return `  '${routeKey}': {
-    inputSchema: typeof ${importName} extends { inputSchema?: infer I } ? I : never;
-    outputSchema: typeof ${importName} extends { outputSchema?: infer O } ? O : never;
-    stream: typeof ${importName} extends { stream?: infer S } ? S : false;
-  };`;
+            inputType = `InferInput<typeof ${importName}['inputSchema']>`;
+            outputType = `InferOutput<typeof ${importName}['outputSchema']>`;
+            inputSchemaType = `typeof ${importName} extends { inputSchema?: infer I } ? I : never`;
+            outputSchemaType = `typeof ${importName} extends { outputSchema?: infer O } ? O : never`;
         }
-        if (route.inputSchemaVariable || route.outputSchemaVariable) {
-            const inputType = route.inputSchemaVariable
-                ? `typeof ${route.inputSchemaVariable}`
-                : 'never';
-            const outputType = route.outputSchemaVariable
-                ? `typeof ${route.outputSchemaVariable}`
-                : 'never';
+        else if (route.inputSchemaVariable || route.outputSchemaVariable) {
+            // Get the aliased schema names for this route's file
+            const filename = route.filename.replace(/\\/g, '/');
+            const withoutSrc = filename.startsWith('src/') ? filename.substring(4) : filename;
+            const withoutLeadingDot = withoutSrc.startsWith('./')
+                ? withoutSrc.substring(2)
+                : withoutSrc;
+            const importPath = `../${withoutLeadingDot.replace(/\.ts$/, '')}`;
+            const aliases = schemaImportAliases.get(importPath);
+            const inputAlias = route.inputSchemaVariable && aliases?.get(route.inputSchemaVariable);
+            const outputAlias = route.outputSchemaVariable && aliases?.get(route.outputSchemaVariable);
+            inputType = inputAlias ? `InferInput<typeof ${inputAlias}>` : 'never';
+            outputType = outputAlias ? `InferOutput<typeof ${outputAlias}>` : 'never';
+            inputSchemaType = inputAlias ? `typeof ${inputAlias}` : 'never';
+            outputSchemaType = outputAlias ? `typeof ${outputAlias}` : 'never';
+        }
+        if (inputType === 'never' && outputType === 'never') {
+            return ''; // Skip routes without schemas
+        }
+        // Build JSDoc with agent description and schema details
+        const inputJSDoc = ['/**', ` * Input type for route: ${routeKey}`];
+        if (agentMeta?.description) {
+            inputJSDoc.push(` * @description ${agentMeta.description}`);
+        }
+        if (agentMeta?.inputSchemaCode) {
+            inputJSDoc.push(` * @schema ${agentMeta.inputSchemaCode}`);
+        }
+        inputJSDoc.push(' */');
+        const outputJSDoc = ['/**', ` * Output type for route: ${routeKey}`];
+        if (agentMeta?.description) {
+            outputJSDoc.push(` * @description ${agentMeta.description}`);
+        }
+        if (agentMeta?.outputSchemaCode) {
+            outputJSDoc.push(` * @schema ${agentMeta.outputSchemaCode}`);
+        }
+        outputJSDoc.push(' */');
+        const parts = [
+            '',
+            ...inputJSDoc,
+            `export type ${pascalName}Input = ${inputType};`,
+            '',
+            ...outputJSDoc,
+            `export type ${pascalName}Output = ${outputType};`,
+            '',
+            `/**`,
+            ` * Input schema type for route: ${routeKey}`,
+            ` */`,
+            `export type ${pascalName}InputSchema = ${inputSchemaType};`,
+            '',
+            `/**`,
+            ` * Output schema type for route: ${routeKey}`,
+            ` */`,
+            `export type ${pascalName}OutputSchema = ${outputSchemaType};`,
+        ];
+        return parts.join('\n');
+    })
+        .filter(Boolean)
+        .join('\n');
+    // Helper to generate route entry - uses exported schema types
+    const generateRouteEntry = (route, pathIncludesMethod = false) => {
+        const routeKey = route.path;
+        // For WebSocket/SSE routes, we need to include the method in the type name
+        // to match the generated types (which use "POST /api/websocket/echo" as the routeKey)
+        // For API routes, the method is already in the path from the caller
+        const typeRouteKey = pathIncludesMethod
+            ? route.path
+            : `${route.method?.toUpperCase()} ${route.path}`;
+        const safeName = typeRouteKey
+            .replace(/[^a-zA-Z0-9]/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .replace(/_+/g, '_');
+        const pascalName = toPascalCase(safeName);
+        if (!route.hasValidator &&
+            !route.inputSchemaVariable &&
+            !route.outputSchemaVariable &&
+            !route.agentVariable) {
             const streamValue = route.stream === true ? 'true' : 'false';
-            return `  '${routeKey}': {
-    inputSchema: ${inputType};
-    outputSchema: ${outputType};
-    stream: ${streamValue};
-  };`;
-        }
-        return `  '${routeKey}': {
-    inputSchema: any;
-    outputSchema: any;
-  };`;
+            return `\t'${routeKey}': {
+\t\tinputSchema: never;
+\t\toutputSchema: never;
+\t\tstream: ${streamValue};
+\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
+                ? 'true'
+                : 'false';
+        return `\t'${routeKey}': {
+\t\tinputSchema: ${pascalName}InputSchema;
+\t\toutputSchema: ${pascalName}OutputSchema;
+\t\tstream: ${streamValue};
+\t};`;
     };
     // Generate route entries with METHOD prefix for API routes
     const apiRouteEntries = apiRoutes
         .map((route) => {
         const routeKey = `${route.method.toUpperCase()} ${route.path}`;
-        return generateRouteEntry({ ...route, path: routeKey });
+        return generateRouteEntry({ ...route, path: routeKey }, true);
     })
         .join('\n');
-    const websocketRouteEntries = websocketRoutes.map(generateRouteEntry).join('\n');
-    const sseRouteEntries = sseRoutes.map(generateRouteEntry).join('\n');
-    const generatedContent = `// Auto-generated by Agentuity - do not edit manually
-${importsStr}
+    const websocketRouteEntries = websocketRoutes
+        .map((r) => generateRouteEntry(r, false))
+        .join('\n');
+    const sseRouteEntries = sseRoutes.map((r) => generateRouteEntry(r, false)).join('\n');
+    // Generate RPC-style nested registry type
+    const rpcRegistryType = generateRPCRegistryType(apiRoutes, websocketRoutes, sseRoutes, agentImports, schemaImportAliases, agentMetadataMap);
+    const rpcRuntimeMetadata = generateRPCRuntimeMetadata(apiRoutes, websocketRoutes, sseRoutes);
+    const generatedContent = `// @generated
+// Auto-generated by Agentuity - DO NOT EDIT
+${importsStr}${typeImports}${!hasReactDependency
+        ? `
+import { createClient } from '@agentuity/frontend';`
+        : ''}
+// ============================================================================
+// Route Schema Type Exports
+// ============================================================================
+${routeSchemaTypes}
+
+// ============================================================================
+// Route Definitions
+// ============================================================================
 
-// Augment @agentuity/react types with project-specific routes
+/**
+ * Route Definitions
+ * 
+ * Type-safe route registry for all API routes, WebSocket connections, and SSE endpoints.
+ * Used by @agentuity/react for client-side type-safe routing.
+ * 
+ * @remarks
+ * This module augmentation is auto-generated from your route files during build.
+ * Individual route Input/Output types are exported above for direct usage.
+ */
+${!hasReactDependency
+        ? `
+/**
+ * RPC Route Registry
+ * 
+ * Nested structure for RPC-style client access (e.g., client.hello.post())
+ * Used by createClient() from @agentuity/frontend for type-safe RPC calls.
+ */
+export interface RPCRouteRegistry {
+${rpcRegistryType}
+}
+`
+        : ''}
 declare module '@agentuity/react' {
-  export interface RouteRegistry {
+\t/**
+\t * API Route Registry
+\t * 
+\t * Maps route keys (METHOD /path) to their input/output schemas
+\t */
+\texport interface RouteRegistry {
 ${apiRouteEntries}
-  }
-  
-  export interface WebSocketRouteRegistry {
+\t}
+\t
+\t/**
+\t * WebSocket Route Registry
+\t * 
+\t * Maps WebSocket route paths to their schemas
+\t */
+\texport interface WebSocketRouteRegistry {
 ${websocketRouteEntries}
-  }
-  
-  export interface SSERouteRegistry {
+\t}
+\t
+\t/**
+\t * Server-Sent Events Route Registry
+\t * 
+\t * Maps SSE route paths to their schemas
+\t */
+\texport interface SSERouteRegistry {
 ${sseRouteEntries}
-  }
+\t}
+
+\t/**
+\t * RPC Route Registry
+\t * 
+\t * Nested structure for RPC-style client access (e.g., client.hello.post())
+\t * Used by createClient() from @agentuity/core for type-safe RPC calls.
+\t */
+\texport interface RPCRouteRegistry {
+${rpcRegistryType}
+\t}
+}
+
+/**
+ * Runtime metadata for RPC routes.
+ * Contains route type information for client routing decisions.
+ * @internal
+ */
+const _rpcRouteMetadata = ${rpcRuntimeMetadata} as const;
+
+// Store metadata globally for createAPIClient() to access
+if (typeof globalThis !== 'undefined') {
+	(globalThis as Record<string, unknown>).__rpcRouteMetadata = _rpcRouteMetadata;
+}
+${!hasReactDependency
+        ? `
+/**
+ * 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.
+ *
+ * @example
+ * \`\`\`typescript
+ * import { createAPIClient } from './generated/routes';
+ *
+ * // Basic usage
+ * const api = createAPIClient();
+ * const result = await api.hello.post({ name: 'World' });
+ *
+ * // With custom headers
+ * const api = createAPIClient({ headers: { 'X-Custom-Header': 'value' } });
+ * await api.hello.post({ name: 'World' });
+ * \`\`\`
+ */
+export function createAPIClient(options?: Parameters<typeof createClient>[0]): import('@agentuity/frontend').Client<RPCRouteRegistry> {
+	return createClient(options || {}, _rpcRouteMetadata) as import('@agentuity/frontend').Client<RPCRouteRegistry>;
 }
+`
+        : `
+/**
+ * Type-safe API client is available from @agentuity/react
+ *
+ * @example
+ * \`\`\`typescript
+ * import { createAPIClient } from '@agentuity/react';
+ *
+ * const api = createAPIClient();
+ * const result = await api.hello.post({ name: 'World' });
+ * \`\`\`
+ */
+`}
+
+// FOUND AN ERROR IN THIS FILE?
+// Please file an issue at https://github.com/agentuity/sdk/issues
+// or if you know the fix please submit a PR!
 `;
-    const projectRoot = join(srcDir, '..');
-    const agentuityDir = join(projectRoot, '.agentuity');
-    const registryPath = join(agentuityDir, 'routes.generated.ts');
-    if (!existsSync(agentuityDir)) {
-        mkdirSync(agentuityDir, { recursive: true });
+    const generatedDir = join(srcDir, 'generated');
+    const registryPath = join(generatedDir, 'routes.ts');
+    if (!existsSync(generatedDir)) {
+        mkdirSync(generatedDir, { recursive: true });
     }
-    writeFileSync(registryPath, generatedContent, 'utf-8');
+    // Collapse 2+ consecutive empty lines into 1 empty line (3+ \n becomes 2 \n)
+    const cleanedContent = generatedContent.replace(/\n{3,}/g, '\n\n');
+    writeFileSync(registryPath, cleanedContent, 'utf-8');
 }
 //# sourceMappingURL=registry-generator.js.map