confused-ai-core 0.1.0

package/src/tools/base-tool.ts

@@ -0,0 +1,223 @@
+/**
+ * Base tool implementation
+ */
+
+import { z } from 'zod';
+import {
+    Tool,
+    ToolParameters,
+    ToolContext,
+    ToolResult,
+    ToolError,
+    ToolExecutionMetadata,
+    ToolPermissions,
+    ToolCategory,
+} from './types.js';
+import type { EntityId } from '../core/types.js';
+import { DebugLogger, createDebugLogger } from '../debug-logger.js';
+
+/**
+ * Configuration for creating a base tool
+ */
+export interface BaseToolConfig<TParams extends ToolParameters> {
+    id?: EntityId;
+    name: string;
+    description: string;
+    parameters: TParams;
+    permissions?: Partial<ToolPermissions>;
+    category?: ToolCategory;
+    version?: string;
+    author?: string;
+    tags?: string[];
+    /** Enable debug logging for this tool */
+    debug?: boolean;
+}
+
+/**
+ * Abstract base class for tools
+ */
+export abstract class BaseTool<TParams extends ToolParameters = ToolParameters, TOutput = unknown>
+    implements Tool<TParams, TOutput> {
+    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[];
+    protected logger: DebugLogger;
+
+    constructor(config: BaseToolConfig<TParams>) {
+        this.id = config.id ?? `tool-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        this.name = config.name;
+        this.description = config.description;
+        this.parameters = config.parameters;
+        this.permissions = {
+            allowNetwork: config.permissions?.allowNetwork ?? false,
+            allowFileSystem: config.permissions?.allowFileSystem ?? false,
+            allowedPaths: config.permissions?.allowedPaths,
+            allowedHosts: config.permissions?.allowedHosts,
+            maxExecutionTimeMs: config.permissions?.maxExecutionTimeMs ?? 30000,
+        };
+        this.category = config.category ?? ToolCategory.UTILITY;
+        this.version = config.version ?? '1.0.0';
+        this.author = config.author;
+        this.tags = config.tags;
+        this.logger = createDebugLogger(`Tool:${this.name}`, config.debug ?? false);
+    }
+
+    /**
+     * Execute the tool with the given parameters
+     */
+    async execute(params: z.infer<TParams>, context: ToolContext): Promise<ToolResult<TOutput>> {
+        const startTime = new Date();
+        let retries = 0;
+
+        this.logger.logStart(`Tool execution: ${this.name}`, {
+            toolId: this.id,
+            category: this.category,
+        });
+
+        try {
+            // Validate parameters
+            this.logger.debug('Validating parameters');
+            const validation = this.parameters.safeParse(params);
+            if (!validation.success) {
+                this.logger.error('Parameter validation failed', undefined, {
+                    error: validation.error.message,
+                });
+                return this.createErrorResult(
+                    startTime,
+                    retries,
+                    'VALIDATION_ERROR',
+                    `Invalid parameters: ${validation.error.message}`
+                );
+            }
+
+            // Check permissions
+            this.logger.debug('Checking permissions');
+            const permissionError = this.checkPermissions(context);
+            if (permissionError) {
+                this.logger.error('Permission denied', undefined, { error: permissionError });
+                return this.createErrorResult(
+                    startTime,
+                    retries,
+                    'PERMISSION_DENIED',
+                    permissionError
+                );
+            }
+
+            // Execute with timeout
+            this.logger.debug('Executing tool logic');
+            const timeoutMs = context.timeoutMs ?? this.permissions.maxExecutionTimeMs;
+            const data = await this.executeWithTimeout(validation.data, context, timeoutMs);
+
+            const endTime = new Date();
+            const metadata: ToolExecutionMetadata = {
+                startTime,
+                endTime,
+                retries,
+            };
+
+            this.logger.logComplete(`Tool execution: ${this.name}`, endTime.getTime() - startTime.getTime());
+            return {
+                success: true,
+                data,
+                executionTimeMs: endTime.getTime() - startTime.getTime(),
+                metadata,
+            };
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Tool execution failed: ${this.name}`, undefined, { error: errorMessage });
+            return this.createErrorResult(startTime, retries, 'EXECUTION_ERROR', errorMessage);
+        }
+    }
+
+    /**
+     * Validate parameters without executing
+     */
+    validate(params: unknown): params is z.infer<TParams> {
+        return this.parameters.safeParse(params).success;
+    }
+
+    /**
+     * Execute the tool's core logic - must be implemented by subclasses
+     */
+    protected abstract performExecute(
+        params: z.infer<TParams>,
+        context: ToolContext
+    ): Promise<TOutput>;
+
+    /**
+     * Execute with timeout support
+     */
+    private async executeWithTimeout(
+        params: z.infer<TParams>,
+        context: ToolContext,
+        timeoutMs: number
+    ): Promise<TOutput> {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error(`Tool execution timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+
+            this.performExecute(params, context)
+                .then(result => {
+                    clearTimeout(timeoutId);
+                    resolve(result);
+                })
+                .catch(error => {
+                    clearTimeout(timeoutId);
+                    reject(error);
+                });
+        });
+    }
+
+    /**
+     * Check if the tool has required permissions
+     */
+    private checkPermissions(context: ToolContext): string | null {
+        // Check network permission
+        if (this.permissions.allowNetwork && !context.permissions.allowNetwork) {
+            return 'Network access not permitted in context';
+        }
+
+        // Check filesystem permission
+        if (this.permissions.allowFileSystem && !context.permissions.allowFileSystem) {
+            return 'Filesystem access not permitted in context';
+        }
+
+        return null;
+    }
+
+    /**
+     * Create an error result
+     */
+    private createErrorResult(
+        startTime: Date,
+        retries: number,
+        code: string,
+        message: string
+    ): ToolResult<TOutput> {
+        const endTime = new Date();
+        const error: ToolError = {
+            code,
+            message,
+        };
+
+        const metadata: ToolExecutionMetadata = {
+            startTime,
+            endTime,
+            retries,
+        };
+
+        return {
+            success: false,
+            error,
+            executionTimeMs: endTime.getTime() - startTime.getTime(),
+            metadata,
+        };
+    }
+}

package/src/tools/browser-tool.ts

@@ -0,0 +1,123 @@
+/**
+ * Browser tool – fetch a URL and return page title, text content, and links
+ */
+
+import { z } from 'zod';
+import { BaseTool, BaseToolConfig } from './base-tool.js';
+import { ToolContext, ToolCategory } from './types.js';
+
+const BrowserToolParameters = z.object({
+    url: z.string().url(),
+    timeout: z.number().min(1000).max(60000).optional(),
+    includeLinks: z.boolean().default(true),
+});
+
+interface BrowserPageResult {
+    url: string;
+    title: string;
+    textContent: string;
+    links: string[];
+    status: number;
+}
+
+function extractTitle(html: string): string {
+    const match = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    return match ? stripTags(match[1]).trim() : '';
+}
+
+function stripTags(html: string): string {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .trim();
+}
+
+function extractLinks(html: string, baseUrl: string): string[] {
+    const hrefRegex = /<a[^>]+href\s*=\s*["']([^"']+)["']/gi;
+    const seen = new Set<string>();
+    const links: string[] = [];
+    let m: RegExpExecArray | null;
+    while ((m = hrefRegex.exec(html)) !== null) {
+        let href = m[1].trim();
+        if (!href || href.startsWith('#') || href.startsWith('javascript:')) continue;
+        try {
+            const resolved = new URL(href, baseUrl).href;
+            if (!seen.has(resolved)) {
+                seen.add(resolved);
+                links.push(resolved);
+            }
+        } catch {
+            // skip invalid URLs
+        }
+    }
+    return links;
+}
+
+export class BrowserTool extends BaseTool<typeof BrowserToolParameters, BrowserPageResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof BrowserToolParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'browser.fetch',
+            description:
+                config?.description ??
+                'Fetch a web page and return its title, main text content, and links (for reading and navigating pages)',
+            parameters: BrowserToolParameters,
+            category: config?.category ?? ToolCategory.WEB,
+            permissions: {
+                allowNetwork: true,
+                maxExecutionTimeMs: 30000,
+                ...config?.permissions,
+            },
+            version: config?.version,
+            author: config?.author,
+            tags: config?.tags,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof BrowserToolParameters>,
+        _context: ToolContext
+    ): Promise<BrowserPageResult> {
+        const { url, timeout, includeLinks } = params;
+
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout ?? 30000);
+
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    Accept: 'text/html, application/xhtml+xml, */*',
+                    'User-Agent':
+                        'Mozilla/5.0 (compatible; ConfusedAI/1.0; +https://github.com/confused-ai)',
+                },
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+
+            const html = await response.text();
+            const title = extractTitle(html);
+            const textContent = stripTags(html);
+            const links = includeLinks ? extractLinks(html, url) : [];
+
+            return {
+                url,
+                title,
+                textContent,
+                links,
+                status: response.status,
+            };
+        } catch (error) {
+            clearTimeout(timeoutId);
+            throw error;
+        }
+    }
+}

package/src/tools/calculator-tool.ts

@@ -0,0 +1,265 @@
+/**
+ * Calculator tool implementation - TypeScript  CalculatorTools
+ */
+
+import { z } from 'zod';
+import { BaseTool, BaseToolConfig } from './base-tool.js';
+import { ToolContext, ToolCategory } from './types.js';
+
+/**
+ * Parameters for calculator operations
+ */
+const CalculatorOperationParameters = z.object({
+    a: z.number().describe('First number'),
+    b: z.number().describe('Second number'),
+});
+
+const CalculatorSingleNumberParameters = z.object({
+    n: z.number().describe('Number to operate on'),
+});
+
+interface CalculatorResult {
+    operation: string;
+    result?: number;
+    error?: string;
+}
+
+/**
+ * Add two numbers
+ */
+export class CalculatorAddTool extends BaseTool<typeof CalculatorOperationParameters, CalculatorResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof CalculatorOperationParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'calculator.add',
+            description: config?.description ?? 'Add two numbers and return the result',
+            parameters: CalculatorOperationParameters,
+            category: config?.category ?? ToolCategory.UTILITY,
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof CalculatorOperationParameters>,
+        _context: ToolContext
+    ): Promise<CalculatorResult> {
+        const result = params.a + params.b;
+        return { operation: 'addition', result };
+    }
+}
+
+/**
+ * Subtract two numbers
+ */
+export class CalculatorSubtractTool extends BaseTool<typeof CalculatorOperationParameters, CalculatorResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof CalculatorOperationParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'calculator.subtract',
+            description: config?.description ?? 'Subtract second number from first and return the result',
+            parameters: CalculatorOperationParameters,
+            category: config?.category ?? ToolCategory.UTILITY,
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof CalculatorOperationParameters>,
+        _context: ToolContext
+    ): Promise<CalculatorResult> {
+        const result = params.a - params.b;
+        return { operation: 'subtraction', result };
+    }
+}
+
+/**
+ * Multiply two numbers
+ */
+export class CalculatorMultiplyTool extends BaseTool<typeof CalculatorOperationParameters, CalculatorResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof CalculatorOperationParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'calculator.multiply',
+            description: config?.description ?? 'Multiply two numbers and return the result',
+            parameters: CalculatorOperationParameters,
+            category: config?.category ?? ToolCategory.UTILITY,
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof CalculatorOperationParameters>,
+        _context: ToolContext
+    ): Promise<CalculatorResult> {
+        const result = params.a * params.b;
+        return { operation: 'multiplication', result };
+    }
+}
+
+/**
+ * Divide two numbers
+ */
+export class CalculatorDivideTool extends BaseTool<typeof CalculatorOperationParameters, CalculatorResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof CalculatorOperationParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'calculator.divide',
+            description: config?.description ?? 'Divide first number by second and return the result',
+            parameters: CalculatorOperationParameters,
+            category: config?.category ?? ToolCategory.UTILITY,
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof CalculatorOperationParameters>,
+        _context: ToolContext
+    ): Promise<CalculatorResult> {
+        if (params.b === 0) {
+            return { operation: 'division', error: 'Division by zero is undefined' };
+        }
+        const result = params.a / params.b;
+        return { operation: 'division', result };
+    }
+}
+
+/**
+ * Raise a number to a power
+ */
+export class CalculatorExponentiateTool extends BaseTool<typeof CalculatorOperationParameters, CalculatorResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof CalculatorOperationParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'calculator.exponentiate',
+            description: config?.description ?? 'Raise first number to the power of the second number',
+            parameters: CalculatorOperationParameters,
+            category: config?.category ?? ToolCategory.UTILITY,
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof CalculatorOperationParameters>,
+        _context: ToolContext
+    ): Promise<CalculatorResult> {
+        const result = Math.pow(params.a, params.b);
+        return { operation: 'exponentiation', result };
+    }
+}
+
+/**
+ * Calculate factorial of a number
+ */
+export class CalculatorFactorialTool extends BaseTool<typeof CalculatorSingleNumberParameters, CalculatorResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof CalculatorSingleNumberParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'calculator.factorial',
+            description: config?.description ?? 'Calculate the factorial of a number',
+            parameters: CalculatorSingleNumberParameters,
+            category: config?.category ?? ToolCategory.UTILITY,
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof CalculatorSingleNumberParameters>,
+        _context: ToolContext
+    ): Promise<CalculatorResult> {
+        if (params.n < 0) {
+            return { operation: 'factorial', error: 'Factorial of a negative number is undefined' };
+        }
+        if (!Number.isInteger(params.n)) {
+            return { operation: 'factorial', error: 'Factorial is only defined for integers' };
+        }
+        let result = 1;
+        for (let i = 2; i <= params.n; i++) {
+            result *= i;
+        }
+        return { operation: 'factorial', result };
+    }
+}
+
+/**
+ * Check if a number is prime
+ */
+export class CalculatorIsPrimeTool extends BaseTool<typeof CalculatorSingleNumberParameters, CalculatorResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof CalculatorSingleNumberParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'calculator.is_prime',
+            description: config?.description ?? 'Check if a number is prime',
+            parameters: CalculatorSingleNumberParameters,
+            category: config?.category ?? ToolCategory.UTILITY,
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof CalculatorSingleNumberParameters>,
+        _context: ToolContext
+    ): Promise<CalculatorResult> {
+        const n = params.n;
+        if (n <= 1) {
+            return { operation: 'prime_check', result: 0 }; // 0 = false
+        }
+        if (n <= 3) {
+            return { operation: 'prime_check', result: 1 }; // 1 = true
+        }
+        if (n % 2 === 0 || n % 3 === 0) {
+            return { operation: 'prime_check', result: 0 };
+        }
+        for (let i = 5; i * i <= n; i += 6) {
+            if (n % i === 0 || n % (i + 2) === 0) {
+                return { operation: 'prime_check', result: 0 };
+            }
+        }
+        return { operation: 'prime_check', result: 1 };
+    }
+}
+
+/**
+ * Calculate square root of a number
+ */
+export class CalculatorSquareRootTool extends BaseTool<typeof CalculatorSingleNumberParameters, CalculatorResult> {
+    constructor(config?: Partial<Omit<BaseToolConfig<typeof CalculatorSingleNumberParameters>, 'parameters'>>) {
+        super({
+            name: config?.name ?? 'calculator.square_root',
+            description: config?.description ?? 'Calculate the square root of a number',
+            parameters: CalculatorSingleNumberParameters,
+            category: config?.category ?? ToolCategory.UTILITY,
+            ...config,
+        });
+    }
+
+    protected async performExecute(
+        params: z.infer<typeof CalculatorSingleNumberParameters>,
+        _context: ToolContext
+    ): Promise<CalculatorResult> {
+        if (params.n < 0) {
+            return { operation: 'square_root', error: 'Square root of a negative number is undefined' };
+        }
+        const result = Math.sqrt(params.n);
+        return { operation: 'square_root', result };
+    }
+}
+
+/**
+ * Calculator toolkit - provides all calculator tools
+ */
+export class CalculatorToolkit {
+    static createAll(): Array<
+        | CalculatorAddTool
+        | CalculatorSubtractTool
+        | CalculatorMultiplyTool
+        | CalculatorDivideTool
+        | CalculatorExponentiateTool
+        | CalculatorFactorialTool
+        | CalculatorIsPrimeTool
+        | CalculatorSquareRootTool
+    > {
+        return [
+            new CalculatorAddTool(),
+            new CalculatorSubtractTool(),
+            new CalculatorMultiplyTool(),
+            new CalculatorDivideTool(),
+            new CalculatorExponentiateTool(),
+            new CalculatorFactorialTool(),
+            new CalculatorIsPrimeTool(),
+            new CalculatorSquareRootTool(),
+        ];
+    }
+}