alineo-mcp 0.2.0 → 0.3.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/README.md +60 -55
- package/dist/index.mjs +376 -82
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -13,49 +13,54 @@ servers (filesystem, GitHub, …), not a hosted worker like [`@alineo-labs/docs-
|
|
|
13
13
|
**alineod — swarm control** (requires alineod running, default `http://127.0.0.1:4600`, override
|
|
14
14
|
with `ALINEOD_URL`):
|
|
15
15
|
|
|
16
|
-
| Tool
|
|
17
|
-
|
|
|
18
|
-
| `
|
|
19
|
-
| `
|
|
20
|
-
| `
|
|
21
|
-
| `
|
|
22
|
-
| `
|
|
23
|
-
| `
|
|
24
|
-
| `
|
|
25
|
-
| `
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
29
|
-
| `
|
|
16
|
+
| Tool | Route | |
|
|
17
|
+
| -------------- | ------------------------------- | ------------------------------------------------------- |
|
|
18
|
+
| `run_start` | `POST /runs` | Load the root agent from an AgentSpec, start a run |
|
|
19
|
+
| `run_get` | `GET /runs/:runId` | The spawn tree — every agent, state, parent pointers |
|
|
20
|
+
| `run_stop` | `DELETE /runs/:runId` | Abort + close every live agent in the run |
|
|
21
|
+
| `run_watch` | `GET /runs/:runId/events` (SSE) | Collect lifecycle + harness events for a bounded window |
|
|
22
|
+
| `agent_spawn` | `POST /runs/:runId/agents` | Fork a child under a live parent |
|
|
23
|
+
| `agent_get` | `GET /agents/:agentId` | Inspect an agent + session stats |
|
|
24
|
+
| `agent_prompt` | `POST /agents/:agentId/prompt` | Drive one turn |
|
|
25
|
+
| `agent_steer` | `POST /agents/:agentId/steer` | Redirect the current turn |
|
|
26
|
+
| `agent_pause` | `POST /agents/:agentId/pause` | Freeze the sandbox container |
|
|
27
|
+
| `agent_resume` | `POST /agents/:agentId/resume` | Thaw a paused container |
|
|
28
|
+
| `agent_stop` | `POST /agents/:agentId/stop` | Abort + close one agent |
|
|
29
|
+
| `result_get` | `GET /agents/:agentId/result` | Resolve a settled agent's output (optional long-poll) |
|
|
30
30
|
|
|
31
31
|
**alineo — local bootstrap + spec management** (no alineod required for these):
|
|
32
32
|
|
|
33
|
-
| Tool
|
|
34
|
-
|
|
|
35
|
-
| `
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
33
|
+
| Tool | |
|
|
34
|
+
| ------------- | ------------------------------------------------------------ |
|
|
35
|
+
| `init` | Start OpenSandbox + alineod locally via Docker |
|
|
36
|
+
| `spec_add` | Fetch an AgentSpec (URL or local file), validate it, save it |
|
|
37
|
+
| `spec_list` | List saved agent specs |
|
|
38
|
+
| `spec_remove` | Remove a saved agent spec |
|
|
39
39
|
|
|
40
|
-
This mirrors
|
|
40
|
+
This mirrors alineod's core swarm-control routes and every `alineo-cli` subcommand except `telemetry`
|
|
41
41
|
(local opt-in/out toggle, not an orchestration feature) and the CLI's direct-sandbox commands
|
|
42
|
-
(`
|
|
43
|
-
`Alineo.
|
|
42
|
+
(`start`/`prompt`/`spawn`/`agents`/`stop`/`logs`) — those drive a sandbox from _this_ process via
|
|
43
|
+
`Alineo.start()`; alineod's routes are the equivalent, network-addressable operations for a
|
|
44
44
|
swarm run through the daemon, which is what an MCP client actually talks to.
|
|
45
45
|
|
|
46
|
+
Not exposed as tools yet: `scope: "subtree"` on pause/resume/stop/steer, `GET
|
|
47
|
+
/agents/:id/transcript`, and the coordination routes (`await`, `notify-on`, inbox) that alineod
|
|
48
|
+
gained after this server was written. They are available over alineod's HTTP API.
|
|
49
|
+
|
|
46
50
|
## Install
|
|
47
51
|
|
|
48
|
-
|
|
52
|
+
Nothing to install — an MCP client launches it on demand with `npx -y alineo-mcp` (or
|
|
53
|
+
`bunx alineo-mcp`), which fetches the published package from npm. The client configs below use
|
|
54
|
+
that form.
|
|
55
|
+
|
|
56
|
+
To run an unreleased change instead, build it locally from the repo and point the client at the
|
|
57
|
+
build (see "A local build" below):
|
|
49
58
|
|
|
50
59
|
```bash
|
|
51
60
|
git clone https://github.com/DrejT/alineo.git && cd alineo
|
|
52
61
|
bun install && bun run --cwd packages/mcp build # → packages/mcp/dist/index.mjs
|
|
53
62
|
```
|
|
54
63
|
|
|
55
|
-
Once published, `npx -y alineo-mcp` (or `bunx alineo-mcp`) will fetch and run it with no local
|
|
56
|
-
checkout needed — the client configs below assume that form; swap in
|
|
57
|
-
`bun /absolute/path/to/alineo/packages/mcp/dist/index.mjs` for a local build.
|
|
58
|
-
|
|
59
64
|
## Configure a client
|
|
60
65
|
|
|
61
66
|
Every MCP client uses the same JSON shape — an entry under `mcpServers` naming the command to
|
|
@@ -83,7 +88,7 @@ launch and (optionally) environment variables to set. Where that JSON lives diff
|
|
|
83
88
|
```
|
|
84
89
|
|
|
85
90
|
`env` is optional — omit it to use the default `http://127.0.0.1:4600`, which is what
|
|
86
|
-
`
|
|
91
|
+
`init` (see below) starts alineod on.
|
|
87
92
|
|
|
88
93
|
**Claude Code CLI**, no file editing needed:
|
|
89
94
|
|
|
@@ -95,7 +100,7 @@ claude mcp add alineo --scope project -- npx -y alineo-mcp
|
|
|
95
100
|
claude mcp add alineo --env ALINEOD_URL=http://127.0.0.1:4600 -- npx -y alineo-mcp
|
|
96
101
|
```
|
|
97
102
|
|
|
98
|
-
**A local build
|
|
103
|
+
**A local build**, in any of the configs above:
|
|
99
104
|
|
|
100
105
|
```json
|
|
101
106
|
{
|
|
@@ -115,12 +120,12 @@ recipe using `@modelcontextprotocol/client`'s `StdioClientTransport`.
|
|
|
115
120
|
|
|
116
121
|
## Configuration reference
|
|
117
122
|
|
|
118
|
-
| Setting | Where
|
|
119
|
-
| ---------------------- |
|
|
120
|
-
| `ALINEOD_URL` | env var on the `alineo-mcp` process
|
|
121
|
-
| `alineo.config.json` | project-local file, or `~/.config/alineo/config.json` global fallback (same resolution as `alineo-cli`)
|
|
122
|
-
| Docker | must be installed and running
|
|
123
|
-
| Model provider API key | in the _caller's_ shell when running `
|
|
123
|
+
| Setting | Where | Default | Affects |
|
|
124
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------- |
|
|
125
|
+
| `ALINEOD_URL` | env var on the `alineo-mcp` process | `http://127.0.0.1:4600` | Every `run_*`/`agent_*`/`result_*` tool |
|
|
126
|
+
| `alineo.config.json` | project-local file, or `~/.config/alineo/config.json` global fallback (same resolution as `alineo-cli`) | written by `init` | `agentsDir` for `spec_add` / `list_specs` / `remove_spec` |
|
|
127
|
+
| Docker | must be installed and running | — | `init` only |
|
|
128
|
+
| Model provider API key | in the _caller's_ shell when running `init` (forwarded into the alineod container) — see the list in `@alineo-labs/cli-shared`'s `pi-model-keys.ts` | none | Whether spawned agents can actually call a model |
|
|
124
129
|
|
|
125
130
|
`alineo.config.json`'s `agentsDir` is shared with `alineo-cli` — specs added via either tool show
|
|
126
131
|
up in both, since they resolve the same config file and directory.
|
|
@@ -128,21 +133,21 @@ up in both, since they resolve the same config file and directory.
|
|
|
128
133
|
## Use
|
|
129
134
|
|
|
130
135
|
```bash
|
|
131
|
-
|
|
136
|
+
init # once, if alineod isn't already running (needs Docker)
|
|
132
137
|
```
|
|
133
138
|
|
|
134
139
|
Typical flow, as a client would call the tools:
|
|
135
140
|
|
|
136
|
-
1. `
|
|
137
|
-
2. `
|
|
138
|
-
3. `
|
|
141
|
+
1. `spec_add` (or `spec_list` if you've already added one) → get an AgentSpec.
|
|
142
|
+
2. `run_start` with that spec → get back a `runId` + `rootAgentId`.
|
|
143
|
+
3. `agent_spawn` with `parentAgentId: rootAgentId` to fan out children — repeat per
|
|
139
144
|
worker; pass `waitFor` on a later spawn to hold it until earlier agents settle.
|
|
140
|
-
4. `
|
|
141
|
-
`
|
|
142
|
-
5. `
|
|
143
|
-
6. `
|
|
145
|
+
4. `agent_prompt` / `agent_steer` to drive them; `agent_pause` /
|
|
146
|
+
`agent_resume` to freeze/thaw without losing state.
|
|
147
|
+
5. `run_watch` (poll as needed) or `run_get` to observe progress.
|
|
148
|
+
6. `result_get` (optionally with `waitSeconds` to long-poll) to read each settled
|
|
144
149
|
agent's output.
|
|
145
|
-
7. `
|
|
150
|
+
7. `agent_stop` per agent and/or `run_stop` to tear the whole run down.
|
|
146
151
|
|
|
147
152
|
See [`cookbooks/mcp-agent-swarm`](../../cookbooks/mcp-agent-swarm) for this flow as a complete,
|
|
148
153
|
runnable script — a lead agent forks two reviewers, one gets paused/resumed and the other
|
|
@@ -151,14 +156,14 @@ MCP tools instead of raw HTTP.
|
|
|
151
156
|
|
|
152
157
|
## Troubleshooting
|
|
153
158
|
|
|
154
|
-
| Symptom
|
|
155
|
-
|
|
|
156
|
-
| Every `
|
|
157
|
-
| `alineod error (404): no run ...` / `no agent ...`
|
|
158
|
-
| `alineod error (409): agent ... is not live`
|
|
159
|
-
| `
|
|
160
|
-
| A spawned agent never produces a result
|
|
161
|
-
| Raw `@alineo-labs/sandbox` SDK code on the host can't follow a sandbox's proxy URL, even though `
|
|
159
|
+
| Symptom | Cause | Fix |
|
|
160
|
+
| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
161
|
+
| Every `run_*`/`agent_*`/`result_*` call returns `alineod error (network): Could not reach alineod...` | alineod isn't running, or `ALINEOD_URL` points at the wrong address | Run `init` (needs Docker), or check what's actually listening on the configured URL |
|
|
162
|
+
| `alineod error (404): no run ...` / `no agent ...` | Wrong ID, or the run/agent was already deleted/stopped | Re-check the ID from the tool result that created it; `run_get` lists current agents |
|
|
163
|
+
| `alineod error (409): agent ... is not live` | The agent's sandbox already ended | Check `agent_get`'s `state`/`outcome` before prompting again |
|
|
164
|
+
| `init` fails at "Checking Docker..." | Docker isn't installed or the daemon isn't running | Start Docker Desktop (or your Docker daemon) and retry |
|
|
165
|
+
| A spawned agent never produces a result | No model provider key was forwarded to alineod | Set the relevant key (e.g. `NVIDIA_API_KEY`) in the shell _before_ running `init`, or add it to the running alineod container's env directly |
|
|
166
|
+
| Raw `@alineo-labs/sandbox` SDK code on the host can't follow a sandbox's proxy URL, even though `init` succeeded | Windows/Mac: alineod reaches OpenSandbox via `host.docker.internal`, which the host itself can't reliably resolve back to itself — see `packages/cli/src/commands/init.ts`'s doc comment | Use the `run_*`/`agent_*` tools instead of the raw SDK against this same OpenSandbox instance, or run OpenSandbox via `uvx opensandbox-server` for direct host-based SDK access |
|
|
162
167
|
|
|
163
168
|
## Local development
|
|
164
169
|
|
|
@@ -180,12 +185,12 @@ see `test/server.test.ts`.
|
|
|
180
185
|
channel, so nothing in this package may `console.log` — diagnostics go to `console.error`.
|
|
181
186
|
- **Thin HTTP client, not the `alineo` SDK.** `src/alineod-client.ts` talks to alineod purely
|
|
182
187
|
over its documented wire contract (`apps/alineod/src/schema.ts`,
|
|
183
|
-
`
|
|
188
|
+
`apps/alineod/spec/openapi.json`), the same way any external MCP client would — alineod is
|
|
184
189
|
"standalone by design" (its own README), and this package doesn't reach into its internals.
|
|
185
190
|
- **Every tool handler is error-safe.** A thrown error (alineod unreachable, a 404, invalid
|
|
186
191
|
input) becomes an `isError` tool result, never an uncaught rejection that could take the
|
|
187
192
|
server down mid-session.
|
|
188
|
-
- **`
|
|
193
|
+
- **`run_watch` is poll-and-collect, not a live stream.** An MCP tool call is
|
|
189
194
|
request/response; the tool collects SSE events for a bounded window (default 20s, capped at
|
|
190
195
|
120s) and returns them, honoring `Last-Event-ID` via `sinceEventId` so repeated calls don't
|
|
191
196
|
miss anything persisted.
|
package/dist/index.mjs
CHANGED
|
@@ -6,18 +6,32 @@ import { join } from "path";
|
|
|
6
6
|
import { homedir } from "os";
|
|
7
7
|
import { existsSync, readdirSync } from "fs";
|
|
8
8
|
import { mkdir, unlink } from "fs/promises";
|
|
9
|
+
import { existsSync as existsSync$1, readFileSync } from "node:fs";
|
|
10
|
+
import { homedir as homedir$1 } from "node:os";
|
|
11
|
+
import { dirname, join as join$1, resolve } from "node:path";
|
|
12
|
+
import { ProjectConfigSchema } from "@alineo-labs/schema";
|
|
9
13
|
import { validateAgentSpec } from "alineo";
|
|
14
|
+
//#region package.json
|
|
15
|
+
var version = "0.3.0";
|
|
16
|
+
//#endregion
|
|
10
17
|
//#region src/alineod-client.ts
|
|
11
18
|
/**
|
|
12
|
-
* Thin HTTP + SSE client for alineod's wire contract
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
19
|
+
* Thin HTTP + SSE client for alineod's wire contract. Still typed against the contract rather
|
|
20
|
+
* than against the daemon's internals — alineod is "standalone by design" (its own README) and
|
|
21
|
+
* this package talks to it the way any external MCP client would, over HTTP. The difference is
|
|
22
|
+
* that the contract is now a published package (`@alineo-labs/schema/alineod`) instead of an
|
|
23
|
+
* app's source file, so honouring that boundary no longer costs a second copy of every shape.
|
|
24
|
+
*
|
|
25
|
+
* `spec` fields below stay `Record<string, unknown>`, not `AgentSpec` — an MCP tool receives
|
|
26
|
+
* arbitrary unvalidated JSON from a model, and typing it as an `AgentSpec` would claim a
|
|
27
|
+
* guarantee this side of the wire cannot make. alineod validates it for real now (its wire
|
|
28
|
+
* schema is `@alineo-labs/schema`'s `AgentSpecSchema`, no longer an opaque record), so an
|
|
29
|
+
* invalid spec comes back as a 400 naming the bad field rather than failing later inside
|
|
30
|
+
* `Alineo.start()`.
|
|
16
31
|
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
* (
|
|
20
|
-
* the same way: opaque here, validated server-side by the SDK's own `Alineo.load()`/`.spawn()`.
|
|
32
|
+
* The interfaces below still mirror alineod's wire contract by hand. Now that the contract
|
|
33
|
+
* itself is a published package, pointing them at it would delete that duplication — the
|
|
34
|
+
* original reason not to (alineod's schemas being internal) no longer holds.
|
|
21
35
|
*/
|
|
22
36
|
var AlineodError = class extends Error {
|
|
23
37
|
status;
|
|
@@ -44,7 +58,7 @@ var AlineodClient = class {
|
|
|
44
58
|
body: body !== void 0 ? JSON.stringify(body) : void 0
|
|
45
59
|
});
|
|
46
60
|
} catch (err) {
|
|
47
|
-
throw new AlineodError(0, `Could not reach alineod at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}. Is it running? Try the
|
|
61
|
+
throw new AlineodError(0, `Could not reach alineod at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}. Is it running? Try the init tool, or set ALINEOD_URL.`);
|
|
48
62
|
}
|
|
49
63
|
if (res.status === 204) return void 0;
|
|
50
64
|
const text = await res.text();
|
|
@@ -169,6 +183,226 @@ function parseSseFrame(frame) {
|
|
|
169
183
|
};
|
|
170
184
|
}
|
|
171
185
|
//#endregion
|
|
186
|
+
//#region ../config-shared/dist/index.mjs
|
|
187
|
+
/** The file name every alineo project config uses. */
|
|
188
|
+
const PROJECT_CONFIG_FILE = "alineo.config.json";
|
|
189
|
+
/**
|
|
190
|
+
* Walk up from `startDir` looking for `alineo.config.json`.
|
|
191
|
+
*
|
|
192
|
+
* Before this existed, `packages/agent` only ever checked `process.cwd()`, so running a script
|
|
193
|
+
* from a subdirectory silently fell back to built-in defaults — a wrong `serverUrl` looked
|
|
194
|
+
* exactly like no config at all.
|
|
195
|
+
*
|
|
196
|
+
* The walk is **bounded**, which matters as much as the walk itself: an unbounded search would
|
|
197
|
+
* let an unrelated `alineo.config.json` several levels up configure a run. It stops after
|
|
198
|
+
* examining:
|
|
199
|
+
*
|
|
200
|
+
* - a directory containing `.git` (the project boundary),
|
|
201
|
+
* - the user's home directory (global config is a separate, explicit source), or
|
|
202
|
+
* - the filesystem root.
|
|
203
|
+
*
|
|
204
|
+
* The stop directory is itself checked before the walk ends, so a config file sitting next to
|
|
205
|
+
* `.git` is still found.
|
|
206
|
+
*/
|
|
207
|
+
function findProjectConfig(startDir = process.cwd()) {
|
|
208
|
+
const home = resolve(homedir$1());
|
|
209
|
+
let dir = resolve(startDir);
|
|
210
|
+
for (;;) {
|
|
211
|
+
const candidate = join$1(dir, PROJECT_CONFIG_FILE);
|
|
212
|
+
if (existsSync$1(candidate)) return candidate;
|
|
213
|
+
if (existsSync$1(join$1(dir, ".git"))) return null;
|
|
214
|
+
if (dir === home) return null;
|
|
215
|
+
const parent = dirname(dir);
|
|
216
|
+
if (parent === dir) return null;
|
|
217
|
+
dir = parent;
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
/** Absolute path of the user-level config, `~/.config/alineo/config.json`. */
|
|
221
|
+
function globalConfigPath$1() {
|
|
222
|
+
return join$1(homedir$1(), ".config", "alineo", "config.json");
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Read and JSON-parse a config file, or return `null` when it isn't there.
|
|
226
|
+
* A file that exists but is malformed throws — a typo in config should be loud, not silently
|
|
227
|
+
* ignored in favour of defaults.
|
|
228
|
+
*/
|
|
229
|
+
function readJsonFile(path) {
|
|
230
|
+
if (!existsSync$1(path)) return null;
|
|
231
|
+
const raw = readFileSync(path, "utf8");
|
|
232
|
+
try {
|
|
233
|
+
return JSON.parse(raw);
|
|
234
|
+
} catch (err) {
|
|
235
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
236
|
+
throw new Error(`${path} is not valid JSON: ${message}`);
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
function isPlainObject(value) {
|
|
240
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
|
|
241
|
+
const proto = Object.getPrototypeOf(value);
|
|
242
|
+
return proto === Object.prototype || proto === null;
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
245
|
+
* Merge config sources, lowest precedence first. Plain objects merge key by key; everything
|
|
246
|
+
* else (arrays, strings, numbers) is replaced wholesale by the later source.
|
|
247
|
+
*
|
|
248
|
+
* `undefined` never overwrites — an absent key in a higher-precedence source leaves the lower
|
|
249
|
+
* one intact, which is what makes "env var not set" mean "don't override" rather than "clear".
|
|
250
|
+
* An explicit `null` *does* overwrite, so a config file can blank a value on purpose.
|
|
251
|
+
*/
|
|
252
|
+
function mergeDeep(...sources) {
|
|
253
|
+
let result = void 0;
|
|
254
|
+
for (const source of sources) {
|
|
255
|
+
if (source === void 0) continue;
|
|
256
|
+
if (isPlainObject(source) && isPlainObject(result)) {
|
|
257
|
+
const merged = { ...result };
|
|
258
|
+
for (const [key, value] of Object.entries(source)) {
|
|
259
|
+
if (value === void 0) continue;
|
|
260
|
+
merged[key] = key in merged ? mergeDeep(merged[key], value) : value;
|
|
261
|
+
}
|
|
262
|
+
result = merged;
|
|
263
|
+
} else result = source;
|
|
264
|
+
}
|
|
265
|
+
return result;
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* Freeze an object and everything reachable from it, so a resolved config can't be mutated
|
|
269
|
+
* after validation. Cycles are impossible in JSON-derived data, so no seen-set is needed.
|
|
270
|
+
*/
|
|
271
|
+
function deepFreeze(value) {
|
|
272
|
+
if (value === null || typeof value !== "object") return value;
|
|
273
|
+
if (Object.isFrozen(value)) return value;
|
|
274
|
+
Object.freeze(value);
|
|
275
|
+
for (const key of Object.getOwnPropertyNames(value)) deepFreeze(value[key]);
|
|
276
|
+
return value;
|
|
277
|
+
}
|
|
278
|
+
/** Env var holding a whole config document inline, as JSON. */
|
|
279
|
+
const CONFIG_CONTENT_ENV = "ALINEO_CONFIG_CONTENT";
|
|
280
|
+
/**
|
|
281
|
+
* Resolve configuration from every source, lowest precedence first:
|
|
282
|
+
*
|
|
283
|
+
* ```
|
|
284
|
+
* schema defaults
|
|
285
|
+
* < ~/.config/alineo/config.json (user)
|
|
286
|
+
* < alineo.config.json (project — found by bounded walk-up)
|
|
287
|
+
* < ALINEO_CONFIG_CONTENT (inline JSON)
|
|
288
|
+
* < ALINEO_* env vars (ops)
|
|
289
|
+
* < overrides (flags / explicit call-site object)
|
|
290
|
+
* ```
|
|
291
|
+
*
|
|
292
|
+
* Validated once, then deep-frozen. **This function is pure with respect to module state** —
|
|
293
|
+
* nothing is cached here and there is no installed singleton, so two bundled copies of this
|
|
294
|
+
* package cannot drift apart. Callers hold the result for as long as they need it.
|
|
295
|
+
*/
|
|
296
|
+
function loadConfigWithSources(options) {
|
|
297
|
+
const { schema, cwd = process.cwd(), env = process.env, fromEnv, overrides, globalPath = globalConfigPath$1(), discover = true, label = "config" } = options;
|
|
298
|
+
const sources = {
|
|
299
|
+
globalFile: null,
|
|
300
|
+
projectFile: null,
|
|
301
|
+
inlineEnv: false,
|
|
302
|
+
envVars: false,
|
|
303
|
+
overrides: overrides !== void 0
|
|
304
|
+
};
|
|
305
|
+
const layers = [];
|
|
306
|
+
if (discover) {
|
|
307
|
+
if (globalPath) {
|
|
308
|
+
const globalData = readJsonFile(globalPath);
|
|
309
|
+
if (globalData !== null) {
|
|
310
|
+
layers.push(globalData);
|
|
311
|
+
sources.globalFile = globalPath;
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
const projectFile = findProjectConfig(cwd);
|
|
315
|
+
if (projectFile) {
|
|
316
|
+
const projectData = readJsonFile(projectFile);
|
|
317
|
+
if (projectData !== null) {
|
|
318
|
+
layers.push(projectData);
|
|
319
|
+
sources.projectFile = projectFile;
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
const inline = env[CONFIG_CONTENT_ENV];
|
|
323
|
+
if (inline !== void 0 && inline.trim() !== "") {
|
|
324
|
+
try {
|
|
325
|
+
layers.push(JSON.parse(inline));
|
|
326
|
+
} catch (err) {
|
|
327
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
328
|
+
throw new Error(`${CONFIG_CONTENT_ENV} is not valid JSON: ${message}`);
|
|
329
|
+
}
|
|
330
|
+
sources.inlineEnv = true;
|
|
331
|
+
}
|
|
332
|
+
if (fromEnv) {
|
|
333
|
+
const fromEnvData = fromEnv(env);
|
|
334
|
+
if (fromEnvData !== void 0) {
|
|
335
|
+
layers.push(fromEnvData);
|
|
336
|
+
sources.envVars = true;
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
if (overrides !== void 0) layers.push(overrides);
|
|
341
|
+
const merged = layers.length > 0 ? mergeDeep(...layers) : {};
|
|
342
|
+
const parsed = schema.safeParse(merged ?? {});
|
|
343
|
+
if (!parsed.success) {
|
|
344
|
+
const details = parsed.error.issues.map((issue) => {
|
|
345
|
+
return ` ${issue.path.length > 0 ? issue.path.join(".") : "(root)"}: ${issue.message}`;
|
|
346
|
+
}).join("\n");
|
|
347
|
+
const from = describeSources(sources);
|
|
348
|
+
throw new Error(`Invalid ${label}${from}:\n${details}`);
|
|
349
|
+
}
|
|
350
|
+
return {
|
|
351
|
+
config: deepFreeze(parsed.data),
|
|
352
|
+
sources
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
/** `loadConfigWithSources` without the provenance — the common case. */
|
|
356
|
+
function loadConfig(options) {
|
|
357
|
+
return loadConfigWithSources(options).config;
|
|
358
|
+
}
|
|
359
|
+
function describeSources(sources) {
|
|
360
|
+
const parts = [];
|
|
361
|
+
if (sources.globalFile) parts.push(sources.globalFile);
|
|
362
|
+
if (sources.projectFile) parts.push(sources.projectFile);
|
|
363
|
+
if (sources.inlineEnv) parts.push(CONFIG_CONTENT_ENV);
|
|
364
|
+
if (sources.envVars) parts.push("environment");
|
|
365
|
+
if (sources.overrides) parts.push("explicit options");
|
|
366
|
+
return parts.length > 0 ? ` (from ${parts.join(", ")})` : "";
|
|
367
|
+
}
|
|
368
|
+
function parseBoolean(raw, name) {
|
|
369
|
+
const value = raw.trim().toLowerCase();
|
|
370
|
+
if ([
|
|
371
|
+
"true",
|
|
372
|
+
"1",
|
|
373
|
+
"yes",
|
|
374
|
+
"on"
|
|
375
|
+
].includes(value)) return true;
|
|
376
|
+
if ([
|
|
377
|
+
"false",
|
|
378
|
+
"0",
|
|
379
|
+
"no",
|
|
380
|
+
"off"
|
|
381
|
+
].includes(value)) return false;
|
|
382
|
+
throw new Error(`${name}=${JSON.stringify(raw)} is not a boolean (use true or false)`);
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* Project-config fields settable from the environment. These are what
|
|
386
|
+
* `apps/alineod/docker-entrypoint.sh` writes into a generated config file before starting the
|
|
387
|
+
* server; reading them directly means the container no longer has to write a file at all.
|
|
388
|
+
*/
|
|
389
|
+
function projectConfigFromEnv(env) {
|
|
390
|
+
const out = {};
|
|
391
|
+
if (env.ALINEO_SERVER_URL !== void 0) out.serverUrl = env.ALINEO_SERVER_URL;
|
|
392
|
+
if (env.ALINEO_API_KEY !== void 0) out.apiKey = env.ALINEO_API_KEY;
|
|
393
|
+
if (env.ALINEO_USE_SERVER_PROXY !== void 0) out.useServerProxy = parseBoolean(env.ALINEO_USE_SERVER_PROXY, "ALINEO_USE_SERVER_PROXY");
|
|
394
|
+
return Object.keys(out).length > 0 ? out : void 0;
|
|
395
|
+
}
|
|
396
|
+
/** Resolve `alineo.config.json` from every source. Validated once, then frozen. */
|
|
397
|
+
function loadProjectConfig(options = {}) {
|
|
398
|
+
return loadConfig({
|
|
399
|
+
schema: ProjectConfigSchema,
|
|
400
|
+
fromEnv: projectConfigFromEnv,
|
|
401
|
+
label: "alineo config",
|
|
402
|
+
...options
|
|
403
|
+
});
|
|
404
|
+
}
|
|
405
|
+
//#endregion
|
|
172
406
|
//#region ../cli-shared/dist/index.mjs
|
|
173
407
|
async function spawn(cmd) {
|
|
174
408
|
let proc;
|
|
@@ -236,6 +470,20 @@ async function removeContainer(name) {
|
|
|
236
470
|
]);
|
|
237
471
|
if (!ok) throw new Error(`Failed to remove container '${name}': ${stderr.trim()}`);
|
|
238
472
|
}
|
|
473
|
+
/**
|
|
474
|
+
* Set a container's restart policy in place (`docker update`, no recreate). Used so containers
|
|
475
|
+
* created before `init` started passing `--restart` still come back after a reboot.
|
|
476
|
+
*/
|
|
477
|
+
async function setRestartPolicy(name, policy) {
|
|
478
|
+
const { ok, stderr } = await spawn([
|
|
479
|
+
"docker",
|
|
480
|
+
"update",
|
|
481
|
+
"--restart",
|
|
482
|
+
policy,
|
|
483
|
+
name
|
|
484
|
+
]);
|
|
485
|
+
if (!ok) throw new Error(`Failed to set restart policy on '${name}': ${stderr.trim()}`);
|
|
486
|
+
}
|
|
239
487
|
async function runContainer(args, label = "container") {
|
|
240
488
|
const { ok, stderr } = await spawn([
|
|
241
489
|
"docker",
|
|
@@ -280,53 +528,42 @@ async function isReachable(url, isHealthy, timeoutMs = 1e4) {
|
|
|
280
528
|
}
|
|
281
529
|
}
|
|
282
530
|
const CONFIG_DIR = ".alineo";
|
|
283
|
-
const CONFIG_FILE = "alineo.config.json";
|
|
284
531
|
function configPath() {
|
|
285
|
-
return
|
|
532
|
+
return PROJECT_CONFIG_FILE;
|
|
286
533
|
}
|
|
287
534
|
function globalConfigPath() {
|
|
288
535
|
return join(serverConfigDir(), "config.json");
|
|
289
536
|
}
|
|
290
|
-
function fillDefaults(data) {
|
|
291
|
-
return {
|
|
292
|
-
serverUrl: data.serverUrl ?? "http://127.0.0.1:8080",
|
|
293
|
-
useServerProxy: data.useServerProxy ?? true,
|
|
294
|
-
apiKey: data.apiKey ?? "",
|
|
295
|
-
adapterPath: data.adapterPath ?? "./.alineo/ledger.db",
|
|
296
|
-
agentsDir: data.agentsDir ?? "./agents",
|
|
297
|
-
defaults: { resources: {
|
|
298
|
-
cpu: data.defaults?.resources?.cpu ?? "1000m",
|
|
299
|
-
memory: data.defaults?.resources?.memory ?? "1Gi"
|
|
300
|
-
} }
|
|
301
|
-
};
|
|
302
|
-
}
|
|
303
537
|
/**
|
|
304
|
-
*
|
|
305
|
-
*
|
|
306
|
-
* `~/.config/alineo/config.json
|
|
307
|
-
*
|
|
538
|
+
* Resolve the CLI's configuration.
|
|
539
|
+
*
|
|
540
|
+
* Sources are merged lowest-first — `~/.config/alineo/config.json`, then the nearest
|
|
541
|
+
* `alineo.config.json` (found by walking up from the working directory), then `ALINEO_*`
|
|
542
|
+
* environment variables. Two things changed when this moved onto `@alineo-labs/config-shared`:
|
|
543
|
+
* a project config is now found from a subdirectory rather than only from the exact working
|
|
544
|
+
* directory, and a global config no longer disappears entirely just because a project config
|
|
545
|
+
* exists — the project file overrides key by key.
|
|
546
|
+
*
|
|
547
|
+
* When neither file exists, the global one is bootstrapped so a fresh `bunx alineo-cli` works
|
|
548
|
+
* without an `init` in every directory.
|
|
308
549
|
*/
|
|
309
550
|
async function readConfig() {
|
|
310
|
-
const
|
|
311
|
-
if (await localFile.exists()) return fillDefaults(await localFile.json());
|
|
551
|
+
const hasProject = findProjectConfig() !== null;
|
|
312
552
|
const globalPath = globalConfigPath();
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
};
|
|
328
|
-
await Bun.write(globalPath, JSON.stringify(config, null, 2) + "\n");
|
|
329
|
-
return config;
|
|
553
|
+
if (!hasProject && !existsSync(globalPath)) {
|
|
554
|
+
const dir = serverConfigDir();
|
|
555
|
+
if (!existsSync(dir)) await mkdir(dir, { recursive: true });
|
|
556
|
+
const bootstrapped = loadProjectConfig({
|
|
557
|
+
discover: false,
|
|
558
|
+
overrides: {
|
|
559
|
+
adapterPath: join(dir, "ledger.db"),
|
|
560
|
+
agentsDir: join(dir, "agents")
|
|
561
|
+
}
|
|
562
|
+
});
|
|
563
|
+
await Bun.write(globalPath, JSON.stringify(bootstrapped, null, 2) + "\n");
|
|
564
|
+
return bootstrapped;
|
|
565
|
+
}
|
|
566
|
+
return loadProjectConfig({ globalPath });
|
|
330
567
|
}
|
|
331
568
|
async function writeConfig(config) {
|
|
332
569
|
if (!existsSync(CONFIG_DIR)) await mkdir(CONFIG_DIR, { recursive: true });
|
|
@@ -346,7 +583,7 @@ function serverConfigPath() {
|
|
|
346
583
|
* only as good as where the db file actually lives: without this mount, it sits in the
|
|
347
584
|
* `alineo-opensandbox` container's own writable layer, so restart is fine but any time the
|
|
348
585
|
* container itself is recreated (host reboot with no restart policy, `docker system prune`,
|
|
349
|
-
* a stray `docker rm`) silently loses every cached snapshot record — every `Alineo.
|
|
586
|
+
* a stray `docker rm`) silently loses every cached snapshot record — every `Alineo.start()`
|
|
350
587
|
* snapshot fast path pays a full cold rebuild next time, indistinguishable from a genuinely
|
|
351
588
|
* changed spec (see issue #20). Bind-mounting this directory makes that data outlive the
|
|
352
589
|
* container's own lifecycle, matching OpenSandbox's own intent.
|
|
@@ -363,6 +600,26 @@ function serverDataDir() {
|
|
|
363
600
|
* message itself suggests does not exist as a published tag. v1.0.22 is the latest.
|
|
364
601
|
*/
|
|
365
602
|
/**
|
|
603
|
+
* Where the OpenSandbox server, running in its own container, reaches the ports it publishes on
|
|
604
|
+
* the host (`[docker].host_ip`). Without it the server falls back to `127.0.0.1` — its own
|
|
605
|
+
* loopback — so the readiness probe for an egress sidecar gets "connection refused" from a
|
|
606
|
+
* sidecar that is healthy, and every sandbox with a `networkPolicy` fails to start
|
|
607
|
+
* ("Egress sidecar did not become ready within 30s"). `init` adds
|
|
608
|
+
* `--add-host host.docker.internal:host-gateway` to the container so the name resolves on native
|
|
609
|
+
* Linux Docker as well as Docker Desktop.
|
|
610
|
+
*/
|
|
611
|
+
const DOCKER_HOST_IP = "host.docker.internal";
|
|
612
|
+
/**
|
|
613
|
+
* Adds `host_ip` to an existing `server.toml` that has none, leaving everything else (including
|
|
614
|
+
* hand edits) alone. Returns `null` when nothing needs to change: a `host_ip` is already set, or
|
|
615
|
+
* there is no `[docker]` table to put it in.
|
|
616
|
+
*/
|
|
617
|
+
function withDockerHostIp(toml) {
|
|
618
|
+
if (/^host_ip\s*=/m.test(toml)) return null;
|
|
619
|
+
if (!/^\[docker\]/m.test(toml)) return null;
|
|
620
|
+
return toml.replace(/^\[docker\][^\n]*\n/m, (header) => `${header}host_ip = "${DOCKER_HOST_IP}"\n`);
|
|
621
|
+
}
|
|
622
|
+
/**
|
|
366
623
|
* `egress.image`/`egress.mode` are configured unconditionally, not opt-in. Per OpenSandbox's
|
|
367
624
|
* own control flow, a configured `egress.image` is inert for any sandbox created without a
|
|
368
625
|
* `networkPolicy` — no sidecar is attached, no behavior changes for anyone not touching
|
|
@@ -384,6 +641,7 @@ execd_image = "opensandbox/execd:v1.0.22"
|
|
|
384
641
|
|
|
385
642
|
[docker]
|
|
386
643
|
network_mode = "bridge"
|
|
644
|
+
host_ip = "${DOCKER_HOST_IP}"
|
|
387
645
|
|
|
388
646
|
[store]
|
|
389
647
|
type = "sqlite"
|
|
@@ -399,7 +657,7 @@ mode = "dns+nft"
|
|
|
399
657
|
* `envMap` in earendil-works/pi's `packages/ai/src/env-api-keys.ts` (plus Anthropic's three,
|
|
400
658
|
* handled separately there). An `AgentSpec`'s env map (`{ NVIDIA_API_KEY: "${NVIDIA_API_KEY}" }`,
|
|
401
659
|
* see `packages/agent/src/schema.ts`) is resolved from `process.env` inside whatever process
|
|
402
|
-
* calls `Alineo.
|
|
660
|
+
* calls `Alineo.start()`/`.spawn()` — for a swarm run through alineod, that's alineod's own
|
|
403
661
|
* container. `alineo init` forwards whichever of these are set in the operator's shell into
|
|
404
662
|
* that container so any Pi-supported model works, not just NVIDIA's free tier.
|
|
405
663
|
*
|
|
@@ -450,7 +708,7 @@ const PI_MODEL_API_KEY_ENV_VARS = [
|
|
|
450
708
|
"COPILOT_GITHUB_TOKEN"
|
|
451
709
|
];
|
|
452
710
|
/**
|
|
453
|
-
* `alineo init` / `
|
|
711
|
+
* `alineo init` / `init` — starts OpenSandbox + alineod locally via Docker and writes
|
|
454
712
|
* `alineo.config.json`. Shared verbatim by `alineo-cli` (`packages/cli/src/commands/init.ts`,
|
|
455
713
|
* which logs to stdout) and `alineo-mcp` (`packages/mcp/src/init.ts`, which collects a log array
|
|
456
714
|
* instead — an MCP stdio server's stdout is the JSON-RPC channel, so tool handlers must never
|
|
@@ -458,6 +716,7 @@ const PI_MODEL_API_KEY_ENV_VARS = [
|
|
|
458
716
|
* hand-copied files did before.
|
|
459
717
|
*/
|
|
460
718
|
const OPENSANDBOX_CONTAINER_NAME = "alineo-opensandbox";
|
|
719
|
+
const OPENSANDBOX_IMAGE = "opensandbox/server:latest";
|
|
461
720
|
const SERVER_URL = "http://127.0.0.1:8080";
|
|
462
721
|
const ALINEOD_CONTAINER_NAME = "alineo-alineod";
|
|
463
722
|
const ALINEOD_IMAGE = "ghcr.io/drejt/alineod:latest";
|
|
@@ -465,6 +724,13 @@ const ALINEOD_URL = "http://127.0.0.1:4600";
|
|
|
465
724
|
const isAlineodHealthy = (body) => body?.ok === true;
|
|
466
725
|
const HOST_DOCKER_INTERNAL_SERVER_URL = "http://host.docker.internal:8080";
|
|
467
726
|
/**
|
|
727
|
+
* Both containers come back after a reboot or a Docker daemon restart. Without this, a host
|
|
728
|
+
* reboot left OpenSandbox down, so nothing worked until someone ran `init` again — and alineod's
|
|
729
|
+
* crash recovery only helps if something restarts alineod. `unless-stopped` rather than
|
|
730
|
+
* `always`, so a deliberate `docker stop` sticks.
|
|
731
|
+
*/
|
|
732
|
+
const RESTART_ARGS = ["--restart", "unless-stopped"];
|
|
733
|
+
/**
|
|
468
734
|
* `--network host` (which makes alineod see `127.0.0.1` exactly as the host does, matching
|
|
469
735
|
* OpenSandbox's configured `eip` — see `ensureAlineod`'s doc comment) only works out of the box
|
|
470
736
|
* on native Linux Docker. Docker Desktop for Windows/Mac ships it behind an opt-in "Enable host
|
|
@@ -483,8 +749,14 @@ async function runInit(log) {
|
|
|
483
749
|
log("Checking Docker...");
|
|
484
750
|
await checkDocker();
|
|
485
751
|
const openSandboxConfigChanged = await ensureServerConfig();
|
|
752
|
+
const hostIpAdded = await ensureServerHostIp();
|
|
486
753
|
await ensureServerDataDir();
|
|
487
|
-
|
|
754
|
+
let state = await getContainerState(OPENSANDBOX_CONTAINER_NAME);
|
|
755
|
+
if (hostIpAdded && state !== "missing") {
|
|
756
|
+
log("OpenSandbox config gained host_ip — recreating the container to match...");
|
|
757
|
+
await removeContainer(OPENSANDBOX_CONTAINER_NAME);
|
|
758
|
+
state = "missing";
|
|
759
|
+
}
|
|
488
760
|
if (state === "running") if (openSandboxConfigChanged) {
|
|
489
761
|
log("OpenSandbox networking config changed — restarting to apply it...");
|
|
490
762
|
await restartContainer(OPENSANDBOX_CONTAINER_NAME);
|
|
@@ -497,13 +769,18 @@ async function runInit(log) {
|
|
|
497
769
|
log("Waiting for OpenSandbox to be ready...");
|
|
498
770
|
await pollHealth(`${SERVER_URL}/health`);
|
|
499
771
|
} else {
|
|
772
|
+
log(`Pulling ${OPENSANDBOX_IMAGE}...`);
|
|
773
|
+
await pullImage(OPENSANDBOX_IMAGE);
|
|
500
774
|
log("Starting OpenSandbox in Docker...");
|
|
501
775
|
await runContainer([
|
|
502
776
|
"-d",
|
|
503
777
|
"--name",
|
|
504
778
|
OPENSANDBOX_CONTAINER_NAME,
|
|
779
|
+
...RESTART_ARGS,
|
|
505
780
|
"-p",
|
|
506
781
|
"8080:8080",
|
|
782
|
+
"--add-host",
|
|
783
|
+
"host.docker.internal:host-gateway",
|
|
507
784
|
"-v",
|
|
508
785
|
"/var/run/docker.sock:/var/run/docker.sock",
|
|
509
786
|
"-v",
|
|
@@ -514,12 +791,14 @@ async function runInit(log) {
|
|
|
514
791
|
"SANDBOX_CONFIG_PATH=/etc/opensandbox/config.toml",
|
|
515
792
|
"-e",
|
|
516
793
|
"OPENSANDBOX_INSECURE_SERVER=YES",
|
|
517
|
-
|
|
794
|
+
OPENSANDBOX_IMAGE
|
|
518
795
|
], "OpenSandbox container");
|
|
519
796
|
log("Waiting for OpenSandbox to be ready...");
|
|
520
797
|
await pollHealth(`${SERVER_URL}/health`);
|
|
521
798
|
}
|
|
522
799
|
await ensureAlineod(log, openSandboxConfigChanged);
|
|
800
|
+
await setRestartPolicy(OPENSANDBOX_CONTAINER_NAME, "unless-stopped");
|
|
801
|
+
await setRestartPolicy(ALINEOD_CONTAINER_NAME, "unless-stopped");
|
|
523
802
|
await ensureProjectConfig(log);
|
|
524
803
|
log(`OpenSandbox running at ${SERVER_URL}, alineod running at ${ALINEOD_URL} — ready.`);
|
|
525
804
|
return {
|
|
@@ -602,6 +881,7 @@ function startAlineodContainer(useHostNetworking, modelKeyArgs) {
|
|
|
602
881
|
"-d",
|
|
603
882
|
"--name",
|
|
604
883
|
ALINEOD_CONTAINER_NAME,
|
|
884
|
+
...RESTART_ARGS,
|
|
605
885
|
...networkArgs,
|
|
606
886
|
"-e",
|
|
607
887
|
`ALINEO_SERVER_URL=${alineodServerUrl}`,
|
|
@@ -642,6 +922,17 @@ async function ensureServerEip(eip) {
|
|
|
642
922
|
return true;
|
|
643
923
|
}
|
|
644
924
|
/**
|
|
925
|
+
* Adds `[docker].host_ip` to a `server.toml` written before `init` set it (see `DOCKER_HOST_IP`).
|
|
926
|
+
* A fresh file already has it from `serverConfigContent`. Returns whether the file changed.
|
|
927
|
+
*/
|
|
928
|
+
async function ensureServerHostIp() {
|
|
929
|
+
const path = serverConfigPath();
|
|
930
|
+
const updated = withDockerHostIp(await Bun.file(path).text());
|
|
931
|
+
if (updated === null) return false;
|
|
932
|
+
await Bun.write(path, updated);
|
|
933
|
+
return true;
|
|
934
|
+
}
|
|
935
|
+
/**
|
|
645
936
|
* Host-side half of the `serverDataDir()` bind mount. `docker run -v` would auto-create
|
|
646
937
|
* a missing host path anyway, but doing it explicitly here matches `ensureServerConfig()`'s
|
|
647
938
|
* pattern and keeps directory creation in one place rather than relying on Docker's
|
|
@@ -670,7 +961,7 @@ async function ensureProjectConfig(log) {
|
|
|
670
961
|
//#endregion
|
|
671
962
|
//#region src/init.ts
|
|
672
963
|
/**
|
|
673
|
-
* `
|
|
964
|
+
* `init` — starts OpenSandbox + alineod locally via Docker and writes
|
|
674
965
|
* `alineo.config.json`. Delegates to `@alineo-labs/cli-shared`'s `runInit`, which `alineo init`
|
|
675
966
|
* (`packages/cli/src/commands/init.ts`) also calls — this collects its log lines into an array
|
|
676
967
|
* instead of writing to stdout, since an MCP stdio server's stdout is the JSON-RPC channel, so
|
|
@@ -741,13 +1032,13 @@ async function listSpecs() {
|
|
|
741
1032
|
const spec = await Bun.file(join(dir, file)).json();
|
|
742
1033
|
specs.push({
|
|
743
1034
|
name: spec.name ?? file.replace(/\.json$/, ""),
|
|
744
|
-
|
|
1035
|
+
harness: spec.harness ?? "?",
|
|
745
1036
|
description: spec.description ?? spec.title ?? ""
|
|
746
1037
|
});
|
|
747
1038
|
} catch {
|
|
748
1039
|
specs.push({
|
|
749
1040
|
name: file.replace(/\.json$/, ""),
|
|
750
|
-
|
|
1041
|
+
harness: "?",
|
|
751
1042
|
description: "(unreadable)"
|
|
752
1043
|
});
|
|
753
1044
|
}
|
|
@@ -796,32 +1087,35 @@ const BudgetOverride = z.object({
|
|
|
796
1087
|
spawnDepth: z.number().int().nonnegative().optional(),
|
|
797
1088
|
maxAgents: z.number().int().nonnegative().optional()
|
|
798
1089
|
}).describe("Overrides the spec's own spawnDepth / maxAgents (flag-beats-config).");
|
|
1090
|
+
const CloseWhen = z.enum(["explicit", "quiescent"]).describe("\"explicit\" (default): the run stays open until run_stop deletes it. \"quiescent\": the run closes itself the moment every agent in it is done.");
|
|
799
1091
|
const AgentSpecInput = z.record(z.string(), z.unknown()).describe("An alineo AgentSpec object (validated server-side by alineod's own SDK call).");
|
|
800
1092
|
function buildServer(clientOpts = {}) {
|
|
801
1093
|
const client = new AlineodClient(clientOpts);
|
|
802
1094
|
const server = new McpServer({
|
|
803
1095
|
name: "alineo-mcp",
|
|
804
|
-
version
|
|
805
|
-
}, { instructions: "Orchestrate swarms of sandboxed coding agents via alineod, alineo's HTTP+SSE control daemon, plus local agent-spec management. Typical flow:
|
|
806
|
-
server.registerTool("
|
|
1096
|
+
version
|
|
1097
|
+
}, { instructions: "Orchestrate swarms of sandboxed coding agents via alineod, alineo's HTTP+SSE control daemon, plus local agent-spec management. Typical flow: init (once, to start OpenSandbox + alineod locally) → spec_add / spec_list to get an AgentSpec → run_start to start a swarm → agent_spawn to fan out children → agent_prompt / agent_steer to drive them → run_watch or run_get to observe progress → result_get to read a settled agent's output → agent_stop / run_stop to tear down. alineod must be reachable (default http://127.0.0.1:4600, override with ALINEOD_URL) for every run_*, agent_* and result_* tool; init starts it." });
|
|
1098
|
+
server.registerTool("run_start", {
|
|
807
1099
|
title: "Create a swarm run",
|
|
808
|
-
description: "POST /runs — load the root agent from an AgentSpec, optionally drive one prompt on it. Returns immediately with state \"provisioning\"; poll
|
|
1100
|
+
description: "POST /runs — load the root agent from an AgentSpec, optionally drive one prompt on it. Returns immediately with state \"provisioning\"; poll run_get for the real state.",
|
|
809
1101
|
inputSchema: z.object({
|
|
810
1102
|
spec: AgentSpecInput,
|
|
811
1103
|
prompt: z.string().optional().describe("If set, drive one turn on the root agent after load."),
|
|
812
|
-
budget: BudgetOverride.optional()
|
|
1104
|
+
budget: BudgetOverride.optional(),
|
|
1105
|
+
closeWhen: CloseWhen.optional()
|
|
813
1106
|
})
|
|
814
|
-
}, safe(async ({ spec, prompt, budget }) => ok(await client.createRun({
|
|
1107
|
+
}, safe(async ({ spec, prompt, budget, closeWhen }) => ok(await client.createRun({
|
|
815
1108
|
spec,
|
|
816
1109
|
prompt,
|
|
817
|
-
budget
|
|
1110
|
+
budget,
|
|
1111
|
+
closeWhen
|
|
818
1112
|
}))));
|
|
819
|
-
server.registerTool("
|
|
1113
|
+
server.registerTool("run_get", {
|
|
820
1114
|
title: "Get a run's spawn tree",
|
|
821
1115
|
description: "GET /runs/:runId — the flat list of every agent in the run, with parent pointers and current state.",
|
|
822
1116
|
inputSchema: z.object({ runId: z.string().min(1) })
|
|
823
1117
|
}, safe(async ({ runId }) => ok(await client.getRun(runId))));
|
|
824
|
-
server.registerTool("
|
|
1118
|
+
server.registerTool("run_stop", {
|
|
825
1119
|
title: "Tear down a run",
|
|
826
1120
|
description: "DELETE /runs/:runId — abort and close every live agent in the run. The ledger is kept.",
|
|
827
1121
|
inputSchema: z.object({ runId: z.string().min(1) })
|
|
@@ -829,9 +1123,9 @@ function buildServer(clientOpts = {}) {
|
|
|
829
1123
|
await client.deleteRun(runId);
|
|
830
1124
|
return ok(`Run ${runId} torn down (every live agent aborted and closed).`);
|
|
831
1125
|
}));
|
|
832
|
-
server.registerTool("
|
|
1126
|
+
server.registerTool("run_watch", {
|
|
833
1127
|
title: "Watch a run's live events",
|
|
834
|
-
description: "GET /runs/:runId/events (SSE) — collects lifecycle events (
|
|
1128
|
+
description: "GET /runs/:runId/events (SSE) — collects lifecycle events (agent.spawned, agent.state_changed, agent.ended, handle.settled, budget.denied, …) and forwarded harness events (message.updated, tool.started, tool.ended, …) for a bounded window, since this is a request/response tool call rather than a live stream. Pass sinceEventId (the last event's `id`) to resume from where you left off without missing anything persisted.",
|
|
835
1129
|
inputSchema: z.object({
|
|
836
1130
|
runId: z.string().min(1),
|
|
837
1131
|
sinceEventId: z.number().int().nonnegative().optional().describe("Resume after this ledger seq (Last-Event-ID)."),
|
|
@@ -843,7 +1137,7 @@ function buildServer(clientOpts = {}) {
|
|
|
843
1137
|
maxWaitMs: maxWaitSeconds !== void 0 ? maxWaitSeconds * 1e3 : void 0,
|
|
844
1138
|
maxEvents
|
|
845
1139
|
}))));
|
|
846
|
-
server.registerTool("
|
|
1140
|
+
server.registerTool("agent_spawn", {
|
|
847
1141
|
title: "Spawn a child agent",
|
|
848
1142
|
description: "POST /runs/:runId/agents — fork a new child under a live parent. Set waitFor to hold the spawn until other agents' results settle (their output is written into the child's sandbox before it starts).",
|
|
849
1143
|
inputSchema: z.object({
|
|
@@ -863,14 +1157,14 @@ function buildServer(clientOpts = {}) {
|
|
|
863
1157
|
budget,
|
|
864
1158
|
idempotencyKey
|
|
865
1159
|
}))));
|
|
866
|
-
server.registerTool("
|
|
1160
|
+
server.registerTool("agent_get", {
|
|
867
1161
|
title: "Inspect an agent",
|
|
868
1162
|
description: "GET /agents/:agentId — the agent's current view plus session stats (token usage, cost, message counts) when live and not paused.",
|
|
869
1163
|
inputSchema: z.object({ agentId: z.string().min(1) })
|
|
870
1164
|
}, safe(async ({ agentId }) => ok(await client.getAgent(agentId))));
|
|
871
|
-
server.registerTool("
|
|
1165
|
+
server.registerTool("agent_prompt", {
|
|
872
1166
|
title: "Prompt an agent",
|
|
873
|
-
description: "POST /agents/:agentId/prompt — drive one turn. Returns immediately (202); poll
|
|
1167
|
+
description: "POST /agents/:agentId/prompt — drive one turn. Returns immediately (202); poll result_get or run_watch for the reply.",
|
|
874
1168
|
inputSchema: z.object({
|
|
875
1169
|
agentId: z.string().min(1),
|
|
876
1170
|
text: z.string().min(1)
|
|
@@ -879,7 +1173,7 @@ function buildServer(clientOpts = {}) {
|
|
|
879
1173
|
await client.promptAgent(agentId, text);
|
|
880
1174
|
return ok(`Prompt accepted for agent ${agentId}.`);
|
|
881
1175
|
}));
|
|
882
|
-
server.registerTool("
|
|
1176
|
+
server.registerTool("agent_steer", {
|
|
883
1177
|
title: "Steer an agent's current turn",
|
|
884
1178
|
description: "POST /agents/:agentId/steer — inject a message into the agent's in-flight turn (lands at the next turn boundary). The named agent only, never a subtree.",
|
|
885
1179
|
inputSchema: z.object({
|
|
@@ -890,7 +1184,7 @@ function buildServer(clientOpts = {}) {
|
|
|
890
1184
|
await client.steerAgent(agentId, message);
|
|
891
1185
|
return ok(`Steer message accepted for agent ${agentId}.`);
|
|
892
1186
|
}));
|
|
893
|
-
server.registerTool("
|
|
1187
|
+
server.registerTool("agent_pause", {
|
|
894
1188
|
title: "Pause an agent",
|
|
895
1189
|
description: "POST /agents/:agentId/pause — freeze the agent's sandbox container.",
|
|
896
1190
|
inputSchema: z.object({ agentId: z.string().min(1) })
|
|
@@ -898,7 +1192,7 @@ function buildServer(clientOpts = {}) {
|
|
|
898
1192
|
await client.pauseAgent(agentId);
|
|
899
1193
|
return ok(`Agent ${agentId} pausing.`);
|
|
900
1194
|
}));
|
|
901
|
-
server.registerTool("
|
|
1195
|
+
server.registerTool("agent_resume", {
|
|
902
1196
|
title: "Resume a paused agent",
|
|
903
1197
|
description: "POST /agents/:agentId/resume — thaw a paused sandbox container.",
|
|
904
1198
|
inputSchema: z.object({ agentId: z.string().min(1) })
|
|
@@ -906,7 +1200,7 @@ function buildServer(clientOpts = {}) {
|
|
|
906
1200
|
await client.resumeAgent(agentId);
|
|
907
1201
|
return ok(`Agent ${agentId} resuming.`);
|
|
908
1202
|
}));
|
|
909
|
-
server.registerTool("
|
|
1203
|
+
server.registerTool("agent_stop", {
|
|
910
1204
|
title: "Stop an agent",
|
|
911
1205
|
description: "POST /agents/:agentId/stop — abort and close one agent. mode defaults to \"abort\" (\"drain\" currently behaves the same).",
|
|
912
1206
|
inputSchema: z.object({
|
|
@@ -917,7 +1211,7 @@ function buildServer(clientOpts = {}) {
|
|
|
917
1211
|
await client.stopAgent(agentId, mode);
|
|
918
1212
|
return ok(`Agent ${agentId} stopping (mode: ${mode ?? "abort"}).`);
|
|
919
1213
|
}));
|
|
920
|
-
server.registerTool("
|
|
1214
|
+
server.registerTool("result_get", {
|
|
921
1215
|
title: "Get an agent's result",
|
|
922
1216
|
description: "GET /agents/:agentId/result — resolve a settled agent's output. Pass waitSeconds to long-poll (server-held) until it settles or the timeout elapses, instead of polling yourself.",
|
|
923
1217
|
inputSchema: z.object({
|
|
@@ -925,25 +1219,25 @@ function buildServer(clientOpts = {}) {
|
|
|
925
1219
|
waitSeconds: z.number().int().min(0).max(240).optional().describe("Server-side long-poll bound, capped at 240.")
|
|
926
1220
|
})
|
|
927
1221
|
}, safe(async ({ agentId, waitSeconds }) => ok(await client.getResult(agentId, waitSeconds))));
|
|
928
|
-
server.registerTool("
|
|
1222
|
+
server.registerTool("init", {
|
|
929
1223
|
title: "Start OpenSandbox + alineod locally",
|
|
930
|
-
description: "Starts OpenSandbox and alineod in Docker (pulling images if needed) and writes alineo.config.json in the current directory if missing. Run this once before any
|
|
1224
|
+
description: "Starts OpenSandbox and alineod in Docker (pulling images if needed) and writes alineo.config.json in the current directory if missing. Run this once before any run_*, agent_* or result_* tool if alineod isn't already running. Requires Docker.",
|
|
931
1225
|
inputSchema: z.object({})
|
|
932
1226
|
}, safe(async () => ok(await init())));
|
|
933
|
-
server.registerTool("
|
|
1227
|
+
server.registerTool("spec_add", {
|
|
934
1228
|
title: "Add an agent spec",
|
|
935
|
-
description: "Fetches an AgentSpec from a URL or local file path, validates it, and saves it to the local agent-spec cache (recursively resolving registryDependencies). The saved spec's object is what
|
|
1229
|
+
description: "Fetches an AgentSpec from a URL or local file path, validates it, and saves it to the local agent-spec cache (recursively resolving registryDependencies). The saved spec's object is what run_start / agent_spawn expect as `spec`.",
|
|
936
1230
|
inputSchema: z.object({
|
|
937
1231
|
url: z.string().min(1).describe("An https:// URL or a local file path to an AgentSpec JSON file."),
|
|
938
1232
|
name: z.string().optional().describe("Override the spec's own name for the saved filename.")
|
|
939
1233
|
})
|
|
940
1234
|
}, safe(async ({ url, name }) => ok(await addSpec(url, name))));
|
|
941
|
-
server.registerTool("
|
|
1235
|
+
server.registerTool("spec_list", {
|
|
942
1236
|
title: "List saved agent specs",
|
|
943
|
-
description: "Lists every AgentSpec saved locally via
|
|
1237
|
+
description: "Lists every AgentSpec saved locally via spec_add.",
|
|
944
1238
|
inputSchema: z.object({})
|
|
945
1239
|
}, safe(async () => ok(await listSpecs())));
|
|
946
|
-
server.registerTool("
|
|
1240
|
+
server.registerTool("spec_remove", {
|
|
947
1241
|
title: "Remove a saved agent spec",
|
|
948
1242
|
description: "Deletes a locally saved AgentSpec by name.",
|
|
949
1243
|
inputSchema: z.object({ name: z.string().min(1) })
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "alineo-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "MCP server exposing alineod's swarm-control API (and local agent-spec management) as tools for MCP clients (Claude Code, Claude Desktop, Cursor, …).",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -31,8 +31,9 @@
|
|
|
31
31
|
"typecheck": "tsc --noEmit"
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
|
+
"@alineo-labs/schema": "0.2.0",
|
|
34
35
|
"@modelcontextprotocol/server": "^2.0.0",
|
|
35
|
-
"alineo": "0.
|
|
36
|
+
"alineo": "0.7.0",
|
|
36
37
|
"zod": "^4"
|
|
37
38
|
},
|
|
38
39
|
"devDependencies": {
|