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.
Files changed (3) hide show
  1. package/README.md +60 -55
  2. package/dist/index.mjs +407 -93
  3. 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 | Route | |
17
- | ---------------------- | ------------------------------- | ------------------------------------------------------- |
18
- | `alineod_create_run` | `POST /runs` | Load the root agent from an AgentSpec, start a run |
19
- | `alineod_get_run` | `GET /runs/:runId` | The spawn tree — every agent, state, parent pointers |
20
- | `alineod_delete_run` | `DELETE /runs/:runId` | Abort + close every live agent in the run |
21
- | `alineod_watch_events` | `GET /runs/:runId/events` (SSE) | Collect lifecycle + harness events for a bounded window |
22
- | `alineod_spawn_agent` | `POST /runs/:runId/agents` | Fork a child under a live parent |
23
- | `alineod_get_agent` | `GET /agents/:agentId` | Inspect an agent + session stats |
24
- | `alineod_prompt_agent` | `POST /agents/:agentId/prompt` | Drive one turn |
25
- | `alineod_steer_agent` | `POST /agents/:agentId/steer` | Redirect the current turn |
26
- | `alineod_pause_agent` | `POST /agents/:agentId/pause` | Freeze the sandbox container |
27
- | `alineod_resume_agent` | `POST /agents/:agentId/resume` | Thaw a paused container |
28
- | `alineod_stop_agent` | `POST /agents/:agentId/stop` | Abort + close one agent |
29
- | `alineod_get_result` | `GET /agents/:agentId/result` | Resolve a settled agent's output (optional long-poll) |
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
- | `alineo_init` | Start OpenSandbox + alineod locally via Docker |
36
- | `alineo_add_spec` | Fetch an AgentSpec (URL or local file), validate it, save it |
37
- | `alineo_list_specs` | List saved agent specs |
38
- | `alineo_remove_spec` | Remove a saved agent spec |
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 every alineod HTTP route and every `alineo-cli` subcommand except `telemetry`
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
- (`spawn`/`prompt`/`fork`/`agents`/`kill`/`logs`) — those drive a sandbox from _this_ process via
43
- `Alineo.load()`; alineod's routes are the equivalent, network-addressable operations for a
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
- Not published to npm yet on this branch — for now, build it locally from the repo:
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
- `alineo_init` (see below) starts alineod on.
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** (this branch, before publishing), in any of the configs above:
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 | Default | Affects |
119
- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------- |
120
- | `ALINEOD_URL` | env var on the `alineo-mcp` process | `http://127.0.0.1:4600` | Every `alineod_*` tool |
121
- | `alineo.config.json` | project-local file, or `~/.config/alineo/config.json` global fallback (same resolution as `alineo-cli`) | written by `alineo_init` | `agentsDir` for `alineo_add_spec` / `list_specs` / `remove_spec` |
122
- | Docker | must be installed and running | — | `alineo_init` only |
123
- | Model provider API key | in the _caller's_ shell when running `alineo_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 |
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
- alineo_init # once, if alineod isn't already running (needs Docker)
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. `alineo_add_spec` (or `alineo_list_specs` if you've already added one) → get an AgentSpec.
137
- 2. `alineod_create_run` with that spec → get back a `runId` + `rootAgentId`.
138
- 3. `alineod_spawn_agent` with `parentAgentId: rootAgentId` to fan out children — repeat per
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. `alineod_prompt_agent` / `alineod_steer_agent` to drive them; `alineod_pause_agent` /
141
- `alineod_resume_agent` to freeze/thaw without losing state.
142
- 5. `alineod_watch_events` (poll as needed) or `alineod_get_run` to observe progress.
143
- 6. `alineod_get_result` (optionally with `waitSeconds` to long-poll) to read each settled
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. `alineod_stop_agent` per agent and/or `alineod_delete_run` to tear the whole run down.
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 | Cause | Fix |
155
- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
156
- | Every `alineod_*` call returns `alineod error (network): Could not reach alineod...` | alineod isn't running, or `ALINEOD_URL` points at the wrong address | Run `alineo_init` (needs Docker), or check what's actually listening on the configured URL |
157
- | `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; `alineod_get_run` lists current agents |
158
- | `alineod error (409): agent ... is not live` | The agent's sandbox already ended | Check `alineod_get_agent`'s `state`/`outcome` before prompting again |
159
- | `alineo_init` fails at "Checking Docker..." | Docker isn't installed or the daemon isn't running | Start Docker Desktop (or your Docker daemon) and retry |
160
- | 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 `alineo_init`, or add it to the running alineod container's env directly |
161
- | Raw `@alineo-labs/sandbox` SDK code on the host can't follow a sandbox's proxy URL, even though `alineo_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 `alineod_*` tools instead of the raw SDK against this same OpenSandbox instance, or run OpenSandbox via `uvx opensandbox-server` for direct host-based SDK access |
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
- `specs/alineod/openapi.json`), the same way any external MCP client would — alineod is
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
- - **`alineod_watch_events` is poll-and-collect, not a live stream.** An MCP tool call is
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 (`apps/alineod/src/schema.ts`,
13
- * `specs/alineod/openapi.json`). Deliberately typed against the wire contract, not against
14
- * alineod's internal Zod schemas — alineod is "standalone by design" (its own README) and this
15
- * package talks to it the same way any external MCP client would: over HTTP.
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
- * `spec` fields below are `Record<string, unknown>`, not `AgentSpec` from `alineo` — an MCP
18
- * tool receives arbitrary unvalidated JSON from the caller, and alineod's own wire schema
19
- * (`apps/alineod/src/schema.ts`'s `AgentSpec = z.record(z.string(), z.unknown())`) treats it
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
- constructor(status, message) {
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 alineo_init tool, or set ALINEOD_URL.`);
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 message = data?.error ?? res.statusText;
54
- throw new AlineodError(res.status, message);
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 CONFIG_FILE;
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
- * Resolves, in order: a project-local `alineo.config.json` (written by `alineo init`
305
- * for repos that want their own agents dir / ledger), then a global
306
- * `~/.config/alineo/config.json`. If neither exists yet, bootstraps the global
307
- * one so a fresh `bunx alineo-cli` works without requiring `init` in every directory.
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 localFile = Bun.file(configPath());
311
- if (await localFile.exists()) return fillDefaults(await localFile.json());
558
+ const hasProject = findProjectConfig() !== null;
312
559
  const globalPath = globalConfigPath();
313
- const globalFile = Bun.file(globalPath);
314
- if (await globalFile.exists()) return fillDefaults(await globalFile.json());
315
- const dir = serverConfigDir();
316
- if (!existsSync(dir)) await mkdir(dir, { recursive: true });
317
- const config = {
318
- serverUrl: "http://127.0.0.1:8080",
319
- useServerProxy: true,
320
- apiKey: "",
321
- adapterPath: join(dir, "ledger.db"),
322
- agentsDir: join(dir, "agents"),
323
- defaults: { resources: {
324
- cpu: "1000m",
325
- memory: "1Gi"
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.load()`
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
- * v1.0.19 (the previous pin) predates cached bwrap-archive support, so every sandbox logged
359
- * "bwrap archive not cached for linux/amd64 -- isolation will be unavailable" and isolation
360
- * sessions (and anything that depends on them, e.g. pause()/resume()) hung indefinitely
361
- * instead of failing cleanly. OpenSandbox's own docs: >=v1.0.20 has base isolation-session
362
- * support, >=v1.0.21 is recommended for full functionality -- the "v1.1.0+" the warning
363
- * message itself suggests does not exist as a published tag. v1.0.22 is the latest.
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 = "opensandbox/execd:v1.0.22"
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.load()`/`.spawn()` — for a swarm run through alineod, that's alineod's own
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` / `alineo_init` — starts OpenSandbox + alineod locally via Docker and writes
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
- const state = await getContainerState(OPENSANDBOX_CONTAINER_NAME);
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
- "opensandbox/server:latest"
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
- * `alineo_init` — starts OpenSandbox + alineod locally via Docker and writes
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
- cli: spec.cli ?? "?",
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
- cli: "?",
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: "0.1.0"
805
- }, { instructions: "Orchestrate swarms of sandboxed coding agents via alineod, alineo's HTTP+SSE control daemon, plus local agent-spec management. Typical flow: alineo_init (once, to start OpenSandbox + alineod locally) → alineo_add_spec / alineo_list_specs to get an AgentSpec → alineod_create_run to start a swarm → alineod_spawn_agent to fan out children → alineod_prompt_agent / alineod_steer_agent to drive them → alineod_watch_events or alineod_get_run to observe progress → alineod_get_result to read a settled agent's output → alineod_stop_agent / alineod_delete_run to tear down. alineod must be reachable (default http://127.0.0.1:4600, override with ALINEOD_URL) for every alineod_* tool; alineo_init starts it." });
806
- server.registerTool("alineod_create_run", {
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 alineod_get_run for the real state.",
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("alineod_get_run", {
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("alineod_delete_run", {
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("alineod_watch_events", {
1146
+ server.registerTool("run_watch", {
833
1147
  title: "Watch a run's live events",
834
- description: "GET /runs/:runId/events (SSE) — collects lifecycle events (agent_spawned, agent_state_changed, agent_ended, handle_settled, budget_denied, …) and forwarded harness events (text, tool_start, tool_end, …) 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.",
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("alineod_spawn_agent", {
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("alineod_get_agent", {
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("alineod_prompt_agent", {
1185
+ server.registerTool("agent_prompt", {
872
1186
  title: "Prompt an agent",
873
- description: "POST /agents/:agentId/prompt — drive one turn. Returns immediately (202); poll alineod_get_result or alineod_watch_events for the reply.",
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("alineod_steer_agent", {
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("alineod_pause_agent", {
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("alineod_resume_agent", {
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("alineod_stop_agent", {
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("alineod_get_result", {
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("alineo_init", {
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 alineod_* tool if alineod isn't already running. Requires Docker.",
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("alineo_add_spec", {
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 alineod_create_run / alineod_spawn_agent expect as `spec`.",
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("alineo_list_specs", {
1255
+ server.registerTool("spec_list", {
942
1256
  title: "List saved agent specs",
943
- description: "Lists every AgentSpec saved locally via alineo_add_spec.",
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("alineo_remove_spec", {
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.2.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.6.0",
37
+ "alineo": "0.8.0",
36
38
  "zod": "^4"
37
39
  },
38
40
  "devDependencies": {