@probelabs/probe 0.6.0-rc159 → 0.6.0-rc162

package/README.md

@@ -29,6 +29,7 @@ During installation, the package will automatically download the appropriate pro
 - **Automatic Binary Management**: Automatically downloads and manages the probe binary
 - **Direct CLI Access**: Use the probe binary directly from the command line when installed globally
 - **MCP Server**: Built-in Model Context Protocol server for AI assistant integration
+- **Context Window Compaction**: Automatic conversation history compression when approaching token limits
 
 ## Usage
 
@@ -92,6 +93,7 @@ const agent = new ProbeAgent({
   model: 'claude-3-5-sonnet-20241022',  // Optional: override model
   allowEdit: false,        // Optional: enable code modification
   debug: true,            // Optional: enable debug logging
+  allowedTools: ['*'],    // Optional: filter available tools (see Tool Filtering below)
   enableMcp: true,        // Optional: enable MCP tool integration
   mcpConfig: {           // Optional: MCP configuration (see MCP section below)
     mcpServers: {...}
@@ -131,11 +133,170 @@ export MODEL_NAME=claude-3-5-sonnet-20241022
 **ProbeAgent Features:**
 - **Multi-turn conversations** with automatic history management
 - **Code search integration** - Uses probe's search capabilities transparently
-- **Multiple AI providers** - Supports Anthropic Claude, OpenAI GPT, Google Gemini
+- **Multiple AI providers** - Supports Anthropic Claude, OpenAI GPT, Google Gemini, AWS Bedrock
+- **Automatic retry with exponential backoff** - Handles transient API failures gracefully
+- **Provider fallback** - Seamlessly switch between providers if one fails (e.g., Azure Claude → Bedrock Claude → OpenAI)
 - **Session management** - Maintain conversation context across calls
 - **Token tracking** - Monitor usage and costs
 - **Configurable personas** - Engineer, architect, code-review, and more
 
+### Retry and Fallback Support
+
+ProbeAgent includes comprehensive retry and fallback capabilities for maximum reliability:
+
+```javascript
+import { ProbeAgent } from '@probelabs/probe';
+
+const agent = new ProbeAgent({
+  path: '/path/to/your/project',
+
+  // Configure retry behavior
+  retry: {
+    maxRetries: 5,           // Retry up to 5 times per provider
+    initialDelay: 1000,      // Start with 1 second delay
+    maxDelay: 30000,         // Cap delays at 30 seconds
+    backoffFactor: 2         // Double the delay each time
+  },
+
+  // Configure provider fallback
+  fallback: {
+    strategy: 'custom',
+    providers: [
+      {
+        provider: 'anthropic',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+        model: 'claude-3-7-sonnet-20250219',
+        maxRetries: 5  // Can override retry config per provider
+      },
+      {
+        provider: 'bedrock',
+        region: 'us-west-2',
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        model: 'anthropic.claude-sonnet-4-20250514-v1:0'
+      },
+      {
+        provider: 'openai',
+        apiKey: process.env.OPENAI_API_KEY,
+        model: 'gpt-4o'
+      }
+    ],
+    maxTotalAttempts: 15  // Maximum attempts across all providers
+  }
+});
+
+// API calls automatically retry on failures and fallback to other providers
+const answer = await agent.answer("Explain this codebase");
+```
+
+**Retry & Fallback Features:**
+- **Exponential backoff** - Intelligently delays retries to avoid overwhelming APIs
+- **Automatic error detection** - Retries on transient errors (Overloaded, 429, 503, timeouts, network errors)
+- **Multi-provider support** - Fallback across Anthropic, OpenAI, Google, and AWS Bedrock
+- **Cross-cloud failover** - Use Azure Claude → Bedrock Claude → OpenAI as fallback chain
+- **Statistics tracking** - Monitor retry attempts and provider usage
+- **Environment variable support** - Configure via env vars for easy deployment
+
+**Quick Setup with Auto-Fallback:**
+```bash
+# Set all your API keys
+export ANTHROPIC_API_KEY=sk-ant-xxx
+export OPENAI_API_KEY=sk-xxx
+export GOOGLE_API_KEY=xxx
+export AUTO_FALLBACK=1  # Enable automatic fallback
+export MAX_RETRIES=5    # Configure retry limit
+```
+
+```javascript
+// No configuration needed - uses all available providers automatically!
+const agent = new ProbeAgent({
+  path: '/path/to/your/project',
+  fallback: { auto: true }
+});
+```
+
+See [docs/RETRY_AND_FALLBACK.md](./docs/RETRY_AND_FALLBACK.md) for complete documentation and examples.
+
+### Tool Filtering
+
+ProbeAgent supports filtering available tools to control what operations the AI can perform. This is useful for security, cost control, or limiting functionality to specific use cases.
+
+```javascript
+import { ProbeAgent } from '@probelabs/probe';
+
+// Allow all tools (default behavior)
+const agent1 = new ProbeAgent({
+  path: '/path/to/project',
+  allowedTools: ['*']  // or undefined
+});
+
+// Allow only specific tools (whitelist mode)
+const agent2 = new ProbeAgent({
+  path: '/path/to/project',
+  allowedTools: ['search', 'query', 'extract']
+});
+
+// Allow all except specific tools (exclusion mode)
+const agent3 = new ProbeAgent({
+  path: '/path/to/project',
+  allowedTools: ['*', '!bash', '!implement']
+});
+
+// Raw AI mode - no tools at all
+const agent4 = new ProbeAgent({
+  path: '/path/to/project',
+  allowedTools: []  // or use disableTools: true
+});
+
+// Convenience flag for raw AI mode (better DX)
+const agent5 = new ProbeAgent({
+  path: '/path/to/project',
+  disableTools: true  // Clearer than allowedTools: []
+});
+```
+
+**Available Tools:**
+- `search` - Semantic code search
+- `query` - Tree-sitter pattern matching
+- `extract` - Extract code blocks
+- `listFiles` - List files and directories
+- `searchFiles` - Find files by glob pattern
+- `bash` - Execute bash commands (requires `enableBash: true`)
+- `implement` - Implement features with aider (requires `allowEdit: true`)
+- `edit` - Edit files with exact string replacement (requires `allowEdit: true`)
+- `create` - Create new files (requires `allowEdit: true`)
+- `delegate` - Delegate tasks to subagents (requires `enableDelegate: true`)
+- `attempt_completion` - Signal task completion
+- `mcp__*` - MCP tools use the `mcp__` prefix (e.g., `mcp__filesystem__read_file`)
+
+**MCP Tool Filtering:**
+MCP tools follow the `mcp__toolname` naming convention. You can:
+- Allow all MCP tools: `allowedTools: ['*']`
+- Allow specific MCP tool: `allowedTools: ['mcp__filesystem__read_file']`
+- Allow all from a server: `allowedTools: ['mcp__filesystem__*']` (using pattern matching)
+- Block MCP tools: `allowedTools: ['*', '!mcp__*']`
+
+**CLI Usage:**
+```bash
+# Allow only search and extract tools
+probe agent "Explain this code" --allowed-tools search,extract
+
+# Raw AI mode (no tools) - option 1
+probe agent "What is this project about?" --allowed-tools none
+
+# Raw AI mode (no tools) - option 2 (better DX)
+probe agent "Tell me about this project" --disable-tools
+
+# All tools (default)
+probe agent "Analyze the architecture" --allowed-tools all
+```
+
+**Notes:**
+- Tool filtering works in conjunction with feature flags (`allowEdit`, `enableBash`, `enableDelegate`)
+- Both the feature flag AND `allowedTools` must permit a tool for it to be available
+- Blocked tools will not appear in the system message and cannot be executed
+- Use `allowedTools: []` for pure conversational AI without code analysis tools
+
 ### Using as an MCP Server
 
 Probe includes a built-in MCP (Model Context Protocol) server for integration with AI assistants:
@@ -612,6 +773,13 @@ probe mcp --timeout 60
 }
 ```
 
+## Additional Documentation
+
+- [Context Window Compaction](./CONTEXT_COMPACTION.md) - Automatic conversation history compression
+- [MCP Integration](./MCP_INTEGRATION_SUMMARY.md) - Model Context Protocol support details
+- [Delegate Tool](./DELEGATE_TOOL_README.md) - Task distribution to subagents
+- [Maid Integration](./MAID_INTEGRATION.md) - Integration with Maid LLM framework
+
 ## Related Projects
 
 - [probe](https://github.com/probelabs/probe) - The core probe code search tool

package/build/agent/FallbackManager.d.ts

@@ -0,0 +1,176 @@
+/**
+ * TypeScript type definitions for FallbackManager
+ */
+
+/**
+ * Fallback strategies
+ */
+export const FALLBACK_STRATEGIES: {
+  /** Try same model on different providers */
+  SAME_MODEL: 'same-model';
+  /** Try different models on same provider */
+  SAME_PROVIDER: 'same-provider';
+  /** Try any available provider/model */
+  ANY: 'any';
+  /** Use custom provider list */
+  CUSTOM: 'custom';
+};
+
+export type FallbackStrategy =
+  | 'same-model'
+  | 'same-provider'
+  | 'any'
+  | 'custom';
+
+/**
+ * Provider configuration
+ */
+export interface ProviderConfig {
+  /** Provider name */
+  provider: 'anthropic' | 'openai' | 'google' | 'bedrock';
+  /** Model name (uses provider default if omitted) */
+  model?: string;
+  /** API key for the provider */
+  apiKey?: string;
+  /** Custom API endpoint */
+  baseURL?: string;
+  /** Max retries for this provider (overrides global) */
+  maxRetries?: number;
+
+  // AWS Bedrock specific
+  /** AWS region (for Bedrock) */
+  region?: string;
+  /** AWS access key ID (for Bedrock) */
+  accessKeyId?: string;
+  /** AWS secret access key (for Bedrock) */
+  secretAccessKey?: string;
+  /** AWS session token (for Bedrock) */
+  sessionToken?: string;
+}
+
+/**
+ * Fallback configuration options
+ */
+export interface FallbackOptions {
+  /** Fallback strategy */
+  strategy?: FallbackStrategy;
+  /** List of models for same-provider fallback */
+  models?: string[];
+  /** List of provider configurations for custom fallback */
+  providers?: ProviderConfig[];
+  /** Stop on first successful response */
+  stopOnSuccess?: boolean;
+  /** Continue to fallback on non-retryable errors */
+  continueOnNonRetryableError?: boolean;
+  /** Maximum total attempts across all providers (1-100) */
+  maxTotalAttempts?: number;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Fallback statistics
+ */
+export interface FallbackStats {
+  /** Total number of provider attempts */
+  totalAttempts: number;
+  /** Number of attempts per provider */
+  providerAttempts: Record<string, number>;
+  /** Name of the successful provider */
+  successfulProvider: string | null;
+  /** List of failed providers with error details */
+  failedProviders: Array<{
+    provider: string;
+    error: {
+      message: string;
+      type: string;
+      statusCode?: number;
+    };
+  }>;
+}
+
+/**
+ * Auto-fallback provider build options
+ */
+export interface BuildFallbackOptions {
+  /** Primary provider to try first */
+  primaryProvider?: string;
+  /** Primary model to use */
+  primaryModel?: string;
+}
+
+/**
+ * FallbackManager class for handling provider and model fallback
+ */
+export class FallbackManager {
+  /** Fallback strategy */
+  strategy: FallbackStrategy;
+  /** List of models for same-provider fallback */
+  models: string[];
+  /** List of provider configurations */
+  providers: ProviderConfig[];
+  /** Stop on first success */
+  stopOnSuccess: boolean;
+  /** Continue on non-retryable errors */
+  continueOnNonRetryableError: boolean;
+  /** Maximum total attempts */
+  maxTotalAttempts: number;
+  /** Debug logging enabled */
+  debug: boolean;
+  /** Fallback statistics */
+  stats: FallbackStats;
+
+  /**
+   * Create a new FallbackManager
+   * @param options - Fallback configuration options
+   */
+  constructor(options?: FallbackOptions);
+
+  /**
+   * Execute a function with fallback support
+   * @param fn - Function that takes (provider, model, config) and returns a Promise
+   * @returns Result from the function
+   * @throws Error if all fallbacks are exhausted
+   */
+  executeWithFallback<T>(
+    fn: (
+      provider: any,
+      model: string,
+      config: ProviderConfig
+    ) => Promise<T>
+  ): Promise<T>;
+
+  /**
+   * Get fallback statistics
+   * @returns Statistics object (copy)
+   */
+  getStats(): FallbackStats;
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void;
+}
+
+/**
+ * Create a FallbackManager from environment variables
+ * @param debug - Enable debug logging
+ * @returns Configured FallbackManager instance or null if no config found
+ */
+export function createFallbackManagerFromEnv(
+  debug?: boolean
+): FallbackManager | null;
+
+/**
+ * Build a fallback provider list from current environment
+ * @param options - Options for building the list
+ * @returns List of provider configurations
+ */
+export function buildFallbackProvidersFromEnv(
+  options?: BuildFallbackOptions
+): ProviderConfig[];
+
+/**
+ * Default model mappings for each provider
+ */
+export const DEFAULT_MODELS: Record<string, string>;