CodeBolt Agent Package

@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.

Installation

npm install @codebolt/agent

Public entry points

The package currently publishes these import paths:

| 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. |

Older examples that import from @codebolt/agent/composable, @codebolt/agent/builder, or @codebolt/agent/processor are obsolete for this package version.

Quick start

import { createCodeboltAgent } from '@codebolt/agent/unified';

const agent = createCodeboltAgent({
  systemPrompt: 'You are a concise CodeBolt coding assistant.',
  allowedTools: ['read_file', 'write_file'],
  maxTurns: 10,
});

const result = await agent.processMessage('Inspect the current project and summarize it.');

if (!result.success) {
  throw new Error(result.error);
}

console.log(result.finalMessage ?? result.result);

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.

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,
});

const response = await agent.processMessage('Fix the lint errors in this package.');

For lower-level control, use Agent, InitialPromptGenerator, AgentStep, and ResponseExecutor from @codebolt/agent/unified.

Processor pieces

Reusable processor pieces are available both through @codebolt/agent/processor-pieces and through the unified entry point.

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 }),
];

Tools

createTool wraps a Zod input schema, optional output schema, and execution function.

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 execution = await echoTool.execute({ text: 'hello' }, {});

Workflows

Workflow executes workflow steps defined by @codebolt/types/agent. Use executeAsync when step implementations are asynchronous.

import { Workflow } from '@codebolt/agent/unified';

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',
      }),
    },
  ],
});

const result = await workflow.executeAsync();

Conversation compaction

The unified framework includes layered compaction utilities:

• CompactionOrchestrator
• SnipCompact
• MicroCompact
• ContextCollapse
• AutoCompact
• ReactiveCompact
• PostCompactCleanup
• TokenEstimator

These are used by Agent and CodeboltAgent to reduce transcript size and recover from token-limit errors.

Development

npm install
npm run build
npm run lint
npm test

Additional documentation generation commands:

npm run docs
npm run docs:clean
npm run docs:watch

Package files

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

MIT