@arcteninc/core 0.0.21 → 0.0.22

package/scripts/cli-extract-types-auto.ts

@@ -1,542 +1,599 @@
 #!/usr/bin/env bun
-/**
- * Automatically discover and extract types for tools used in ArctenAgent/useAgent
- * Scans the project, finds all tool usages, and generates metadata only for used tools
- */
-
-import * as ts from 'typescript';
-import * as fs from 'fs';
-import * as path from 'path';
-import { glob } from 'glob';
-
-interface TypeMetadata {
-  type: string;
-  description?: string;
-  required: boolean;
-  default?: string;
-  values?: string[];
-  arrayItemType?: TypeMetadata;
-  properties?: Record<string, TypeMetadata>;
-}
-
-interface FunctionMetadata {
-  name: string;
-  description: string;
-  parameters: Record<string, TypeMetadata>;
-  returnType?: string;
-  isAsync?: boolean;
-}
-
-interface GeneratedMetadata {
-  generated: string;
-  discoveredFrom: string[];
-  functions: Record<string, FunctionMetadata>;
-}
-
-interface ToolUsage {
-  toolNames: Set<string>;
-  file: string;
-  component: 'ArctenAgent' | 'useAgent';
-}
-
-/**
- * Find all files that use ArctenAgent or useAgent
- */
-async function findToolUsageFiles(projectRoot: string): Promise<string[]> {
-  const pattern = path.join(projectRoot, '**/*.{ts,tsx}').replace(/\\/g, '/');
-  const files = await glob(pattern, {
-    ignore: ['**/node_modules/**', '**/dist/**', '**/.next/**', '**/build/**'],
-  });
-
-  console.log(`📂 Found ${files.length} TypeScript files to scan`);
-  return files;
-}
-
-/**
- * Extract tool names from ArctenAgent or useAgent usage
- */
-function extractToolNamesFromFile(sourceFile: ts.SourceFile): ToolUsage[] {
-  const usages: ToolUsage[] = [];
-
-  function visit(node: ts.Node) {
-    // Check for <ArctenAgent tools={[...]} safeTools={[...]} />
-    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
-      const tagName = ts.isJsxElement(node)
-        ? node.openingElement.tagName.getText(sourceFile)
-        : node.tagName.getText(sourceFile);
-
-      if (tagName === 'ArctenAgent') {
-        const toolNames = new Set<string>();
-        const attributes = ts.isJsxElement(node)
-          ? node.openingElement.attributes.properties
-          : node.attributes.properties;
-
-        for (const attr of attributes) {
-          if (ts.isJsxAttribute(attr)) {
-            const attrName = attr.name.getText(sourceFile);
-            if (attrName === 'tools' || attrName === 'safeTools') {
-              if (attr.initializer && ts.isJsxExpression(attr.initializer)) {
-                const expr = attr.initializer.expression;
-                if (expr && ts.isArrayLiteralExpression(expr)) {
-                  for (const element of expr.elements) {
-                    const name = element.getText(sourceFile).trim();
-                    // Remove any object property access (e.g., tools.getOrders -> getOrders)
-                    const simpleName = name.split('.').pop() || name;
-                    toolNames.add(simpleName);
-                  }
-                }
-              }
-            }
-          }
-        }
-
-        if (toolNames.size > 0) {
-          usages.push({
-            toolNames,
-            file: sourceFile.fileName,
-            component: 'ArctenAgent',
-          });
-        }
-      }
-    }
-
-    // Check for useAgent({ tools: [...], safeTools: [...] })
-    if (ts.isCallExpression(node)) {
-      const expr = node.expression;
-      if (ts.isIdentifier(expr) && expr.getText(sourceFile) === 'useAgent') {
-        const toolNames = new Set<string>();
-
-        if (node.arguments.length > 0) {
-          const arg = node.arguments[0];
-          if (ts.isObjectLiteralExpression(arg)) {
-            for (const prop of arg.properties) {
-              if (ts.isPropertyAssignment(prop)) {
-                const propName = prop.name.getText(sourceFile);
-                if (propName === 'tools' || propName === 'safeTools') {
-                  if (ts.isArrayLiteralExpression(prop.initializer)) {
-                    for (const element of prop.initializer.elements) {
-                      const name = element.getText(sourceFile).trim();
-                      const simpleName = name.split('.').pop() || name;
-                      toolNames.add(simpleName);
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-
-        if (toolNames.size > 0) {
-          usages.push({
-            toolNames,
-            file: sourceFile.fileName,
-            component: 'useAgent',
-          });
-        }
-      }
-    }
-
-    ts.forEachChild(node, visit);
-  }
-
-  visit(sourceFile);
-  return usages;
-}
-
-/**
- * Find where a tool function is defined
- */
-function findFunctionDefinition(
-  functionName: string,
-  sourceFile: ts.SourceFile,
-  program: ts.Program
-): { sourceFile: ts.SourceFile; node: ts.FunctionDeclaration } | null {
-  // First, check if it's defined in the current file
-  let foundNode: ts.FunctionDeclaration | null = null;
-
-  function visitForDefinition(node: ts.Node) {
-    if (ts.isFunctionDeclaration(node) && node.name) {
-      if (node.name.getText(sourceFile) === functionName) {
-        foundNode = node;
-      }
-    }
-    if (!foundNode) {
-      ts.forEachChild(node, visitForDefinition);
-    }
-  }
-
-  visitForDefinition(sourceFile);
-
-  if (foundNode) {
-    return { sourceFile, node: foundNode };
-  }
-
-  // If not found, check imports
-  const imports: { name: string; from: string }[] = [];
-
-  function visitForImports(node: ts.Node) {
-    if (ts.isImportDeclaration(node)) {
-      const moduleSpecifier = node.moduleClause;
-      if (moduleSpecifier && ts.isImportClause(moduleSpecifier)) {
-        const namedBindings = moduleSpecifier.namedBindings;
-        if (namedBindings && ts.isNamedImports(namedBindings)) {
-          for (const element of namedBindings.elements) {
-            const importedName = element.name.getText(sourceFile);
-            if (importedName === functionName) {
-              const modulePath = (node.moduleSpecifier as ts.StringLiteral).text;
-              imports.push({ name: importedName, from: modulePath });
-            }
-          }
-        }
-      }
-    }
-    ts.forEachChild(node, visitForImports);
-  }
-
-  visitForImports(sourceFile);
-
-  // Follow imports to find definition
-  for (const imp of imports) {
-    const resolvedPath = resolveImportPath(imp.from, sourceFile.fileName);
-    if (resolvedPath) {
-      const importedSourceFile = program.getSourceFile(resolvedPath);
-      if (importedSourceFile) {
-        const result = findFunctionDefinition(functionName, importedSourceFile, program);
-        if (result) {
-          return result;
-        }
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * Resolve import path to actual file path
- */
-function resolveImportPath(importPath: string, fromFile: string): string | null {
-  if (importPath.startsWith('.')) {
-    // Relative import
-    const dir = path.dirname(fromFile);
-    const resolved = path.resolve(dir, importPath);
-
-    // Try common extensions
-    const extensions = ['.ts', '.tsx', '.js', '.jsx'];
-    for (const ext of extensions) {
-      const withExt = resolved + ext;
-      if (fs.existsSync(withExt)) {
-        return withExt;
-      }
-    }
-
-    // Try index files
-    for (const ext of extensions) {
-      const indexPath = path.join(resolved, `index${ext}`);
-      if (fs.existsSync(indexPath)) {
-        return indexPath;
-      }
-    }
-
-    return resolved;
-  }
-
-  // Node modules - we'll skip for now
-  return null;
-}
-
-/**
- * Serialize a TypeScript type (same as previous implementation)
- */
-function serializeType(
-  type: ts.Type,
-  checker: ts.TypeChecker,
-  visited = new Set<number>(),
-  depth = 0
-): TypeMetadata {
-  const typeString = checker.typeToString(type);
-
-  if (depth > 10) {
-    return { type: 'any', required: true };
-  }
-
-  const typeId = (type as any).id;
-  if (typeId !== undefined && visited.has(typeId)) {
-    return { type: 'any', required: true };
-  }
-
-  if (type.flags & ts.TypeFlags.String) {
-    return { type: 'string', required: true };
-  }
-  if (type.flags & ts.TypeFlags.Number) {
-    return { type: 'number', required: true };
-  }
-  if (type.flags & ts.TypeFlags.Boolean) {
-    return { type: 'boolean', required: true };
-  }
-  if (type.flags & ts.TypeFlags.Undefined || type.flags & ts.TypeFlags.Void) {
-    return { type: 'undefined', required: false };
-  }
-
-  if (type.isUnion()) {
-    const types = type.types;
-    const stringLiterals = types
-      .filter(t => t.flags & ts.TypeFlags.StringLiteral)
-      .map(t => (t as ts.StringLiteralType).value);
-
-    if (stringLiterals.length === types.length) {
-      return { type: 'enum', values: stringLiterals, required: true };
-    }
-
-    const hasUndefined = types.some(t => t.flags & ts.TypeFlags.Undefined);
-    const nonUndefinedTypes = types.filter(t => !(t.flags & ts.TypeFlags.Undefined));
-
-    if (hasUndefined && nonUndefinedTypes.length === 1) {
-      const metadata = serializeType(nonUndefinedTypes[0], checker, visited, depth + 1);
-      metadata.required = false;
-      return metadata;
-    }
-
-    return {
-      type: types.map(t => checker.typeToString(t)).join(' | '),
-      required: true,
-    };
-  }
-
-  if (checker.isArrayType(type)) {
-    const typeArgs = (type as ts.TypeReference).typeArguments;
-    if (typeArgs && typeArgs.length > 0) {
-      return {
-        type: 'array',
-        arrayItemType: serializeType(typeArgs[0], checker, visited, depth + 1),
-        required: true,
-      };
-    }
-    return { type: 'array', required: true };
-  }
-
-  if (type.flags & ts.TypeFlags.Object) {
-    if (typeId !== undefined) {
-      visited.add(typeId);
-    }
-
-    const properties: Record<string, TypeMetadata> = {};
-    const props = checker.getPropertiesOfType(type);
-
-    if (props.length > 0) {
-      for (const prop of props) {
-        const propDeclaration = prop.valueDeclaration || prop.declarations?.[0];
-
-        if (propDeclaration) {
-          const propType = checker.getTypeOfSymbolAtLocation(prop, propDeclaration);
-          const isOptional = (prop.flags & ts.SymbolFlags.Optional) !== 0;
-
-          const propMetadata = serializeType(propType, checker, visited, depth + 1);
-          propMetadata.required = !isOptional;
-
-          properties[prop.name] = propMetadata;
-        }
-      }
-
-      return { type: 'object', properties, required: true };
-    }
-  }
-
-  return {
-    type: typeString.length < 100 ? typeString : 'any',
-    required: true,
-  };
-}
-
-/**
- * Extract metadata from a function
- */
-function extractFunctionMetadata(
-  node: ts.FunctionDeclaration,
-  checker: ts.TypeChecker,
-  sourceFile: ts.SourceFile
-): FunctionMetadata | null {
-  if (!node.name) {
-    return null;
-  }
-
-  const functionName = node.name.getText(sourceFile);
-
-  const jsDocTags = ts.getJSDocTags(node);
-  const jsDocComments = ts.getJSDocCommentsAndTags(node);
-
-  let description = `Execute ${functionName}`;
-  for (const comment of jsDocComments) {
-    if (ts.isJSDoc(comment) && comment.comment) {
-      if (typeof comment.comment === 'string') {
-        description = comment.comment.trim();
-      }
-      break;
-    }
-  }
-
-  const paramDescriptions = new Map<string, string>();
-  for (const tag of jsDocTags) {
-    if (tag.tagName.text === 'param' && ts.isJSDocParameterTag(tag)) {
-      const paramName = tag.name?.getText(sourceFile);
-      const paramDesc = typeof tag.comment === 'string' ? tag.comment.trim() : '';
-      if (paramName && paramDesc) {
-        paramDescriptions.set(paramName, paramDesc);
-      }
-    }
-  }
-
-  const parameters: Record<string, TypeMetadata> = {};
-  const isAsync = node.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword) || false;
-
-  for (const param of node.parameters) {
-    const paramName = param.name.getText(sourceFile);
-    const hasDefault = param.initializer !== undefined;
-
-    let typeMetadata: TypeMetadata;
-    if (param.type) {
-      const type = checker.getTypeFromTypeNode(param.type);
-      typeMetadata = serializeType(type, checker);
-    } else {
-      typeMetadata = { type: 'any', required: true };
-    }
-
-    const isOptional = param.questionToken !== undefined || hasDefault;
-    if (isOptional) {
-      typeMetadata.required = false;
-    }
-
-    if (hasDefault) {
-      typeMetadata.default = param.initializer!.getText(sourceFile);
-    }
-
-    if (paramDescriptions.has(paramName)) {
-      typeMetadata.description = paramDescriptions.get(paramName);
-    }
-
-    parameters[paramName] = typeMetadata;
-  }
-
-  let returnType = 'any';
-  if (node.type) {
-    returnType = node.type.getText(sourceFile);
-  }
-
-  return {
-    name: functionName,
-    description,
-    parameters,
-    returnType,
-    isAsync,
-  };
-}
-
-/**
- * Main function
- */
-async function autoDiscoverAndExtract(projectRoot: string, outputPath: string) {
-  console.log(`\n🔍 Auto-discovering tools in: ${projectRoot}\n`);
-
-  // Find all TypeScript files
-  const files = await findToolUsageFiles(projectRoot);
-
-  // Read tsconfig
-  const configPath = ts.findConfigFile(projectRoot, ts.sys.fileExists, 'tsconfig.json');
-  let compilerOptions: ts.CompilerOptions = {
-    target: ts.ScriptTarget.ESNext,
-    module: ts.ModuleKind.ESNext,
-    jsx: ts.JsxEmit.React,
-  };
-
-  if (configPath) {
-    const config = ts.readConfigFile(configPath, ts.sys.readFile);
-    const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, path.dirname(configPath));
-    compilerOptions = parsed.options;
-  }
-
-  // Create program with all files
-  const program = ts.createProgram(files, compilerOptions);
-  const checker = program.getTypeChecker();
-
-  // Scan for tool usages
-  const allToolUsages: ToolUsage[] = [];
-  const allToolNames = new Set<string>();
-
-  for (const file of files) {
-    const sourceFile = program.getSourceFile(file);
-    if (sourceFile) {
-      const usages = extractToolNamesFromFile(sourceFile);
-      if (usages.length > 0) {
-        allToolUsages.push(...usages);
-        usages.forEach(u => u.toolNames.forEach(name => allToolNames.add(name)));
-      }
-    }
-  }
-
-  console.log(`✓ Found ${allToolUsages.length} usage site(s) with ${allToolNames.size} unique tool(s)`);
-  allToolUsages.forEach(usage => {
-    console.log(`  - ${usage.component} in ${path.relative(projectRoot, usage.file)}`);
-    console.log(`    Tools: ${Array.from(usage.toolNames).join(', ')}`);
-  });
-
-  // Extract metadata for discovered tools
-  console.log(`\n📝 Extracting types for discovered tools...\n`);
-
-  const functionsMap: Record<string, FunctionMetadata> = {};
-  const discoveredFrom: string[] = [];
-
-  for (const toolName of allToolNames) {
-    let found = false;
-
-    // Search in all files for the definition
-    for (const file of files) {
-      const sourceFile = program.getSourceFile(file);
-      if (sourceFile) {
-        const result = findFunctionDefinition(toolName, sourceFile, program);
-        if (result) {
-          const metadata = extractFunctionMetadata(result.node, checker, result.sourceFile);
-          if (metadata) {
-            functionsMap[toolName] = metadata;
-            discoveredFrom.push(path.relative(projectRoot, result.sourceFile.fileName));
-            console.log(`  ✓ ${toolName} (from ${path.relative(projectRoot, result.sourceFile.fileName)})`);
-            found = true;
-            break;
-          }
-        }
-      }
-    }
-
-    if (!found) {
-      console.log(`  ⚠ ${toolName} (definition not found)`);
-    }
-  }
-
-  // Generate output
-  const output: GeneratedMetadata = {
-    generated: new Date().toISOString(),
-    discoveredFrom: Array.from(new Set(discoveredFrom)),
-    functions: functionsMap,
-  };
-
-  const outputDir = path.dirname(outputPath);
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
-  }
-
-  fs.writeFileSync(outputPath, JSON.stringify(output, null, 2));
-  console.log(`\n✅ Generated metadata for ${Object.keys(functionsMap).length} tool(s)`);
-  console.log(`📁 Output: ${outputPath}\n`);
-}
-
-// CLI
-if (import.meta.main) {
-  const args = process.argv.slice(2);
-  const projectRoot = args[0] ? path.resolve(args[0]) : process.cwd();
-  const outputPath = args[1]
-    ? path.resolve(args[1])
-    : path.join(projectRoot, '.arcten', 'tool-types.json');
-
-  autoDiscoverAndExtract(projectRoot, outputPath);
-}
-
-export { autoDiscoverAndExtract };
+/**
+ * Automatically discover and extract types for tools used in ArctenAgent/useAgent
+ * Scans the project, finds all tool usages, and generates metadata only for used tools
+ */
+
+import * as ts from 'typescript';
+import * as fs from 'fs';
+import * as path from 'path';
+import { glob } from 'glob';
+
+// JSON Schema compatible format
+interface JsonSchemaProperty {
+  type: string;
+  description?: string;
+  default?: string;
+  enum?: string[]; // For enum types
+  items?: JsonSchemaProperty; // For array types
+  properties?: Record<string, JsonSchemaProperty>; // For object types
+  required?: string[]; // For nested objects
+}
+
+interface FunctionMetadata {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[]; // Array of required parameter names
+  };
+  returnType?: string;
+  isAsync?: boolean;
+}
+
+interface GeneratedMetadata {
+  generated: string;
+  discoveredFrom: string[];
+  functions: Record<string, FunctionMetadata>;
+}
+
+interface ToolUsage {
+  toolNames: Set<string>;
+  file: string;
+  component: 'ArctenAgent' | 'useAgent';
+}
+
+/**
+ * Find all files that use ArctenAgent or useAgent
+ */
+async function findToolUsageFiles(projectRoot: string): Promise<string[]> {
+  const pattern = path.join(projectRoot, '**/*.{ts,tsx}').replace(/\\/g, '/');
+  const files = await glob(pattern, {
+    ignore: ['**/node_modules/**', '**/dist/**', '**/.next/**', '**/build/**'],
+  });
+
+  console.log(`📂 Found ${files.length} TypeScript files to scan`);
+  return files;
+}
+
+/**
+ * Extract tool names from ArctenAgent or useAgent usage
+ */
+function extractToolNamesFromFile(sourceFile: ts.SourceFile): ToolUsage[] {
+  const usages: ToolUsage[] = [];
+
+  function visit(node: ts.Node) {
+    // Check for <ArctenAgent tools={[...]} safeTools={[...]} />
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const tagName = ts.isJsxElement(node)
+        ? node.openingElement.tagName.getText(sourceFile)
+        : node.tagName.getText(sourceFile);
+
+      if (tagName === 'ArctenAgent') {
+        const toolNames = new Set<string>();
+        const attributes = ts.isJsxElement(node)
+          ? node.openingElement.attributes.properties
+          : node.attributes.properties;
+
+        for (const attr of attributes) {
+          if (ts.isJsxAttribute(attr)) {
+            const attrName = attr.name.getText(sourceFile);
+            if (attrName === 'tools' || attrName === 'safeTools') {
+              if (attr.initializer && ts.isJsxExpression(attr.initializer)) {
+                const expr = attr.initializer.expression;
+                if (expr && ts.isArrayLiteralExpression(expr)) {
+                  for (const element of expr.elements) {
+                    const name = element.getText(sourceFile).trim();
+                    // Remove any object property access (e.g., tools.getOrders -> getOrders)
+                    const simpleName = name.split('.').pop() || name;
+                    toolNames.add(simpleName);
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        if (toolNames.size > 0) {
+          usages.push({
+            toolNames,
+            file: sourceFile.fileName,
+            component: 'ArctenAgent',
+          });
+        }
+      }
+    }
+
+    // Check for useAgent({ tools: [...], safeTools: [...] })
+    if (ts.isCallExpression(node)) {
+      const expr = node.expression;
+      if (ts.isIdentifier(expr) && expr.getText(sourceFile) === 'useAgent') {
+        const toolNames = new Set<string>();
+
+        if (node.arguments.length > 0) {
+          const arg = node.arguments[0];
+          if (ts.isObjectLiteralExpression(arg)) {
+            for (const prop of arg.properties) {
+              if (ts.isPropertyAssignment(prop)) {
+                const propName = prop.name.getText(sourceFile);
+                if (propName === 'tools' || propName === 'safeTools') {
+                  if (ts.isArrayLiteralExpression(prop.initializer)) {
+                    for (const element of prop.initializer.elements) {
+                      const name = element.getText(sourceFile).trim();
+                      const simpleName = name.split('.').pop() || name;
+                      toolNames.add(simpleName);
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        if (toolNames.size > 0) {
+          usages.push({
+            toolNames,
+            file: sourceFile.fileName,
+            component: 'useAgent',
+          });
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return usages;
+}
+
+/**
+ * Find where a tool function is defined
+ */
+function findFunctionDefinition(
+  functionName: string,
+  sourceFile: ts.SourceFile,
+  program: ts.Program
+): { sourceFile: ts.SourceFile; node: ts.FunctionDeclaration } | null {
+  // First, check if it's defined in the current file
+  let foundNode: ts.FunctionDeclaration | null = null;
+
+  function visitForDefinition(node: ts.Node) {
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      if (node.name.getText(sourceFile) === functionName) {
+        foundNode = node;
+      }
+    }
+    if (!foundNode) {
+      ts.forEachChild(node, visitForDefinition);
+    }
+  }
+
+  visitForDefinition(sourceFile);
+
+  if (foundNode) {
+    return { sourceFile, node: foundNode };
+  }
+
+  // If not found, check imports
+  const imports: { name: string; from: string }[] = [];
+
+  function visitForImports(node: ts.Node) {
+    if (ts.isImportDeclaration(node)) {
+      const moduleSpecifier = node.moduleClause;
+      if (moduleSpecifier && ts.isImportClause(moduleSpecifier)) {
+        const namedBindings = moduleSpecifier.namedBindings;
+        if (namedBindings && ts.isNamedImports(namedBindings)) {
+          for (const element of namedBindings.elements) {
+            const importedName = element.name.getText(sourceFile);
+            if (importedName === functionName) {
+              const modulePath = (node.moduleSpecifier as ts.StringLiteral).text;
+              imports.push({ name: importedName, from: modulePath });
+            }
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visitForImports);
+  }
+
+  visitForImports(sourceFile);
+
+  // Follow imports to find definition
+  for (const imp of imports) {
+    const resolvedPath = resolveImportPath(imp.from, sourceFile.fileName);
+    if (resolvedPath) {
+      const importedSourceFile = program.getSourceFile(resolvedPath);
+      if (importedSourceFile) {
+        const result = findFunctionDefinition(functionName, importedSourceFile, program);
+        if (result) {
+          return result;
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve import path to actual file path
+ */
+function resolveImportPath(importPath: string, fromFile: string): string | null {
+  if (importPath.startsWith('.')) {
+    // Relative import
+    const dir = path.dirname(fromFile);
+    const resolved = path.resolve(dir, importPath);
+
+    // Try common extensions
+    const extensions = ['.ts', '.tsx', '.js', '.jsx'];
+    for (const ext of extensions) {
+      const withExt = resolved + ext;
+      if (fs.existsSync(withExt)) {
+        return withExt;
+      }
+    }
+
+    // Try index files
+    for (const ext of extensions) {
+      const indexPath = path.join(resolved, `index${ext}`);
+      if (fs.existsSync(indexPath)) {
+        return indexPath;
+      }
+    }
+
+    return resolved;
+  }
+
+  // Node modules - we'll skip for now
+  return null;
+}
+
+/**
+ * Serialize a TypeScript type to JSON Schema format
+ * Returns: { isOptional, schema }
+ */
+function serializeType(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  visited = new Set<number>(),
+  depth = 0
+): { isOptional: boolean; schema: JsonSchemaProperty } {
+  const typeString = checker.typeToString(type);
+
+  if (depth > 10) {
+    return { isOptional: false, schema: { type: 'any' } };
+  }
+
+  const typeId = (type as any).id;
+  if (typeId !== undefined && visited.has(typeId)) {
+    return { isOptional: false, schema: { type: 'any' } };
+  }
+
+  // Handle primitives
+  if (type.flags & ts.TypeFlags.String) {
+    return { isOptional: false, schema: { type: 'string' } };
+  }
+  if (type.flags & ts.TypeFlags.Number) {
+    return { isOptional: false, schema: { type: 'number' } };
+  }
+  if (type.flags & ts.TypeFlags.Boolean) {
+    return { isOptional: false, schema: { type: 'boolean' } };
+  }
+  if (type.flags & ts.TypeFlags.Undefined || type.flags & ts.TypeFlags.Void) {
+    return { isOptional: true, schema: { type: 'null' } };
+  }
+
+  // Handle union types
+  if (type.isUnion()) {
+    const types = type.types;
+
+    // Check if it's a string literal union (enum)
+    const stringLiterals = types
+      .filter(t => t.flags & ts.TypeFlags.StringLiteral)
+      .map(t => (t as ts.StringLiteralType).value);
+
+    if (stringLiterals.length === types.length) {
+      return {
+        isOptional: false,
+        schema: { type: 'string', enum: stringLiterals }
+      };
+    }
+
+    // Check for optional (T | undefined)
+    const hasUndefined = types.some(t => t.flags & ts.TypeFlags.Undefined);
+    const nonUndefinedTypes = types.filter(t => !(t.flags & ts.TypeFlags.Undefined));
+
+    if (hasUndefined && nonUndefinedTypes.length === 1) {
+      const result = serializeType(nonUndefinedTypes[0], checker, visited, depth + 1);
+      return { isOptional: true, schema: result.schema };
+    }
+
+    // Generic union - just use string representation
+    return {
+      isOptional: false,
+      schema: { type: types.map(t => checker.typeToString(t)).join(' | ') }
+    };
+  }
+
+  // Handle arrays
+  if (checker.isArrayType(type)) {
+    const typeArgs = (type as ts.TypeReference).typeArguments;
+    if (typeArgs && typeArgs.length > 0) {
+      const itemResult = serializeType(typeArgs[0], checker, visited, depth + 1);
+      return {
+        isOptional: false,
+        schema: { type: 'array', items: itemResult.schema }
+      };
+    }
+    return { isOptional: false, schema: { type: 'array' } };
+  }
+
+  // Handle objects
+  if (type.flags & ts.TypeFlags.Object) {
+    if (typeId !== undefined) {
+      visited.add(typeId);
+    }
+
+    const properties: Record<string, JsonSchemaProperty> = {};
+    const required: string[] = [];
+    const props = checker.getPropertiesOfType(type);
+
+    if (props.length > 0) {
+      for (const prop of props) {
+        const propDeclaration = prop.valueDeclaration || prop.declarations?.[0];
+
+        if (propDeclaration) {
+          const propType = checker.getTypeOfSymbolAtLocation(prop, propDeclaration);
+          const isOptional = (prop.flags & ts.SymbolFlags.Optional) !== 0;
+
+          const propResult = serializeType(propType, checker, visited, depth + 1);
+          properties[prop.name] = propResult.schema;
+
+          // Track required properties
+          if (!isOptional && !propResult.isOptional) {
+            required.push(prop.name);
+          }
+        }
+      }
+
+      const schema: JsonSchemaProperty = {
+        type: 'object',
+        properties
+      };
+
+      if (required.length > 0) {
+        schema.required = required;
+      }
+
+      return { isOptional: false, schema };
+    }
+  }
+
+  // Fallback
+  return {
+    isOptional: false,
+    schema: { type: typeString.length < 100 ? typeString : 'any' }
+  };
+}
+
+/**
+ * Extract metadata from a function
+ */
+function extractFunctionMetadata(
+  node: ts.FunctionDeclaration,
+  checker: ts.TypeChecker,
+  sourceFile: ts.SourceFile
+): FunctionMetadata | null {
+  if (!node.name) {
+    return null;
+  }
+
+  const functionName = node.name.getText(sourceFile);
+
+  const jsDocTags = ts.getJSDocTags(node);
+  const jsDocComments = ts.getJSDocCommentsAndTags(node);
+
+  let description = `Execute ${functionName}`;
+  for (const comment of jsDocComments) {
+    if (ts.isJSDoc(comment) && comment.comment) {
+      if (typeof comment.comment === 'string') {
+        description = comment.comment.trim();
+      }
+      break;
+    }
+  }
+
+  const paramDescriptions = new Map<string, string>();
+  for (const tag of jsDocTags) {
+    if (tag.tagName.text === 'param' && ts.isJSDocParameterTag(tag)) {
+      const paramName = tag.name?.getText(sourceFile);
+      const paramDesc = typeof tag.comment === 'string' ? tag.comment.trim() : '';
+      if (paramName && paramDesc) {
+        paramDescriptions.set(paramName, paramDesc);
+      }
+    }
+  }
+
+  const properties: Record<string, JsonSchemaProperty> = {};
+  const required: string[] = [];
+  const isAsync = node.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword) || false;
+
+  for (const param of node.parameters) {
+    const paramName = param.name.getText(sourceFile);
+    const hasDefault = param.initializer !== undefined;
+
+    let propSchema: JsonSchemaProperty;
+    let isOptional = false;
+
+    if (param.type) {
+      const type = checker.getTypeFromTypeNode(param.type);
+      const result = serializeType(type, checker);
+      propSchema = result.schema;
+      isOptional = result.isOptional;
+    } else {
+      propSchema = { type: 'any' };
+    }
+
+    // Check if parameter has default value or question mark
+    const hasQuestionMark = param.questionToken !== undefined;
+    if (hasDefault || hasQuestionMark) {
+      isOptional = true;
+    }
+
+    // Add default value if present
+    if (hasDefault) {
+      propSchema.default = param.initializer!.getText(sourceFile);
+    }
+
+    // Add description from JSDoc
+    if (paramDescriptions.has(paramName)) {
+      propSchema.description = paramDescriptions.get(paramName);
+    }
+
+    properties[paramName] = propSchema;
+
+    // Track required params
+    if (!isOptional) {
+      required.push(paramName);
+    }
+  }
+
+  let returnType = 'any';
+  if (node.type) {
+    returnType = node.type.getText(sourceFile);
+  }
+
+  return {
+    name: functionName,
+    description,
+    parameters: {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined
+    },
+    returnType,
+    isAsync,
+  };
+}
+
+/**
+ * Main function
+ */
+async function autoDiscoverAndExtract(projectRoot: string, outputPath: string) {
+  console.log(`\n🔍 Auto-discovering tools in: ${projectRoot}\n`);
+
+  // Find all TypeScript files
+  const files = await findToolUsageFiles(projectRoot);
+
+  // Read tsconfig
+  const configPath = ts.findConfigFile(projectRoot, ts.sys.fileExists, 'tsconfig.json');
+  let compilerOptions: ts.CompilerOptions = {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    jsx: ts.JsxEmit.React,
+  };
+
+  if (configPath) {
+    const config = ts.readConfigFile(configPath, ts.sys.readFile);
+    const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, path.dirname(configPath));
+    compilerOptions = parsed.options;
+  }
+
+  // Create program with all files
+  const program = ts.createProgram(files, compilerOptions);
+  const checker = program.getTypeChecker();
+
+  // Scan for tool usages
+  const allToolUsages: ToolUsage[] = [];
+  const allToolNames = new Set<string>();
+
+  for (const file of files) {
+    const sourceFile = program.getSourceFile(file);
+    if (sourceFile) {
+      const usages = extractToolNamesFromFile(sourceFile);
+      if (usages.length > 0) {
+        allToolUsages.push(...usages);
+        usages.forEach(u => u.toolNames.forEach(name => allToolNames.add(name)));
+      }
+    }
+  }
+
+  console.log(`✓ Found ${allToolUsages.length} usage site(s) with ${allToolNames.size} unique tool(s)`);
+  allToolUsages.forEach(usage => {
+    console.log(`  - ${usage.component} in ${path.relative(projectRoot, usage.file)}`);
+    console.log(`    Tools: ${Array.from(usage.toolNames).join(', ')}`);
+  });
+
+  // Extract metadata for discovered tools
+  console.log(`\n📝 Extracting types for discovered tools...\n`);
+
+  const functionsMap: Record<string, FunctionMetadata> = {};
+  const discoveredFrom: string[] = [];
+
+  for (const toolName of allToolNames) {
+    let found = false;
+
+    // Search in all files for the definition
+    for (const file of files) {
+      const sourceFile = program.getSourceFile(file);
+      if (sourceFile) {
+        const result = findFunctionDefinition(toolName, sourceFile, program);
+        if (result) {
+          const metadata = extractFunctionMetadata(result.node, checker, result.sourceFile);
+          if (metadata) {
+            functionsMap[toolName] = metadata;
+            discoveredFrom.push(path.relative(projectRoot, result.sourceFile.fileName));
+            console.log(`  ✓ ${toolName} (from ${path.relative(projectRoot, result.sourceFile.fileName)})`);
+            found = true;
+            break;
+          }
+        }
+      }
+    }
+
+    if (!found) {
+      console.log(`  ⚠ ${toolName} (definition not found)`);
+    }
+  }
+
+  // Generate output
+  const output: GeneratedMetadata = {
+    generated: new Date().toISOString(),
+    discoveredFrom: Array.from(new Set(discoveredFrom)),
+    functions: functionsMap,
+  };
+
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Generate TypeScript module instead of JSON for easier bundler integration
+  const tsContent = `// Auto-generated by arcten-extract-types
+// Do not edit this file manually
+
+export const toolMetadata = ${JSON.stringify(output, null, 2)} as const;
+`;
+
+  fs.writeFileSync(outputPath, tsContent);
+  console.log(`\n✅ Generated metadata for ${Object.keys(functionsMap).length} tool(s)`);
+  console.log(`📁 Output: ${outputPath}`);
+  console.log(`\n💡 Usage in your component:`);
+  console.log(`   import { toolMetadata } from './.arcten/tool-metadata';`);
+  console.log(`   useAgent({ tools: [...], toolMetadata: toolMetadata.functions })\n`);
+}
+
+// CLI
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const projectRoot = args[0] ? path.resolve(args[0]) : process.cwd();
+  const outputPath = args[1]
+    ? path.resolve(args[1])
+    : path.join(projectRoot, '.arcten', 'tool-metadata.ts');
+
+  autoDiscoverAndExtract(projectRoot, outputPath);
+}
+
+export { autoDiscoverAndExtract };