alineo-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,429 @@
1
+ import { a as readConfig } from "./index.mjs";
2
+ import { n as getSessions, t as formatAge } from "./sessions-data-BYaLq9wh.mjs";
3
+ import { join } from "path";
4
+ import { existsSync, readdirSync } from "fs";
5
+ import { Agent } from "@alineo-labs/agent";
6
+ import { Alineo } from "alineo";
7
+ import { SQLiteAdapter } from "@alineo-labs/sqlite";
8
+ import { BoxRenderable, InputRenderable, InputRenderableEvents, ScrollBoxRenderable, SelectRenderable, SelectRenderableEvents, TextRenderable, createCliRenderer } from "@opentui/core";
9
+ //#region src/tui/dashboard.ts
10
+ function createDashboardView(renderer, onOpen, onQuit, onNew, onLogs) {
11
+ const box = new BoxRenderable(renderer, {
12
+ id: "dashboard",
13
+ width: "100%",
14
+ height: "100%",
15
+ flexDirection: "column",
16
+ padding: 1
17
+ });
18
+ box.add(new TextRenderable(renderer, {
19
+ id: "dashboard-title",
20
+ content: "alineo — sessions (↑/↓ move · enter chat · n new · l logs · k kill · r refresh · q quit)"
21
+ }));
22
+ const select = new SelectRenderable(renderer, {
23
+ id: "dashboard-select",
24
+ width: "100%",
25
+ height: "100%",
26
+ options: []
27
+ });
28
+ box.add(select);
29
+ select.focus();
30
+ const status = new TextRenderable(renderer, {
31
+ id: "dashboard-status",
32
+ content: "loading..."
33
+ });
34
+ box.add(status);
35
+ async function refresh() {
36
+ status.content = "refreshing...";
37
+ const { tracked, untracked } = await getSessions();
38
+ const options = tracked.map((s) => ({
39
+ name: `${s.name} ${s.sandboxId.slice(0, 8)}`,
40
+ description: `${formatAge(s.startedAt)} · ${s.execCount} execs`,
41
+ value: s
42
+ }));
43
+ select.options = options.length > 0 ? options : [{
44
+ name: "(no running sessions)",
45
+ description: "press 'n' to start one",
46
+ value: null
47
+ }];
48
+ status.content = untracked.length > 0 ? `${tracked.length} tracked · ${untracked.length} untracked (agent-spawned) sandboxes running` : `${tracked.length} tracked session(s) running`;
49
+ }
50
+ async function killSelected() {
51
+ const session = select.getSelectedOption()?.value;
52
+ if (!session) return;
53
+ status.content = `killing ${session.name}...`;
54
+ try {
55
+ const config = await readConfig();
56
+ await (await new Alineo({
57
+ baseUrl: config.serverUrl,
58
+ apiKey: config.apiKey,
59
+ adapter: new SQLiteAdapter(config.adapterPath),
60
+ useServerProxy: config.useServerProxy
61
+ }).connect(session.sandboxId, session.name)).close();
62
+ await refresh();
63
+ } catch (err) {
64
+ status.content = `failed to kill '${session.name}': ${err instanceof Error ? err.message : String(err)}`;
65
+ }
66
+ }
67
+ select.on(SelectRenderableEvents.ITEM_SELECTED, (_index, option) => {
68
+ if (option.value) onOpen(option.value);
69
+ });
70
+ const onKeypress = (event) => {
71
+ if (event.name === "q") onQuit();
72
+ else if (event.name === "r") refresh();
73
+ else if (event.name === "n") onNew();
74
+ else if (event.name === "k") killSelected();
75
+ else if (event.name === "l") {
76
+ const session = select.getSelectedOption()?.value;
77
+ if (session) onLogs(session);
78
+ }
79
+ };
80
+ renderer.keyInput.on("keypress", onKeypress);
81
+ refresh();
82
+ return {
83
+ box,
84
+ setStatus(message) {
85
+ status.content = message;
86
+ },
87
+ dispose() {
88
+ renderer.keyInput.off("keypress", onKeypress);
89
+ }
90
+ };
91
+ }
92
+ //#endregion
93
+ //#region src/tui/chat.ts
94
+ /**
95
+ * Renders a subset of the `AgentEvent` vocabulary (text, tool_start, tool_end,
96
+ * extension_error) that the web dashboard's `agentChat.ts` also handles, into a
97
+ * scrollbox instead of the DOM — other event types are currently ignored.
98
+ * Pressing Escape returns to the dashboard without calling `agent.close()` —
99
+ * the sandbox and Pi session keep running, same detach semantics as the
100
+ * `spawn`/`prompt` commands.
101
+ */
102
+ function createChatView(renderer, agent, onBack) {
103
+ const box = new BoxRenderable(renderer, {
104
+ id: "chat",
105
+ width: "100%",
106
+ height: "100%",
107
+ flexDirection: "column",
108
+ padding: 1
109
+ });
110
+ box.add(new TextRenderable(renderer, {
111
+ id: "chat-title",
112
+ content: `${agent.name} (${agent.sandboxId}) — esc: back to dashboard (session keeps running)`
113
+ }));
114
+ const scroll = new ScrollBoxRenderable(renderer, {
115
+ id: "chat-scroll",
116
+ width: "100%",
117
+ height: "100%",
118
+ stickyScroll: true,
119
+ stickyStart: "bottom"
120
+ });
121
+ box.add(scroll);
122
+ let lineCounter = 0;
123
+ function appendLine(content) {
124
+ const text = new TextRenderable(renderer, {
125
+ id: `chat-line-${lineCounter++}`,
126
+ content
127
+ });
128
+ scroll.add(text);
129
+ return text;
130
+ }
131
+ const input = new InputRenderable(renderer, {
132
+ id: "chat-input",
133
+ width: "100%",
134
+ placeholder: "Type a prompt and press enter..."
135
+ });
136
+ box.add(input);
137
+ let busy = false;
138
+ async function send(message) {
139
+ if (busy) return;
140
+ busy = true;
141
+ appendLine(`> ${message}`);
142
+ let assistant = null;
143
+ let assistantText = "";
144
+ try {
145
+ for await (const ev of agent.prompt(message)) switch (ev.type) {
146
+ case "text":
147
+ assistantText += ev.text;
148
+ if (assistant) assistant.content = assistantText;
149
+ else assistant = appendLine(assistantText);
150
+ break;
151
+ case "tool_start":
152
+ appendLine(`[tool] ${ev.toolName} ${JSON.stringify(ev.args).slice(0, 160)}`);
153
+ break;
154
+ case "tool_end":
155
+ appendLine(`[tool] ${ev.toolName} ${ev.isError ? "failed" : "done"}`);
156
+ break;
157
+ case "extension_error":
158
+ appendLine(`[extension error] ${ev.extensionPath}: ${ev.error}`);
159
+ break;
160
+ default: break;
161
+ }
162
+ } catch (err) {
163
+ appendLine(`[error] ${err instanceof Error ? err.message : String(err)}`);
164
+ }
165
+ busy = false;
166
+ }
167
+ input.on(InputRenderableEvents.ENTER, (value) => {
168
+ const trimmed = value.trim();
169
+ input.value = "";
170
+ if (trimmed) send(trimmed);
171
+ });
172
+ input.focus();
173
+ const onKeypress = (event) => {
174
+ if (event.name === "escape") onBack();
175
+ };
176
+ renderer.keyInput.on("keypress", onKeypress);
177
+ return {
178
+ box,
179
+ dispose() {
180
+ renderer.keyInput.off("keypress", onKeypress);
181
+ input.blur();
182
+ }
183
+ };
184
+ }
185
+ //#endregion
186
+ //#region src/tui/new-session.ts
187
+ const REGISTRY_INDEX_URL = "https://registry.alineo.dev/agents/index.json";
188
+ async function fetchRegistryItems() {
189
+ const res = await fetch(REGISTRY_INDEX_URL, { signal: AbortSignal.timeout(5e3) });
190
+ if (!res.ok) throw new Error(`registry returned ${res.status}`);
191
+ return await res.json();
192
+ }
193
+ async function listLocalSpecs(config) {
194
+ if (!existsSync(config.agentsDir)) return [];
195
+ const out = [];
196
+ for (const f of readdirSync(config.agentsDir).filter((f) => f.endsWith(".json"))) try {
197
+ const specPath = join(config.agentsDir, f);
198
+ const spec = await Bun.file(specPath).json();
199
+ const name = spec.name ?? f.replace(/\.json$/, "");
200
+ out.push({
201
+ name,
202
+ specPath,
203
+ title: spec.title ?? name,
204
+ description: spec.description ?? ""
205
+ });
206
+ } catch {}
207
+ return out;
208
+ }
209
+ /**
210
+ * Combines locally-`add`ed specs with the registry.alineo.dev catalog into one
211
+ * pick list. Selecting a registry entry fetches + saves it (via the same
212
+ * `add()` command `alineo add` uses) before launching, so it becomes a local
213
+ * spec from then on.
214
+ */
215
+ function createNewSessionView(renderer, onLaunch, onCancel) {
216
+ const box = new BoxRenderable(renderer, {
217
+ id: "new-session",
218
+ width: "100%",
219
+ height: "100%",
220
+ flexDirection: "column",
221
+ padding: 1
222
+ });
223
+ box.add(new TextRenderable(renderer, {
224
+ id: "new-session-title",
225
+ content: "alineo — start an agent (↑/↓ move · enter run · esc cancel)"
226
+ }));
227
+ const select = new SelectRenderable(renderer, {
228
+ id: "new-session-select",
229
+ width: "100%",
230
+ height: "100%",
231
+ options: [{
232
+ name: "loading...",
233
+ description: "",
234
+ value: null
235
+ }]
236
+ });
237
+ box.add(select);
238
+ select.focus();
239
+ const status = new TextRenderable(renderer, {
240
+ id: "new-session-status",
241
+ content: ""
242
+ });
243
+ box.add(status);
244
+ async function load() {
245
+ const local = await listLocalSpecs(await readConfig());
246
+ const localNames = new Set(local.map((l) => l.name));
247
+ const options = local.map((l) => ({
248
+ name: l.name,
249
+ description: l.description,
250
+ origin: "local",
251
+ specPath: l.specPath
252
+ }));
253
+ try {
254
+ const registryItems = await fetchRegistryItems();
255
+ for (const item of registryItems) {
256
+ if (localNames.has(item.name)) continue;
257
+ options.push({
258
+ name: item.name,
259
+ description: item.description,
260
+ origin: "registry",
261
+ registryUrl: item.url
262
+ });
263
+ }
264
+ } catch (err) {
265
+ status.content = `registry unreachable (${err instanceof Error ? err.message : String(err)}) — showing local specs only`;
266
+ }
267
+ select.options = options.length > 0 ? options.map((o) => ({
268
+ name: `${o.name} (${o.origin})`,
269
+ description: o.description,
270
+ value: o
271
+ })) : [{
272
+ name: "(no specs found)",
273
+ description: "add one at registry.alineo.dev, or 'alineo add <url>'",
274
+ value: null
275
+ }];
276
+ }
277
+ async function launch(entry) {
278
+ status.content = `starting ${entry.name}...`;
279
+ try {
280
+ let specPath = entry.specPath;
281
+ if (!specPath && entry.registryUrl) {
282
+ const { add } = await import("./add-Dv8ui6gU.mjs");
283
+ await add(entry.registryUrl, { log: (msg) => status.content = msg });
284
+ specPath = join((await readConfig()).agentsDir, `${entry.name}.json`);
285
+ }
286
+ if (!specPath) throw new Error("no spec path resolved");
287
+ onLaunch(specPath);
288
+ } catch (err) {
289
+ status.content = `failed to start '${entry.name}': ${err instanceof Error ? err.message : String(err)}`;
290
+ }
291
+ }
292
+ select.on(SelectRenderableEvents.ITEM_SELECTED, (_index, option) => {
293
+ const entry = option.value;
294
+ if (entry) launch(entry);
295
+ });
296
+ const onKeypress = (event) => {
297
+ if (event.name === "escape") onCancel();
298
+ };
299
+ renderer.keyInput.on("keypress", onKeypress);
300
+ load();
301
+ return {
302
+ box,
303
+ dispose() {
304
+ renderer.keyInput.off("keypress", onKeypress);
305
+ }
306
+ };
307
+ }
308
+ //#endregion
309
+ //#region src/tui/logs.ts
310
+ function createLogsView(renderer, session, onBack) {
311
+ const box = new BoxRenderable(renderer, {
312
+ id: "logs",
313
+ width: "100%",
314
+ height: "100%",
315
+ flexDirection: "column",
316
+ padding: 1
317
+ });
318
+ box.add(new TextRenderable(renderer, {
319
+ id: "logs-title",
320
+ content: `alineo — logs: ${session.name} (${session.sandboxId.slice(0, 8)}) (↑/↓ scroll · esc back)`
321
+ }));
322
+ const scroll = new ScrollBoxRenderable(renderer, {
323
+ id: "logs-scroll",
324
+ width: "100%",
325
+ height: "100%",
326
+ stickyScroll: true,
327
+ stickyStart: "top"
328
+ });
329
+ box.add(scroll);
330
+ scroll.focus();
331
+ scroll.add(new TextRenderable(renderer, {
332
+ id: "logs-loading",
333
+ content: "loading..."
334
+ }));
335
+ async function load() {
336
+ const config = await readConfig();
337
+ const adapter = new SQLiteAdapter(config.adapterPath);
338
+ await new Alineo({
339
+ baseUrl: config.serverUrl,
340
+ apiKey: config.apiKey,
341
+ adapter,
342
+ useServerProxy: config.useServerProxy
343
+ }).sandboxes.list();
344
+ for (const child of scroll.getChildren()) scroll.remove(child);
345
+ const entries = await adapter.readAll(session.name, session.sandboxId);
346
+ if (entries.length === 0) {
347
+ scroll.add(new TextRenderable(renderer, {
348
+ id: "logs-empty",
349
+ content: "(no events)"
350
+ }));
351
+ return;
352
+ }
353
+ entries.forEach((entry, i) => {
354
+ const ts = new Date(entry.ts).toISOString();
355
+ const suffix = entry.error ? ` error=${entry.error}` : "";
356
+ scroll.add(new TextRenderable(renderer, {
357
+ id: `logs-line-${i}`,
358
+ content: `${ts} ${entry.event}${suffix}`
359
+ }));
360
+ });
361
+ }
362
+ const onKeypress = (event) => {
363
+ if (event.name === "escape") onBack();
364
+ };
365
+ renderer.keyInput.on("keypress", onKeypress);
366
+ load();
367
+ return {
368
+ box,
369
+ dispose() {
370
+ renderer.keyInput.off("keypress", onKeypress);
371
+ }
372
+ };
373
+ }
374
+ //#endregion
375
+ //#region src/tui/index.ts
376
+ async function launchTui() {
377
+ const renderer = await createCliRenderer({ exitOnCtrlC: true });
378
+ const root = new BoxRenderable(renderer, {
379
+ id: "tui-root",
380
+ width: "100%",
381
+ height: "100%"
382
+ });
383
+ renderer.root.add(root);
384
+ let current = null;
385
+ function mount(view) {
386
+ if (current) {
387
+ root.remove(current.box);
388
+ current.dispose();
389
+ }
390
+ current = view;
391
+ root.add(view.box);
392
+ }
393
+ function quit() {
394
+ renderer.destroy();
395
+ process.exit(0);
396
+ }
397
+ function showDashboard(initialStatus) {
398
+ const view = createDashboardView(renderer, (session) => void openSession(session), quit, showNewSession, (session) => mount(createLogsView(renderer, session, () => showDashboard())));
399
+ mount(view);
400
+ if (initialStatus) view.setStatus(initialStatus);
401
+ }
402
+ function showNewSession() {
403
+ mount(createNewSessionView(renderer, (specPath) => void launchNewAgent(specPath), () => showDashboard()));
404
+ }
405
+ async function openSession(session) {
406
+ const config = await readConfig();
407
+ const adapter = new SQLiteAdapter(config.adapterPath);
408
+ try {
409
+ mount(createChatView(renderer, await Agent.resume(session.sandboxId, {
410
+ adapter,
411
+ specPath: `${config.agentsDir}/${session.name}.json`
412
+ }), () => showDashboard()));
413
+ } catch (err) {
414
+ showDashboard(`failed to open '${session.name}': ${err instanceof Error ? err.message : String(err)}`);
415
+ }
416
+ }
417
+ async function launchNewAgent(specPath) {
418
+ const adapter = new SQLiteAdapter((await readConfig()).adapterPath);
419
+ try {
420
+ mount(createChatView(renderer, await Agent.load(specPath, { adapter }), () => showDashboard()));
421
+ } catch (err) {
422
+ showDashboard(`failed to start '${specPath}': ${err instanceof Error ? err.message : String(err)}`);
423
+ }
424
+ }
425
+ showDashboard();
426
+ renderer.start();
427
+ }
428
+ //#endregion
429
+ export { launchTui };
package/package.json ADDED
@@ -0,0 +1,51 @@
1
+ {
2
+ "name": "alineo-cli",
3
+ "version": "0.1.0",
4
+ "license": "Apache-2.0",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/DrejT/alineo.git",
8
+ "directory": "packages/cli"
9
+ },
10
+ "bin": {
11
+ "alineo": "./dist/index.mjs"
12
+ },
13
+ "files": [
14
+ "dist",
15
+ "pi-extension"
16
+ ],
17
+ "type": "module",
18
+ "exports": {
19
+ ".": {
20
+ "import": "./dist/index.mjs"
21
+ }
22
+ },
23
+ "publishConfig": {
24
+ "access": "public",
25
+ "provenance": true
26
+ },
27
+ "scripts": {
28
+ "build": "tsdown",
29
+ "test": "bun test"
30
+ },
31
+ "dependencies": {
32
+ "@alineo-labs/agent": "0.1.0",
33
+ "@alineo-labs/opensandbox": "0.1.0",
34
+ "@alineo-labs/sqlite": "0.1.0",
35
+ "@opentui/core": "^0.4.3",
36
+ "alineo": "0.1.0"
37
+ },
38
+ "devDependencies": {
39
+ "@earendil-works/pi-coding-agent": "^0.80.3",
40
+ "bun-types": "1.3.14",
41
+ "tsdown": "0.22.3",
42
+ "typebox": "^1.3.5",
43
+ "typescript": "6.0.3"
44
+ },
45
+ "pi": {
46
+ "extensions": [
47
+ "./pi-extension/alineo.ts"
48
+ ],
49
+ "extensionsDeprecationNotice": "pi-extension/alineo.ts's alineo_spawn/alineo_prompt/alineo_agents/alineo_kill typed tools have been removed in favor of bash-only CLI usage for all five alineo subcommands (alineo_fork was already bash-only) -- the typed-vs-not asymmetry between them was implicated in issue #21 Bug B (a model reached for the typed alineo_spawn tool instead of the alineo fork shell command the guidance text recommended for that scenario). Kept in place for backward compatibility -- no removal planned yet. The general Pi-extension-loading mechanism itself (this \"pi.extensions\" field, and a spec's own setup steps installing a custom .pi/extensions/*.ts file, e.g. @alineo-labs/agent-browser's) is NOT deprecated -- only this specific extension's typed-tool-registration responsibility is."
50
+ }
51
+ }
@@ -0,0 +1,179 @@
1
+ import type { ExtensionAPI, ExtensionContext, ExecResult } from "@earendil-works/pi-coding-agent";
2
+
3
+ /**
4
+ * DEPRECATED — see the "extensionsDeprecationNotice" field in this package's package.json.
5
+ * Kept in place for backward compatibility (the before_agent_start guidance injection and
6
+ * ensureAlineoReady() bootstrap below still work) — no removal planned yet.
7
+ *
8
+ * Used to also register alineo_spawn/alineo_prompt/alineo_agents/alineo_kill as typed tool calls,
9
+ * wrapping the CLI's session-lifecycle primitives so a Pi agent didn't have to hand-roll shell
10
+ * commands for them. Removed (see issue #21 Bug B): `alineo fork` — the core RLM fan-out
11
+ * primitive — was deliberately never wrapped as a typed tool, on the reasoning that forking is
12
+ * a judgment call about how to decompose a task and belongs in a real shell command the model
13
+ * writes itself, not a verbal decision to call a fixed-shape registered tool. That left spawn/
14
+ * prompt/agents/kill as typed tools sitting right next to fork's bash-only form — an asymmetry
15
+ * that measurably steered models toward the wrong primitive in practice (a real run picked the
16
+ * typed `alineo_spawn` tool over the `alineo fork` shell command the guidance text recommended for
17
+ * that exact scenario). All five subcommands are bash-only now, with no asymmetry to lean on.
18
+ *
19
+ * Install on a host machine (recommended — makes this available in every Pi
20
+ * session afterward, not just one project):
21
+ * pi install npm:alineo-cli
22
+ *
23
+ * `packages/cli/package.json`'s `"pi": { "extensions": [...] }` field is what
24
+ * makes that resolve to this file (see `resolveExtensionEntries()` in Pi's
25
+ * own `package-manager.js`).
26
+ *
27
+ * Install into a single sandbox via a spec's setup steps instead (what
28
+ * `examples/rlm-repo-fanout` does today, project-scoped):
29
+ * npm install -g alineo-cli
30
+ * mkdir -p .pi/extensions && cp "$(npm root -g)/alineo-cli/pi-extension/alineo.ts" .pi/extensions/alineo.ts
31
+ */
32
+ export default function (pi: ExtensionAPI) {
33
+ pi.on("session_start", async (_event, ctx) => {
34
+ await ensureAlineoReady(pi, ctx);
35
+ });
36
+
37
+ // `ALINEO_SANDBOX_ID` is only set inside a sandbox created by an agent-creation
38
+ // path (Agent.load()/resume()/spawn(), see packages/agent/src/agent.ts) — its
39
+ // presence here means THIS Pi process is itself running inside one, so it has
40
+ // live state (installed packages, a checked-out repo, files on disk) worth
41
+ // forking into children via `alineo fork`. A host-level session (a user's own
42
+ // local Pi, no sandbox of its own) has nothing to fork — only `alineo spawn`
43
+ // (start a fresh, independent agent) makes sense there.
44
+ const canFork = Boolean(process.env.ALINEO_SANDBOX_ID);
45
+
46
+ // Mechanical CLI guidance (above) is safe to inject unconditionally — it's
47
+ // just "here's the syntax," true for any session. The RLM *mindset* prompt
48
+ // below is opt-in: a one-off coding session shouldn't be told "you are an
49
+ // orchestrator" unconditionally, only a spec deliberately built to act as
50
+ // one. Gated on ALINEO_RLM_MASTER (set in that spec's own `env`), with
51
+ // ALINEO_RLM_SYSTEM_PROMPT as a full override for specs that want their own
52
+ // wording instead of the default — same ${VAR}-interpolation pattern every
53
+ // other agent-spec env value already uses (see
54
+ // examples/rlm-repo-fanout/agents/master.json's RLM_FANOUT_SECRET/
55
+ // MASTER_AGENT_OPENSANDBOX_DOMAIN for the existing precedent).
56
+ const rlmMindset = process.env.ALINEO_RLM_SYSTEM_PROMPT
57
+ ? `\n\n${process.env.ALINEO_RLM_SYSTEM_PROMPT}`
58
+ : process.env.ALINEO_RLM_MASTER
59
+ ? DEFAULT_RLM_MINDSET
60
+ : "";
61
+
62
+ pi.on("before_agent_start", (event) => ({
63
+ systemPrompt: event.systemPrompt + (canFork ? FORK_GUIDANCE : SPAWN_ONLY_GUIDANCE) + rlmMindset,
64
+ }));
65
+ }
66
+
67
+ const FORK_GUIDANCE = `
68
+
69
+ ## Orchestrating sub-agents with alineo
70
+
71
+ You have the \`alineo\` CLI available. Your own session is running inside a
72
+ alineo-managed sandbox, so you can fork YOUR OWN live filesystem state
73
+ (installed packages, a checked-out repo, any files already on disk) into
74
+ independent child agents:
75
+
76
+ alineo fork <your-session-name> <child-spec.json> --prompt "<plain-English instruction>" --json
77
+
78
+ Each forked child starts from your exact current state, not a fresh clone —
79
+ use this when children need to see something you've already set up. Run this
80
+ as an actual shell command via your bash tool, not by describing it — you
81
+ decide how many children to fork and how to split the work; nothing scripts
82
+ that decision for you. Add \`--depth N\` / \`--max N\` to override a spec's own
83
+ nesting-depth or total-descendant budget if it has one.
84
+
85
+ To start a completely independent agent instead (no shared state needed):
86
+ \`alineo spawn <spec.json> --prompt "<msg>" --json\`. Other commands:
87
+ \`alineo agents [--json]\` (list running sessions), \`alineo prompt <sandbox-id>
88
+ <msg>\` (continue talking to one), \`alineo kill <sandbox-id>\` (stop one).
89
+
90
+ Only reach for forking when a task genuinely splits into independent pieces
91
+ of real size — for something you can finish yourself in a few tool calls,
92
+ just do it directly.`;
93
+
94
+ const SPAWN_ONLY_GUIDANCE = `
95
+
96
+ ## Starting sub-agents with alineo
97
+
98
+ You have the \`alineo\` CLI available to start independent agent sessions in
99
+ their own sandboxes:
100
+
101
+ alineo spawn <spec.json> --prompt "<msg>" --json
102
+
103
+ Other commands: \`alineo agents [--json]\` (list running sessions), \`alineo
104
+ prompt <sandbox-id> <msg>\` (continue talking to one), \`alineo kill
105
+ <sandbox-id>\` (stop one). A spawned agent running inside its own sandbox may
106
+ itself be able to fork further sub-agents from its own live state via
107
+ \`alineo fork\` — that's its own decision to make, not yours to script for it.`;
108
+
109
+ const DEFAULT_RLM_MINDSET = `
110
+
111
+ ## Your role: RLM orchestrator
112
+
113
+ Think in terms of decompose, delegate, and collect. When a task is large
114
+ enough to genuinely split into independent pieces, prefer forking dedicated
115
+ sub-agents over doing everything yourself in one long session — each
116
+ sub-agent should get a clear, bounded slice of the work and report back a
117
+ concise result, not its full transcript. Keep your own context focused on
118
+ decomposition and integration, not on redoing what a child already did. For
119
+ small or genuinely atomic tasks, just do the work yourself — decomposition
120
+ should reflect the task's real shape, not be forced on something that
121
+ doesn't need it.`;
122
+
123
+ // Runs once per extension load, not once per `session_start` — that event
124
+ // also fires on reload/new/resume/fork, and `alineo init` (while itself
125
+ // idempotent) has a few seconds of Docker-state-check overhead not worth
126
+ // repeating every time. Reset on failure so a later session_start can retry
127
+ // instead of a transient failure (no network, Docker not running yet)
128
+ // permanently wedging bootstrap for the rest of the process.
129
+ let bootstrapped = false;
130
+
131
+ async function execOk(
132
+ pi: ExtensionAPI,
133
+ command: string,
134
+ args: string[],
135
+ ): Promise<ExecResult | null> {
136
+ try {
137
+ return await pi.exec(command, args);
138
+ } catch {
139
+ return null;
140
+ }
141
+ }
142
+
143
+ /**
144
+ * Ensures `alineo` is installed and OpenSandbox is reachable, so the user
145
+ * never has to run either setup step themselves — this extension is meant
146
+ * to be the entire distribution/setup path. `alineo init` already no-ops
147
+ * cleanly when OpenSandbox is already running (see `packages/cli/src/commands/init.ts`),
148
+ * so it's safe to call unconditionally rather than trying to detect
149
+ * reachability here first.
150
+ */
151
+ async function ensureAlineoReady(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
152
+ if (bootstrapped) return;
153
+ bootstrapped = true;
154
+
155
+ const check = await execOk(pi, "alineo", ["--version"]);
156
+ if (!check || check.code !== 0) {
157
+ ctx.ui.notify("Installing alineo...", "info");
158
+ const install = await execOk(pi, "npm", ["install", "-g", "alineo-cli"]);
159
+ if (!install || install.code !== 0) {
160
+ ctx.ui.notify(
161
+ `Failed to install alineo: ${install?.stderr || "npm not available"}. ` +
162
+ `RLM flows won't work until this is resolved — install manually with "npm install -g alineo-cli".`,
163
+ "error",
164
+ );
165
+ bootstrapped = false;
166
+ return;
167
+ }
168
+ }
169
+
170
+ const init = await execOk(pi, "alineo", ["init"]);
171
+ if (!init || init.code !== 0) {
172
+ ctx.ui.notify(
173
+ `"alineo init" failed: ${init?.stderr || "unknown error"}. ` +
174
+ `RLM flows won't work until OpenSandbox is reachable — see "alineo init" for manual setup.`,
175
+ "warning",
176
+ );
177
+ bootstrapped = false;
178
+ }
179
+ }