@codebolt/agent 6.0.1 → 6.1.3

package/README.md

@@ -1,211 +1,176 @@
 # CodeBolt Agent Package
 
-A comprehensive TypeScript framework for building and managing AI agents with CodeBolt. This package provides multiple architectural patterns and utilities to meet different development needs, from simple composable agents to complex multi-step workflows.
+`@codebolt/agent` provides TypeScript utilities for building CodeBolt agents with a unified execution pipeline, reusable processor pieces, tool definitions, workflows, loop detection, and conversation compaction.
 
-## 🚀 Quick Start
-
-```typescript
-import { ComposableAgent, createTool } from '@codebolt/agent/composable';
-import { z } from 'zod';
-
-// Create a simple weather tool
-const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get current weather for a location',
-  inputSchema: z.object({ location: z.string() }),
-  outputSchema: z.object({ temperature: z.number(), conditions: z.string() }),
-  execute: async ({ context }) => {
-    return await getWeatherAPI(context.location);
-  },
-});
-
-// Create and run agent
-const agent = new ComposableAgent({
-  name: 'Weather Agent',
-  instructions: 'You are a helpful weather assistant.',
-  model: 'gpt-4o-mini',
-  tools: { weatherTool },
-  memory: createCodeBoltAgentMemory('weather_agent')
-});
-
-const result = await agent.execute('What is the weather in New York?');
-```
-
-## ✨ Key Features
-
-- **Multiple Patterns**: Choose between Composable, Builder, and Processor patterns
-- **Type Safety**: Full TypeScript support with Zod validation
-- **Memory Management**: Persistent conversation storage with CodeBolt integration
-- **Tool System**: Extensible tool framework with validation
-- **Workflow Orchestration**: Multi-step agent processes with conditional logic
-- **Model Agnostic**: Support for OpenAI, Anthropic, Ollama, and more
-- **Stream Support**: Real-time streaming responses
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @codebolt/agent
 ```
 
-## 📖 Documentation
+## Public entry points
 
-**📚 [View Complete Documentation](./DOCUMENTATION.md)** - Comprehensive guide with examples, API reference, and best practices
+The package currently publishes these import paths:
 
-### Quick Links
-- [Architectural Patterns](./DOCUMENTATION.md#architectural-patterns) - Choose the right pattern for your use case
-- [API Reference](./API_REFERENCE.md) - Complete API documentation  
-- [Examples](./EXAMPLES.md) - Real-world usage examples and tutorials
-- [Best Practices](./DOCUMENTATION.md#best-practices) - Tips for optimal agent development
-- [Migration Guide](./DOCUMENTATION.md#migration-guide) - Upgrading from previous versions
+| Import path | Purpose |
+| --- | --- |
+| `@codebolt/agent` | Main entry point; re-exports the unified framework and `ProcessorPieces` namespace. |
+| `@codebolt/agent/unified` | Agent runtime, tools, workflows, compaction services, and core framework types. |
+| `@codebolt/agent/processor-pieces` | Reusable message modifiers and pre/post inference/tool processors. |
 
-## 🎯 Architecture Patterns
+Older examples that import from `@codebolt/agent/composable`, `@codebolt/agent/builder`, or `@codebolt/agent/processor` are obsolete for this package version.
 
-### Composable Pattern (Recommended)
-**Best for**: Rapid prototyping, simple agents, beginners
+## Quick start
 
 ```typescript
-import { ComposableAgent, createTool, createCodeBoltAgentMemory } from '@codebolt/agent/composable';
-
-const agent = new ComposableAgent({
-  name: 'My Agent',
-  instructions: 'You are a helpful assistant.',
-  model: 'gpt-4o-mini',
-  tools: { myTool },
-  memory: createCodeBoltAgentMemory('agent_id')
-});
-
-const result = await agent.execute('Help me with this task');
-```
+import { createCodeboltAgent } from '@codebolt/agent/unified';
 
-### Builder Pattern
-**Best for**: Complex workflows, fine-grained control
+const agent = createCodeboltAgent({
+  systemPrompt: 'You are a concise CodeBolt coding assistant.',
+  allowedTools: ['read_file', 'write_file'],
+  maxTurns: 10,
+});
 
-```typescript
-import { Agent, InitialPromptBuilder, LLMOutputHandler } from '@codebolt/agent/builder';
+const result = await agent.processMessage('Inspect the current project and summarize it.');
 
-const promptBuilder = new InitialPromptBuilder(userMessage)
-  .addSystemInstructions("You are a coding assistant")
-  .addFile("./src/main.ts")
-  .addTaskDetails("Fix compilation errors");
+if (!result.success) {
+  throw new Error(result.error);
+}
 
-const prompt = await promptBuilder.build();
-const agent = new Agent(tools, systemPrompt);
-const result = await agent.runAgent(prompt);
+console.log(result.finalMessage ?? result.result);
 ```
 
-### Processor Pattern
-**Best for**: Advanced customization, specialized requirements
+## Unified agent runtime
+
+Use `CodeboltAgent` or `createCodeboltAgent` for the default CodeBolt-aware runtime. It automatically adds common message modifiers for chat history, environment context, directory context, IDE context, system prompt injection, tool injection, and `@file` processing.
 
 ```typescript
-import { BaseProcessor, AgentStep } from '@codebolt/agent/processor';
+import {
+  CodeboltAgent,
+  ChatCompressionModifier,
+  ToolValidationModifier,
+} from '@codebolt/agent/unified';
+
+const agent = new CodeboltAgent({
+  instructions: 'Help the user safely modify code.',
+  processors: {
+    preInferenceProcessors: [new ChatCompressionModifier()],
+    preToolCallProcessors: [new ToolValidationModifier()],
+  },
+  enableLogging: true,
+  maxTurns: 25,
+});
 
-class CustomProcessor extends BaseProcessor {
-  async process(messages: any[]): Promise<any> {
-    return this.executeCustomFlow(messages);
-  }
-}
+const response = await agent.processMessage('Fix the lint errors in this package.');
 ```
 
-## 🛠️ Available Exports
+For lower-level control, use `Agent`, `InitialPromptGenerator`, `AgentStep`, and `ResponseExecutor` from `@codebolt/agent/unified`.
 
-### Composable Pattern
-```typescript
-import { 
-  ComposableAgent, createTool, createWorkflow,
-  Memory, createCodeBoltAgentMemory, MDocument 
-} from '@codebolt/agent/composable';
-```
+## Processor pieces
 
-### Builder Pattern  
-```typescript
-import { 
-  Agent, InitialPromptBuilder, LLMOutputHandler,
-  SystemPrompt, TaskInstruction, UserMessage 
-} from '@codebolt/agent/builder';
-```
+Reusable processor pieces are available both through `@codebolt/agent/processor-pieces` and through the unified entry point.
 
-### Processor Pattern
 ```typescript
-import { 
-  BaseProcessor, AgentStep, BaseTool,
-  ChatCompressionProcessor, LoopDetectionProcessor 
-} from '@codebolt/agent/processor';
+import {
+  EnvironmentContextModifier,
+  CoreSystemPromptModifier,
+  ToolInjectionModifier,
+} from '@codebolt/agent/processor-pieces';
+
+const messageModifiers = [
+  new EnvironmentContextModifier({ enableFullContext: true }),
+  new CoreSystemPromptModifier({ customSystemPrompt: 'You are helpful.' }),
+  new ToolInjectionModifier({ includeToolDescriptions: true }),
+];
 ```
 
-## 🏗️ Workflow System
+## Tools
 
-Create complex multi-agent workflows:
+`createTool` wraps a Zod input schema, optional output schema, and execution function.
 
 ```typescript
-const workflow = createWorkflow({
-  name: 'Content Pipeline',
-  steps: [
-    createAgentStep({
-      id: 'research', 
-      agent: researchAgent,
-      messageTemplate: 'Research: {{topic}}'
-    }),
-    createAgentStep({
-      id: 'write',
-      agent: writingAgent, 
-      messageTemplate: 'Write article: {{researchData}}'
-    })
-  ]
+import { createTool } from '@codebolt/agent/unified';
+import { z } from 'zod';
+
+const echoTool = createTool({
+  id: 'echo',
+  description: 'Echoes the provided text.',
+  inputSchema: z.object({
+    text: z.string(),
+  }),
+  outputSchema: z.object({
+    text: z.string(),
+  }),
+  execute: async ({ input }) => ({
+    text: input.text,
+  }),
 });
 
-const result = await workflow.execute({ topic: 'AI Ethics' });
+const execution = await echoTool.execute({ text: 'hello' }, {});
 ```
 
-## 🧠 Memory & Storage
+## Workflows
 
-Integrated with CodeBolt's storage system:
+`Workflow` executes workflow steps defined by `@codebolt/types/agent`. Use `executeAsync` when step implementations are asynchronous.
 
 ```typescript
-// Agent-scoped persistent storage
-const agentMemory = createCodeBoltAgentMemory('my_agent');
+import { Workflow } from '@codebolt/agent/unified';
 
-// Project-scoped storage
-const projectMemory = createCodeBoltProjectMemory('project_agent');
+const workflow = new Workflow({
+  name: 'Example Workflow',
+  steps: [
+    {
+      id: 'first-step',
+      name: 'First Step',
+      type: 'custom',
+      execute: async () => ({
+        stepId: 'first-step',
+        success: true,
+        result: 'done',
+      }),
+    },
+  ],
+});
 
-// Fast access memory database  
-const dbMemory = createCodeBoltDbMemory('cache_agent');
+const result = await workflow.executeAsync();
 ```
 
-## 🔧 Development
+## Conversation compaction
 
-```bash
-# Install dependencies
-npm install
+The unified framework includes layered compaction utilities:
 
-# Build the project
-npm run build
+- `CompactionOrchestrator`
+- `SnipCompact`
+- `MicroCompact`
+- `ContextCollapse`
+- `AutoCompact`
+- `ReactiveCompact`
+- `PostCompactCleanup`
+- `TokenEstimator`
 
-# Development mode
-npm run dev
+These are used by `Agent` and `CodeboltAgent` to reduce transcript size and recover from token-limit errors.
 
-# Run tests
-npm run test
+## Development
 
-# Lint code
+```bash
+npm install
+npm run build
 npm run lint
+npm test
 ```
 
-## 📋 Pattern Comparison
-
-| Pattern | Complexity | Use Case | Learning Curve |
-|---------|------------|----------|----------------|
-| **Composable** | Low | Rapid prototyping, simple agents | Low |
-| **Builder** | Medium | Complex workflows, custom logic | Medium |
-| **Processor** | High | Advanced customization | High |
-
-## 🤝 Contributing
+Additional documentation generation commands:
 
-See our [Contributing Guide](./DOCUMENTATION.md#contributing) for development setup, coding standards, and submission guidelines.
+```bash
+npm run docs
+npm run docs:clean
+npm run docs:watch
+```
 
-## 📄 License
+## Package files
 
-MIT - See the main CodeBolt repository for details.
+Only built files from `dist`, `README.md`, and `LICENSE` are published. The `dist` directory is generated by `npm run build` and should not be edited directly.
 
----
+## License
 
-**📚 [Complete Documentation](./DOCUMENTATION.md)** | **🐛 [Report Issues](https://github.com/codeboltai/codeboltjs/issues)** | **💬 [Join Community](https://discord.gg/codebolt)**
+MIT

package/dist/unified/agent/codeboltAgent.js

@@ -33,7 +33,10 @@ class CodeboltAgent {
     }
     createDefaultMessageModifiers(systemPrompt, allowedTools) {
         return [
-            new processor_pieces_1.ChatHistoryMessageModifier({ enableChatHistory: true }),
+            new processor_pieces_1.ChatHistoryMessageModifier({
+                enableChatHistory: true,
+                includeSystemMessages: false,
+            }),
             new processor_pieces_1.EnvironmentContextModifier({ enableFullContext: true }),
             new processor_pieces_1.DirectoryContextModifier(),
             new processor_pieces_1.IdeContextModifier({

package/dist/unified/base/responseExecutor.d.ts

@@ -16,7 +16,7 @@ export declare class ResponseExecutor implements AgentResponseExecutor {
     private extractLastMessageContent;
     private getToolCalls;
     private executeTools;
-    private isConcurrencySafe;
+    private sendFinalMessageToChat;
     private executeSingleToolCall;
     private executeTool;
     private parseToolResult;

package/dist/unified/base/responseExecutor.js

@@ -146,6 +146,7 @@ class ResponseExecutor {
         const lastMessageContent = this.extractLastMessageContent(llmResponse);
         const toolCalls = this.getToolCalls(llmResponse);
         if (toolCalls.length === 0) {
+            await this.sendFinalMessageToChat(lastMessageContent);
             return {
                 toolResults: [],
                 followUpMessages: [],
@@ -179,44 +180,16 @@ class ResponseExecutor {
         const toolResults = [];
         const followUpMessages = [];
         let userRejectedToolUse = false;
-        let currentIndex = 0;
-        while (currentIndex < executionToolCalls.length) {
-            const currentToolCall = executionToolCalls[currentIndex];
-            if (!currentToolCall) {
-                currentIndex += 1;
-                continue;
-            }
+        for (const currentToolCall of executionToolCalls) {
             if (userRejectedToolUse) {
                 const skippedResult = this.parseToolResult(currentToolCall.toolUseId, 'Skipping tool execution due to previous tool user rejection.');
                 toolResults.push(skippedResult);
-                currentIndex += 1;
                 continue;
             }
-            if (!this.isConcurrencySafe(currentToolCall)) {
-                const executionResult = await this.executeSingleToolCall(currentToolCall);
-                toolResults.push(executionResult.toolResult);
-                followUpMessages.push(...executionResult.followUpMessages);
-                userRejectedToolUse = executionResult.didUserReject;
-                currentIndex += 1;
-                continue;
-            }
-            const parallelBatch = [];
-            while (currentIndex < executionToolCalls.length) {
-                const candidateToolCall = executionToolCalls[currentIndex];
-                if (!candidateToolCall ||
-                    candidateToolCall.waitForPrevious ||
-                    !this.isConcurrencySafe(candidateToolCall)) {
-                    break;
-                }
-                parallelBatch.push(candidateToolCall);
-                currentIndex += 1;
-            }
-            const batchResults = await Promise.all(parallelBatch.map((toolCall) => this.executeSingleToolCall(toolCall)));
-            for (const batchResult of batchResults) {
-                toolResults.push(batchResult.toolResult);
-                followUpMessages.push(...batchResult.followUpMessages);
-                userRejectedToolUse = userRejectedToolUse || batchResult.didUserReject;
-            }
+            const executionResult = await this.executeSingleToolCall(currentToolCall);
+            toolResults.push(executionResult.toolResult);
+            followUpMessages.push(...executionResult.followUpMessages);
+            userRejectedToolUse = executionResult.didUserReject;
         }
         if (completionToolCalls.length > 0) {
             const completionToolCall = completionToolCalls.at(-1);
@@ -236,61 +209,16 @@ class ResponseExecutor {
             hadToolCalls: true,
         };
     }
-    isConcurrencySafe(toolCall) {
-        var _a;
-        if (toolCall.waitForPrevious) {
-            return false;
+    async sendFinalMessageToChat(message) {
+        if (!message || message.trim().length === 0) {
+            return;
         }
-        const normalizedToolName = toolCall.toolName.toLowerCase();
-        if (normalizedToolName.startsWith('subagent--') ||
-            normalizedToolName.includes('thread_management')) {
-            return false;
+        try {
+            await Promise.resolve(codeboltjs_1.default.chat.sendMessage(message));
         }
-        const actualToolName = (_a = normalizedToolName.split('--').at(-1)) !== null && _a !== void 0 ? _a : normalizedToolName;
-        const toolNameTokens = actualToolName
-            .split(/[^a-z0-9]+/)
-            .filter((token) => token.length > 0);
-        const mutatingKeywords = new Set([
-            'write',
-            'edit',
-            'create',
-            'delete',
-            'remove',
-            'rename',
-            'move',
-            'copy',
-            'apply',
-            'shell',
-            'command',
-            'run',
-            'exec',
-            'thread_management',
-            'attempt_completion',
-            'completion',
-            'todo',
-            'spawn',
-            'start',
-        ]);
-        if (toolNameTokens.some((token) => mutatingKeywords.has(token))) {
-            return false;
+        catch (error) {
+            console.error('[ResponseExecutor] Failed to send final chat message:', error);
         }
-        const readOnlyKeywords = new Set([
-            'read',
-            'search',
-            'list',
-            'find',
-            'glob',
-            'grep',
-            'view',
-            'stat',
-            'inspect',
-            'get',
-            'show',
-            'query',
-            'ls',
-            'cat',
-        ]);
-        return toolNameTokens.some((token) => readOnlyKeywords.has(token));
     }
     async executeSingleToolCall(toolCall) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codebolt/agent",
-  "version": "6.0.1",
+  "version": "6.1.3",
   "description": "CodeBolt Agent utilities for building and managing AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,8 @@
     "clean": "rm -rf dist",
     "dev": "tsc --watch",
     "test": "echo \"No tests yet, but build passes\" && exit 0",
-    "lint:test": "eslint src/**/*.ts && tsc --noEmit",
+    "lint": "eslint src/**/*.ts && tsc --noEmit",
+    "lint:test": "npm run lint",
     "docs": "node script/gen-docusaurus-agent-types.js",
     "docs:clean": "node script/gen-docusaurus-agent-types.js --clean",
     "docs:watch": "node script/gen-docusaurus-agent-types.js --watch"
@@ -48,13 +49,16 @@
   "devDependencies": {
     "@codebolt/codeboltjs": "*",
     "@codebolt/types": "*",
+    "@eslint/js": "^8.57.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.14.2",
     "@types/uri-templates": "^0.1.34",
     "@types/ws": "^8.5.10",
+    "eslint": "^8.57.1",
     "typedoc": "0.28.16",
     "typedoc-plugin-markdown": "4.9.0",
-    "typescript": "^5.4.5"
+    "typescript": "^5.4.5",
+    "typescript-eslint": "^7.18.0"
   },
   "exports": {
     ".": {