@codebolt/agent 6.0.0 → 6.1.2

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/index.d.ts

@@ -0,0 +1,2 @@
+export * as ProcessorPieces from './processor-pieces';
+export * from './unified';

package/dist/index.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessorPieces = void 0;
+exports.ProcessorPieces = __importStar(require("./processor-pieces"));
+__exportStar(require("./unified"), exports);

package/dist/processor-pieces/messageModifiers/chatHistoryMessageModifier.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatHistoryMessageModifier = void 0;
 const base_1 = require("../base");
 const codeboltjs_1 = __importDefault(require("@codebolt/codeboltjs"));
+const promptContext_1 = require("../../unified/base/promptContext");
 // Using MessageObject from SDK types for chat history messages
 class ChatHistoryMessageModifier extends base_1.BaseMessageModifier {
     constructor(options = {}) {
@@ -26,10 +27,7 @@ class ChatHistoryMessageModifier extends base_1.BaseMessageModifier {
             }
             // Directly use the chat history messages - they're already in MessageObject format
             return {
-                message: {
-                    ...createdMessage.message,
-                    messages: [...chatHistory, ...createdMessage.message.messages]
-                },
+                ...(0, promptContext_1.prependTranscriptMessages)(createdMessage, chatHistory),
                 metadata: {
                     ...createdMessage.metadata,
                     chatHistoryAdded: true,

package/dist/processor-pieces/messageModifiers/contextAssemblyModifier.d.ts

@@ -0,0 +1,81 @@
+import { ProcessedMessage } from "@codebolt/types/agent";
+import { BaseMessageModifier } from "../base";
+import { FlatUserMessage } from "@codebolt/types/sdk";
+import type { ContextConstraints, MemoryContribution } from "@codebolt/types/lib";
+export interface ContextAssemblyModifierOptions {
+    /** Scope variables to pass to the context assembly engine */
+    scopeVariables?: Record<string, any>;
+    /** Additional variables for memory resolution */
+    additionalVariables?: Record<string, any> | undefined;
+    /** Explicit memory IDs to include */
+    explicitMemory?: string[] | undefined;
+    /** Rule engine IDs to use for filtering */
+    ruleEngineIds?: string[] | undefined;
+    /** Constraints for context assembly */
+    constraints?: ContextConstraints | undefined;
+    /** Whether to include the user's input in the context request */
+    includeUserInput?: boolean;
+    /** Whether to inject context as system or user message */
+    messageRole?: 'system' | 'user';
+    /** Whether to validate the request before assembling */
+    validateBeforeAssembly?: boolean;
+    /** Custom formatter for memory contributions */
+    formatContribution?: ((contribution: MemoryContribution) => string) | undefined;
+}
+export declare class ContextAssemblyModifier extends BaseMessageModifier {
+    private readonly options;
+    constructor(options?: ContextAssemblyModifierOptions);
+    modify(_originalRequest: FlatUserMessage, createdMessage: ProcessedMessage): Promise<ProcessedMessage>;
+    private buildRequest;
+    private formatContext;
+    private defaultFormatContribution;
+    /** Update scope variables at runtime */
+    setScopeVariables(variables: Record<string, any>): void;
+    /** Update additional variables at runtime */
+    setAdditionalVariables(variables: Record<string, any>): void;
+    /** Set explicit memory IDs to include */
+    setExplicitMemory(memoryIds: string[]): void;
+    /** Set constraints for context assembly */
+    setConstraints(constraints: ContextConstraints): void;
+}
+export interface RuleBasedContextModifierOptions {
+    /** Scope variables for rule evaluation */
+    scopeVariables?: Record<string, any>;
+    /** Specific rule engine IDs to evaluate */
+    ruleEngineIds?: string[] | undefined;
+    /** Whether to inject context as system or user message */
+    messageRole?: 'system' | 'user';
+    /** Constraints for the final context assembly */
+    constraints?: ContextConstraints | undefined;
+}
+export declare class RuleBasedContextModifier extends BaseMessageModifier {
+    private readonly options;
+    constructor(options?: RuleBasedContextModifierOptions);
+    modify(_originalRequest: FlatUserMessage, createdMessage: ProcessedMessage): Promise<ProcessedMessage>;
+    /** Update scope variables at runtime */
+    setScopeVariables(variables: Record<string, any>): void;
+    /** Set specific rule engine IDs to evaluate */
+    setRuleEngineIds(ruleEngineIds: string[]): void;
+}
+export interface MemoryTypeContextModifierOptions {
+    /** Specific memory type names to fetch */
+    memoryNames: string[];
+    /** Scope variables for context assembly */
+    scopeVariables?: Record<string, any>;
+    /** Whether to auto-resolve required variables from the message */
+    autoResolveVariables?: boolean;
+    /** Whether to inject context as system or user message */
+    messageRole?: 'system' | 'user';
+    /** Constraints for context assembly */
+    constraints?: ContextConstraints | undefined;
+}
+export declare class MemoryTypeContextModifier extends BaseMessageModifier {
+    private readonly options;
+    constructor(options: MemoryTypeContextModifierOptions);
+    modify(_originalRequest: FlatUserMessage, createdMessage: ProcessedMessage): Promise<ProcessedMessage>;
+    private resolveVariables;
+    /** Update memory names to fetch */
+    setMemoryNames(memoryNames: string[]): void;
+    /** Update scope variables at runtime */
+    setScopeVariables(variables: Record<string, any>): void;
+}