@compilr-dev/agents 0.0.1

package/dist/hooks/types.d.ts

@@ -0,0 +1,368 @@
+/**
+ * Hooks System - Lifecycle hooks for agent customization
+ *
+ * Hooks provide extension points for customizing agent behavior without
+ * subclassing. They enable middleware-like patterns for:
+ * - Logging and tracing
+ * - Input/output transformation
+ * - Custom validation
+ * - Metrics collection
+ * - Integration with external systems
+ */
+import type { Message } from '../providers/types.js';
+import type { ToolDefinition, ToolExecutionResult } from '../tools/types.js';
+/**
+ * Context available in all hook calls
+ */
+export interface HookContext {
+    /**
+     * Current session ID
+     */
+    sessionId: string;
+    /**
+     * Current iteration number (1-indexed)
+     */
+    iteration: number;
+    /**
+     * Abort signal for cancellation
+     */
+    signal?: AbortSignal;
+    /**
+     * Custom metadata that can be passed between hooks
+     */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Context for iteration hooks
+ */
+export interface IterationHookContext extends HookContext {
+    /**
+     * Maximum iterations allowed
+     */
+    maxIterations: number;
+    /**
+     * Current message history
+     */
+    messages: Message[];
+}
+/**
+ * Hook called before each iteration starts.
+ *
+ * Can be used for:
+ * - Logging iteration boundaries
+ * - Custom iteration budget tracking
+ * - Early termination checks
+ *
+ * @returns void, or { skip: true } to skip this iteration
+ */
+export type BeforeIterationHook = (context: IterationHookContext) => undefined | Promise<undefined> | {
+    skip: true;
+} | Promise<{
+    skip: true;
+}>;
+/**
+ * Hook called after each iteration completes.
+ *
+ * Can be used for:
+ * - Logging iteration results
+ * - Metrics collection
+ * - State snapshots
+ */
+export type AfterIterationHook = (context: IterationHookContext & {
+    /**
+     * Tool calls made in this iteration
+     */
+    toolCalls: Array<{
+        name: string;
+        input: Record<string, unknown>;
+        result: ToolExecutionResult;
+    }>;
+    /**
+     * Whether LLM returned text without tool calls
+     */
+    completedWithText: boolean;
+}) => undefined | Promise<undefined>;
+/**
+ * Context for LLM hooks
+ */
+export interface LLMHookContext extends HookContext {
+    /**
+     * Messages to be sent to LLM
+     */
+    messages: Message[];
+    /**
+     * Tool definitions available to LLM
+     */
+    tools: ToolDefinition[];
+}
+/**
+ * Result from before:llm hook that modifies messages or tools
+ */
+export interface BeforeLLMHookResult {
+    /**
+     * Modified messages (optional, original used if not provided)
+     */
+    messages?: Message[];
+    /**
+     * Modified tools (optional, original used if not provided)
+     */
+    tools?: ToolDefinition[];
+}
+/**
+ * Hook called before LLM call.
+ *
+ * Can be used for:
+ * - Prompt transformation/injection
+ * - Tool filtering
+ * - Request logging
+ * - Caching checks
+ *
+ * @returns void to proceed unchanged, or modified messages/tools
+ */
+export type BeforeLLMHook = (context: LLMHookContext) => undefined | Promise<undefined> | BeforeLLMHookResult | Promise<BeforeLLMHookResult>;
+/**
+ * Context for after:llm hook
+ */
+export interface AfterLLMHookContext extends LLMHookContext {
+    /**
+     * Text response from LLM
+     */
+    text: string;
+    /**
+     * Tool uses requested by LLM
+     */
+    toolUses: Array<{
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    }>;
+    /**
+     * Token usage from the call
+     */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /**
+     * Model that was used
+     */
+    model?: string;
+    /**
+     * Duration of the LLM call in milliseconds
+     */
+    durationMs: number;
+}
+/**
+ * Hook called after LLM response is received.
+ *
+ * Can be used for:
+ * - Response logging
+ * - Token tracking
+ * - Response validation
+ * - Metrics collection
+ */
+export type AfterLLMHook = (context: AfterLLMHookContext) => undefined | Promise<undefined>;
+/**
+ * Context for tool hooks
+ */
+export interface ToolHookContext extends HookContext {
+    /**
+     * Name of the tool being executed
+     */
+    toolName: string;
+    /**
+     * Input arguments for the tool
+     */
+    input: Record<string, unknown>;
+}
+/**
+ * Result from before:tool hook that can skip or modify execution
+ */
+export interface BeforeToolHookResult {
+    /**
+     * Skip tool execution and use this result instead
+     */
+    skip?: boolean;
+    /**
+     * Custom result to return (when skip is true)
+     */
+    result?: ToolExecutionResult;
+    /**
+     * Modified input (when not skipping)
+     */
+    input?: Record<string, unknown>;
+}
+/**
+ * Hook called before tool execution (after permissions and guardrails).
+ *
+ * Can be used for:
+ * - Custom validation
+ * - Input transformation
+ * - Execution mocking for tests
+ * - Rate limiting
+ *
+ * @returns void to proceed, or skip/modify options
+ */
+export type BeforeToolHook = (context: ToolHookContext) => undefined | Promise<undefined> | BeforeToolHookResult | Promise<BeforeToolHookResult>;
+/**
+ * Context for after:tool hook
+ */
+export interface AfterToolHookContext extends ToolHookContext {
+    /**
+     * Result from tool execution
+     */
+    result: ToolExecutionResult;
+    /**
+     * Duration of tool execution in milliseconds
+     */
+    durationMs: number;
+}
+/**
+ * Result from after:tool hook that can modify the result
+ */
+export interface AfterToolHookResult {
+    /**
+     * Modified result (optional, original used if not provided)
+     */
+    result?: ToolExecutionResult;
+}
+/**
+ * Hook called after tool execution.
+ *
+ * Can be used for:
+ * - Result transformation
+ * - Logging and metrics
+ * - Result validation
+ * - Error enrichment
+ */
+export type AfterToolHook = (context: AfterToolHookContext) => undefined | Promise<undefined> | AfterToolHookResult | Promise<AfterToolHookResult>;
+/**
+ * Context for error hooks
+ */
+export interface ErrorHookContext extends HookContext {
+    /**
+     * The error that occurred
+     */
+    error: Error;
+    /**
+     * Phase where the error occurred
+     */
+    phase: 'llm' | 'tool' | 'iteration';
+    /**
+     * Tool name (if error occurred during tool execution)
+     */
+    toolName?: string;
+}
+/**
+ * Result from error hook that can recover or transform the error
+ */
+export interface ErrorHookResult {
+    /**
+     * Whether to suppress the error and continue
+     */
+    handled?: boolean;
+    /**
+     * Transformed error to throw instead
+     */
+    error?: Error;
+    /**
+     * Recovery result (for tool errors, replaces failed result)
+     */
+    recovery?: ToolExecutionResult;
+}
+/**
+ * Hook called when an error occurs.
+ *
+ * Can be used for:
+ * - Error logging
+ * - Error transformation
+ * - Recovery strategies
+ * - Alerting
+ */
+export type OnErrorHook = (context: ErrorHookContext) => undefined | Promise<undefined> | ErrorHookResult | Promise<ErrorHookResult>;
+/**
+ * Configuration for the hooks system
+ */
+export interface HooksConfig {
+    /**
+     * Hooks called before each iteration
+     */
+    beforeIteration?: BeforeIterationHook[];
+    /**
+     * Hooks called after each iteration
+     */
+    afterIteration?: AfterIterationHook[];
+    /**
+     * Hooks called before LLM calls
+     */
+    beforeLLM?: BeforeLLMHook[];
+    /**
+     * Hooks called after LLM responses
+     */
+    afterLLM?: AfterLLMHook[];
+    /**
+     * Hooks called before tool execution
+     */
+    beforeTool?: BeforeToolHook[];
+    /**
+     * Hooks called after tool execution
+     */
+    afterTool?: AfterToolHook[];
+    /**
+     * Hooks called when errors occur
+     */
+    onError?: OnErrorHook[];
+}
+/**
+ * Internal representation of a registered hook
+ */
+export interface RegisteredHook<T> {
+    /**
+     * Unique ID for this hook registration
+     */
+    id: string;
+    /**
+     * The hook function
+     */
+    hook: T;
+    /**
+     * Optional name for debugging
+     */
+    name?: string;
+    /**
+     * Priority (lower = runs first, default: 0)
+     */
+    priority?: number;
+}
+/**
+ * Options for hook registration
+ */
+export interface HookRegistrationOptions {
+    /**
+     * Name for debugging/logging
+     */
+    name?: string;
+    /**
+     * Priority (lower = runs first, default: 0)
+     */
+    priority?: number;
+}
+/**
+ * Event types for hook operations
+ */
+export type HookEventType = 'hook:registered' | 'hook:unregistered' | 'hook:started' | 'hook:completed' | 'hook:error';
+/**
+ * Hook execution event payload
+ */
+export interface HookEvent {
+    type: HookEventType;
+    hookType: keyof HooksConfig;
+    hookId?: string;
+    hookName?: string;
+    durationMs?: number;
+    error?: Error;
+}
+/**
+ * Event handler for hook events
+ */
+export type HookEventHandler = (event: HookEvent) => void;

package/dist/hooks/types.js

@@ -0,0 +1,12 @@
+/**
+ * Hooks System - Lifecycle hooks for agent customization
+ *
+ * Hooks provide extension points for customizing agent behavior without
+ * subclassing. They enable middleware-like patterns for:
+ * - Logging and tracing
+ * - Input/output transformation
+ * - Custom validation
+ * - Metrics collection
+ * - Integration with external systems
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @compilr-dev/agents
+ *
+ * Lightweight multi-LLM agent library for building CLI AI assistants
+ */
+export { Agent } from './agent.js';
+export type { AgentConfig, AgentRunResult, AgentEvent, AgentEventHandler, RunOptions, SubAgentConfig, SubAgentResult, StreamWriter, CustomEventConfig, } from './agent.js';
+export type { LLMProvider, Message, MessageRole, ContentBlock, ContentBlockType, TextBlock, ToolUseBlock, ToolResultBlock, StreamChunk, LLMUsage, ChatOptions, ToolDefinition, ToolResult, MockProviderConfig, MockResponse, MockToolCall, } from './providers/index.js';
+export { MockProvider, createMockProvider } from './providers/index.js';
+export { ClaudeProvider, createClaudeProvider } from './providers/index.js';
+export type { ClaudeProviderConfig } from './providers/index.js';
+export type { Tool, ToolHandler, ToolRegistry, ToolInputSchema, ToolExecutionResult, ToolRegistryOptions, DefineToolOptions, ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, } from './tools/index.js';
+export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, DefaultToolRegistry, createToolRegistry, } from './tools/index.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 './tools/index.js';
+export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';
+export type { ToolPairingValidation } from './messages/index.js';
+export { generateId, sleep, retry, truncate } from './utils/index.js';
+export { AgentError, ProviderError, ToolError, ToolTimeoutError, ToolLoopError, ValidationError, MaxIterationsError, AbortError, ContextOverflowError, isAgentError, isProviderError, isToolError, isToolTimeoutError, isToolLoopError, isContextOverflowError, wrapError, } from './errors.js';
+export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './context/index.js';
+export type { ContextManagerOptions, ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, } from './context/index.js';
+export { SkillRegistry, defineSkill, createSkillRegistry, builtinSkills, getDefaultSkillRegistry, resetDefaultSkillRegistry, } from './skills/index.js';
+export type { Skill, SkillInvocationResult, SkillInvokeOptions } from './skills/index.js';
+export { JsonSerializer, CompactJsonSerializer, defaultSerializer, MemoryCheckpointer, FileCheckpointer, StateError, StateErrorCode, CURRENT_STATE_VERSION, } from './state/index.js';
+export type { AgentState, SessionMetadata, SessionInfo, StateSerializer, Checkpointer, CheckpointerWithPending, PendingWrite, ListSessionsOptions, ResumeOptions, FromStateOptions, FileCheckpointerOptions, } from './state/index.js';
+export { AnchorManager, getDefaultAnchors, isBuiltinAnchor, getBuiltinAnchorIds, DEFAULT_SAFETY_ANCHORS, } from './anchors/index.js';
+export type { Anchor, AnchorInput, AnchorPriority, AnchorScope, AnchorQueryOptions, AnchorClearOptions, AnchorManagerOptions, AnchorEventType, AnchorEvent, AnchorEventHandler, SerializedAnchor, } from './anchors/index.js';
+export { GuardrailManager, getBuiltinGuardrails, isBuiltinGuardrail, getBuiltinGuardrailIds, getGuardrailsByTag, BUILTIN_GUARDRAILS, } from './guardrails/index.js';
+export type { Guardrail, GuardrailInput, GuardrailAction, GuardrailResult, GuardrailContext, GuardrailManagerOptions, GuardrailTriggeredHandler, GuardrailEventType, GuardrailEvent, GuardrailEventHandler, } from './guardrails/index.js';
+export { MCPClient, MCPManager, mcpToolToTool, mcpToolsToTools, convertMCPResult, contentBlocksToString, generateToolName, normalizeServerConfig, MCPError, MCPErrorCode, isMCPError, createSDKNotInstalledError, } from './mcp/index.js';
+export type { MCPTransport, MCPConnectionStatus, MCPStdioOptions, MCPHttpOptions, MCPClientConfig, MCPServerConfig, MCPToolDefinition, MCPContentBlock, MCPToolResult, MCPClientEventType, MCPClientEvent, MCPClientEventHandler, MCPManagerOptions, MCPToolConversionOptions, } from './mcp/index.js';
+export { PermissionManager } from './permissions/index.js';
+export type { PermissionLevel, ToolPermission, PermissionRequest, PermissionCheckResult, PermissionHandler, PreviewGenerator, PermissionManagerOptions, PermissionEventType, PermissionEvent, PermissionEventHandler, } from './permissions/index.js';
+export { ProjectMemoryLoader, createProjectMemoryLoader, loadProjectMemory, hasProjectMemory, getProviderPatterns, getSupportedProviders, getGenericPatterns, PROVIDER_PATTERNS, GENERIC_PATTERNS, } from './memory/index.js';
+export type { LLMProviderName, MemoryFile, ProjectMemory, FilePattern, CombineStrategy, ProjectMemoryOptions, ProjectMemoryEventType, ProjectMemoryEvent, ProjectMemoryEventHandler, MemoryDiscoveryResult, ProviderPatterns, } from './memory/index.js';
+export { UsageTracker, createUsageTracker } from './costs/index.js';
+export type { TokenUsage, UsageRecord, UsageStats, TokenBudgetConfig, BudgetStatus, UsageEventType, UsageEvent, UsageEventHandler, UsageTrackerOptions, RecordUsageInput, } from './costs/index.js';
+export { HooksManager } from './hooks/index.js';
+export type { HooksManagerOptions } from './hooks/index.js';
+export type { HooksConfig, HookRegistrationOptions, HookContext, IterationHookContext, LLMHookContext, AfterLLMHookContext, ToolHookContext, AfterToolHookContext, ErrorHookContext, BeforeIterationHook, AfterIterationHook, BeforeLLMHook, AfterLLMHook, BeforeToolHook, AfterToolHook, OnErrorHook, BeforeLLMHookResult, BeforeToolHookResult, AfterToolHookResult, ErrorHookResult, RegisteredHook, HookEventType, HookEvent, HookEventHandler, } from './hooks/index.js';
+export { TracingManager, createTracingHooks, createLoggingHooks, mergeHooks, createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, SemanticAttributes, } from './tracing/index.js';
+export type { Span, SpanStatus, SpanKind, SpanAttributes, SpanContext, SpanEvent, AttributeValue, Trace, TracingManagerOptions, StartSpanOptions, EndSpanOptions, TracingHooksConfig, TracingEvent, TracingEventHandler, OTelExporter, OTelSDK, OTelTracer, OTelSpan, LogLevel, LogEntry, StructuredLogger, StructuredLoggerOptions, TracingHookContext, TracingManagerInterface, } from './tracing/index.js';
+export { TokenBucketRateLimiter, createRateLimiter, createNoopRateLimiter, RateLimitExceededError, isRateLimitExceededError, withRetry, createRetryWithRateLimit, RetryPresets, RetryStats, RateLimitedProvider, wrapWithRateLimit, ProviderRateLimits, } from './rate-limit/index.js';
+export type { RateLimiterConfig, RateLimiterStats, RetryConfig, RateLimitRetryConfig, AcquireResult, RateLimiter, } from './rate-limit/index.js';
+export { RehearsalManager, createRehearsalManager, GitRehearsalAnalyzer, createGitAnalyzer, FileRehearsalAnalyzer, createFileAnalyzer, } from './rehearsal/index.js';
+export type { ImpactSeverity, RehearsalRecommendation, OperationCategory, AffectedFile, RehearsalImpact, RehearsalResult, RehearsalContext, RehearsalAnalyzer, RehearsalManagerOptions, RehearsalEventType, RehearsalEvent, RehearsalEventHandler, } from './rehearsal/index.js';

package/dist/index.js

@@ -0,0 +1,73 @@
+/**
+ * @compilr-dev/agents
+ *
+ * Lightweight multi-LLM agent library for building CLI AI assistants
+ */
+// Core agent
+export { Agent } from './agent.js';
+// Providers
+export { MockProvider, createMockProvider } from './providers/index.js';
+export { ClaudeProvider, createClaudeProvider } from './providers/index.js';
+// Tool utilities
+export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, DefaultToolRegistry, createToolRegistry, } from './tools/index.js';
+// Built-in tools
+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, 
+// Task tool (sub-agent spawning)
+createTaskTool, defaultAgentTypes, builtinTools, allBuiltinTools, } from './tools/index.js';
+// Message utilities
+export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';
+// Utilities
+export { generateId, sleep, retry, truncate } from './utils/index.js';
+// Errors
+export { AgentError, ProviderError, ToolError, ToolTimeoutError, ToolLoopError, ValidationError, MaxIterationsError, AbortError, ContextOverflowError, isAgentError, isProviderError, isToolError, isToolTimeoutError, isToolLoopError, isContextOverflowError, wrapError, } from './errors.js';
+// Context management
+export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './context/index.js';
+// Skills system
+export { SkillRegistry, defineSkill, createSkillRegistry, builtinSkills, getDefaultSkillRegistry, resetDefaultSkillRegistry, } from './skills/index.js';
+// State management
+export { 
+// Serializers
+JsonSerializer, CompactJsonSerializer, defaultSerializer, 
+// Checkpointers
+MemoryCheckpointer, FileCheckpointer, 
+// Errors
+StateError, StateErrorCode, 
+// Constants
+CURRENT_STATE_VERSION, } from './state/index.js';
+// Anchors - Critical information that survives context compaction
+export { AnchorManager, getDefaultAnchors, isBuiltinAnchor, getBuiltinAnchorIds, DEFAULT_SAFETY_ANCHORS, } from './anchors/index.js';
+// Guardrails - Pattern-based safety checks for tool execution
+export { GuardrailManager, getBuiltinGuardrails, isBuiltinGuardrail, getBuiltinGuardrailIds, getGuardrailsByTag, BUILTIN_GUARDRAILS, } from './guardrails/index.js';
+// MCP (Model Context Protocol) support
+// Note: Requires optional peer dependency @modelcontextprotocol/sdk
+export { MCPClient, MCPManager, mcpToolToTool, mcpToolsToTools, convertMCPResult, contentBlocksToString, generateToolName, normalizeServerConfig, MCPError, MCPErrorCode, isMCPError, createSDKNotInstalledError, } from './mcp/index.js';
+// Permissions - Tool-level permission management
+export { PermissionManager } from './permissions/index.js';
+// Memory - Project-level instruction loading (CLAUDE.md, GEMINI.md, etc.)
+export { ProjectMemoryLoader, createProjectMemoryLoader, loadProjectMemory, hasProjectMemory, getProviderPatterns, getSupportedProviders, getGenericPatterns, PROVIDER_PATTERNS, GENERIC_PATTERNS, } from './memory/index.js';
+// Usage tracking - Token usage tracking (no dollar costs)
+export { UsageTracker, createUsageTracker } from './costs/index.js';
+// Hooks - Lifecycle hooks for agent customization
+export { HooksManager } from './hooks/index.js';
+// Tracing - Observability and distributed tracing
+export { 
+// Manager
+TracingManager, 
+// Built-in hooks
+createTracingHooks, createLoggingHooks, mergeHooks, 
+// Structured logging
+createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, 
+// OpenTelemetry integration
+createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, 
+// Semantic conventions
+SemanticAttributes, } from './tracing/index.js';
+// Rate Limiting & Retry
+export { 
+// Rate Limiter
+TokenBucketRateLimiter, createRateLimiter, createNoopRateLimiter, RateLimitExceededError, isRateLimitExceededError, 
+// Retry
+withRetry, createRetryWithRateLimit, RetryPresets, RetryStats, 
+// Provider Wrapper
+RateLimitedProvider, wrapWithRateLimit, ProviderRateLimits, } from './rate-limit/index.js';
+// Rehearsal - Impact analysis for destructive operations
+export { RehearsalManager, createRehearsalManager, GitRehearsalAnalyzer, createGitAnalyzer, FileRehearsalAnalyzer, createFileAnalyzer, } from './rehearsal/index.js';

package/dist/mcp/client.d.ts

@@ -0,0 +1,93 @@
+/**
+ * MCP Client - Connects to MCP servers and discovers tools
+ *
+ * Uses the official @modelcontextprotocol/sdk as an optional peer dependency.
+ * If the SDK is not installed, attempting to use MCP features will throw
+ * a helpful error with installation instructions.
+ */
+import type { MCPClientConfig, MCPConnectionStatus, MCPToolDefinition, MCPToolResult, MCPClientEventHandler } from './types.js';
+/**
+ * MCP Client for connecting to a single MCP server
+ *
+ * @example
+ * ```typescript
+ * const client = new MCPClient({
+ *   name: 'filesystem',
+ *   transport: 'stdio',
+ *   stdio: {
+ *     command: 'npx',
+ *     args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+ *   },
+ * });
+ *
+ * await client.connect();
+ * const tools = await client.listTools();
+ * const result = await client.callTool('read_file', { path: '/tmp/test.txt' });
+ * await client.disconnect();
+ * ```
+ */
+export declare class MCPClient {
+    readonly name: string;
+    private readonly config;
+    private client;
+    private transport;
+    private _status;
+    private readonly eventHandlers;
+    private cachedTools;
+    constructor(config: MCPClientConfig);
+    /**
+     * Current connection status
+     */
+    get status(): MCPConnectionStatus;
+    /**
+     * Whether the client is connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Connect to the MCP server
+     * @throws MCPError if connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the MCP server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * List available tools from the server
+     * @throws MCPError if not connected or listing fails
+     */
+    listTools(): Promise<MCPToolDefinition[]>;
+    /**
+     * Call a tool on the server
+     * @param toolName Name of the tool to call
+     * @param args Arguments to pass to the tool
+     * @throws MCPError if not connected, tool not found, or execution fails
+     */
+    callTool(toolName: string, args?: Record<string, unknown>): Promise<MCPToolResult>;
+    /**
+     * Register an event handler
+     */
+    onEvent(handler: MCPClientEventHandler): () => void;
+    /**
+     * Convenience method to listen for tools changed events
+     */
+    onToolsChanged(callback: (tools: MCPToolDefinition[]) => void): () => void;
+    /**
+     * Convenience method to listen for errors
+     */
+    onError(callback: (error: Error) => void): () => void;
+    /**
+     * Convenience method to listen for disconnect
+     */
+    onDisconnect(callback: () => void): () => void;
+    /**
+     * Emit an event to all handlers
+     */
+    private emit;
+    /**
+     * Get the connected client, throwing if not connected
+     * @throws MCPError if not connected
+     * @returns The connected SDK client
+     */
+    private getConnectedClient;
+}