alineo-mcp 0.2.0 → 0.3.1
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 +407 -93
- package/package.json +4 -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
|
@@ -2,28 +2,47 @@
|
|
|
2
2
|
import { serveStdio } from "@modelcontextprotocol/server/stdio";
|
|
3
3
|
import { McpServer } from "@modelcontextprotocol/server";
|
|
4
4
|
import { z } from "zod";
|
|
5
|
+
import { isErrorCode } from "@alineo-labs/errors";
|
|
5
6
|
import { join } from "path";
|
|
6
7
|
import { homedir } from "os";
|
|
7
8
|
import { existsSync, readdirSync } from "fs";
|
|
8
9
|
import { mkdir, unlink } from "fs/promises";
|
|
10
|
+
import { existsSync as existsSync$1, readFileSync } from "node:fs";
|
|
11
|
+
import { homedir as homedir$1 } from "node:os";
|
|
12
|
+
import { dirname, join as join$1, resolve } from "node:path";
|
|
13
|
+
import { ProjectConfigSchema } from "@alineo-labs/schema";
|
|
9
14
|
import { validateAgentSpec } from "alineo";
|
|
15
|
+
//#region package.json
|
|
16
|
+
var version = "0.3.1";
|
|
17
|
+
//#endregion
|
|
10
18
|
//#region src/alineod-client.ts
|
|
11
19
|
/**
|
|
12
|
-
* Thin HTTP + SSE client for alineod's wire contract
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
20
|
+
* Thin HTTP + SSE client for alineod's wire contract. Still typed against the contract rather
|
|
21
|
+
* than against the daemon's internals — alineod is "standalone by design" (its own README) and
|
|
22
|
+
* this package talks to it the way any external MCP client would, over HTTP. The difference is
|
|
23
|
+
* that the contract is now a published package (`@alineo-labs/schema/alineod`) instead of an
|
|
24
|
+
* app's source file, so honouring that boundary no longer costs a second copy of every shape.
|
|
25
|
+
*
|
|
26
|
+
* `spec` fields below stay `Record<string, unknown>`, not `AgentSpec` — an MCP tool receives
|
|
27
|
+
* arbitrary unvalidated JSON from a model, and typing it as an `AgentSpec` would claim a
|
|
28
|
+
* guarantee this side of the wire cannot make. alineod validates it for real now (its wire
|
|
29
|
+
* schema is `@alineo-labs/schema`'s `AgentSpecSchema`, no longer an opaque record), so an
|
|
30
|
+
* invalid spec comes back as a 400 naming the bad field rather than failing later inside
|
|
31
|
+
* `Alineo.start()`.
|
|
16
32
|
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
* (
|
|
20
|
-
* the same way: opaque here, validated server-side by the SDK's own `Alineo.load()`/`.spawn()`.
|
|
33
|
+
* The interfaces below still mirror alineod's wire contract by hand. Now that the contract
|
|
34
|
+
* itself is a published package, pointing them at it would delete that duplication — the
|
|
35
|
+
* original reason not to (alineod's schemas being internal) no longer holds.
|
|
21
36
|
*/
|
|
22
37
|
var AlineodError = class extends Error {
|
|
23
38
|
status;
|
|
24
|
-
|
|
39
|
+
code;
|
|
40
|
+
hint;
|
|
41
|
+
constructor(status, message, code, hint) {
|
|
25
42
|
super(message);
|
|
26
43
|
this.status = status;
|
|
44
|
+
this.code = code;
|
|
45
|
+
this.hint = hint;
|
|
27
46
|
this.name = "AlineodError";
|
|
28
47
|
}
|
|
29
48
|
};
|
|
@@ -44,14 +63,15 @@ var AlineodClient = class {
|
|
|
44
63
|
body: body !== void 0 ? JSON.stringify(body) : void 0
|
|
45
64
|
});
|
|
46
65
|
} 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
|
|
66
|
+
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
67
|
}
|
|
49
68
|
if (res.status === 204) return void 0;
|
|
50
69
|
const text = await res.text();
|
|
51
70
|
const data = text.length > 0 ? JSON.parse(text) : void 0;
|
|
52
71
|
if (!res.ok) {
|
|
53
|
-
const
|
|
54
|
-
|
|
72
|
+
const body = data;
|
|
73
|
+
const message = body?.error ?? res.statusText;
|
|
74
|
+
throw new AlineodError(res.status, message, isErrorCode(body?.code) ? body.code : void 0, typeof body?.hint === "string" ? body.hint : void 0);
|
|
55
75
|
}
|
|
56
76
|
return data;
|
|
57
77
|
}
|
|
@@ -169,6 +189,227 @@ function parseSseFrame(frame) {
|
|
|
169
189
|
};
|
|
170
190
|
}
|
|
171
191
|
//#endregion
|
|
192
|
+
//#region ../config-shared/dist/index.mjs
|
|
193
|
+
/** The file name every alineo project config uses. */
|
|
194
|
+
const PROJECT_CONFIG_FILE = "alineo.config.json";
|
|
195
|
+
/**
|
|
196
|
+
* Walk up from `startDir` looking for `alineo.config.json`.
|
|
197
|
+
*
|
|
198
|
+
* Before this existed, `packages/agent` only ever checked `process.cwd()`, so running a script
|
|
199
|
+
* from a subdirectory silently fell back to built-in defaults — a wrong `serverUrl` looked
|
|
200
|
+
* exactly like no config at all.
|
|
201
|
+
*
|
|
202
|
+
* The walk is **bounded**, which matters as much as the walk itself: an unbounded search would
|
|
203
|
+
* let an unrelated `alineo.config.json` several levels up configure a run. It stops after
|
|
204
|
+
* examining:
|
|
205
|
+
*
|
|
206
|
+
* - a directory containing `.git` (the project boundary),
|
|
207
|
+
* - the user's home directory (global config is a separate, explicit source), or
|
|
208
|
+
* - the filesystem root.
|
|
209
|
+
*
|
|
210
|
+
* The stop directory is itself checked before the walk ends, so a config file sitting next to
|
|
211
|
+
* `.git` is still found.
|
|
212
|
+
*/
|
|
213
|
+
function findProjectConfig(startDir = process.cwd()) {
|
|
214
|
+
const home = resolve(homedir$1());
|
|
215
|
+
let dir = resolve(startDir);
|
|
216
|
+
for (;;) {
|
|
217
|
+
const candidate = join$1(dir, PROJECT_CONFIG_FILE);
|
|
218
|
+
if (existsSync$1(candidate)) return candidate;
|
|
219
|
+
if (existsSync$1(join$1(dir, ".git"))) return null;
|
|
220
|
+
if (dir === home) return null;
|
|
221
|
+
const parent = dirname(dir);
|
|
222
|
+
if (parent === dir) return null;
|
|
223
|
+
dir = parent;
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
/** Absolute path of the user-level config, `~/.config/alineo/config.json`. */
|
|
227
|
+
function globalConfigPath$1() {
|
|
228
|
+
return join$1(homedir$1(), ".config", "alineo", "config.json");
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* Read and JSON-parse a config file, or return `null` when it isn't there.
|
|
232
|
+
* A file that exists but is malformed throws — a typo in config should be loud, not silently
|
|
233
|
+
* ignored in favour of defaults.
|
|
234
|
+
*/
|
|
235
|
+
function readJsonFile(path) {
|
|
236
|
+
if (!existsSync$1(path)) return null;
|
|
237
|
+
const raw = readFileSync(path, "utf8");
|
|
238
|
+
try {
|
|
239
|
+
return JSON.parse(raw);
|
|
240
|
+
} catch (err) {
|
|
241
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
242
|
+
throw new Error(`${path} is not valid JSON: ${message}`);
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
function isPlainObject(value) {
|
|
246
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
|
|
247
|
+
const proto = Object.getPrototypeOf(value);
|
|
248
|
+
return proto === Object.prototype || proto === null;
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* Merge config sources, lowest precedence first. Plain objects merge key by key; everything
|
|
252
|
+
* else (arrays, strings, numbers) is replaced wholesale by the later source.
|
|
253
|
+
*
|
|
254
|
+
* `undefined` never overwrites — an absent key in a higher-precedence source leaves the lower
|
|
255
|
+
* one intact, which is what makes "env var not set" mean "don't override" rather than "clear".
|
|
256
|
+
* An explicit `null` *does* overwrite, so a config file can blank a value on purpose.
|
|
257
|
+
*/
|
|
258
|
+
function mergeDeep(...sources) {
|
|
259
|
+
let result = void 0;
|
|
260
|
+
for (const source of sources) {
|
|
261
|
+
if (source === void 0) continue;
|
|
262
|
+
if (isPlainObject(source) && isPlainObject(result)) {
|
|
263
|
+
const merged = { ...result };
|
|
264
|
+
for (const [key, value] of Object.entries(source)) {
|
|
265
|
+
if (value === void 0) continue;
|
|
266
|
+
merged[key] = key in merged ? mergeDeep(merged[key], value) : value;
|
|
267
|
+
}
|
|
268
|
+
result = merged;
|
|
269
|
+
} else result = source;
|
|
270
|
+
}
|
|
271
|
+
return result;
|
|
272
|
+
}
|
|
273
|
+
/**
|
|
274
|
+
* Freeze an object and everything reachable from it, so a resolved config can't be mutated
|
|
275
|
+
* after validation. Cycles are impossible in JSON-derived data, so no seen-set is needed.
|
|
276
|
+
*/
|
|
277
|
+
function deepFreeze(value) {
|
|
278
|
+
if (value === null || typeof value !== "object") return value;
|
|
279
|
+
if (Object.isFrozen(value)) return value;
|
|
280
|
+
Object.freeze(value);
|
|
281
|
+
for (const key of Object.getOwnPropertyNames(value)) deepFreeze(value[key]);
|
|
282
|
+
return value;
|
|
283
|
+
}
|
|
284
|
+
/** Env var holding a whole config document inline, as JSON. */
|
|
285
|
+
const CONFIG_CONTENT_ENV = "ALINEO_CONFIG_CONTENT";
|
|
286
|
+
/**
|
|
287
|
+
* Resolve configuration from every source, lowest precedence first:
|
|
288
|
+
*
|
|
289
|
+
* ```
|
|
290
|
+
* schema defaults
|
|
291
|
+
* < ~/.config/alineo/config.json (user)
|
|
292
|
+
* < alineo.config.json (project — found by bounded walk-up)
|
|
293
|
+
* < ALINEO_CONFIG_CONTENT (inline JSON)
|
|
294
|
+
* < ALINEO_* env vars (ops)
|
|
295
|
+
* < overrides (flags / explicit call-site object)
|
|
296
|
+
* ```
|
|
297
|
+
*
|
|
298
|
+
* Validated once, then deep-frozen. **This function is pure with respect to module state** —
|
|
299
|
+
* nothing is cached here and there is no installed singleton, so two bundled copies of this
|
|
300
|
+
* package cannot drift apart. Callers hold the result for as long as they need it.
|
|
301
|
+
*/
|
|
302
|
+
function loadConfigWithSources(options) {
|
|
303
|
+
const { schema, cwd = process.cwd(), env = process.env, fromEnv, overrides, globalPath = globalConfigPath$1(), discover = true, label = "config" } = options;
|
|
304
|
+
const sources = {
|
|
305
|
+
globalFile: null,
|
|
306
|
+
projectFile: null,
|
|
307
|
+
inlineEnv: false,
|
|
308
|
+
envVars: false,
|
|
309
|
+
overrides: overrides !== void 0
|
|
310
|
+
};
|
|
311
|
+
const layers = [];
|
|
312
|
+
if (discover) {
|
|
313
|
+
if (globalPath) {
|
|
314
|
+
const globalData = readJsonFile(globalPath);
|
|
315
|
+
if (globalData !== null) {
|
|
316
|
+
layers.push(globalData);
|
|
317
|
+
sources.globalFile = globalPath;
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
const projectFile = findProjectConfig(cwd);
|
|
321
|
+
if (projectFile) {
|
|
322
|
+
const projectData = readJsonFile(projectFile);
|
|
323
|
+
if (projectData !== null) {
|
|
324
|
+
layers.push(projectData);
|
|
325
|
+
sources.projectFile = projectFile;
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
const inline = env[CONFIG_CONTENT_ENV];
|
|
329
|
+
if (inline !== void 0 && inline.trim() !== "") {
|
|
330
|
+
try {
|
|
331
|
+
layers.push(JSON.parse(inline));
|
|
332
|
+
} catch (err) {
|
|
333
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
334
|
+
throw new Error(`${CONFIG_CONTENT_ENV} is not valid JSON: ${message}`);
|
|
335
|
+
}
|
|
336
|
+
sources.inlineEnv = true;
|
|
337
|
+
}
|
|
338
|
+
if (fromEnv) {
|
|
339
|
+
const fromEnvData = fromEnv(env);
|
|
340
|
+
if (fromEnvData !== void 0) {
|
|
341
|
+
layers.push(fromEnvData);
|
|
342
|
+
sources.envVars = true;
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
if (overrides !== void 0) layers.push(overrides);
|
|
347
|
+
const merged = layers.length > 0 ? mergeDeep(...layers) : {};
|
|
348
|
+
const parsed = schema.safeParse(merged ?? {});
|
|
349
|
+
if (!parsed.success) {
|
|
350
|
+
const details = parsed.error.issues.map((issue) => {
|
|
351
|
+
return ` ${issue.path.length > 0 ? issue.path.join(".") : "(root)"}: ${issue.message}`;
|
|
352
|
+
}).join("\n");
|
|
353
|
+
const from = describeSources(sources);
|
|
354
|
+
throw new Error(`Invalid ${label}${from}:\n${details}`);
|
|
355
|
+
}
|
|
356
|
+
return {
|
|
357
|
+
config: deepFreeze(parsed.data),
|
|
358
|
+
sources
|
|
359
|
+
};
|
|
360
|
+
}
|
|
361
|
+
/** `loadConfigWithSources` without the provenance — the common case. */
|
|
362
|
+
function loadConfig(options) {
|
|
363
|
+
return loadConfigWithSources(options).config;
|
|
364
|
+
}
|
|
365
|
+
function describeSources(sources) {
|
|
366
|
+
const parts = [];
|
|
367
|
+
if (sources.globalFile) parts.push(sources.globalFile);
|
|
368
|
+
if (sources.projectFile) parts.push(sources.projectFile);
|
|
369
|
+
if (sources.inlineEnv) parts.push(CONFIG_CONTENT_ENV);
|
|
370
|
+
if (sources.envVars) parts.push("environment");
|
|
371
|
+
if (sources.overrides) parts.push("explicit options");
|
|
372
|
+
return parts.length > 0 ? ` (from ${parts.join(", ")})` : "";
|
|
373
|
+
}
|
|
374
|
+
function parseBoolean(raw, name) {
|
|
375
|
+
const value = raw.trim().toLowerCase();
|
|
376
|
+
if ([
|
|
377
|
+
"true",
|
|
378
|
+
"1",
|
|
379
|
+
"yes",
|
|
380
|
+
"on"
|
|
381
|
+
].includes(value)) return true;
|
|
382
|
+
if ([
|
|
383
|
+
"false",
|
|
384
|
+
"0",
|
|
385
|
+
"no",
|
|
386
|
+
"off"
|
|
387
|
+
].includes(value)) return false;
|
|
388
|
+
throw new Error(`${name}=${JSON.stringify(raw)} is not a boolean (use true or false)`);
|
|
389
|
+
}
|
|
390
|
+
/**
|
|
391
|
+
* Project-config fields settable from the environment. These are what
|
|
392
|
+
* `apps/alineod/docker-entrypoint.sh` writes into a generated config file before starting the
|
|
393
|
+
* server; reading them directly means the container no longer has to write a file at all.
|
|
394
|
+
*/
|
|
395
|
+
function projectConfigFromEnv(env) {
|
|
396
|
+
const out = {};
|
|
397
|
+
if (env.ALINEO_PROVIDER !== void 0) out.provider = env.ALINEO_PROVIDER;
|
|
398
|
+
if (env.ALINEO_SERVER_URL !== void 0) out.serverUrl = env.ALINEO_SERVER_URL;
|
|
399
|
+
if (env.ALINEO_API_KEY !== void 0) out.apiKey = env.ALINEO_API_KEY;
|
|
400
|
+
if (env.ALINEO_USE_SERVER_PROXY !== void 0) out.useServerProxy = parseBoolean(env.ALINEO_USE_SERVER_PROXY, "ALINEO_USE_SERVER_PROXY");
|
|
401
|
+
return Object.keys(out).length > 0 ? out : void 0;
|
|
402
|
+
}
|
|
403
|
+
/** Resolve `alineo.config.json` from every source. Validated once, then frozen. */
|
|
404
|
+
function loadProjectConfig(options = {}) {
|
|
405
|
+
return loadConfig({
|
|
406
|
+
schema: ProjectConfigSchema,
|
|
407
|
+
fromEnv: projectConfigFromEnv,
|
|
408
|
+
label: "alineo config",
|
|
409
|
+
...options
|
|
410
|
+
});
|
|
411
|
+
}
|
|
412
|
+
//#endregion
|
|
172
413
|
//#region ../cli-shared/dist/index.mjs
|
|
173
414
|
async function spawn(cmd) {
|
|
174
415
|
let proc;
|
|
@@ -236,6 +477,20 @@ async function removeContainer(name) {
|
|
|
236
477
|
]);
|
|
237
478
|
if (!ok) throw new Error(`Failed to remove container '${name}': ${stderr.trim()}`);
|
|
238
479
|
}
|
|
480
|
+
/**
|
|
481
|
+
* Set a container's restart policy in place (`docker update`, no recreate). Used so containers
|
|
482
|
+
* created before `init` started passing `--restart` still come back after a reboot.
|
|
483
|
+
*/
|
|
484
|
+
async function setRestartPolicy(name, policy) {
|
|
485
|
+
const { ok, stderr } = await spawn([
|
|
486
|
+
"docker",
|
|
487
|
+
"update",
|
|
488
|
+
"--restart",
|
|
489
|
+
policy,
|
|
490
|
+
name
|
|
491
|
+
]);
|
|
492
|
+
if (!ok) throw new Error(`Failed to set restart policy on '${name}': ${stderr.trim()}`);
|
|
493
|
+
}
|
|
239
494
|
async function runContainer(args, label = "container") {
|
|
240
495
|
const { ok, stderr } = await spawn([
|
|
241
496
|
"docker",
|
|
@@ -280,53 +535,42 @@ async function isReachable(url, isHealthy, timeoutMs = 1e4) {
|
|
|
280
535
|
}
|
|
281
536
|
}
|
|
282
537
|
const CONFIG_DIR = ".alineo";
|
|
283
|
-
const CONFIG_FILE = "alineo.config.json";
|
|
284
538
|
function configPath() {
|
|
285
|
-
return
|
|
539
|
+
return PROJECT_CONFIG_FILE;
|
|
286
540
|
}
|
|
287
541
|
function globalConfigPath() {
|
|
288
542
|
return join(serverConfigDir(), "config.json");
|
|
289
543
|
}
|
|
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
544
|
/**
|
|
304
|
-
*
|
|
305
|
-
*
|
|
306
|
-
* `~/.config/alineo/config.json
|
|
307
|
-
*
|
|
545
|
+
* Resolve the CLI's configuration.
|
|
546
|
+
*
|
|
547
|
+
* Sources are merged lowest-first — `~/.config/alineo/config.json`, then the nearest
|
|
548
|
+
* `alineo.config.json` (found by walking up from the working directory), then `ALINEO_*`
|
|
549
|
+
* environment variables. Two things changed when this moved onto `@alineo-labs/config-shared`:
|
|
550
|
+
* a project config is now found from a subdirectory rather than only from the exact working
|
|
551
|
+
* directory, and a global config no longer disappears entirely just because a project config
|
|
552
|
+
* exists — the project file overrides key by key.
|
|
553
|
+
*
|
|
554
|
+
* When neither file exists, the global one is bootstrapped so a fresh `bunx alineo-cli` works
|
|
555
|
+
* without an `init` in every directory.
|
|
308
556
|
*/
|
|
309
557
|
async function readConfig() {
|
|
310
|
-
const
|
|
311
|
-
if (await localFile.exists()) return fillDefaults(await localFile.json());
|
|
558
|
+
const hasProject = findProjectConfig() !== null;
|
|
312
559
|
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;
|
|
560
|
+
if (!hasProject && !existsSync(globalPath)) {
|
|
561
|
+
const dir = serverConfigDir();
|
|
562
|
+
if (!existsSync(dir)) await mkdir(dir, { recursive: true });
|
|
563
|
+
const bootstrapped = loadProjectConfig({
|
|
564
|
+
discover: false,
|
|
565
|
+
overrides: {
|
|
566
|
+
adapterPath: join(dir, "ledger.db"),
|
|
567
|
+
agentsDir: join(dir, "agents")
|
|
568
|
+
}
|
|
569
|
+
});
|
|
570
|
+
await Bun.write(globalPath, JSON.stringify(bootstrapped, null, 2) + "\n");
|
|
571
|
+
return bootstrapped;
|
|
572
|
+
}
|
|
573
|
+
return loadProjectConfig({ globalPath });
|
|
330
574
|
}
|
|
331
575
|
async function writeConfig(config) {
|
|
332
576
|
if (!existsSync(CONFIG_DIR)) await mkdir(CONFIG_DIR, { recursive: true });
|
|
@@ -346,7 +590,7 @@ function serverConfigPath() {
|
|
|
346
590
|
* only as good as where the db file actually lives: without this mount, it sits in the
|
|
347
591
|
* `alineo-opensandbox` container's own writable layer, so restart is fine but any time the
|
|
348
592
|
* 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.
|
|
593
|
+
* a stray `docker rm`) silently loses every cached snapshot record — every `Alineo.start()`
|
|
350
594
|
* snapshot fast path pays a full cold rebuild next time, indistinguishable from a genuinely
|
|
351
595
|
* changed spec (see issue #20). Bind-mounting this directory makes that data outlive the
|
|
352
596
|
* container's own lifecycle, matching OpenSandbox's own intent.
|
|
@@ -355,13 +599,45 @@ function serverDataDir() {
|
|
|
355
599
|
return join(serverConfigDir(), "opensandbox-data");
|
|
356
600
|
}
|
|
357
601
|
/**
|
|
358
|
-
*
|
|
359
|
-
*
|
|
360
|
-
*
|
|
361
|
-
*
|
|
362
|
-
*
|
|
363
|
-
*
|
|
602
|
+
* The execd image the generated server config pins.
|
|
603
|
+
*
|
|
604
|
+
* `release-1.1.1`, not `v1.0.22`. Two reasons, both measured:
|
|
605
|
+
*
|
|
606
|
+
* - **Newlines.** `v1.0.22` emits one stdout event per line with the newline stripped, so
|
|
607
|
+
* `ExecResult.stdout` of `echo one; echo two` was `"onetwo"`. From `release-1.1.1` the event
|
|
608
|
+
* text keeps its newline (`"one\n"`), which is what `ExecHandle` assumes when it joins events.
|
|
609
|
+
* `tests/contract` fails three exec cases on `v1.0.22` and passes all twenty on `release-1.1.1`.
|
|
610
|
+
* - **Post-completion delay.** `/command` holds the stream open for 1.00 s after
|
|
611
|
+
* `execution_complete` on `v1.0.22` and 0.20 s from 1.1.1 (opensandbox-group/OpenSandbox#1277).
|
|
612
|
+
*
|
|
613
|
+
* History: v1.0.19 predates cached bwrap-archive support, so every sandbox logged "bwrap archive
|
|
614
|
+
* not cached for linux/amd64 -- isolation will be unavailable" and isolation sessions (and
|
|
615
|
+
* anything that depends on them, e.g. pause()/resume()) hung instead of failing cleanly.
|
|
616
|
+
*
|
|
617
|
+
* Tags are `v1.0.x` up to v1.0.22 and `release-1.x.y` from 1.1.1. Re-run `tests/contract`
|
|
618
|
+
* against a server on the new tag before changing this.
|
|
364
619
|
*/
|
|
620
|
+
const EXECD_IMAGE = "opensandbox/execd:release-1.1.1";
|
|
621
|
+
/**
|
|
622
|
+
* Where the OpenSandbox server, running in its own container, reaches the ports it publishes on
|
|
623
|
+
* the host (`[docker].host_ip`). Without it the server falls back to `127.0.0.1` — its own
|
|
624
|
+
* loopback — so the readiness probe for an egress sidecar gets "connection refused" from a
|
|
625
|
+
* sidecar that is healthy, and every sandbox with a `networkPolicy` fails to start
|
|
626
|
+
* ("Egress sidecar did not become ready within 30s"). `init` adds
|
|
627
|
+
* `--add-host host.docker.internal:host-gateway` to the container so the name resolves on native
|
|
628
|
+
* Linux Docker as well as Docker Desktop.
|
|
629
|
+
*/
|
|
630
|
+
const DOCKER_HOST_IP = "host.docker.internal";
|
|
631
|
+
/**
|
|
632
|
+
* Adds `host_ip` to an existing `server.toml` that has none, leaving everything else (including
|
|
633
|
+
* hand edits) alone. Returns `null` when nothing needs to change: a `host_ip` is already set, or
|
|
634
|
+
* there is no `[docker]` table to put it in.
|
|
635
|
+
*/
|
|
636
|
+
function withDockerHostIp(toml) {
|
|
637
|
+
if (/^host_ip\s*=/m.test(toml)) return null;
|
|
638
|
+
if (!/^\[docker\]/m.test(toml)) return null;
|
|
639
|
+
return toml.replace(/^\[docker\][^\n]*\n/m, (header) => `${header}host_ip = "${DOCKER_HOST_IP}"\n`);
|
|
640
|
+
}
|
|
365
641
|
/**
|
|
366
642
|
* `egress.image`/`egress.mode` are configured unconditionally, not opt-in. Per OpenSandbox's
|
|
367
643
|
* own control flow, a configured `egress.image` is inert for any sandbox created without a
|
|
@@ -380,10 +656,11 @@ eip = "${eip}"
|
|
|
380
656
|
|
|
381
657
|
[runtime]
|
|
382
658
|
type = "docker"
|
|
383
|
-
execd_image = "
|
|
659
|
+
execd_image = "${EXECD_IMAGE}"
|
|
384
660
|
|
|
385
661
|
[docker]
|
|
386
662
|
network_mode = "bridge"
|
|
663
|
+
host_ip = "${DOCKER_HOST_IP}"
|
|
387
664
|
|
|
388
665
|
[store]
|
|
389
666
|
type = "sqlite"
|
|
@@ -399,7 +676,7 @@ mode = "dns+nft"
|
|
|
399
676
|
* `envMap` in earendil-works/pi's `packages/ai/src/env-api-keys.ts` (plus Anthropic's three,
|
|
400
677
|
* handled separately there). An `AgentSpec`'s env map (`{ NVIDIA_API_KEY: "${NVIDIA_API_KEY}" }`,
|
|
401
678
|
* see `packages/agent/src/schema.ts`) is resolved from `process.env` inside whatever process
|
|
402
|
-
* calls `Alineo.
|
|
679
|
+
* calls `Alineo.start()`/`.spawn()` — for a swarm run through alineod, that's alineod's own
|
|
403
680
|
* container. `alineo init` forwards whichever of these are set in the operator's shell into
|
|
404
681
|
* that container so any Pi-supported model works, not just NVIDIA's free tier.
|
|
405
682
|
*
|
|
@@ -450,7 +727,7 @@ const PI_MODEL_API_KEY_ENV_VARS = [
|
|
|
450
727
|
"COPILOT_GITHUB_TOKEN"
|
|
451
728
|
];
|
|
452
729
|
/**
|
|
453
|
-
* `alineo init` / `
|
|
730
|
+
* `alineo init` / `init` — starts OpenSandbox + alineod locally via Docker and writes
|
|
454
731
|
* `alineo.config.json`. Shared verbatim by `alineo-cli` (`packages/cli/src/commands/init.ts`,
|
|
455
732
|
* which logs to stdout) and `alineo-mcp` (`packages/mcp/src/init.ts`, which collects a log array
|
|
456
733
|
* instead — an MCP stdio server's stdout is the JSON-RPC channel, so tool handlers must never
|
|
@@ -458,6 +735,7 @@ const PI_MODEL_API_KEY_ENV_VARS = [
|
|
|
458
735
|
* hand-copied files did before.
|
|
459
736
|
*/
|
|
460
737
|
const OPENSANDBOX_CONTAINER_NAME = "alineo-opensandbox";
|
|
738
|
+
const OPENSANDBOX_IMAGE = "opensandbox/server:latest";
|
|
461
739
|
const SERVER_URL = "http://127.0.0.1:8080";
|
|
462
740
|
const ALINEOD_CONTAINER_NAME = "alineo-alineod";
|
|
463
741
|
const ALINEOD_IMAGE = "ghcr.io/drejt/alineod:latest";
|
|
@@ -465,6 +743,13 @@ const ALINEOD_URL = "http://127.0.0.1:4600";
|
|
|
465
743
|
const isAlineodHealthy = (body) => body?.ok === true;
|
|
466
744
|
const HOST_DOCKER_INTERNAL_SERVER_URL = "http://host.docker.internal:8080";
|
|
467
745
|
/**
|
|
746
|
+
* Both containers come back after a reboot or a Docker daemon restart. Without this, a host
|
|
747
|
+
* reboot left OpenSandbox down, so nothing worked until someone ran `init` again — and alineod's
|
|
748
|
+
* crash recovery only helps if something restarts alineod. `unless-stopped` rather than
|
|
749
|
+
* `always`, so a deliberate `docker stop` sticks.
|
|
750
|
+
*/
|
|
751
|
+
const RESTART_ARGS = ["--restart", "unless-stopped"];
|
|
752
|
+
/**
|
|
468
753
|
* `--network host` (which makes alineod see `127.0.0.1` exactly as the host does, matching
|
|
469
754
|
* OpenSandbox's configured `eip` — see `ensureAlineod`'s doc comment) only works out of the box
|
|
470
755
|
* on native Linux Docker. Docker Desktop for Windows/Mac ships it behind an opt-in "Enable host
|
|
@@ -483,8 +768,14 @@ async function runInit(log) {
|
|
|
483
768
|
log("Checking Docker...");
|
|
484
769
|
await checkDocker();
|
|
485
770
|
const openSandboxConfigChanged = await ensureServerConfig();
|
|
771
|
+
const hostIpAdded = await ensureServerHostIp();
|
|
486
772
|
await ensureServerDataDir();
|
|
487
|
-
|
|
773
|
+
let state = await getContainerState(OPENSANDBOX_CONTAINER_NAME);
|
|
774
|
+
if (hostIpAdded && state !== "missing") {
|
|
775
|
+
log("OpenSandbox config gained host_ip — recreating the container to match...");
|
|
776
|
+
await removeContainer(OPENSANDBOX_CONTAINER_NAME);
|
|
777
|
+
state = "missing";
|
|
778
|
+
}
|
|
488
779
|
if (state === "running") if (openSandboxConfigChanged) {
|
|
489
780
|
log("OpenSandbox networking config changed — restarting to apply it...");
|
|
490
781
|
await restartContainer(OPENSANDBOX_CONTAINER_NAME);
|
|
@@ -497,13 +788,18 @@ async function runInit(log) {
|
|
|
497
788
|
log("Waiting for OpenSandbox to be ready...");
|
|
498
789
|
await pollHealth(`${SERVER_URL}/health`);
|
|
499
790
|
} else {
|
|
791
|
+
log(`Pulling ${OPENSANDBOX_IMAGE}...`);
|
|
792
|
+
await pullImage(OPENSANDBOX_IMAGE);
|
|
500
793
|
log("Starting OpenSandbox in Docker...");
|
|
501
794
|
await runContainer([
|
|
502
795
|
"-d",
|
|
503
796
|
"--name",
|
|
504
797
|
OPENSANDBOX_CONTAINER_NAME,
|
|
798
|
+
...RESTART_ARGS,
|
|
505
799
|
"-p",
|
|
506
800
|
"8080:8080",
|
|
801
|
+
"--add-host",
|
|
802
|
+
"host.docker.internal:host-gateway",
|
|
507
803
|
"-v",
|
|
508
804
|
"/var/run/docker.sock:/var/run/docker.sock",
|
|
509
805
|
"-v",
|
|
@@ -514,12 +810,14 @@ async function runInit(log) {
|
|
|
514
810
|
"SANDBOX_CONFIG_PATH=/etc/opensandbox/config.toml",
|
|
515
811
|
"-e",
|
|
516
812
|
"OPENSANDBOX_INSECURE_SERVER=YES",
|
|
517
|
-
|
|
813
|
+
OPENSANDBOX_IMAGE
|
|
518
814
|
], "OpenSandbox container");
|
|
519
815
|
log("Waiting for OpenSandbox to be ready...");
|
|
520
816
|
await pollHealth(`${SERVER_URL}/health`);
|
|
521
817
|
}
|
|
522
818
|
await ensureAlineod(log, openSandboxConfigChanged);
|
|
819
|
+
await setRestartPolicy(OPENSANDBOX_CONTAINER_NAME, "unless-stopped");
|
|
820
|
+
await setRestartPolicy(ALINEOD_CONTAINER_NAME, "unless-stopped");
|
|
523
821
|
await ensureProjectConfig(log);
|
|
524
822
|
log(`OpenSandbox running at ${SERVER_URL}, alineod running at ${ALINEOD_URL} — ready.`);
|
|
525
823
|
return {
|
|
@@ -602,6 +900,7 @@ function startAlineodContainer(useHostNetworking, modelKeyArgs) {
|
|
|
602
900
|
"-d",
|
|
603
901
|
"--name",
|
|
604
902
|
ALINEOD_CONTAINER_NAME,
|
|
903
|
+
...RESTART_ARGS,
|
|
605
904
|
...networkArgs,
|
|
606
905
|
"-e",
|
|
607
906
|
`ALINEO_SERVER_URL=${alineodServerUrl}`,
|
|
@@ -642,6 +941,17 @@ async function ensureServerEip(eip) {
|
|
|
642
941
|
return true;
|
|
643
942
|
}
|
|
644
943
|
/**
|
|
944
|
+
* Adds `[docker].host_ip` to a `server.toml` written before `init` set it (see `DOCKER_HOST_IP`).
|
|
945
|
+
* A fresh file already has it from `serverConfigContent`. Returns whether the file changed.
|
|
946
|
+
*/
|
|
947
|
+
async function ensureServerHostIp() {
|
|
948
|
+
const path = serverConfigPath();
|
|
949
|
+
const updated = withDockerHostIp(await Bun.file(path).text());
|
|
950
|
+
if (updated === null) return false;
|
|
951
|
+
await Bun.write(path, updated);
|
|
952
|
+
return true;
|
|
953
|
+
}
|
|
954
|
+
/**
|
|
645
955
|
* Host-side half of the `serverDataDir()` bind mount. `docker run -v` would auto-create
|
|
646
956
|
* a missing host path anyway, but doing it explicitly here matches `ensureServerConfig()`'s
|
|
647
957
|
* pattern and keeps directory creation in one place rather than relying on Docker's
|
|
@@ -654,6 +964,7 @@ async function ensureServerDataDir() {
|
|
|
654
964
|
async function ensureProjectConfig(log) {
|
|
655
965
|
if (!existsSync(configPath())) {
|
|
656
966
|
await writeConfig({
|
|
967
|
+
provider: "opensandbox",
|
|
657
968
|
serverUrl: SERVER_URL,
|
|
658
969
|
useServerProxy: true,
|
|
659
970
|
apiKey: "",
|
|
@@ -670,7 +981,7 @@ async function ensureProjectConfig(log) {
|
|
|
670
981
|
//#endregion
|
|
671
982
|
//#region src/init.ts
|
|
672
983
|
/**
|
|
673
|
-
* `
|
|
984
|
+
* `init` — starts OpenSandbox + alineod locally via Docker and writes
|
|
674
985
|
* `alineo.config.json`. Delegates to `@alineo-labs/cli-shared`'s `runInit`, which `alineo init`
|
|
675
986
|
* (`packages/cli/src/commands/init.ts`) also calls — this collects its log lines into an array
|
|
676
987
|
* instead of writing to stdout, since an MCP stdio server's stdout is the JSON-RPC channel, so
|
|
@@ -741,13 +1052,13 @@ async function listSpecs() {
|
|
|
741
1052
|
const spec = await Bun.file(join(dir, file)).json();
|
|
742
1053
|
specs.push({
|
|
743
1054
|
name: spec.name ?? file.replace(/\.json$/, ""),
|
|
744
|
-
|
|
1055
|
+
harness: (typeof spec.harness === "object" ? spec.harness.id : spec.harness) ?? "?",
|
|
745
1056
|
description: spec.description ?? spec.title ?? ""
|
|
746
1057
|
});
|
|
747
1058
|
} catch {
|
|
748
1059
|
specs.push({
|
|
749
1060
|
name: file.replace(/\.json$/, ""),
|
|
750
|
-
|
|
1061
|
+
harness: "?",
|
|
751
1062
|
description: "(unreadable)"
|
|
752
1063
|
});
|
|
753
1064
|
}
|
|
@@ -777,7 +1088,7 @@ function fail(err) {
|
|
|
777
1088
|
return {
|
|
778
1089
|
content: [{
|
|
779
1090
|
type: "text",
|
|
780
|
-
text: err instanceof AlineodError ? `alineod error (${err.status || "network"}): ${err.message}` : err instanceof Error ? err.message : String(err)
|
|
1091
|
+
text: err instanceof AlineodError ? `alineod error (${err.status || "network"}${err.code ? `, ${err.code}` : ""}): ${err.message}` + (err.hint ? `\nHint: ${err.hint}` : "") : err instanceof Error ? err.message : String(err)
|
|
781
1092
|
}],
|
|
782
1093
|
isError: true
|
|
783
1094
|
};
|
|
@@ -796,32 +1107,35 @@ const BudgetOverride = z.object({
|
|
|
796
1107
|
spawnDepth: z.number().int().nonnegative().optional(),
|
|
797
1108
|
maxAgents: z.number().int().nonnegative().optional()
|
|
798
1109
|
}).describe("Overrides the spec's own spawnDepth / maxAgents (flag-beats-config).");
|
|
1110
|
+
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
1111
|
const AgentSpecInput = z.record(z.string(), z.unknown()).describe("An alineo AgentSpec object (validated server-side by alineod's own SDK call).");
|
|
800
1112
|
function buildServer(clientOpts = {}) {
|
|
801
1113
|
const client = new AlineodClient(clientOpts);
|
|
802
1114
|
const server = new McpServer({
|
|
803
1115
|
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("
|
|
1116
|
+
version
|
|
1117
|
+
}, { 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." });
|
|
1118
|
+
server.registerTool("run_start", {
|
|
807
1119
|
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
|
|
1120
|
+
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
1121
|
inputSchema: z.object({
|
|
810
1122
|
spec: AgentSpecInput,
|
|
811
1123
|
prompt: z.string().optional().describe("If set, drive one turn on the root agent after load."),
|
|
812
|
-
budget: BudgetOverride.optional()
|
|
1124
|
+
budget: BudgetOverride.optional(),
|
|
1125
|
+
closeWhen: CloseWhen.optional()
|
|
813
1126
|
})
|
|
814
|
-
}, safe(async ({ spec, prompt, budget }) => ok(await client.createRun({
|
|
1127
|
+
}, safe(async ({ spec, prompt, budget, closeWhen }) => ok(await client.createRun({
|
|
815
1128
|
spec,
|
|
816
1129
|
prompt,
|
|
817
|
-
budget
|
|
1130
|
+
budget,
|
|
1131
|
+
closeWhen
|
|
818
1132
|
}))));
|
|
819
|
-
server.registerTool("
|
|
1133
|
+
server.registerTool("run_get", {
|
|
820
1134
|
title: "Get a run's spawn tree",
|
|
821
1135
|
description: "GET /runs/:runId — the flat list of every agent in the run, with parent pointers and current state.",
|
|
822
1136
|
inputSchema: z.object({ runId: z.string().min(1) })
|
|
823
1137
|
}, safe(async ({ runId }) => ok(await client.getRun(runId))));
|
|
824
|
-
server.registerTool("
|
|
1138
|
+
server.registerTool("run_stop", {
|
|
825
1139
|
title: "Tear down a run",
|
|
826
1140
|
description: "DELETE /runs/:runId — abort and close every live agent in the run. The ledger is kept.",
|
|
827
1141
|
inputSchema: z.object({ runId: z.string().min(1) })
|
|
@@ -829,9 +1143,9 @@ function buildServer(clientOpts = {}) {
|
|
|
829
1143
|
await client.deleteRun(runId);
|
|
830
1144
|
return ok(`Run ${runId} torn down (every live agent aborted and closed).`);
|
|
831
1145
|
}));
|
|
832
|
-
server.registerTool("
|
|
1146
|
+
server.registerTool("run_watch", {
|
|
833
1147
|
title: "Watch a run's live events",
|
|
834
|
-
description: "GET /runs/:runId/events (SSE) — collects lifecycle events (
|
|
1148
|
+
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
1149
|
inputSchema: z.object({
|
|
836
1150
|
runId: z.string().min(1),
|
|
837
1151
|
sinceEventId: z.number().int().nonnegative().optional().describe("Resume after this ledger seq (Last-Event-ID)."),
|
|
@@ -843,7 +1157,7 @@ function buildServer(clientOpts = {}) {
|
|
|
843
1157
|
maxWaitMs: maxWaitSeconds !== void 0 ? maxWaitSeconds * 1e3 : void 0,
|
|
844
1158
|
maxEvents
|
|
845
1159
|
}))));
|
|
846
|
-
server.registerTool("
|
|
1160
|
+
server.registerTool("agent_spawn", {
|
|
847
1161
|
title: "Spawn a child agent",
|
|
848
1162
|
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
1163
|
inputSchema: z.object({
|
|
@@ -863,14 +1177,14 @@ function buildServer(clientOpts = {}) {
|
|
|
863
1177
|
budget,
|
|
864
1178
|
idempotencyKey
|
|
865
1179
|
}))));
|
|
866
|
-
server.registerTool("
|
|
1180
|
+
server.registerTool("agent_get", {
|
|
867
1181
|
title: "Inspect an agent",
|
|
868
1182
|
description: "GET /agents/:agentId — the agent's current view plus session stats (token usage, cost, message counts) when live and not paused.",
|
|
869
1183
|
inputSchema: z.object({ agentId: z.string().min(1) })
|
|
870
1184
|
}, safe(async ({ agentId }) => ok(await client.getAgent(agentId))));
|
|
871
|
-
server.registerTool("
|
|
1185
|
+
server.registerTool("agent_prompt", {
|
|
872
1186
|
title: "Prompt an agent",
|
|
873
|
-
description: "POST /agents/:agentId/prompt — drive one turn. Returns immediately (202); poll
|
|
1187
|
+
description: "POST /agents/:agentId/prompt — drive one turn. Returns immediately (202); poll result_get or run_watch for the reply.",
|
|
874
1188
|
inputSchema: z.object({
|
|
875
1189
|
agentId: z.string().min(1),
|
|
876
1190
|
text: z.string().min(1)
|
|
@@ -879,7 +1193,7 @@ function buildServer(clientOpts = {}) {
|
|
|
879
1193
|
await client.promptAgent(agentId, text);
|
|
880
1194
|
return ok(`Prompt accepted for agent ${agentId}.`);
|
|
881
1195
|
}));
|
|
882
|
-
server.registerTool("
|
|
1196
|
+
server.registerTool("agent_steer", {
|
|
883
1197
|
title: "Steer an agent's current turn",
|
|
884
1198
|
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
1199
|
inputSchema: z.object({
|
|
@@ -890,7 +1204,7 @@ function buildServer(clientOpts = {}) {
|
|
|
890
1204
|
await client.steerAgent(agentId, message);
|
|
891
1205
|
return ok(`Steer message accepted for agent ${agentId}.`);
|
|
892
1206
|
}));
|
|
893
|
-
server.registerTool("
|
|
1207
|
+
server.registerTool("agent_pause", {
|
|
894
1208
|
title: "Pause an agent",
|
|
895
1209
|
description: "POST /agents/:agentId/pause — freeze the agent's sandbox container.",
|
|
896
1210
|
inputSchema: z.object({ agentId: z.string().min(1) })
|
|
@@ -898,7 +1212,7 @@ function buildServer(clientOpts = {}) {
|
|
|
898
1212
|
await client.pauseAgent(agentId);
|
|
899
1213
|
return ok(`Agent ${agentId} pausing.`);
|
|
900
1214
|
}));
|
|
901
|
-
server.registerTool("
|
|
1215
|
+
server.registerTool("agent_resume", {
|
|
902
1216
|
title: "Resume a paused agent",
|
|
903
1217
|
description: "POST /agents/:agentId/resume — thaw a paused sandbox container.",
|
|
904
1218
|
inputSchema: z.object({ agentId: z.string().min(1) })
|
|
@@ -906,7 +1220,7 @@ function buildServer(clientOpts = {}) {
|
|
|
906
1220
|
await client.resumeAgent(agentId);
|
|
907
1221
|
return ok(`Agent ${agentId} resuming.`);
|
|
908
1222
|
}));
|
|
909
|
-
server.registerTool("
|
|
1223
|
+
server.registerTool("agent_stop", {
|
|
910
1224
|
title: "Stop an agent",
|
|
911
1225
|
description: "POST /agents/:agentId/stop — abort and close one agent. mode defaults to \"abort\" (\"drain\" currently behaves the same).",
|
|
912
1226
|
inputSchema: z.object({
|
|
@@ -917,7 +1231,7 @@ function buildServer(clientOpts = {}) {
|
|
|
917
1231
|
await client.stopAgent(agentId, mode);
|
|
918
1232
|
return ok(`Agent ${agentId} stopping (mode: ${mode ?? "abort"}).`);
|
|
919
1233
|
}));
|
|
920
|
-
server.registerTool("
|
|
1234
|
+
server.registerTool("result_get", {
|
|
921
1235
|
title: "Get an agent's result",
|
|
922
1236
|
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
1237
|
inputSchema: z.object({
|
|
@@ -925,25 +1239,25 @@ function buildServer(clientOpts = {}) {
|
|
|
925
1239
|
waitSeconds: z.number().int().min(0).max(240).optional().describe("Server-side long-poll bound, capped at 240.")
|
|
926
1240
|
})
|
|
927
1241
|
}, safe(async ({ agentId, waitSeconds }) => ok(await client.getResult(agentId, waitSeconds))));
|
|
928
|
-
server.registerTool("
|
|
1242
|
+
server.registerTool("init", {
|
|
929
1243
|
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
|
|
1244
|
+
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
1245
|
inputSchema: z.object({})
|
|
932
1246
|
}, safe(async () => ok(await init())));
|
|
933
|
-
server.registerTool("
|
|
1247
|
+
server.registerTool("spec_add", {
|
|
934
1248
|
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
|
|
1249
|
+
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
1250
|
inputSchema: z.object({
|
|
937
1251
|
url: z.string().min(1).describe("An https:// URL or a local file path to an AgentSpec JSON file."),
|
|
938
1252
|
name: z.string().optional().describe("Override the spec's own name for the saved filename.")
|
|
939
1253
|
})
|
|
940
1254
|
}, safe(async ({ url, name }) => ok(await addSpec(url, name))));
|
|
941
|
-
server.registerTool("
|
|
1255
|
+
server.registerTool("spec_list", {
|
|
942
1256
|
title: "List saved agent specs",
|
|
943
|
-
description: "Lists every AgentSpec saved locally via
|
|
1257
|
+
description: "Lists every AgentSpec saved locally via spec_add.",
|
|
944
1258
|
inputSchema: z.object({})
|
|
945
1259
|
}, safe(async () => ok(await listSpecs())));
|
|
946
|
-
server.registerTool("
|
|
1260
|
+
server.registerTool("spec_remove", {
|
|
947
1261
|
title: "Remove a saved agent spec",
|
|
948
1262
|
description: "Deletes a locally saved AgentSpec by name.",
|
|
949
1263
|
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.1",
|
|
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,10 @@
|
|
|
31
31
|
"typecheck": "tsc --noEmit"
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
|
+
"@alineo-labs/errors": "0.1.0",
|
|
35
|
+
"@alineo-labs/schema": "0.3.0",
|
|
34
36
|
"@modelcontextprotocol/server": "^2.0.0",
|
|
35
|
-
"alineo": "0.
|
|
37
|
+
"alineo": "0.8.0",
|
|
36
38
|
"zod": "^4"
|
|
37
39
|
},
|
|
38
40
|
"devDependencies": {
|