botinabox 0.5.5 → 0.5.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +130 -205
- package/dist/index.js +5 -3
- package/package.json +5 -1
package/README.md
CHANGED
|
@@ -4,248 +4,173 @@ A modular TypeScript framework for building multi-agent bots with LLM orchestrat
|
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
|
-
- **Multi-agent orchestration**
|
|
8
|
-
- **LLM provider abstraction**
|
|
9
|
-
- **Channel adapters**
|
|
10
|
-
- **Workflow engine**
|
|
11
|
-
- **SQLite data layer**
|
|
12
|
-
- **Event-driven hooks**
|
|
13
|
-
- **Budget controls**
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
|
|
18
|
-
##
|
|
19
|
-
|
|
20
|
-
| Package | Description |
|
|
21
|
-
|---------|-------------|
|
|
22
|
-
| [`@botinabox/core`](packages/core) | Core framework — config, data, hooks, LLM, orchestration, chat, security |
|
|
23
|
-
| [`@botinabox/shared`](packages/shared) | Shared types, interfaces, and constants (zero dependencies) |
|
|
24
|
-
| [`@botinabox/cli`](packages/cli) | CLI tool for scaffolding new projects |
|
|
25
|
-
| [`@botinabox/provider-anthropic`](packages/providers/anthropic) | Anthropic Claude provider |
|
|
26
|
-
| [`@botinabox/provider-openai`](packages/providers/openai) | OpenAI GPT provider |
|
|
27
|
-
| [`@botinabox/provider-ollama`](packages/providers/ollama) | Ollama local model provider |
|
|
28
|
-
| [`@botinabox/channel-slack`](packages/channels/slack) | Slack channel adapter |
|
|
29
|
-
| [`@botinabox/channel-discord`](packages/channels/discord) | Discord channel adapter |
|
|
30
|
-
| [`@botinabox/channel-webhook`](packages/channels/webhook) | Webhook channel adapter with HMAC verification |
|
|
31
|
-
|
|
32
|
-
## Quick Start
|
|
33
|
-
|
|
34
|
-
### Prerequisites
|
|
35
|
-
|
|
36
|
-
- Node.js 20+
|
|
37
|
-
- pnpm 9+
|
|
38
|
-
|
|
39
|
-
### Install
|
|
7
|
+
- **Multi-agent orchestration** -- Define agents with different models, roles, and execution adapters. Task queue with priority scheduling, retry policies, and followup chains.
|
|
8
|
+
- **LLM provider abstraction** -- Swap between Anthropic, OpenAI, and Ollama with a unified interface. Model aliasing, purpose-based routing, and fallback chains.
|
|
9
|
+
- **Channel adapters** -- Connect to Slack, Discord, and webhooks. Auto-discovery, session management, and notification queuing.
|
|
10
|
+
- **Workflow engine** -- Define multi-step workflows with dependency resolution, parallel execution, and conditional branching.
|
|
11
|
+
- **SQLite data layer** -- Schema-driven tables, migrations, entity context rendering, and query builder via [latticesql](https://github.com/automated-industries/lattice). WAL mode for concurrent reads.
|
|
12
|
+
- **Event-driven hooks** -- Priority-ordered, filter-based event bus for decoupled inter-layer communication.
|
|
13
|
+
- **Budget controls** -- Per-agent and global cost tracking with warning thresholds and hard stops.
|
|
14
|
+
- **Scheduling** -- Database-backed cron and one-time schedules that fire hook events.
|
|
15
|
+
- **Google connectors** -- Gmail and Calendar integration via OAuth2.
|
|
16
|
+
- **Security** -- Input sanitization, field length enforcement, audit logging, and HMAC webhook verification.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
40
19
|
|
|
41
20
|
```bash
|
|
42
|
-
|
|
43
|
-
cd botinabox
|
|
44
|
-
pnpm install
|
|
45
|
-
pnpm build
|
|
21
|
+
npm install botinabox
|
|
46
22
|
```
|
|
47
23
|
|
|
48
|
-
|
|
24
|
+
Install peer dependencies for the providers you need:
|
|
49
25
|
|
|
50
26
|
```bash
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
```
|
|
27
|
+
# For Anthropic
|
|
28
|
+
npm install @anthropic-ai/sdk
|
|
54
29
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
### Configure
|
|
58
|
-
|
|
59
|
-
Edit `botinabox.config.yml`:
|
|
60
|
-
|
|
61
|
-
```yaml
|
|
62
|
-
data:
|
|
63
|
-
path: ./data/bot.db
|
|
64
|
-
walMode: true
|
|
65
|
-
|
|
66
|
-
channels:
|
|
67
|
-
slack:
|
|
68
|
-
enabled: true
|
|
69
|
-
botToken: ${SLACK_BOT_TOKEN}
|
|
70
|
-
|
|
71
|
-
providers:
|
|
72
|
-
anthropic:
|
|
73
|
-
enabled: true
|
|
74
|
-
apiKey: ${ANTHROPIC_API_KEY}
|
|
75
|
-
|
|
76
|
-
agents:
|
|
77
|
-
- slug: assistant
|
|
78
|
-
name: Assistant
|
|
79
|
-
adapter: api
|
|
80
|
-
model: smart
|
|
81
|
-
|
|
82
|
-
models:
|
|
83
|
-
default: claude-sonnet-4-6
|
|
84
|
-
aliases:
|
|
85
|
-
fast: claude-haiku-4-5
|
|
86
|
-
smart: claude-opus-4-6
|
|
87
|
-
balanced: claude-sonnet-4-6
|
|
88
|
-
routing:
|
|
89
|
-
conversation: fast
|
|
90
|
-
task_execution: smart
|
|
91
|
-
classification: fast
|
|
92
|
-
fallbackChain: []
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
Set environment variables in `.env`:
|
|
30
|
+
# For OpenAI
|
|
31
|
+
npm install openai
|
|
96
32
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
SLACK_BOT_TOKEN=xoxb-your-token
|
|
33
|
+
# For Google connectors
|
|
34
|
+
npm install googleapis
|
|
100
35
|
```
|
|
101
36
|
|
|
102
|
-
|
|
37
|
+
## Quick Start
|
|
103
38
|
|
|
104
39
|
```typescript
|
|
105
|
-
import {
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
//
|
|
115
|
-
const { config } = loadConfig({ configPath: 'botinabox.config.yml' });
|
|
116
|
-
|
|
117
|
-
// Initialize systems
|
|
40
|
+
import {
|
|
41
|
+
HookBus,
|
|
42
|
+
DataStore,
|
|
43
|
+
defineCoreTables,
|
|
44
|
+
AgentRegistry,
|
|
45
|
+
TaskQueue,
|
|
46
|
+
RunManager,
|
|
47
|
+
} from 'botinabox';
|
|
48
|
+
|
|
49
|
+
// 1. Create core services
|
|
118
50
|
const hooks = new HookBus();
|
|
119
|
-
const db = new DataStore({ dbPath:
|
|
120
|
-
defineCoreTables(db);
|
|
121
|
-
db.init();
|
|
51
|
+
const db = new DataStore({ dbPath: './data/bot.db', wal: true, hooks });
|
|
122
52
|
|
|
123
|
-
//
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
const router = new ModelRouter(providers, config.models);
|
|
127
|
-
|
|
128
|
-
// Channels
|
|
129
|
-
const channels = new ChannelRegistry();
|
|
130
|
-
channels.register(createSlackAdapter(), config.channels.slack);
|
|
53
|
+
// 2. Define tables and initialize
|
|
54
|
+
defineCoreTables(db);
|
|
55
|
+
await db.init();
|
|
131
56
|
|
|
132
|
-
//
|
|
57
|
+
// 3. Set up orchestration
|
|
133
58
|
const agents = new AgentRegistry(db, hooks);
|
|
134
59
|
const tasks = new TaskQueue(db, hooks);
|
|
135
60
|
const runs = new RunManager(db, hooks);
|
|
136
|
-
const pipeline = new MessagePipeline(hooks, agents, tasks, config);
|
|
137
61
|
|
|
138
|
-
//
|
|
139
|
-
|
|
140
|
-
|
|
62
|
+
// 4. Register an agent
|
|
63
|
+
const agentId = await agents.register({
|
|
64
|
+
slug: 'assistant',
|
|
65
|
+
name: 'Assistant',
|
|
66
|
+
adapter: 'api',
|
|
67
|
+
role: 'general',
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
// 5. Listen for task creation
|
|
71
|
+
hooks.register('task.created', async (ctx) => {
|
|
72
|
+
console.log(`Task created: ${ctx.taskId}`);
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
// 6. Create a task
|
|
76
|
+
const taskId = await tasks.create({
|
|
77
|
+
title: 'Summarize the quarterly report',
|
|
78
|
+
description: 'Read the Q4 report and produce a 3-paragraph summary.',
|
|
79
|
+
assignee_id: agentId,
|
|
80
|
+
priority: 3,
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
// 7. Wire up task completion hooks
|
|
84
|
+
hooks.register('run.completed', async (ctx) => {
|
|
85
|
+
console.log(`Run finished for task ${ctx.taskId}, exit code: ${ctx.exitCode}`);
|
|
86
|
+
});
|
|
141
87
|
```
|
|
142
88
|
|
|
89
|
+
## Subpath Exports
|
|
90
|
+
|
|
91
|
+
| Import path | Description |
|
|
92
|
+
|---|---|
|
|
93
|
+
| `botinabox` | Core framework -- HookBus, DataStore, AgentRegistry, TaskQueue, RunManager, ChannelRegistry, MessagePipeline, Scheduler, config, security, and all shared types |
|
|
94
|
+
| `botinabox/anthropic` | Anthropic Claude provider (`createAnthropicProvider`) |
|
|
95
|
+
| `botinabox/openai` | OpenAI GPT provider (`createOpenAIProvider`) |
|
|
96
|
+
| `botinabox/ollama` | Ollama local model provider (`createOllamaProvider`) |
|
|
97
|
+
| `botinabox/slack` | Slack channel adapter (`SlackAdapter`) |
|
|
98
|
+
| `botinabox/discord` | Discord channel adapter (`DiscordAdapter`) |
|
|
99
|
+
| `botinabox/webhook` | Webhook channel adapter with HMAC verification (`WebhookAdapter`) |
|
|
100
|
+
| `botinabox/google` | Google connectors -- Gmail and Calendar via OAuth2 |
|
|
101
|
+
|
|
143
102
|
## Architecture
|
|
144
103
|
|
|
145
104
|
```
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
105
|
+
+-------------------------------------+
|
|
106
|
+
| Channel Adapters |
|
|
107
|
+
| Slack . Discord . Webhook |
|
|
108
|
+
+--------------+-----------------------+
|
|
109
|
+
| InboundMessage
|
|
110
|
+
+--------------v-----------------------+
|
|
111
|
+
| Message Pipeline |
|
|
112
|
+
| routing . policies . sessions |
|
|
113
|
+
+--------------+-----------------------+
|
|
114
|
+
| Task
|
|
115
|
+
+--------------v-----------------------+
|
|
116
|
+
| Task Queue |
|
|
117
|
+
| priority . retry . followup chains |
|
|
118
|
+
+--------------+-----------------------+
|
|
119
|
+
|
|
|
120
|
+
+--------------v-----------------------+
|
|
121
|
+
| Run Manager |
|
|
122
|
+
| locking . retries . cost tracking |
|
|
123
|
+
+--------------+-----------------------+
|
|
124
|
+
|
|
|
125
|
+
+--------------------+--------------------+
|
|
126
|
+
v v v
|
|
127
|
+
+------------------+ +------------------+ +---------------+
|
|
128
|
+
| CLI Adapter | | API Adapter | | Custom |
|
|
129
|
+
| (subprocess) | | (LLM + tools) | | Adapters |
|
|
130
|
+
+------------------+ +--------+----------+ +---------------+
|
|
131
|
+
|
|
|
132
|
+
+--------------v-----------------------+
|
|
133
|
+
| LLM Layer |
|
|
134
|
+
| ProviderRegistry . ModelRouter |
|
|
135
|
+
| BudgetController . Tool Loop |
|
|
136
|
+
+--------------+-----------------------+
|
|
137
|
+
|
|
|
138
|
+
+--------------------+-------------------+
|
|
139
|
+
v v v
|
|
140
|
+
+---------------+ +---------------+ +---------------+
|
|
141
|
+
| Anthropic | | OpenAI | | Ollama |
|
|
142
|
+
+---------------+ +---------------+ +---------------+
|
|
184
143
|
```
|
|
185
144
|
|
|
186
|
-
Cross-cutting concerns
|
|
145
|
+
Cross-cutting concerns -- **HookBus** (events), **DataStore** (persistence), **Security** (sanitization + audit) -- connect all layers.
|
|
187
146
|
|
|
188
|
-
##
|
|
147
|
+
## Core Concepts
|
|
189
148
|
|
|
190
|
-
|
|
191
|
-
- [Configuration](docs/configuration.md) — Full config reference
|
|
192
|
-
- [Architecture](docs/architecture.md) — System design and patterns
|
|
193
|
-
- [Providers](docs/providers.md) — LLM provider setup and custom providers
|
|
194
|
-
- [Channels](docs/channels.md) — Channel adapter setup and custom adapters
|
|
195
|
-
- [Orchestration](docs/orchestration.md) — Agents, tasks, workflows, and budget controls
|
|
196
|
-
- [API Reference](docs/api-reference.md) — Complete API documentation
|
|
149
|
+
**HookBus** is the central event bus. Handlers subscribe to named events with optional priority ordering and payload filters. Errors in one handler never block others. Use it to decouple layers -- the task queue emits `task.created`, the run manager emits `run.completed`, channels emit `message.inbound`, and your application code listens to whichever events it needs.
|
|
197
150
|
|
|
198
|
-
|
|
151
|
+
**DataStore** wraps [latticesql](https://github.com/automated-industries/lattice) to provide schema-driven SQLite persistence. You call `db.define()` to register table schemas, then `db.init()` to create them. It supports insert, update, upsert, get, query, delete, and migrations. WAL mode is enabled by default for concurrent read access.
|
|
199
152
|
|
|
200
|
-
|
|
201
|
-
# Install dependencies
|
|
202
|
-
pnpm install
|
|
153
|
+
**AgentRegistry** manages the lifecycle of agents -- registration, status transitions (idle/running/paused/terminated), configuration revisions, and activity logging. Each agent has a slug, name, adapter type, role, and optional budget. Agents are stored in the database and can be seeded from config on startup.
|
|
203
154
|
|
|
204
|
-
|
|
205
|
-
pnpm build
|
|
155
|
+
**TaskQueue** is a priority-ordered work queue backed by SQLite. Tasks have a title, description, assignee, priority (1-10), and support retry policies and followup chains. Chain depth is enforced to prevent infinite recursion. The queue emits `task.created` on the HookBus and supports polling for stale tasks.
|
|
206
156
|
|
|
207
|
-
|
|
208
|
-
pnpm test:run
|
|
157
|
+
**RunManager** handles task execution lifecycle. It acquires a per-agent lock, creates a run record, delegates to an execution adapter (API or CLI), and records the result including exit code, cost, and token usage. Failed runs trigger retry logic with exponential backoff.
|
|
209
158
|
|
|
210
|
-
|
|
211
|
-
pnpm typecheck
|
|
212
|
-
```
|
|
159
|
+
**ChannelRegistry** manages channel adapter connections. Register adapters (Slack, Discord, webhook) with their config, then call `start()` to connect them all. Supports hot reconfiguration, health checks, and graceful shutdown.
|
|
213
160
|
|
|
214
|
-
|
|
161
|
+
**MessagePipeline** routes inbound messages from channels to the task queue. It resolves the sender to a user identity, picks the right agent based on channel bindings, applies policy checks (allowlists, mention gates), and creates a task for the assigned agent.
|
|
215
162
|
|
|
216
|
-
|
|
217
|
-
botinabox/
|
|
218
|
-
├── packages/
|
|
219
|
-
│ ├── core/ # Core framework
|
|
220
|
-
│ │ └── src/
|
|
221
|
-
│ │ ├── config/ # YAML config loader + validation
|
|
222
|
-
│ │ ├── data/ # SQLite ORM, migrations, entity rendering
|
|
223
|
-
│ │ ├── hooks/ # Event bus
|
|
224
|
-
│ │ ├── llm/ # Provider registry, model router, cost tracking
|
|
225
|
-
│ │ ├── chat/ # Channel registry, message pipeline, sessions
|
|
226
|
-
│ │ ├── orchestrator/ # Agents, tasks, runs, workflows, adapters
|
|
227
|
-
│ │ ├── security/ # Sanitizer, audit, column validation
|
|
228
|
-
│ │ └── update/ # Self-update system
|
|
229
|
-
│ ├── shared/ # Types and constants (zero deps)
|
|
230
|
-
│ ├── cli/ # CLI scaffolding tool
|
|
231
|
-
│ ├── providers/
|
|
232
|
-
│ │ ├── anthropic/ # Claude models
|
|
233
|
-
│ │ ├── openai/ # GPT models
|
|
234
|
-
│ │ └── ollama/ # Local models
|
|
235
|
-
│ └── channels/
|
|
236
|
-
│ ├── slack/ # Slack adapter
|
|
237
|
-
│ ├── discord/ # Discord adapter
|
|
238
|
-
│ └── webhook/ # Webhook adapter + HMAC
|
|
239
|
-
├── package.json
|
|
240
|
-
├── pnpm-workspace.yaml
|
|
241
|
-
└── tsconfig.json
|
|
242
|
-
```
|
|
163
|
+
**Scheduler** provides database-backed job scheduling with cron expressions. Register recurring or one-time schedules that emit hook events when they fire. The scheduler polls for due jobs and emits the schedule's `action` as a hook event with its configured payload.
|
|
243
164
|
|
|
244
|
-
##
|
|
245
|
-
|
|
246
|
-
**CLI users:** The `botinabox` CLI checks for new versions automatically and prints a notice when an update is available. Run `botinabox update` to upgrade in place. Alternatively, use `npx botinabox` to always run the latest version without a global install.
|
|
165
|
+
## Documentation
|
|
247
166
|
|
|
248
|
-
|
|
167
|
+
- [Getting Started](docs/getting-started.md) -- Installation, project setup, first bot
|
|
168
|
+
- [Configuration](docs/configuration.md) -- Full config reference
|
|
169
|
+
- [Architecture](docs/architecture.md) -- System design and patterns
|
|
170
|
+
- [Providers](docs/providers.md) -- LLM provider setup and custom providers
|
|
171
|
+
- [Channels](docs/channels.md) -- Channel adapter setup and custom adapters
|
|
172
|
+
- [Orchestration](docs/orchestration.md) -- Agents, tasks, workflows, and budget controls
|
|
173
|
+
- [API Reference](docs/api-reference.md) -- Complete API documentation
|
|
249
174
|
|
|
250
175
|
## License
|
|
251
176
|
|
package/dist/index.js
CHANGED
|
@@ -1155,15 +1155,17 @@ var DataStore = class {
|
|
|
1155
1155
|
outputFile: def.indexFile,
|
|
1156
1156
|
render: def.indexRender ?? ((rows) => {
|
|
1157
1157
|
const active = rows.filter((r) => r.deleted_at == null);
|
|
1158
|
-
const
|
|
1158
|
+
const dir = def.directory;
|
|
1159
|
+
const title = dir.charAt(0).toUpperCase() + dir.slice(1);
|
|
1159
1160
|
if (!active.length) return `# ${title}
|
|
1160
1161
|
|
|
1161
1162
|
None.
|
|
1162
1163
|
`;
|
|
1163
1164
|
const lines = active.map((r) => {
|
|
1164
|
-
const
|
|
1165
|
+
const slug = String(r[def.slugColumn] ?? r.name ?? r.id ?? "unknown");
|
|
1166
|
+
const name2 = String(r.name ?? slug);
|
|
1165
1167
|
const status = r.status ? ` (${r.status})` : "";
|
|
1166
|
-
return `-
|
|
1168
|
+
return `- [${name2}](${dir}/${slug}/)${status}`;
|
|
1167
1169
|
});
|
|
1168
1170
|
return `# ${title}
|
|
1169
1171
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "botinabox",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.7",
|
|
4
4
|
"description": "Bot in a Box — framework for building multi-agent bots",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -79,6 +79,10 @@
|
|
|
79
79
|
"optional": true
|
|
80
80
|
}
|
|
81
81
|
},
|
|
82
|
+
"repository": {
|
|
83
|
+
"type": "git",
|
|
84
|
+
"url": "https://github.com/automated-industries/botinabox.git"
|
|
85
|
+
},
|
|
82
86
|
"devDependencies": {
|
|
83
87
|
"@anthropic-ai/sdk": "^0.52.0",
|
|
84
88
|
"@types/better-sqlite3": "^7.6.12",
|