alineo-mcp 0.2.0 → 0.3.0

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