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.
package/README.md ADDED
@@ -0,0 +1,195 @@
1
+ # alineo
2
+
3
+ CLI for [alineo](https://alineo.tech) — start a local OpenSandbox server, manage saved agent specs, and run/orchestrate `@alineo-labs/agent` sessions.
4
+
5
+ ```bash
6
+ bunx alineo-cli init
7
+ ```
8
+
9
+ Prefer not to run commands manually at all? `pi install npm:alineo` installs the alineo [Pi extension](#pi-extension), which bootstraps `alineo` automatically and teaches Pi its CLI syntax.
10
+
11
+ ---
12
+
13
+ ## SDK — OpenSandbox config and the local spec cache
14
+
15
+ ### `alineo init`
16
+
17
+ Starts an [OpenSandbox](https://open-sandbox.ai) server in Docker and writes config to `~/.config/alineo/server.toml` and `alineo.config.json`.
18
+
19
+ ```bash
20
+ alineo init
21
+ ```
22
+
23
+ When using a server started this way, `useServerProxy: true` is written into `alineo.config.json` automatically — sandbox containers run on Docker's bridge network and aren't reachable directly from the host.
24
+
25
+ OpenSandbox's own snapshot metadata (what makes `Agent.load()`'s cached-snapshot fast path possible) lives in a SQLite db bind-mounted from `~/.config/alineo/opensandbox-data` into the container — so it survives the container being stopped/started, _and_ being fully removed and recreated (a host reboot with no restart policy, `docker system prune`, a stray `docker rm`). It's only lost if that host directory itself is deleted, or you point a different machine/user at a fresh one. If a cached snapshot ever does fail to restore for some other reason, `Agent.load()` now logs the real error (`[agent] snapshot restore failed (<real error>), rebuilding...`) instead of an undiagnosable `snapshot stale, rebuilding...`.
26
+
27
+ ### `alineo add <url> [--name <n>]`
28
+
29
+ Fetches an agent spec (JSON) from a URL or local file and saves it under `agentsDir` (default `./agents`).
30
+
31
+ ```bash
32
+ alineo add https://registry.alineo.tech/agents/python-data.json
33
+ ```
34
+
35
+ ### `alineo list`
36
+
37
+ Lists saved agent specs.
38
+
39
+ ```bash
40
+ alineo list
41
+ ```
42
+
43
+ ### `alineo remove <name>`
44
+
45
+ Removes a saved agent spec.
46
+
47
+ ```bash
48
+ alineo remove python-data
49
+ ```
50
+
51
+ ### `alineo telemetry status|enable|disable`
52
+
53
+ Shows or changes whether `alineo` sends anonymous usage telemetry — which subcommand ran, a per-command allowlist of boolean flag presence (never values or raw argv), success/failure, and timing. Default-on, sent to `https://telemetry.alineo.tech`.
54
+
55
+ ```bash
56
+ alineo telemetry status
57
+ # [alineo] telemetry: enabled
58
+ # anonymous id: 3f2e9c1a-8b7d-4e6f-a1c2-9d8e7f6a5b4c
59
+ ```
60
+
61
+ Also respects `ALINEO_TELEMETRY_DISABLED=1` and the cross-tool `DO_NOT_TRACK=1` convention, either of which disables telemetry regardless of the persisted config.
62
+
63
+ ---
64
+
65
+ ## Agent — session lifecycle
66
+
67
+ These wrap `@alineo-labs/agent`'s `Agent.load()`/`Agent.resume()`/`Agent.attach()`/`Agent.spawn()`. Sessions are always addressed by **sandbox ID**, not name — names aren't unique (running `alineo spawn` twice on the same spec produces two sandboxes with the same name), and a name-based lookup can hand back a sandbox that already died ungracefully. `alineo spawn`/`alineo fork` print the sandbox ID; save it.
68
+
69
+ ### `alineo spawn <spec> [--prompt <msg>] [--rebuild] [--depth <n>] [--max <n>] [--json]`
70
+
71
+ Start a **brand-new, independent** agent sandbox from a spec's own snapshot. This is the entry point for a fresh session — e.g. a host-level Pi session starting the master of a recursive-agent run.
72
+
73
+ ```bash
74
+ alineo spawn ./agents/my-agent.json
75
+ alineo spawn ./agents/my-agent.json --prompt "Explain this repo" --json
76
+ ```
77
+
78
+ - `--rebuild` forces a full reinstall instead of restoring from the cached snapshot.
79
+ - `--depth <n>` overrides the spec's own `spawnDepth` — see [Recursive spawning](#recursive-spawning-alineo-fork) below.
80
+ - `--max <n>` overrides the spec's own `maxAgents` — see below.
81
+
82
+ ### `alineo prompt <sandbox-id> <msg> [--spec <path>] [--json]`
83
+
84
+ Send one prompt to a running sandbox and print the reply.
85
+
86
+ ```bash
87
+ alineo prompt 4af65c3b-24a2-4fd1-999d-918faa9b97fd "What's in /tmp?"
88
+ ```
89
+
90
+ `--spec <path>` skips the ledger lookup for the spec file — needed when the sandbox's own creation event lives in a different ledger than this CLI invocation's own (e.g. a child spawned via `alineo fork` from inside another sandbox).
91
+
92
+ ### `alineo fork <name> <child-spec> [--prompt <msg>] [--depth <n>] [--max <n>] [--json]`
93
+
94
+ Fork **your own currently-running session's live sandbox** — filesystem, installed packages, everything on disk right now — into a brand-new independent child. Meant to be run by that session's own Pi bash tool: `name` is the _caller's own_ running session (used only to resolve its sandbox ID; not the child's).
95
+
96
+ ```bash
97
+ alineo fork my-session ./agents/worker.json --prompt "Handle the auth module"
98
+ ```
99
+
100
+ Unlike `alineo spawn` (always starts from a spec's own snapshot), `alineo fork` sees exactly what the calling sandbox sees right now, including uncommitted work — no install/setup steps run.
101
+
102
+ ### `alineo agents [--json]`
103
+
104
+ List running agent sessions. Cross-checks the local ledger's "Running" entries against a live query to the OpenSandbox control plane (not just the ledger, which can go stale if a sandbox died ungracefully). Also lists sandboxes running on the same server that weren't created by `alineo` (e.g. agent-spawned children using their own internal ledger).
105
+
106
+ ```bash
107
+ alineo agents
108
+ ```
109
+
110
+ ### `alineo kill <sandbox-id>`
111
+
112
+ Stop a sandbox.
113
+
114
+ ```bash
115
+ alineo kill 4af65c3b-24a2-4fd1-999d-918faa9b97fd
116
+ ```
117
+
118
+ ### `alineo logs <name> [--json]`
119
+
120
+ Print ledger events for a session.
121
+
122
+ ```bash
123
+ alineo logs my-session
124
+ ```
125
+
126
+ ### `alineo --version`
127
+
128
+ Print the installed version.
129
+
130
+ ---
131
+
132
+ ## Recursive spawning (`alineo fork`)
133
+
134
+ A spec's `spawnDepth` is a nesting-depth budget — required for `alineo fork` to be allowed from inside a session at all. Each fork force-decrements it (`current - 1`) into the child's env; `0` means no budget left, `undefined` means forking was never enabled for that spec.
135
+
136
+ `maxAgents` is a separate, optional ceiling on total descendants for one lineage, independent of nesting depth. Unset means uncapped. **Not** coordinated across sibling branches spawned in parallel — it's a per-lineage counter, not a global one.
137
+
138
+ ```json
139
+ {
140
+ "name": "orchestrator",
141
+ "cli": "pi",
142
+ "spawnDepth": 2,
143
+ "maxAgents": 10
144
+ }
145
+ ```
146
+
147
+ ---
148
+
149
+ ## Pi extension
150
+
151
+ `pi install npm:alineo` installs the alineo extension into Pi at user scope. Once installed, any Pi session:
152
+
153
+ - Bootstraps `alineo` automatically on first use (installs it, runs `alineo init`) — no manual setup.
154
+ - Gets `alineo spawn`/`alineo fork` CLI syntax injected into its own guidance, dynamically chosen based on whether the current session is itself running inside a alineo-managed sandbox.
155
+
156
+ The extension source lives at `pi-extension/alineo.ts` in this package.
157
+
158
+ ---
159
+
160
+ ## Manual server setup
161
+
162
+ If you prefer not to use Docker, run the server directly with `uvx`:
163
+
164
+ ```bash
165
+ uvx opensandbox-server
166
+ ```
167
+
168
+ With `~/.sandbox.toml`:
169
+
170
+ ```toml
171
+ [server]
172
+ host = "127.0.0.1"
173
+ port = 8080
174
+
175
+ [runtime]
176
+ type = "docker"
177
+ execd_image = "opensandbox/execd:v1.0.19"
178
+
179
+ [docker]
180
+ network_mode = "bridge"
181
+
182
+ [ingress]
183
+ mode = "direct"
184
+
185
+ [egress]
186
+ mode = "dns"
187
+ ```
188
+
189
+ With this setup, leave `useServerProxy` unset (defaults to `false`) — the server is on the host, so direct container IPs are reachable.
190
+
191
+ ---
192
+
193
+ ## License
194
+
195
+ Apache 2.0
@@ -0,0 +1,47 @@
1
+ import { a as readConfig } from "./index.mjs";
2
+ import { t as flag } from "./args-BBPtXttx.mjs";
3
+ import { join } from "path";
4
+ import { existsSync } from "fs";
5
+ import { mkdir } from "fs/promises";
6
+ import { validateAgentSpec } from "@alineo-labs/agent";
7
+ //#region src/commands/add.ts
8
+ async function add(url, opts = {}) {
9
+ const log = opts.log ?? console.log;
10
+ if (!url) throw new Error("Usage: alineo add <url>");
11
+ const config = await readConfig();
12
+ const spec = await fetchSpec(url);
13
+ for (const depUrl of spec.registryDependencies ?? []) {
14
+ log(`Resolving dependency: ${depUrl}`);
15
+ await add(depUrl, { log });
16
+ }
17
+ const name = opts.name ?? spec.name;
18
+ const agentsDir = config.agentsDir;
19
+ if (!existsSync(agentsDir)) await mkdir(agentsDir, { recursive: true });
20
+ const dest = join(agentsDir, `${name}.json`);
21
+ await Bun.write(dest, JSON.stringify(spec, null, 2) + "\n");
22
+ log(`Agent spec saved: ${dest}`);
23
+ log(`Load it with: Agent.load("${dest}") from @alineo-labs/agent`);
24
+ }
25
+ async function fetchSpec(url) {
26
+ if (url.startsWith("http://") || url.startsWith("https://")) {
27
+ const res = await fetch(url);
28
+ if (!res.ok) throw new Error(`Failed to fetch spec: ${res.status} ${res.statusText}`);
29
+ return validateAgentSpec(await res.json());
30
+ }
31
+ const file = Bun.file(url);
32
+ if (!await file.exists()) throw new Error(`File not found: ${url}`);
33
+ return validateAgentSpec(await file.json());
34
+ }
35
+ const addCommand = {
36
+ name: "add",
37
+ group: "sdk",
38
+ variants: [{
39
+ usage: "alineo add <url> [--name <n>]",
40
+ summary: "Fetch and save an agent spec locally"
41
+ }],
42
+ run: async (argv) => {
43
+ await add(argv.find((a) => !a.startsWith("--")) ?? "", { name: flag(argv, "--name") });
44
+ }
45
+ };
46
+ //#endregion
47
+ export { add, addCommand };
@@ -0,0 +1,17 @@
1
+ //#region src/agent-prompt.ts
2
+ /** Sends one prompt and collects the text chunks plus a record of any tool calls made. */
3
+ async function collectReply(agent, message, opts) {
4
+ let text = "";
5
+ const toolCalls = [];
6
+ for await (const ev of agent.prompt(message, opts)) if (ev.type === "text") text += ev.text;
7
+ else if (ev.type === "tool_end") toolCalls.push({
8
+ name: ev.toolName,
9
+ isError: ev.isError
10
+ });
11
+ return {
12
+ text,
13
+ toolCalls
14
+ };
15
+ }
16
+ //#endregion
17
+ export { collectReply as t };
@@ -0,0 +1,46 @@
1
+ import { n as getSessions, t as formatAge } from "./sessions-data-BYaLq9wh.mjs";
2
+ //#region src/commands/agents.ts
3
+ async function agents(opts = {}) {
4
+ const { tracked, untracked } = await getSessions();
5
+ if (opts.json) {
6
+ console.log(JSON.stringify(tracked, null, 2));
7
+ return;
8
+ }
9
+ const cols = [
10
+ 20,
11
+ 38,
12
+ 10,
13
+ 10
14
+ ];
15
+ console.log([
16
+ "NAME",
17
+ "SANDBOX ID",
18
+ "STARTED",
19
+ "EXECS"
20
+ ].map((h, i) => h.padEnd(cols[i])).join(" "));
21
+ console.log("-".repeat(80));
22
+ for (const s of tracked) console.log([
23
+ s.name.slice(0, cols[0] - 1).padEnd(cols[0]),
24
+ s.sandboxId.padEnd(cols[1]),
25
+ formatAge(s.startedAt).padEnd(cols[2]),
26
+ String(s.execCount).padEnd(cols[3])
27
+ ].join(" "));
28
+ if (tracked.length === 0) console.log("(no running alineo-tracked sessions — run 'alineo spawn <spec>' to start one)");
29
+ if (untracked.length > 0) {
30
+ console.log(`\nUntracked (not created by alineo, e.g. agent-spawned children):`);
31
+ for (const id of untracked) console.log(` ${id}`);
32
+ }
33
+ }
34
+ const agentsCommand = {
35
+ name: "agents",
36
+ group: "agent",
37
+ variants: [{
38
+ usage: "alineo agents [--json]",
39
+ summary: "List running agent sessions"
40
+ }],
41
+ run: async (argv) => {
42
+ await agents({ json: argv.includes("--json") });
43
+ }
44
+ };
45
+ //#endregion
46
+ export { agentsCommand };
@@ -0,0 +1,8 @@
1
+ //#region src/commands/args.ts
2
+ /** Read the value following a `--flag` in argv, e.g. `flag(argv, "--prompt")`. */
3
+ function flag(argv, name) {
4
+ const i = argv.indexOf(name);
5
+ return i !== -1 ? argv[i + 1] : void 0;
6
+ }
7
+ //#endregion
8
+ export { flag as t };
@@ -0,0 +1,89 @@
1
+ import { a as readConfig } from "./index.mjs";
2
+ import { t as flag } from "./args-BBPtXttx.mjs";
3
+ import { t as collectReply } from "./agent-prompt-DeTX84DU.mjs";
4
+ import { Agent } from "@alineo-labs/agent";
5
+ import { Alineo, SandboxStatus } from "alineo";
6
+ import { SQLiteAdapter } from "@alineo-labs/sqlite";
7
+ //#region src/commands/fork.ts
8
+ /**
9
+ * Fork a running session's own sandbox into a brand-new independent child, per
10
+ * `Agent.spawn()`. Meant to be run BY that session's own Pi bash tool — `name` is
11
+ * the caller's own running session, not the child's. Uses `Agent.attach()`, not
12
+ * `Agent.resume()`, to avoid killing the very bridge process making this call.
13
+ *
14
+ * Resolves the caller's own sandbox ID from `ALINEO_SANDBOX_ID` when present
15
+ * (written to `/etc/alineo-env` by every agent-creation path, so it's already
16
+ * in this process's env since it's a descendant of Pi's own bridge process) —
17
+ * preferred over a ledger lookup when available, since the calling agent may
18
+ * have been created via an `IStorageAdapter` this CLI invocation has no
19
+ * access to (e.g. a host-side ledger for an `Agent.load()` call this
20
+ * sandbox's own `alineo.config.json` knows nothing about). Falls back to
21
+ * looking `name` up in the ledger of currently-running sessions when
22
+ * `ALINEO_SANDBOX_ID` isn't set (e.g. invoked outside a sandbox). `name` also
23
+ * always labels the resulting `Agent` object.
24
+ */
25
+ async function fork(name, childSpecPath, opts = {}) {
26
+ if (!name || !childSpecPath) throw new Error("Usage: alineo fork <name> <child-spec> [--prompt <msg>] [--depth N] [--max N] [--timeout SECONDS] [--json]");
27
+ const config = await readConfig();
28
+ const adapter = new SQLiteAdapter(config.adapterPath);
29
+ let selfSandboxId = process.env.ALINEO_SANDBOX_ID;
30
+ if (!selfSandboxId) {
31
+ const session = (await new Alineo({
32
+ baseUrl: config.serverUrl,
33
+ apiKey: config.apiKey,
34
+ adapter,
35
+ useServerProxy: config.useServerProxy
36
+ }).sandboxes.list({ status: SandboxStatus.Running })).find((s) => s.name === name);
37
+ if (!session) throw new Error(`No running session named '${name}'. Run 'alineo agents' to see running sessions.`);
38
+ selfSandboxId = session.sandboxId;
39
+ }
40
+ const child = await (await Agent.attach(selfSandboxId, {
41
+ adapter,
42
+ name
43
+ })).spawn(childSpecPath, {
44
+ spawnDepth: opts.depth,
45
+ maxAgents: opts.max
46
+ });
47
+ const collected = opts.prompt ? await collectReply(child, opts.prompt, { inactivityTimeoutMs: opts.timeoutSeconds !== void 0 ? opts.timeoutSeconds * 1e3 : void 0 }) : void 0;
48
+ if (opts.json) {
49
+ console.log(JSON.stringify({
50
+ name: child.name,
51
+ sandboxId: child.sandboxId,
52
+ reply: collected?.text,
53
+ toolCalls: collected?.toolCalls
54
+ }, null, 2));
55
+ return;
56
+ }
57
+ console.log(`\n[alineo] forked: ${child.name} sandbox: ${child.sandboxId}`);
58
+ if (collected) {
59
+ if (collected.text) console.log(`\n${collected.text}`);
60
+ else if (collected.toolCalls.length > 0) {
61
+ const names = collected.toolCalls.map((t) => t.name).join(", ");
62
+ console.log(`\n[alineo] (no final text — ${collected.toolCalls.length} tool call(s): ${names})`);
63
+ }
64
+ }
65
+ }
66
+ const forkCommand = {
67
+ name: "fork",
68
+ group: "agent",
69
+ variants: [{
70
+ usage: "alineo fork <name> <child-spec>",
71
+ summary: "Fork a running session's own live sandbox into a new child"
72
+ }],
73
+ run: async (argv) => {
74
+ const name = argv[0] ?? "";
75
+ const childSpec = argv.slice(1).find((a) => !a.startsWith("--")) ?? "";
76
+ const depthFlag = flag(argv, "--depth");
77
+ const maxFlag = flag(argv, "--max");
78
+ const timeoutFlag = flag(argv, "--timeout");
79
+ await fork(name, childSpec, {
80
+ prompt: flag(argv, "--prompt"),
81
+ depth: depthFlag !== void 0 ? Number(depthFlag) : void 0,
82
+ max: maxFlag !== void 0 ? Number(maxFlag) : void 0,
83
+ timeoutSeconds: timeoutFlag !== void 0 ? Number(timeoutFlag) : void 0,
84
+ json: argv.includes("--json")
85
+ });
86
+ }
87
+ };
88
+ //#endregion
89
+ export { forkCommand };