confused-ai-core 0.1.0

package/src/tools/telegram-tool.ts

@@ -0,0 +1,127 @@
+/**
+ * Telegram tool implementation - TypeScript TelegramTools
+ */
+
+import { z } from 'zod';
+import { BaseTool, BaseToolConfig } from './base-tool.js';
+import { ToolContext, ToolCategory } from './types.js';
+
+/**
+ * Telegram API response
+ */
+interface TelegramResponse {
+    ok: boolean;
+    result?: unknown;
+    description?: string;
+    error_code?: number;
+}
+
+interface TelegramResult {
+    success: boolean;
+    message?: string;
+    error?: string;
+    response?: unknown;
+}
+
+/**
+ * Parameters for sending a Telegram message
+ */
+const TelegramSendMessageParameters = z.object({
+    message: z.string().describe('The message to send'),
+    chat_id: z.string().optional().describe('Chat ID to send message to (overrides default)'),
+    parse_mode: z.enum(['HTML', 'Markdown', 'MarkdownV2']).optional().describe('Parse mode for the message'),
+});
+
+/**
+ * Telegram tool for sending messages
+ */
+export class TelegramTool extends BaseTool<typeof TelegramSendMessageParameters, TelegramResult> {
+    private token: string;
+    private defaultChatId: string;
+    private baseUrl = 'https://api.telegram.org';
+
+    constructor(
+        config?: Partial<Omit<BaseToolConfig<typeof TelegramSendMessageParameters>, 'parameters'>> & {
+            token?: string;
+            chatId?: string;
+        }
+    ) {
+        super({
+            name: config?.name ?? 'telegram.send_message',
+            description: config?.description ?? 'Send a message to a Telegram chat',
+            parameters: TelegramSendMessageParameters,
+            category: config?.category ?? ToolCategory.API,
+            permissions: {
+                allowNetwork: true,
+                maxExecutionTimeMs: 30000,
+                ...config?.permissions,
+            },
+            ...config,
+        });
+
+        this.token = config?.token || process.env.TELEGRAM_TOKEN || '';
+        this.defaultChatId = config?.chatId || process.env.TELEGRAM_CHAT_ID || '';
+
+        if (!this.token) {
+            throw new Error('Telegram token is required. Set TELEGRAM_TOKEN environment variable or pass token in config.');
+        }
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof TelegramSendMessageParameters>,
+        _context: ToolContext
+    ): Promise<TelegramResult> {
+        const chatId = params.chat_id || this.defaultChatId;
+
+        if (!chatId) {
+            return {
+                success: false,
+                error: 'Chat ID is required. Set TELEGRAM_CHAT_ID environment variable, pass chatId in config, or provide chat_id in parameters.',
+            };
+        }
+
+        try {
+            const response = await fetch(`${this.baseUrl}/bot${this.token}/sendMessage`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    chat_id: chatId,
+                    text: params.message,
+                    parse_mode: params.parse_mode,
+                }),
+            });
+
+            const data = (await response.json()) as TelegramResponse;
+
+            if (data.ok) {
+                return {
+                    success: true,
+                    message: 'Message sent successfully',
+                    response: data.result,
+                };
+            } else {
+                return {
+                    success: false,
+                    error: data.description || 'Unknown error from Telegram API',
+                    response: data,
+                };
+            }
+        } catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error occurred',
+            };
+        }
+    }
+}
+
+/**
+ * Telegram toolkit
+ */
+export class TelegramToolkit {
+    static create(options: { token?: string; chatId?: string }): Array<TelegramTool> {
+        return [new TelegramTool({ token: options.token, chatId: options.chatId })];
+    }
+}

package/src/tools/types.ts

@@ -0,0 +1,229 @@
+/**
+ * Tool integration types and interfaces
+ */
+
+import type { EntityId } from '../core/types.js';
+import { z } from 'zod';
+
+/**
+ * Tool parameter schema using Zod
+ */
+export type ToolParameters = z.ZodObject<Record<string, z.ZodType>>;
+
+/**
+ * Tool execution context
+ */
+export interface ToolContext {
+    readonly toolId: EntityId;
+    readonly agentId: EntityId;
+    readonly sessionId: string;
+    readonly timeoutMs?: number;
+    readonly permissions: ToolPermissions;
+}
+
+/**
+ * Tool permissions
+ */
+export interface ToolPermissions {
+    readonly allowNetwork: boolean;
+    readonly allowFileSystem: boolean;
+    readonly allowedPaths?: string[];
+    readonly allowedHosts?: string[];
+    readonly maxExecutionTimeMs: number;
+}
+
+/**
+ * Tool execution result
+ */
+export interface ToolResult<T = unknown> {
+    readonly success: boolean;
+    readonly data?: T;
+    readonly error?: ToolError;
+    readonly executionTimeMs: number;
+    readonly metadata: ToolExecutionMetadata;
+}
+
+/**
+ * Tool error details
+ */
+export interface ToolError {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: unknown;
+}
+
+/**
+ * Tool execution metadata
+ */
+export interface ToolExecutionMetadata {
+    readonly startTime: Date;
+    readonly endTime: Date;
+    readonly retries: number;
+    readonly tokensUsed?: number;
+}
+
+/**
+ * Tool definition
+ */
+export interface Tool<TParams extends ToolParameters = ToolParameters, TOutput = unknown> {
+    readonly id: EntityId;
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: TParams;
+    readonly permissions: ToolPermissions;
+    readonly category: ToolCategory;
+    readonly version: string;
+    readonly author?: string;
+    readonly tags?: string[];
+
+    /**
+     * Execute the tool with validated parameters
+     */
+    execute(params: z.infer<TParams>, context: ToolContext): Promise<ToolResult<TOutput>>;
+
+    /**
+     * Validate parameters without executing
+     */
+    validate(params: unknown): params is z.infer<TParams>;
+}
+
+/**
+ * Tool categories
+ */
+export enum ToolCategory {
+    WEB = 'web',
+    DATABASE = 'database',
+    FILE_SYSTEM = 'file_system',
+    API = 'api',
+    UTILITY = 'utility',
+    AI = 'ai',
+    CUSTOM = 'custom',
+}
+
+/**
+ * Tool registry for managing available tools
+ */
+export interface ToolRegistry {
+    /**
+     * Register a tool
+     */
+    register(tool: Tool): void;
+
+    /**
+     * Unregister a tool by ID
+     */
+    unregister(toolId: EntityId): boolean;
+
+    /**
+     * Get a tool by ID
+     */
+    get(toolId: EntityId): Tool | undefined;
+
+    /**
+     * Get a tool by name
+     */
+    getByName(name: string): Tool | undefined;
+
+    /**
+     * List all registered tools
+     */
+    list(): Tool[];
+
+    /**
+     * List tools by category
+     */
+    listByCategory(category: ToolCategory): Tool[];
+
+    /**
+     * Search tools by name or description
+     */
+    search(query: string): Tool[];
+
+    /**
+     * Check if a tool is registered
+     */
+    has(toolId: EntityId): boolean;
+
+    /**
+     * Clear all registered tools
+     */
+    clear(): void;
+}
+
+/**
+ * Tool sandbox configuration
+ */
+export interface ToolSandboxConfig {
+    readonly enabled: boolean;
+    readonly timeoutMs: number;
+    readonly maxMemoryMb: number;
+    readonly allowedModules?: string[];
+    readonly blockedModules?: string[];
+    readonly environmentVariables?: Record<string, string>;
+}
+
+/**
+ * Tool middleware for intercepting tool calls
+ */
+export interface ToolMiddleware {
+    /**
+     * Called before tool execution
+     */
+    beforeExecute?: (tool: Tool, params: unknown, context: ToolContext) => Promise<void> | void;
+
+    /**
+     * Called after tool execution
+     */
+    afterExecute?: (tool: Tool, result: ToolResult, context: ToolContext) => Promise<void> | void;
+
+    /**
+     * Called on tool execution error
+     */
+    onError?: (tool: Tool, error: Error, context: ToolContext) => Promise<void> | void;
+}
+
+/**
+ * Tool factory for creating tool instances
+ */
+export interface ToolFactory {
+    /**
+     * Create a tool instance
+     */
+    create(config: Record<string, unknown>): Tool;
+
+    /**
+     * Get the tool schema
+     */
+    getSchema(): ToolSchema;
+}
+
+/**
+ * Tool schema for documentation and validation
+ */
+export interface ToolSchema {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, ParameterSchema>;
+    readonly returns: ParameterSchema;
+    readonly examples?: ToolExample[];
+}
+
+/**
+ * Parameter schema
+ */
+export interface ParameterSchema {
+    readonly type: string;
+    readonly description: string;
+    readonly required: boolean;
+    readonly default?: unknown;
+    readonly enum?: unknown[];
+}
+
+/**
+ * Tool usage example
+ */
+export interface ToolExample {
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly expectedOutput?: unknown;
+}

package/src/tools/websearch-tool.ts

@@ -0,0 +1,335 @@
+/**
+ * Web search tool implementation - TypeScript  WebSearchTools and DuckDuckGoTools
+ */
+
+import { z } from 'zod';
+import { BaseTool, BaseToolConfig } from './base-tool.js';
+import { ToolContext, ToolCategory } from './types.js';
+
+/**
+ * Search result item
+ */
+interface SearchResult {
+    title: string;
+    url: string;
+    snippet?: string;
+    source?: string;
+}
+
+interface WebSearchResponse {
+    query: string;
+    results: SearchResult[];
+    backend?: string;
+}
+
+interface NewsResult {
+    title: string;
+    url: string;
+    snippet?: string;
+    date?: string;
+    source?: string;
+}
+
+interface NewsSearchResponse {
+    query: string;
+    results: NewsResult[];
+    backend?: string;
+}
+
+/**
+ * Parameters for web search
+ */
+const WebSearchParameters = z.object({
+    query: z.string().describe('The search query'),
+    max_results: z.number().min(1).max(20).optional().default(5).describe('Maximum number of results to return'),
+});
+
+/**
+ * DuckDuckGo search tool using DuckDuckGo's HTML interface
+ */
+export class DuckDuckGoSearchTool extends BaseTool<typeof WebSearchParameters, WebSearchResponse> {
+    private modifier?: string;
+
+    constructor(
+        config?: Partial<Omit<BaseToolConfig<typeof WebSearchParameters>, 'parameters'>> & {
+            modifier?: string;
+        }
+    ) {
+        super({
+            name: config?.name ?? 'duckduckgo.search',
+            description: config?.description ?? 'Search the web using DuckDuckGo',
+            parameters: WebSearchParameters,
+            category: config?.category ?? ToolCategory.WEB,
+            permissions: {
+                allowNetwork: true,
+                maxExecutionTimeMs: 30000,
+                ...config?.permissions,
+            },
+            ...config,
+        });
+        this.modifier = config?.modifier;
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof WebSearchParameters>,
+        _context: ToolContext
+    ): Promise<WebSearchResponse> {
+        const searchQuery = this.modifier ? `${this.modifier} ${params.query}` : params.query;
+
+        try {
+            // Use DuckDuckGo's instant answer API
+            const response = await fetch(
+                `https://duckduckgo.com/html/?q=${encodeURIComponent(searchQuery)}`,
+                {
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+                    },
+                }
+            );
+
+            if (!response.ok) {
+                throw new Error(`DuckDuckGo search failed: ${response.status}`);
+            }
+
+            const html = await response.text();
+            const results = this.parseResults(html, params.max_results);
+
+            return {
+                query: searchQuery,
+                results,
+                backend: 'duckduckgo',
+            };
+        } catch (error) {
+            // Fallback to returning empty results with error info
+            return {
+                query: searchQuery,
+                results: [],
+                backend: 'duckduckgo',
+            };
+        }
+    }
+
+    private parseResults(html: string, maxResults: number): SearchResult[] {
+        const results: SearchResult[] = [];
+        // Simple regex-based parsing for DuckDuckGo HTML results
+        const resultRegex = /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi;
+
+        let match;
+        const titles: string[] = [];
+        const urls: string[] = [];
+
+        while ((match = resultRegex.exec(html)) !== null && urls.length < maxResults) {
+            const url = match[1];
+            const title = match[2].replace(/<[^>]*>/g, ''); // Strip HTML tags
+            if (url && !url.startsWith('/')) {
+                urls.push(url);
+                titles.push(title);
+            }
+        }
+
+        for (let i = 0; i < urls.length; i++) {
+            results.push({
+                title: titles[i] || 'Untitled',
+                url: urls[i],
+                source: 'DuckDuckGo',
+            });
+        }
+
+        return results;
+    }
+}
+
+/**
+ * DuckDuckGo news search tool
+ */
+export class DuckDuckGoNewsTool extends BaseTool<typeof WebSearchParameters, NewsSearchResponse> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof WebSearchParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'duckduckgo.news',
+            description: config?.description ?? 'Search for news using DuckDuckGo',
+            parameters: WebSearchParameters,
+            category: config?.category ?? ToolCategory.WEB,
+            permissions: {
+                allowNetwork: true,
+                maxExecutionTimeMs: 30000,
+                ...config?.permissions,
+            },
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof WebSearchParameters>,
+        _context: ToolContext
+    ): Promise<NewsSearchResponse> {
+        try {
+            const response = await fetch(
+                `https://duckduckgo.com/html/?q=${encodeURIComponent(params.query + ' news')}`,
+                {
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+                    },
+                }
+            );
+
+            if (!response.ok) {
+                throw new Error(`DuckDuckGo news search failed: ${response.status}`);
+            }
+
+            const html = await response.text();
+            const results = this.parseNewsResults(html, params.max_results);
+
+            return {
+                query: params.query,
+                results,
+                backend: 'duckduckgo',
+            };
+        } catch (error) {
+            return {
+                query: params.query,
+                results: [],
+                backend: 'duckduckgo',
+            };
+        }
+    }
+
+    private parseNewsResults(html: string, maxResults: number): NewsResult[] {
+        const results: NewsResult[] = [];
+        // Similar parsing logic for news
+        const resultRegex = /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi;
+
+        let match;
+        while ((match = resultRegex.exec(html)) !== null && results.length < maxResults) {
+            const url = match[1];
+            const title = match[2].replace(/<[^>]*>/g, '');
+            if (url && !url.startsWith('/')) {
+                results.push({
+                    title: title || 'Untitled',
+                    url: url,
+                    source: 'DuckDuckGo News',
+                });
+            }
+        }
+
+        return results;
+    }
+}
+
+/**
+ * Generic web search tool that can use different backends
+ */
+const GenericWebSearchParameters = z.object({
+    query: z.string().describe('The search query'),
+    max_results: z.number().min(1).max(20).optional().default(5).describe('Maximum number of results to return'),
+    backend: z.enum(['duckduckgo', 'bing', 'google']).optional().default('duckduckgo').describe('Search backend to use'),
+});
+
+export class WebSearchTool extends BaseTool<typeof GenericWebSearchParameters, WebSearchResponse> {
+    private modifier?: string;
+
+    constructor(
+        config?: Partial<Omit<BaseToolConfig<typeof GenericWebSearchParameters>, 'parameters'>> & {
+            modifier?: string;
+        }
+    ) {
+        super({
+            name: config?.name ?? 'web.search',
+            description: config?.description ?? 'Search the web using various search engines',
+            parameters: GenericWebSearchParameters,
+            category: config?.category ?? ToolCategory.WEB,
+            permissions: {
+                allowNetwork: true,
+                maxExecutionTimeMs: 30000,
+                ...config?.permissions,
+            },
+            ...config,
+        });
+        this.modifier = config?.modifier;
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof GenericWebSearchParameters>,
+        _context: ToolContext
+    ): Promise<WebSearchResponse> {
+        const searchQuery = this.modifier ? `${this.modifier} ${params.query}` : params.query;
+
+        // For now, only DuckDuckGo is implemented without API keys
+        // Other backends would require API keys
+        switch (params.backend) {
+            case 'duckduckgo':
+            default:
+                return this.searchDuckDuckGo(searchQuery, params.max_results);
+        }
+    }
+
+    private async searchDuckDuckGo(query: string, maxResults: number): Promise<WebSearchResponse> {
+        try {
+            const response = await fetch(
+                `https://duckduckgo.com/html/?q=${encodeURIComponent(query)}`,
+                {
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+                    },
+                }
+            );
+
+            if (!response.ok) {
+                throw new Error(`Search failed: ${response.status}`);
+            }
+
+            const html = await response.text();
+            const results = this.parseResults(html, maxResults);
+
+            return {
+                query,
+                results,
+                backend: 'duckduckgo',
+            };
+        } catch (error) {
+            return {
+                query,
+                results: [],
+                backend: 'duckduckgo',
+            };
+        }
+    }
+
+    private parseResults(html: string, maxResults: number): SearchResult[] {
+        const results: SearchResult[] = [];
+        const resultRegex = /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi;
+
+        let match;
+        while ((match = resultRegex.exec(html)) !== null && results.length < maxResults) {
+            const url = match[1];
+            const title = match[2].replace(/<[^>]*>/g, '');
+            if (url && !url.startsWith('/')) {
+                results.push({
+                    title: title || 'Untitled',
+                    url: url,
+                    source: 'DuckDuckGo',
+                });
+            }
+        }
+
+        return results;
+    }
+}
+
+/**
+ * Web search toolkit
+ */
+export class WebSearchToolkit {
+    static createDuckDuckGo(options?: { modifier?: string; enableNews?: boolean }): Array<DuckDuckGoSearchTool | DuckDuckGoNewsTool> {
+        const tools: Array<DuckDuckGoSearchTool | DuckDuckGoNewsTool> = [
+            new DuckDuckGoSearchTool({ modifier: options?.modifier }),
+        ];
+        if (options?.enableNews !== false) {
+            tools.push(new DuckDuckGoNewsTool());
+        }
+        return tools;
+    }
+
+    static createGeneric(options?: { modifier?: string }): Array<WebSearchTool> {
+        return [new WebSearchTool({ modifier: options?.modifier })];
+    }
+}