coleo 0.1.0
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/LICENSE.txt +62 -0
- package/README.md +269 -0
- package/dist/index.js +88760 -0
- package/package.json +78 -0
package/LICENSE.txt
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
Business Source License 1.1
|
|
2
|
+
|
|
3
|
+
Parameters
|
|
4
|
+
|
|
5
|
+
Licensor: Systematic UI, LLC
|
|
6
|
+
Licensed Work: The licensed work is (c) 2026 Systematic UI, LLC
|
|
7
|
+
This license applies to all files in this repository
|
|
8
|
+
unless another license is specified in a subdirectory.
|
|
9
|
+
The Licensed Work is (c) 2025 [Your Name].
|
|
10
|
+
Additional Use Grant:
|
|
11
|
+
You may use the Licensed Work for production purposes
|
|
12
|
+
if you are:
|
|
13
|
+
|
|
14
|
+
(a) An individual natural person (sole proprietor)
|
|
15
|
+
developing software for yourself or for clients,
|
|
16
|
+
regardless of revenue generated; or
|
|
17
|
+
|
|
18
|
+
(b) A company or organization with fewer than 5 employees
|
|
19
|
+
AND less than $1,000,000 USD in annual revenue; or
|
|
20
|
+
|
|
21
|
+
(c) Using the Licensed Work solely for non-production
|
|
22
|
+
evaluation, testing, development, or educational
|
|
23
|
+
purposes.
|
|
24
|
+
|
|
25
|
+
Any other production use requires a Commercial License.
|
|
26
|
+
|
|
27
|
+
Change Date: 2029-01-31 (4 years from release date)
|
|
28
|
+
|
|
29
|
+
Change License: Apache License, Version 2.0
|
|
30
|
+
|
|
31
|
+
For information about alternative licensing arrangements for the Software,
|
|
32
|
+
please visit: [your-website.com/licensing]
|
|
33
|
+
|
|
34
|
+
-----------------------------------------------------------------------------
|
|
35
|
+
|
|
36
|
+
Business Source License 1.1
|
|
37
|
+
|
|
38
|
+
License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
|
|
39
|
+
"Business Source License" is a trademark of MariaDB Corporation Ab.
|
|
40
|
+
|
|
41
|
+
Terms
|
|
42
|
+
The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work. The Licensor may make an Additional Use Grant, above, permitting limited production use.
|
|
43
|
+
|
|
44
|
+
Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first, the Licensor hereby grants you rights under the terms of the Change License, and the rights granted in the paragraph above terminate.
|
|
45
|
+
|
|
46
|
+
If your use of the Licensed Work does not comply with the requirements currently in effect as described in this License, you must purchase a commercial license from the Licensor, its affiliated entities, or authorized resellers, or you must refrain from using the Licensed Work.
|
|
47
|
+
|
|
48
|
+
All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are subject to this License. This License applies separately for each version of the Licensed Work and the Change Date may vary for each version of the Licensed Work released by Licensor.
|
|
49
|
+
|
|
50
|
+
You must conspicuously display this License on each original or modified copy of the Licensed Work. If you receive the Licensed Work in original or modified form from a third party, the terms and conditions set forth in this License apply to your use of that work.
|
|
51
|
+
|
|
52
|
+
Any use of the Licensed Work in violation of this License will automatically terminate your rights under this License for the current and all other versions of the Licensed Work.
|
|
53
|
+
|
|
54
|
+
This License does not grant you any right in any trademark or logo of Licensor or its affiliates (provided that you may use a trademark or logo of Licensor as expressly required by this License).TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE. MariaDB hereby grants you permission to use this License’s text to license your works, and to refer to it using the trademark “Business Source License”, as long as you comply with the Covenants of Licensor below.
|
|
55
|
+
|
|
56
|
+
Covenants of Licensor
|
|
57
|
+
In consideration of the right to use this License’s text and the “Business Source License” name and trademark, Licensor covenants to MariaDB, and to all other recipients of the licensed work to be provided by Licensor:
|
|
58
|
+
|
|
59
|
+
To specify as the Change License the GPL Version 2.0 or any later version, or a license that is compatible with GPL Version 2.0 or a later version, where “compatible” means that software provided under the Change License can be included in a program with software provided under GPL Version 2.0 or a later version. Licensor may specify additional Change Licenses without limitation.
|
|
60
|
+
To either: (a) specify an additional grant of rights to use that does not impose any additional restriction on the right granted in this License, as the Additional Use Grant; or (b) insert the text “None” to specify a Change Date. Not to modify this License in any other way.
|
|
61
|
+
|
|
62
|
+
[full BSL 1.1 legal text https://mariadb.com/bsl11/]
|
package/README.md
ADDED
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
[](LICENSE.txt)
|
|
2
|
+
|
|
3
|
+
# Coleo
|
|
4
|
+
|
|
5
|
+
Distributed agent orchestration for software development. Coleo is a coordination layer that turns existing agent harnesses into a supervised multi-agent system: a central Brain, persistent state, and an Observatory for visibility.
|
|
6
|
+
|
|
7
|
+
> *Named after Coleoidea, the subclass of intelligent cephalopods that ditched rigid shells for distributed neural architecture.*
|
|
8
|
+
|
|
9
|
+
## Quick Start
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# Install dependencies
|
|
13
|
+
bun install
|
|
14
|
+
|
|
15
|
+
# Initialize Coleo
|
|
16
|
+
bun run src/cli/index.ts init
|
|
17
|
+
|
|
18
|
+
# Terminal 1: start the API server (required for harness-based arms)
|
|
19
|
+
bun run src/cli/index.ts serve
|
|
20
|
+
|
|
21
|
+
# Terminal 2: start the Brain (foreground polling loop)
|
|
22
|
+
bun run src/cli/index.ts brain run
|
|
23
|
+
|
|
24
|
+
# Terminal 3: spawn an Arm (headless by default via opencode-api)
|
|
25
|
+
bun run src/cli/index.ts arm spawn --name explorer --harness opencode-api --workdir ./your-repo
|
|
26
|
+
|
|
27
|
+
# Send a task via mail
|
|
28
|
+
bun run src/cli/index.ts mail send "Explore the codebase and identify refactoring opportunities"
|
|
29
|
+
|
|
30
|
+
# Check status
|
|
31
|
+
bun run src/cli/index.ts status
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Docker Quick Start
|
|
35
|
+
|
|
36
|
+
Run Coleo in a container with SSH access:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
# Copy env file and add your API keys
|
|
40
|
+
cp .env.example .env
|
|
41
|
+
# Edit .env with your ANTHROPIC_API_KEY, etc.
|
|
42
|
+
|
|
43
|
+
# Build and start
|
|
44
|
+
docker compose up -d
|
|
45
|
+
|
|
46
|
+
# SSH into the container
|
|
47
|
+
ssh -p 2222 coleo@localhost # password: coleo
|
|
48
|
+
|
|
49
|
+
# Inside the container:
|
|
50
|
+
coleo serve # Start the API server
|
|
51
|
+
coleo brain run # Start the Brain
|
|
52
|
+
coleo arm spawn -n coder --terminal tmux # Spawn in tmux (uses opencode-tui)
|
|
53
|
+
coleo status # Check status
|
|
54
|
+
|
|
55
|
+
# View Arm logs (headless mode)
|
|
56
|
+
tail -f ~/.coleo/logs/coleo_coder.log
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Ports:
|
|
60
|
+
- **2222**: Coleo SSH
|
|
61
|
+
- **3000**: Gitea web UI
|
|
62
|
+
- **2223**: Gitea git SSH
|
|
63
|
+
|
|
64
|
+
## Architecture
|
|
65
|
+
|
|
66
|
+
See `docs/architecture/overview.md` for detailed system documentation.
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
Human (You)
|
|
70
|
+
│
|
|
71
|
+
▼
|
|
72
|
+
┌─────────┐
|
|
73
|
+
│ Maildir │ ◄── himalaya/luk reads this
|
|
74
|
+
└────┬────┘
|
|
75
|
+
│
|
|
76
|
+
┌────▼────┐
|
|
77
|
+
│ Brain │ ← Polling loop, MCP server
|
|
78
|
+
└────┬────┘
|
|
79
|
+
│
|
|
80
|
+
┌────┴────┬─────────┐
|
|
81
|
+
▼ ▼ ▼
|
|
82
|
+
Arm Arm Arm
|
|
83
|
+
(opencode)(claude) (aider)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Commands
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
coleo init # Initialize ~/.coleo
|
|
90
|
+
coleo serve # Start the API server
|
|
91
|
+
coleo brain run # Start Brain (foreground)
|
|
92
|
+
coleo brain run --once # Single poll cycle
|
|
93
|
+
coleo arm spawn -n NAME # Spawn an Arm (via API server)
|
|
94
|
+
coleo arm spawn -n NAME --terminal tmux # Spawn in a visible terminal (opencode-tui)
|
|
95
|
+
coleo arm list # List active Arms
|
|
96
|
+
coleo mail inbox # View inbox
|
|
97
|
+
coleo mail send "task" # Send task to Brain
|
|
98
|
+
coleo status # Overall status
|
|
99
|
+
coleo mcp serve # Run MCP server (for Arms)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Harness Modes
|
|
103
|
+
|
|
104
|
+
Coleo separates “coordination” from “agent UI” via harnesses:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
# Headless (API-driven) harness
|
|
108
|
+
coleo arm spawn -n worker --harness opencode-api --workdir /path/to/repo
|
|
109
|
+
|
|
110
|
+
# Visible terminal harness (recommended when you want to watch/debug)
|
|
111
|
+
coleo arm spawn -n worker --terminal tmux --workdir /path/to/repo
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Local Development
|
|
115
|
+
|
|
116
|
+
### Prerequisites
|
|
117
|
+
|
|
118
|
+
- [Bun](https://bun.sh/) runtime (v1.0+)
|
|
119
|
+
- [NATS Server](https://nats.io/) with JetStream enabled (optional, for event streaming)
|
|
120
|
+
- [OpenCode](https://opencode.ai/) CLI (for spawning AI Arms)
|
|
121
|
+
|
|
122
|
+
### Setup
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
# Clone and install dependencies
|
|
126
|
+
git clone <repo-url>
|
|
127
|
+
cd coleo
|
|
128
|
+
bun install
|
|
129
|
+
|
|
130
|
+
# Initialize Coleo (creates ~/.coleo directory and database)
|
|
131
|
+
bun run src/cli/index.ts init
|
|
132
|
+
|
|
133
|
+
# Build the web UI
|
|
134
|
+
bun run web:build
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Running Locally
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
# Start the API server
|
|
141
|
+
bun run src/cli/index.ts serve
|
|
142
|
+
|
|
143
|
+
# Start the Brain orchestrator
|
|
144
|
+
bun run src/cli/index.ts brain run
|
|
145
|
+
|
|
146
|
+
# Development mode for web UI (hot reload)
|
|
147
|
+
bun run web:dev
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Available Scripts
|
|
151
|
+
|
|
152
|
+
| Script | Description |
|
|
153
|
+
|--------|-------------|
|
|
154
|
+
| `bun run dev` | Run CLI commands directly |
|
|
155
|
+
| `bun run brain` | Start the Brain orchestrator |
|
|
156
|
+
| `bun run typecheck` | Run TypeScript type checking |
|
|
157
|
+
| `bun run test` | Run unit tests |
|
|
158
|
+
| `bun run test:watch` | Run unit tests in watch mode |
|
|
159
|
+
| `bun run test:integration` | Run quick integration tests |
|
|
160
|
+
| `bun run test:e2e` | Run full end-to-end regression tests |
|
|
161
|
+
| `bun run web:dev` | Start web UI dev server (hot reload) |
|
|
162
|
+
| `bun run web:build` | Build web UI for production |
|
|
163
|
+
| `bun run docs:dev` | Start documentation dev server |
|
|
164
|
+
|
|
165
|
+
### Environment Variables
|
|
166
|
+
|
|
167
|
+
Create a `.env` file in the project root:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
# Required for AI Arms
|
|
171
|
+
ANTHROPIC_API_KEY=your-key-here
|
|
172
|
+
OPENAI_API_KEY=your-key-here # Optional
|
|
173
|
+
|
|
174
|
+
# Optional configuration
|
|
175
|
+
COLEO_API_PORT=8080 # API server port (default: 8080)
|
|
176
|
+
COLEO_API_HOST=0.0.0.0 # API server host (default: 0.0.0.0)
|
|
177
|
+
COLEO_API_KEY=your-key-here # Optional API key for the Observatory/API
|
|
178
|
+
COLEO_DB_PATH=~/.coleo/coleo.db # Database location
|
|
179
|
+
COLEO_NATS_URL=nats://localhost:4222 # NATS server URL
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Testing
|
|
183
|
+
|
|
184
|
+
Coleo has three levels of testing:
|
|
185
|
+
|
|
186
|
+
### Unit Tests
|
|
187
|
+
|
|
188
|
+
Fast, isolated tests for individual modules.
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
# Run all unit tests
|
|
192
|
+
bun run test
|
|
193
|
+
|
|
194
|
+
# Run in watch mode during development
|
|
195
|
+
bun run test:watch
|
|
196
|
+
|
|
197
|
+
# Run tests for a specific module
|
|
198
|
+
bun test src/mcp/__tests__/
|
|
199
|
+
bun test src/api/__tests__/
|
|
200
|
+
bun test src/brain/__tests__/
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Integration Tests
|
|
204
|
+
|
|
205
|
+
Standalone scripts for quick manual verification of specific features. These are **not** run by `test:integration`—they're meant for ad-hoc testing during development.
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
# Session isolation test - verifies each Arm gets a unique session
|
|
209
|
+
bun run test-session-isolation.ts
|
|
210
|
+
|
|
211
|
+
# JetStream pattern test - verifies multi-part event subjects work
|
|
212
|
+
bun run test-jetstream-pattern.ts
|
|
213
|
+
|
|
214
|
+
# Task assignment test
|
|
215
|
+
bun run test-task-assignment.ts
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### Regression Tests
|
|
219
|
+
|
|
220
|
+
Comprehensive test suite that runs scenarios against multiple AI models. Use `test:integration` for quick checks or `test:e2e` for full coverage.
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
# Quick regression tests (only scenarios tagged 'quick')
|
|
224
|
+
bun run test:integration
|
|
225
|
+
|
|
226
|
+
# Full regression test suite (all scenarios)
|
|
227
|
+
bun run test:e2e
|
|
228
|
+
|
|
229
|
+
# Run the regression runner directly with options
|
|
230
|
+
bun run src/regression/runner.ts --quick
|
|
231
|
+
bun run src/regression/runner.ts --scenario session-isolation
|
|
232
|
+
bun run src/regression/runner.ts --tag core
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Regression test results are saved to `~/.coleo/regression-results/`.
|
|
236
|
+
|
|
237
|
+
### Test Scenarios
|
|
238
|
+
|
|
239
|
+
Located in `src/regression/scenarios/`. Scenarios tagged `quick` run with `test:integration`.
|
|
240
|
+
|
|
241
|
+
| Scenario | Tags | Description |
|
|
242
|
+
|----------|------|-------------|
|
|
243
|
+
| `infrastructure-startup` | quick | Verifies all infrastructure components start correctly |
|
|
244
|
+
| `session-isolation` | quick | Verifies Arms don't share session history |
|
|
245
|
+
| `self-healing-api-restart` | - | Tests API server recovery after restart |
|
|
246
|
+
| `zombie-arm-detection` | - | Tests detection and cleanup of zombie Arms |
|
|
247
|
+
| `simple-task-completion` | - | Tests basic task assignment and completion |
|
|
248
|
+
| `arm-recovery` | - | Tests Arm crash recovery and session restoration |
|
|
249
|
+
|
|
250
|
+
### Writing New Tests
|
|
251
|
+
|
|
252
|
+
**Unit tests**: Create `*.test.ts` files in `__tests__/` directories alongside source files.
|
|
253
|
+
|
|
254
|
+
**Integration tests**: Create standalone `test-*.ts` files in the project root. These should be self-contained and clean up after themselves.
|
|
255
|
+
|
|
256
|
+
**Regression scenarios**: Add new scenarios to `src/regression/scenarios/` following the existing pattern. Export them from `src/regression/scenarios.ts`.
|
|
257
|
+
|
|
258
|
+
## Gitea (Optional)
|
|
259
|
+
|
|
260
|
+
For local git collaboration:
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
docker compose up -d
|
|
264
|
+
open http://localhost:3000
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
## License
|
|
268
|
+
|
|
269
|
+
Business Source License 1.1 (BSL 1.1). Free for individual use. Contact for organizational licensing.
|