Tools and Extensions

/**
 * Base declarative tool class for creating custom AI agent tools
 */
abstract class DeclarativeTool<TParams = any, TResult = any> {
  abstract readonly name: string;
  abstract readonly description: string;
  abstract readonly parameters: object; // JSON Schema
  
  abstract invoke(params: TParams): Promise<ToolResult<TResult>>;
  
  // Optional overrides
  validate?(params: TParams): void;
  getConfirmationDetails?(params: TParams): ToolCallConfirmationDetails;
}

/**
 * Enhanced base class with built-in validation and error handling
 */
abstract class BaseDeclarativeTool<TParams = any, TResult = any> extends DeclarativeTool<TParams, TResult> {
  constructor();
  
  // Built-in parameter validation using JSON schema
  protected validateParams(params: TParams): void;
  
  // Helper methods for tool development
  protected createResult(result: TResult, displayResult?: ToolResultDisplay): ToolResult<TResult>;
  protected createError(message: string, details?: any): ToolResult<TResult>;
}

/**
 * Tool invocation interface
 */
interface ToolInvocation {
  tool: AnyDeclarativeTool;
  params: any;
  invocationId: string;
}

/**
 * Base tool invocation class
 */
abstract class BaseToolInvocation implements ToolInvocation {
  constructor(tool: AnyDeclarativeTool, params: any, invocationId: string);
  
  readonly tool: AnyDeclarativeTool;
  readonly params: any;
  readonly invocationId: string;
  
  abstract execute(): Promise<ToolResult>;
}

/**
 * Tool execution result
 */
interface ToolResult<T = any> {
  result: T;
  confirmationState?: ToolConfirmationOutcome;
  displayResult?: ToolResultDisplay;
  error?: ToolError;
}

/**
 * Tool result display options
 */
type ToolResultDisplay = 
  | string 
  | { type: 'text'; content: string }
  | { type: 'json'; content: any }
  | { type: 'diff'; before: string; after: string }
  | { type: 'file'; path: string; content: string };

/**
 * Tool confirmation outcomes
 */
enum ToolConfirmationOutcome {
  ProceedOnce = 'ProceedOnce',
  ProceedAlways = 'ProceedAlways', 
  ProceedAlwaysServer = 'ProceedAlwaysServer',
  ProceedAlwaysTool = 'ProceedAlwaysTool',
  ModifyWithEditor = 'ModifyWithEditor',
  Cancel = 'Cancel'
}

/**
 * Tool confirmation details for different operation types
 */
type ToolCallConfirmationDetails = 
  | ToolEditConfirmationDetails
  | ToolExecuteConfirmationDetails  
  | ToolMcpConfirmationDetails
  | ToolInfoConfirmationDetails;

/**
 * Edit operation confirmation details
 */
interface ToolEditConfirmationDetails {
  type: 'edit';
  filePath: string;
  originalContent: string;
  newContent: string;
  diff: FileDiff;
}

/**
 * Execute operation confirmation details
 */
interface ToolExecuteConfirmationDetails {
  type: 'execute';
  command: string;
  args: string[];
  cwd?: string;
  env?: Record<string, string>;
}

/**
 * MCP operation confirmation details
 */
interface ToolMcpConfirmationDetails {
  type: 'mcp';
  serverName: string;
  toolName: string;
  params: any;
}

/**
 * Info operation confirmation details
 */
interface ToolInfoConfirmationDetails {
  type: 'info';
  message: string;
  details?: any;
}

/**
 * Tool confirmation payload
 */
interface ToolConfirmationPayload {
  invocationId: string;
  toolName: string;
  details: ToolCallConfirmationDetails;
  location?: ToolLocation;
}

/**
 * Tool operation kinds for classification and approval workflows
 */
enum Kind {
  Read = 'Read',
  Edit = 'Edit',
  Delete = 'Delete', 
  Move = 'Move',
  Search = 'Search',
  Execute = 'Execute',
  Think = 'Think',
  Fetch = 'Fetch',
  Other = 'Other'
}

/**
 * Tool location information
 */
interface ToolLocation {
  filePath?: string;
  lineNumber?: number;
  columnNumber?: number;
  workspaceRoot?: string;
}

/**
 * Read file tool for accessing file contents
 */
class ReadFileTool extends DeclarativeTool<{path: string}, string> {
  readonly name = 'read_file';
  readonly description = 'Read contents of a file';
  
  invoke(params: {path: string}): Promise<ToolResult<string>>;
}

/**
 * Write file tool for creating or overwriting files
 */
class WriteFileTool extends DeclarativeTool<{path: string, content: string}, void> {
  readonly name = 'write_file';
  readonly description = 'Write content to a file';
  
  invoke(params: {path: string, content: string}): Promise<ToolResult<void>>;
}

/**
 * Edit file tool for making targeted changes to files
 */
class EditTool extends DeclarativeTool {
  readonly name = 'edit';
  readonly description = 'Edit a file with find and replace operations';
  
  invoke(params: {
    path: string;
    edits: Array<{
      oldText: string;
      newText: string;
      replaceAll?: boolean;
    }>;
  }): Promise<ToolResult>;
}

/**
 * Directory listing tool
 */
class LsTool extends DeclarativeTool {
  readonly name = 'ls';
  readonly description = 'List directory contents';
  
  invoke(params: {
    path?: string;
    all?: boolean;
    long?: boolean;
  }): Promise<ToolResult<string[]>>;
}

/**
 * Read multiple files tool for batch file operations
 */
class ReadManyFilesTool extends DeclarativeTool {
  readonly name = 'read_many_files';
  readonly description = 'Read contents of multiple files';
  
  invoke(params: {
    paths: string[];
    maxFiles?: number;
  }): Promise<ToolResult<{[path: string]: string}>>;
}

/**
 * Grep tool for text search within files
 */
class GrepTool extends DeclarativeTool {
  readonly name = 'grep';
  readonly description = 'Search for text patterns in files';
  
  invoke(params: {
    pattern: string;
    paths?: string[];
    recursive?: boolean;
    ignoreCase?: boolean;
    lineNumbers?: boolean;
  }): Promise<ToolResult<string>>;
}

/**
 * Ripgrep tool for fast text search
 */
class RipGrepTool extends DeclarativeTool {
  readonly name = 'rg';
  readonly description = 'Fast text search using ripgrep';
  
  invoke(params: {
    pattern: string;
    paths?: string[];
    type?: string;
    ignoreCase?: boolean;
    contextLines?: number;
  }): Promise<ToolResult<string>>;
}

/**
 * Glob tool for file pattern matching
 */
class GlobTool extends DeclarativeTool {
  readonly name = 'glob';
  readonly description = 'Find files matching glob patterns';
  
  invoke(params: {
    pattern: string;
    cwd?: string;
    ignore?: string[];
  }): Promise<ToolResult<string[]>>;
}

/**
 * Shell command execution tool
 */
class ShellTool extends DeclarativeTool {
  readonly name = 'shell';
  readonly description = 'Execute shell commands';
  
  invoke(params: {
    command: string;
    args?: string[];
    cwd?: string;
    env?: Record<string, string>;
    timeout?: number;
  }): Promise<ToolResult<{stdout: string, stderr: string, exitCode: number}>>;
}

/**
 * Web fetch tool for downloading web content
 */
class WebFetchTool extends DeclarativeTool {
  readonly name = 'web_fetch';
  readonly description = 'Fetch content from web URLs';
  
  invoke(params: {
    url: string;
    headers?: Record<string, string>;
    timeout?: number;
  }): Promise<ToolResult<{content: string, contentType: string, status: number}>>;
}

/**
 * Web search tool for search engine queries
 */
class WebSearchTool extends DeclarativeTool {
  readonly name = 'web_search';
  readonly description = 'Search the web for information';
  
  invoke(params: {
    query: string;
    maxResults?: number;
    site?: string;
  }): Promise<ToolResult<Array<{title: string, url: string, snippet: string}>>>;
}

/**
 * MCP client tool for server communication
 */
class McpClientTool extends DeclarativeTool {
  readonly name = 'mcp_client';
  readonly description = 'Communicate with MCP servers';
  
  invoke(params: {
    serverName: string;
    method: string;
    params?: any;
  }): Promise<ToolResult<any>>;
}

/**
 * MCP tool wrapper for external MCP tools
 */
class McpTool extends DeclarativeTool {
  constructor(
    private serverName: string,
    private toolDefinition: any
  );
  
  invoke(params: any): Promise<ToolResult<any>>;
}

/**
 * Memory management tool for AI context
 */
class MemoryTool extends DeclarativeTool {
  readonly name = 'memory';
  readonly description = 'Manage AI memory and context';
  
  invoke(params: {
    action: 'read' | 'write' | 'append' | 'clear';
    key?: string;
    value?: any;
    scope?: 'session' | 'global' | 'project';
  }): Promise<ToolResult<any>>;
}

/**
 * Type definitions
 */
type AnyToolInvocation = ToolInvocation;
type AnyDeclarativeTool = DeclarativeTool<any, any>;

/**
 * File diff information
 */
interface FileDiff {
  added: number;
  removed: number;
  modified: number;
  hunks: DiffHunk[];
}

interface DiffHunk {
  oldStart: number;
  oldLines: number;
  newStart: number;
  newLines: number;
  lines: string[];
}

/**
 * Diff statistics
 */
interface DiffStat {
  files: number;
  insertions: number;
  deletions: number;
}

/**
 * Tool type guard
 * @param obj - Object to check
 * @returns True if object is a tool
 */
function isTool(obj: unknown): obj is AnyDeclarativeTool;

/**
 * Detect cycles in JSON schema
 * @param schema - Schema object to check
 * @returns True if schema has cycles
 */
function hasCycleInSchema(schema: object): boolean;

import { 
  DeclarativeTool, 
  BaseDeclarativeTool,
  ToolResult,
  Kind,
  ReadFileTool,
  ShellTool 
} from '@google/gemini-cli-core';

// Custom tool development
class CustomAnalysisTool extends BaseDeclarativeTool<{path: string}, {summary: string}> {
  readonly name = 'analyze_code';
  readonly description = 'Analyze code file for complexity and patterns';
  readonly parameters = {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'File path to analyze' }
    },
    required: ['path']
  };
  
  async invoke(params: {path: string}): Promise<ToolResult<{summary: string}>> {
    try {
      // Validate parameters automatically
      this.validateParams(params);
      
      // Perform analysis
      const analysis = await this.analyzeFile(params.path);
      
      return this.createResult({summary: analysis});
    } catch (error) {
      return this.createError(`Analysis failed: ${error.message}`);
    }
  }
  
  private async analyzeFile(path: string): Promise<string> {
    // Implementation details
    return 'Analysis complete';
  }
}

// Using built-in tools
const readTool = new ReadFileTool();
const result = await readTool.invoke({path: '/path/to/file.txt'});

if (result.error) {
  console.error('Read failed:', result.error.message);
} else {
  console.log('File contents:', result.result);
}

// Shell command execution
const shellTool = new ShellTool();
const cmdResult = await shellTool.invoke({
  command: 'git',
  args: ['status', '--porcelain'],
  cwd: '/path/to/repo'
});

console.log('Git status:', cmdResult.result.stdout);