@compilr-dev/agents 0.0.1

package/dist/tools/define.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Helper for defining tools with type safety
+ */
+import type { Tool, ToolExecutionResult, ToolInputSchema } from './types.js';
+/**
+ * Options for defining a tool
+ */
+export interface DefineToolOptions<T extends object> {
+    /**
+     * Unique name for the tool
+     */
+    name: string;
+    /**
+     * Description of what the tool does (shown to LLM)
+     */
+    description: string;
+    /**
+     * JSON Schema for the tool's input parameters
+     */
+    inputSchema: ToolInputSchema;
+    /**
+     * Function that executes the tool
+     */
+    execute: (input: T) => Promise<ToolExecutionResult>;
+}
+/**
+ * Define a tool with type-safe input handling
+ *
+ * @example
+ * ```typescript
+ * const readFile = defineTool({
+ *   name: 'read_file',
+ *   description: 'Read the contents of a file',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       path: { type: 'string', description: 'File path to read' },
+ *     },
+ *     required: ['path'],
+ *   },
+ *   execute: async ({ path }) => {
+ *     const content = await fs.readFile(path, 'utf-8');
+ *     return { success: true, result: content };
+ *   },
+ * });
+ * ```
+ */
+export declare function defineTool<T extends object>(options: DefineToolOptions<T>): Tool<T>;
+/**
+ * Create a simple tool that returns success with a result
+ */
+export declare function createSuccessResult(result: unknown): ToolExecutionResult;
+/**
+ * Create an error result for a tool
+ */
+export declare function createErrorResult(error: string | Error): ToolExecutionResult;
+/**
+ * Wrap an async function to catch errors and return ToolExecutionResult
+ */
+export declare function wrapToolExecute<T extends object>(fn: (input: T) => Promise<unknown>): (input: T) => Promise<ToolExecutionResult>;

package/dist/tools/define.js

@@ -0,0 +1,65 @@
+/**
+ * Helper for defining tools with type safety
+ */
+/**
+ * Define a tool with type-safe input handling
+ *
+ * @example
+ * ```typescript
+ * const readFile = defineTool({
+ *   name: 'read_file',
+ *   description: 'Read the contents of a file',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       path: { type: 'string', description: 'File path to read' },
+ *     },
+ *     required: ['path'],
+ *   },
+ *   execute: async ({ path }) => {
+ *     const content = await fs.readFile(path, 'utf-8');
+ *     return { success: true, result: content };
+ *   },
+ * });
+ * ```
+ */
+export function defineTool(options) {
+    const definition = {
+        name: options.name,
+        description: options.description,
+        inputSchema: options.inputSchema,
+    };
+    return {
+        definition,
+        execute: options.execute,
+    };
+}
+/**
+ * Create a simple tool that returns success with a result
+ */
+export function createSuccessResult(result) {
+    return { success: true, result };
+}
+/**
+ * Create an error result for a tool
+ */
+export function createErrorResult(error) {
+    return {
+        success: false,
+        error: error instanceof Error ? error.message : error,
+    };
+}
+/**
+ * Wrap an async function to catch errors and return ToolExecutionResult
+ */
+export function wrapToolExecute(fn) {
+    return async (input) => {
+        try {
+            const result = await fn(input);
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error : new Error(String(error)));
+        }
+    };
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tools exports
+ */
+export * from './types.js';
+export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute } from './define.js';
+export type { DefineToolOptions } from './define.js';
+export { DefaultToolRegistry, createToolRegistry } from './registry.js';
+export type { ToolRegistryOptions } from './registry.js';
+export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, createTaskTool, defaultAgentTypes, builtinTools, allBuiltinTools, } from './builtin/index.js';
+export type { ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, BashOutputInput, BashOutputResult, KillShellInput, KillShellResult, ShellStatus, BackgroundShell, ShellOutput, ShellManagerOptions, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, WebFetchInput, WebFetchResult, WebFetchOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, } from './builtin/index.js';

package/dist/tools/index.js

@@ -0,0 +1,37 @@
+/**
+ * Tools exports
+ */
+// Core types
+export * from './types.js';
+// Tool definition helper
+export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute } from './define.js';
+// Tool registry
+export { DefaultToolRegistry, createToolRegistry } from './registry.js';
+// Built-in tools
+export { 
+// Read file
+readFileTool, createReadFileTool, 
+// Write file
+writeFileTool, createWriteFileTool, 
+// Bash
+bashTool, createBashTool, execStream, detectFifoUsage, 
+// Bash output (background shell monitoring)
+bashOutputTool, createBashOutputTool, 
+// Kill shell
+killShellTool, createKillShellTool, 
+// Shell manager
+ShellManager, getDefaultShellManager, setDefaultShellManager, 
+// Grep
+grepTool, createGrepTool, 
+// Glob
+globTool, createGlobTool, 
+// Edit
+editTool, createEditTool, 
+// Todo
+todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, 
+// WebFetch
+webFetchTool, createWebFetchTool, 
+// Task (sub-agent spawning)
+createTaskTool, defaultAgentTypes, 
+// Collections
+builtinTools, allBuiltinTools, } from './builtin/index.js';

package/dist/tools/registry.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ToolRegistry - Manages available tools for an agent
+ */
+import type { Tool, ToolDefinition, ToolRegistry as IToolRegistry, ToolExecutionResult } from './types.js';
+/**
+ * Options for creating a DefaultToolRegistry
+ */
+export interface ToolRegistryOptions {
+    /**
+     * Default timeout for tool execution in milliseconds.
+     * Default: 30000 (30 seconds). Set to 0 to disable timeout.
+     */
+    defaultTimeoutMs?: number;
+    /**
+     * Per-tool timeout overrides (tool name -> timeout in ms)
+     */
+    toolTimeouts?: Record<string, number>;
+}
+/**
+ * Default implementation of ToolRegistry
+ */
+export declare class DefaultToolRegistry implements IToolRegistry {
+    private readonly tools;
+    private readonly defaultTimeoutMs;
+    private readonly toolTimeouts;
+    constructor(options?: ToolRegistryOptions);
+    /**
+     * Register a tool
+     */
+    register(tool: Tool): void;
+    /**
+     * Register multiple tools at once
+     */
+    registerAll(tools: Tool[]): void;
+    /**
+     * Unregister a tool by name
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a tool by name
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * Check if a tool is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered tool names
+     */
+    getNames(): string[];
+    /**
+     * Get all tool definitions (for sending to LLM)
+     */
+    getDefinitions(): ToolDefinition[];
+    /**
+     * Get the number of registered tools
+     */
+    get size(): number;
+    /**
+     * Execute a tool by name with given input
+     *
+     * @param name - Tool name
+     * @param input - Tool input parameters
+     * @param timeoutMs - Optional timeout override (uses default if not provided)
+     */
+    execute(name: string, input: Record<string, unknown>, timeoutMs?: number): Promise<ToolExecutionResult>;
+    /**
+     * Execute a tool with a timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Clear all registered tools
+     */
+    clear(): void;
+}
+/**
+ * Create a new ToolRegistry with optional initial tools and options
+ */
+export declare function createToolRegistry(tools?: Tool[], options?: ToolRegistryOptions): DefaultToolRegistry;

package/dist/tools/registry.js

@@ -0,0 +1,151 @@
+/**
+ * ToolRegistry - Manages available tools for an agent
+ */
+import { ToolError, ToolTimeoutError } from '../errors.js';
+/**
+ * Default tool execution timeout (30 seconds)
+ */
+const DEFAULT_TOOL_TIMEOUT_MS = 30000;
+/**
+ * Default implementation of ToolRegistry
+ */
+export class DefaultToolRegistry {
+    tools = new Map();
+    defaultTimeoutMs;
+    toolTimeouts;
+    constructor(options) {
+        this.defaultTimeoutMs = options?.defaultTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+        this.toolTimeouts = options?.toolTimeouts ?? {};
+    }
+    /**
+     * Register a tool
+     */
+    register(tool) {
+        if (this.tools.has(tool.definition.name)) {
+            throw new ToolError(`Tool already registered: ${tool.definition.name}`, tool.definition.name);
+        }
+        this.tools.set(tool.definition.name, tool);
+    }
+    /**
+     * Register multiple tools at once
+     */
+    registerAll(tools) {
+        for (const tool of tools) {
+            this.register(tool);
+        }
+    }
+    /**
+     * Unregister a tool by name
+     */
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    /**
+     * Get a tool by name
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Check if a tool is registered
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Get all registered tool names
+     */
+    getNames() {
+        return Array.from(this.tools.keys());
+    }
+    /**
+     * Get all tool definitions (for sending to LLM)
+     */
+    getDefinitions() {
+        return Array.from(this.tools.values()).map((t) => t.definition);
+    }
+    /**
+     * Get the number of registered tools
+     */
+    get size() {
+        return this.tools.size;
+    }
+    /**
+     * Execute a tool by name with given input
+     *
+     * @param name - Tool name
+     * @param input - Tool input parameters
+     * @param timeoutMs - Optional timeout override (uses default if not provided)
+     */
+    async execute(name, input, timeoutMs) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            return {
+                success: false,
+                error: `Tool not found: ${name}`,
+            };
+        }
+        // Determine timeout: explicit param > per-tool config > default
+        const perToolTimeout = Object.hasOwn(this.toolTimeouts, name)
+            ? this.toolTimeouts[name]
+            : undefined;
+        const timeout = timeoutMs ?? perToolTimeout ?? this.defaultTimeoutMs;
+        // If timeout is 0 or negative, execute without timeout
+        if (timeout <= 0) {
+            try {
+                return await tool.execute(input);
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+        // Execute with timeout
+        try {
+            return await this.executeWithTimeout(tool, name, input, timeout);
+        }
+        catch (error) {
+            if (error instanceof ToolTimeoutError) {
+                return {
+                    success: false,
+                    error: error.message,
+                };
+            }
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Execute a tool with a timeout
+     */
+    async executeWithTimeout(tool, name, input, timeoutMs) {
+        // Create a promise that rejects after the timeout
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new ToolTimeoutError(name, timeoutMs));
+            }, timeoutMs);
+        });
+        // Race the tool execution against the timeout
+        return Promise.race([tool.execute(input), timeoutPromise]);
+    }
+    /**
+     * Clear all registered tools
+     */
+    clear() {
+        this.tools.clear();
+    }
+}
+/**
+ * Create a new ToolRegistry with optional initial tools and options
+ */
+export function createToolRegistry(tools, options) {
+    const registry = new DefaultToolRegistry(options);
+    if (tools) {
+        registry.registerAll(tools);
+    }
+    return registry;
+}

package/dist/tools/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Core types for tools that AI agents can use
+ */
+/**
+ * JSON Schema for tool input parameters
+ */
+export interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+}
+/**
+ * Tool definition - describes a tool the AI can call
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+}
+/**
+ * Result of executing a tool
+ */
+export interface ToolExecutionResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}
+/**
+ * Tool handler function type
+ */
+export type ToolHandler<T = object> = (input: T) => Promise<ToolExecutionResult>;
+/**
+ * Tool implementation - combines definition with handler
+ */
+export interface Tool<T = object> {
+    definition: ToolDefinition;
+    execute: ToolHandler<T>;
+}
+/**
+ * Tool registry for managing available tools
+ */
+export interface ToolRegistry {
+    /**
+     * Register a tool
+     */
+    register(tool: Tool): void;
+    /**
+     * Get a tool by name
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * Get all tool definitions (for sending to LLM)
+     */
+    getDefinitions(): ToolDefinition[];
+    /**
+     * Execute a tool by name with given input
+     */
+    execute(name: string, input: Record<string, unknown>): Promise<ToolExecutionResult>;
+}

package/dist/tools/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core types for tools that AI agents can use
+ */
+export {};

package/dist/tracing/hooks.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Built-in Tracing Hooks
+ *
+ * Pre-built hooks for common tracing patterns that integrate with the HooksManager.
+ * These hooks automatically create spans for LLM calls, tool executions, and iterations.
+ */
+import type { HooksConfig } from '../hooks/types.js';
+import type { TracingHooksConfig } from './types.js';
+import { TracingManager } from './manager.js';
+/**
+ * Create tracing hooks that automatically instrument agent execution
+ *
+ * @param manager - TracingManager instance
+ * @param config - Tracing hooks configuration
+ * @returns HooksConfig with tracing hooks
+ *
+ * @example
+ * ```typescript
+ * const tracingManager = new TracingManager({ serviceName: 'my-agent' });
+ * const tracingHooks = createTracingHooks(tracingManager, {
+ *   traceLLM: true,
+ *   traceTools: true,
+ *   traceIterations: true,
+ * });
+ *
+ * const agent = new Agent({
+ *   provider,
+ *   hooks: tracingHooks,
+ * });
+ * ```
+ */
+export declare function createTracingHooks(manager: TracingManager, config?: TracingHooksConfig): HooksConfig;
+/**
+ * Create a simple logging hook that logs all agent events
+ *
+ * @param logger - Logger function (default: console.log)
+ * @returns HooksConfig with logging hooks
+ *
+ * @example
+ * ```typescript
+ * const loggingHooks = createLoggingHooks((msg) => myLogger.info(msg));
+ * const agent = new Agent({ provider, hooks: loggingHooks });
+ * ```
+ */
+export declare function createLoggingHooks(logger?: (message: string, data?: Record<string, unknown>) => void): HooksConfig;
+/**
+ * Merge multiple HooksConfig objects
+ *
+ * @param configs - HooksConfig objects to merge
+ * @returns Merged HooksConfig
+ *
+ * @example
+ * ```typescript
+ * const hooks = mergeHooks(tracingHooks, loggingHooks, customHooks);
+ * const agent = new Agent({ provider, hooks });
+ * ```
+ */
+export declare function mergeHooks(...configs: HooksConfig[]): HooksConfig;