@robota-sdk/agent-core 3.0.0-beta.4 → 3.0.0-beta.43

package/README.md

@@ -1,33 +1,27 @@
-# @robota-sdk/agent-core
+# Agent Core
 
-The comprehensive AI agent framework with type-safe architecture and advanced plugin system.
-
-## Overview
-
-The `@robota-sdk/agent-core` package is the unified core of the Robota SDK, providing a complete AI agent system with advanced capabilities for conversation management, tool execution, and extensible plugin architecture.
+The foundation layer of the Robota SDK. Provides the `Robota` agent class, abstract base classes for providers/tools/plugins, the permission system, hook system, event services, and error hierarchy.
 
 ## Installation
 
 ```bash
 npm install @robota-sdk/agent-core
-# or
-pnpm add @robota-sdk/agent-core
 ```
 
 ## Quick Start
 
 ```typescript
 import { Robota } from '@robota-sdk/agent-core';
-import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';
+import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
 
-const openaiProvider = new OpenAIProvider({ apiKey: 'sk-...' });
+const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY });
 
 const agent = new Robota({
   name: 'MyAgent',
-  aiProviders: [openaiProvider],
+  aiProviders: [provider],
   defaultModel: {
-    provider: 'openai',
-    model: 'gpt-4',
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-6',
     systemMessage: 'You are a helpful assistant.',
   },
 });
@@ -36,194 +30,86 @@ const response = await agent.run('Hello, world!');
 console.log(response);
 ```
 
-### Browser Quick Start
-
-```typescript
-import { Robota, LoggingPlugin, UsagePlugin } from '@robota-sdk/agent-core';
-import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';
-
-const openaiProvider = new OpenAIProvider({
-  apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY, // or proxy endpoint
-});
-
-// Browser-optimized configuration
-const agent = new Robota({
-  name: 'BrowserAgent',
-  aiProviders: [openaiProvider],
-  defaultModel: {
-    provider: 'openai',
-    model: 'gpt-3.5-turbo',
-  },
-  plugins: [
-    new LoggingPlugin({ strategy: 'console' }), // Console logging
-    new UsagePlugin({ strategy: 'memory' }), // Memory storage
-  ],
-});
-
-const response = await agent.run('Hello from browser!');
-console.log(response);
-```
-
 ## Key Features
 
-### 🌐 Cross-Platform Compatibility
-
-- **Universal Runtime Support**: Works seamlessly in Node.js, browsers, and WebWorkers
-- **Zero Breaking Changes**: Existing Node.js code runs unchanged in browsers
-- **Pure JavaScript Implementation**: No Node.js-specific dependencies in core functionality
-- **Browser-Optimized Storage**: Memory-based alternatives for file system operations
-- **Secure API Patterns**: Proxy server support for secure browser deployments
-
-### 🤖 Agent System
-
-- **Type-Safe Architecture**: Full TypeScript support with generic type parameters
-- **Robota Class**: Complete AI agent implementation with conversation + tool system + plugin integration
-- **Stateless Service Layer**: ConversationService, ToolExecutionService, ExecutionService for business logic
-- **Manager Layer**: AIProviders, Tools, AgentFactory, Plugins, ConversationHistory for resource management
-- **Parallel Tool Execution**: Concurrent multi-tool calling support
-
-### 🌊 Streaming Response System
-
-- **Real-time Streaming**: Full streaming support across all AI providers
-- **Modular Architecture**: Separate streaming/parsing logic for each provider
-- **Provider Support**: OpenAI, Anthropic, Google with dedicated stream handlers
-
-### 🔧 Tool System
-
-- **Type-Safe Tools**: `BaseTool<TParameters, TResult>` with compile-time type checking
-- **ToolRegistry**: Schema storage and validation system
-- **Function Tools**: Zod schema-based function tool implementation
-- **OpenAPI/MCP Support**: Basic structure for extensibility
-
-## Recent Updates
-
-- Tool execution results preserve `executionId` mappings for both success and failure to keep deterministic ordering.
-
-### 🔌 Plugin System
-
-Eight core plugins with type-safe configuration and BasePluginOptions integration:
-
-- **ConversationHistoryPlugin**: Comprehensive conversation storage with support for memory, file, and database backends. Features auto-save, batch processing, and configurable limits.
-- **UsagePlugin**: Advanced usage analytics including token counting, cost calculation, aggregated statistics, and multiple storage strategies (memory/file/remote).
-- **LoggingPlugin**: Multi-level logging system with console, file, and remote endpoints. Supports custom formatters, batch processing, and structured logging.
-- **PerformancePlugin**: Real-time performance monitoring including execution time tracking, memory usage, CPU metrics, and customizable performance thresholds.
-- **ErrorHandlingPlugin**: Robust error management with multiple strategies (simple, exponential-backoff, circuit-breaker, silent) and custom error handlers.
-- **LimitsPlugin**: Advanced rate limiting with token bucket, sliding window, and fixed window strategies. Supports cost tracking and custom calculators.
-- **EventEmitterPlugin**: Comprehensive event system with async/sync event handling, filtering, buffering, and lifecycle event tracking.
-- **WebhookPlugin**: HTTP webhook notifications with batch processing, retry logic, custom transformers, and concurrent request management.
-
-#### Plugin Features
-
-- **Type Safety**: All plugins extend BasePluginOptions for consistent configuration
-- **Lifecycle Integration**: Automatic integration with agent lifecycle events
-- **Resource Management**: Built-in cleanup and resource optimization
-- **Performance Monitoring**: All plugins include built-in statistics and monitoring
-- **Error Resilience**: Graceful error handling across all plugin operations
-
-#### Plugin Control and Configuration
-
-- **Clear Disable Options**: Every plugin provides multiple ways to disable functionality
-- **No Arbitrary Decisions**: Plugins avoid making policy decisions without explicit configuration
-- **Explicit Configuration**: All automatic behaviors can be controlled through configuration
-- **Silent Modes**: Most plugins support 'silent' strategies for performance-critical scenarios
+- **Robota class**: AI agent with conversation history, tool execution, and plugin support
+- **ConversationStore**: Append-only conversation history with streaming buffer (`beginAssistant`/`appendStreaming`/`commitAssistant`)
+- **IBaseMessage**: Every message has a unique `id` (UUID) and `state` (`'complete'` | `'interrupted'`)
+- **Multi-provider**: Register multiple providers, switch dynamically with `setModel()`
+- **AbstractAIProvider.streamWithAbort()**: Standard streaming wrapper for all providers — handles AbortSignal, returns partial content on abort
+- **Permission system**: Deterministic 3-step policy evaluation (`evaluatePermission`)
+- **Hook system**: Shell command-based lifecycle hooks (`runHooks`)
+- **Plugin system**: `AbstractPlugin` base class with lifecycle hooks (beforeRun, afterRun, onError, etc.)
+- **Event services**: Unified event emission with owner path tracking
+- **Error hierarchy**: Typed errors extending `RobotaError` (ProviderError, RateLimitError, etc.)
+- **Model definitions**: Central `CLAUDE_MODELS` registry with context windows, output limits, and human-readable names
+- **callProviderWithCache**: Accepts `Partial<IChatOptions>` overrides for per-call configuration
+- **AbortSignal propagation**: Signal flows through the entire execution chain (Session -> Robota -> Provider)
+- **Type safety**: Strict TypeScript, zero `any` in production code
+
+## Robota API
 
 ```typescript
-// Complete plugin disable
-const agent = new Robota({
-  plugins: [], // No plugins
-});
+const agent = new Robota(config);
 
-// Selective plugin disable
-const agent = new Robota({
-  plugins: [
-    new LoggingPlugin({ strategy: 'silent', enabled: false }),
-    new LimitsPlugin({ strategy: 'none' }),
-    new UsagePlugin({ strategy: 'silent' }),
-  ],
-});
-```
+// Send a message (executes tool calls automatically)
+const response = await agent.run('Hello');
 
-#### Plugin Documentation
+// Conversation history
+const history = agent.getHistory(); // TUniversalMessage[]
+agent.clearHistory();
 
-- **[Plugin Guide](./docs/PLUGINS.md)**: Unified plugin behavior and configuration guide
+// Switch provider/model mid-conversation
+agent.setModel({ provider: 'openai', model: 'gpt-4o' });
+```
 
-### 🔒 Type Safety Features
+## IAgentConfig
 
-- **Generic Type Parameters**: `BaseAgent<TConfig, TContext, TMessage>`
-- **Provider Agnostic**: Dynamic provider registration with type safety
-- **Extended RunContext**: Provider-specific options with type preservation
-- **Plugin Type Parameters**: `BasePlugin<TOptions, TStats>` for specialized configurations
+| Field                        | Type                       | Description                    |
+| ---------------------------- | -------------------------- | ------------------------------ |
+| `name`                       | `string`                   | Agent name                     |
+| `aiProviders`                | `IAIProvider[]`            | One or more provider instances |
+| `defaultModel.provider`      | `string`                   | Provider name                  |
+| `defaultModel.model`         | `string`                   | Model identifier               |
+| `defaultModel.systemMessage` | `string?`                  | System prompt                  |
+| `tools`                      | `IToolWithEventService[]?` | Tools the agent can call       |
+| `plugins`                    | `IPluginContract[]?`       | Plugins for lifecycle hooks    |
 
 ## Architecture
 
-### Core Abstraction Layers
-
 ```
-BaseAgent<TConfig, TContext, TMessage> (Abstract Class)
-└── Robota (Implementation - AI conversation + tool system + plugins)
-
-BaseAIProvider<TConfig, TMessage, TResponse>
-├── OpenAIProvider (via @robota-sdk/agent-provider-openai)
-├── AnthropicProvider (via @robota-sdk/agent-provider-anthropic)
-└── GoogleProvider (via @robota-sdk/agent-provider-google)
-
-BaseTool<TParameters, TResult>
-├── FunctionTool (Zod schema-based)
-├── OpenAPITool (API specification-based)
-└── MCPTool (Model Context Protocol)
-
-BasePlugin<TOptions, TStats>
-├── Core Plugins (8 essential plugins)
-└── Custom Plugins (User-defined extensions)
-```
-
-### Module Structure
-
+agent-core (this package — zero workspace dependencies)
+  ↑
+agent-sessions    ← Session lifecycle
+agent-tools       ← Tool implementations
+agent-providers   ← AI provider implementations
+agent-plugins     ← Plugin implementations (8 extracted packages)
+  ↑
+agent-sdk         ← Assembly layer
+  ↑
+agent-cli         ← Terminal UI
 ```
-packages/agents/src/
-├── abstracts/           # Abstract base classes with type parameters
-├── interfaces/          # Type-safe interface definitions
-├── agents/             # Main agent system
-│   ├── managers/       # Resource managers
-│   ├── services/       # Stateless business logic
-│   └── tools/          # Tool system
-├── plugins/            # Plugin system with Facade pattern
-└── utils/              # Core utilities
-```
-
-## Development
-
-See [Development Guide](./docs/DEVELOPMENT.md) for development guidelines.
-
-## API Reference
-
-See [api.md](api.md) for complete API documentation.
-
-## Architecture Guide
-
-See [Architecture](./docs/ARCHITECTURE.md) for detailed architecture information.
-
-## Examples
-
-- [Basic Usage](../../../docs/examples/basic-usage.md)
-- [Browser Usage](../../../docs/examples/browser-usage.md) 🌐
-- [Tool Integration](../../../docs/examples/tool-integration.md)
-- [Plugin Development](../../../docs/examples/plugin-development.md)
-- [Streaming Responses](../../../docs/examples/streaming.md)
-
-## Package Compatibility
-
-### Integrated Packages
-
-- **@robota-sdk/agent-provider-openai**: Complete agents standard migration
-- **@robota-sdk/agent-provider-anthropic**: Complete agents standard migration
-- **@robota-sdk/agent-provider-google**: Complete agents standard migration
-- **@robota-sdk/agent-team**: assignTask MCP tool collection (team creation removed)
-
-### Deprecated Packages
 
-- **@robota-sdk/core**: Deprecated - functionality moved to agents
-- **@robota-sdk/agent-tools**: Deprecated - functionality moved to agents
+## Public API Surface
+
+| Category        | Exports                                                                                                                                                                                   |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Core**        | `Robota`, `ConversationStore`, `AbstractAgent`, `AbstractAIProvider` (+ `streamWithAbort`), `AbstractPlugin`, `AbstractTool`, `AbstractExecutor`, `LocalExecutor`                         |
+| **Permissions** | `evaluatePermission`, `MODE_POLICY`, `TRUST_TO_MODE`, `UNKNOWN_TOOL_FALLBACK`, `TPermissionMode`, `TTrustLevel`, `TPermissionDecision`, `TToolArgs`, `IPermissionLists`, `TKnownToolName` |
+| **Hooks**       | `runHooks`, `CommandExecutor`, `HttpExecutor`, `IHookTypeExecutor`, `THookEvent`, `THooksConfig`, `IHookGroup`, `IHookDefinition`, `IHookInput`, `IHookResult`                            |
+| **Events**      | `EventEmitterPlugin`, `IEventService`, `IOwnerPathSegment`                                                                                                                                |
+| **Models**      | `CLAUDE_MODELS`, `DEFAULT_CONTEXT_WINDOW`, `DEFAULT_MAX_OUTPUT`, `getModelContextWindow()`, `getModelMaxOutput()`, `getModelName()`, `formatTokenCount()`, `IModelDefinition`             |
+| **Types**       | `TUniversalMessage`, `IBaseMessage` (`id`, `state`), `TMessageState`, `IAgentConfig`, `IAIProvider`, `IToolSchema`, `IContextWindowState`, `IContextTokenUsage`, `TTextDeltaCallback`     |
+| **Errors**      | `RobotaError`, `ProviderError`, `RateLimitError`, `AuthenticationError`, `ToolExecutionError`, etc.                                                                                       |
+| **Managers**    | `AgentFactory`, `AgentTemplates`, `ConversationHistory`, `EventHistoryModule`                                                                                                             |
+
+## What Moved Out in v3
+
+| What                                          | Moved to                     |
+| --------------------------------------------- | ---------------------------- |
+| `FunctionTool`, `ToolRegistry`, `OpenAPITool` | `@robota-sdk/agent-tools`    |
+| `MCPTool`, `RelayMcpTool`                     | `@robota-sdk/agent-tool-mcp` |
+| 8 plugins (logging, usage, performance, etc.) | `@robota-sdk/agent-plugin-*` |
 
 ## License