alineo-cli 0.3.0 → 0.4.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.
@@ -20,18 +20,18 @@ async function list() {
20
20
  ];
21
21
  console.log([
22
22
  "NAME",
23
- "CLI",
23
+ "HARNESS",
24
24
  "DESCRIPTION"
25
25
  ].map((h, i) => cols[i] ? h.padEnd(cols[i]) : h).join(" "));
26
26
  console.log("-".repeat(60));
27
27
  for (const file of files) try {
28
28
  const spec = await Bun.file(join(dir, file)).json();
29
29
  const name = (spec.name ?? file.replace(/\.json$/, "")).slice(0, 19);
30
- const cli = (spec.cli ?? "?").slice(0, 7);
30
+ const harness = (spec.harness ?? "?").slice(0, 7);
31
31
  const desc = spec.description ?? spec.title ?? "";
32
32
  console.log([
33
33
  name.padEnd(cols[0]),
34
- cli.padEnd(cols[1]),
34
+ harness.padEnd(cols[1]),
35
35
  desc
36
36
  ].join(" "));
37
37
  } catch {
@@ -1,4 +1,4 @@
1
1
  //#region package.json
2
- var version = "0.3.0";
2
+ var version = "0.4.0";
3
3
  //#endregion
4
4
  export { version };
@@ -6,7 +6,7 @@ import { SQLiteAdapter } from "@alineo-labs/sqlite";
6
6
  //#region src/commands/prompt.ts
7
7
  /**
8
8
  * Addressed by sandbox ID, not session name — names aren't unique (re-running
9
- * `alineo spawn` on the same spec produces two sandboxes with the same name)
9
+ * `alineo start` on the same spec produces two sandboxes with the same name)
10
10
  * and a name-based ledger lookup can hand back a sandbox that died ungracefully
11
11
  * (crashed before its `close()` ran, expired via OpenSandbox's own TTL) since
12
12
  * nothing ever told the ledger it stopped. `Alineo.resume()`'s own `connect()`
@@ -16,7 +16,7 @@ import { SQLiteAdapter } from "@alineo-labs/sqlite";
16
16
  * `opts.specPath` lets a caller skip `Alineo.resume()`'s own ledger lookup for
17
17
  * the spec file entirely — necessary when prompting a sandbox whose
18
18
  * `sandbox_created` event lives in a different ledger than this CLI
19
- * invocation's own (e.g. a child spawned via `alineo fork` from inside
19
+ * invocation's own (e.g. a child spawned via `alineo spawn` from inside
20
20
  * another sandbox).
21
21
  */
22
22
  async function prompt(sandboxId, message, opts = {}) {
@@ -4,7 +4,7 @@ import { SQLiteAdapter } from "@alineo-labs/sqlite";
4
4
  import { ControlClient, SandboxState } from "@alineo-labs/opensandbox";
5
5
  //#region src/sessions-data.ts
6
6
  /**
7
- * Data layer shared by `alineo ps` and the TUI dashboard: alineo-tracked running
7
+ * Data layer shared by `alineo agents` and the TUI dashboard: alineo-tracked running
8
8
  * sessions from the ledger, merged with raw OpenSandbox sandboxes the ledger
9
9
  * never recorded.
10
10
  *
@@ -4,26 +4,26 @@ import { t as collectReply } from "./agent-prompt-DeTX84DU.mjs";
4
4
  import { Alineo } from "alineo";
5
5
  import { Sandbox, SandboxStatus } from "@alineo-labs/sandbox";
6
6
  import { SQLiteAdapter } from "@alineo-labs/sqlite";
7
- //#region src/commands/fork.ts
7
+ //#region src/commands/spawn.ts
8
8
  /**
9
- * Fork a running session's own sandbox into a brand-new independent child, per
10
- * `Alineo.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 `Alineo.attach()`, not
12
- * `Alineo.resume()`, to avoid killing the very bridge process making this call.
9
+ * Spawn a child agent from a running session's own live sandbox, per
10
+ * `Alineo.spawn()`. Meant to be run BY that session's own Pi bash tool — `parent`
11
+ * is the caller's own running session, not the child's. Uses `Alineo.attach()`,
12
+ * not `Alineo.resume()`, to avoid closing the very bridge process making this call.
13
13
  *
14
14
  * Resolves the caller's own sandbox ID from `ALINEO_SANDBOX_ID` when present
15
15
  * (written to `/etc/alineo-env` by every agent-creation path, so it's already
16
16
  * in this process's env since it's a descendant of Pi's own bridge process) —
17
17
  * preferred over a ledger lookup when available, since the calling agent may
18
18
  * have been created via an `IStorageAdapter` this CLI invocation has no
19
- * access to (e.g. a host-side ledger for an `Alineo.load()` call this
19
+ * access to (e.g. a host-side ledger for an `Alineo.start()` call this
20
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
21
+ * looking `parent` up in the ledger of currently-running sessions when
22
+ * `ALINEO_SANDBOX_ID` isn't set (e.g. invoked outside a sandbox). `parent` also
23
23
  * always labels the resulting `Alineo` object.
24
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]");
25
+ async function spawn(parent, childSpecPath, opts = {}) {
26
+ if (!parent || !childSpecPath) throw new Error("Usage: alineo spawn <parent> <child-spec> [--prompt <msg>] [--depth N] [--max N] [--timeout SECONDS] [--json]");
27
27
  const config = await readConfig();
28
28
  const adapter = new SQLiteAdapter(config.adapterPath);
29
29
  let selfSandboxId = process.env.ALINEO_SANDBOX_ID;
@@ -33,13 +33,13 @@ async function fork(name, childSpecPath, opts = {}) {
33
33
  apiKey: config.apiKey,
34
34
  adapter,
35
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.`);
36
+ }).sandboxes.list({ status: SandboxStatus.Running })).find((s) => s.name === parent);
37
+ if (!session) throw new Error(`No running session named '${parent}'. Run 'alineo agents' to see running sessions.`);
38
38
  selfSandboxId = session.sandboxId;
39
39
  }
40
40
  const child = await (await Alineo.attach(selfSandboxId, {
41
41
  adapter,
42
- name
42
+ name: parent
43
43
  })).spawn(childSpecPath, {
44
44
  spawnDepth: opts.depth,
45
45
  maxAgents: opts.max
@@ -54,7 +54,7 @@ async function fork(name, childSpecPath, opts = {}) {
54
54
  }, null, 2));
55
55
  return;
56
56
  }
57
- console.log(`\n[alineo] forked: ${child.name} sandbox: ${child.sandboxId}`);
57
+ console.log(`\n[alineo] spawned: ${child.name} sandbox: ${child.sandboxId}`);
58
58
  if (collected) {
59
59
  if (collected.text) console.log(`\n${collected.text}`);
60
60
  else if (collected.toolCalls.length > 0) {
@@ -63,20 +63,20 @@ async function fork(name, childSpecPath, opts = {}) {
63
63
  }
64
64
  }
65
65
  }
66
- const forkCommand = {
67
- name: "fork",
66
+ const spawnCommand = {
67
+ name: "spawn",
68
68
  group: "agent",
69
69
  variants: [{
70
- usage: "alineo fork <name> <child-spec>",
71
- summary: "Fork a running session's own live sandbox into a new child"
70
+ usage: "alineo spawn <parent> <child-spec>",
71
+ summary: "Spawn a child from a running session's own live sandbox"
72
72
  }],
73
73
  run: async (argv) => {
74
- const name = argv[0] ?? "";
74
+ const parent = argv[0] ?? "";
75
75
  const childSpec = argv.slice(1).find((a) => !a.startsWith("--")) ?? "";
76
76
  const depthFlag = flag(argv, "--depth");
77
77
  const maxFlag = flag(argv, "--max");
78
78
  const timeoutFlag = flag(argv, "--timeout");
79
- await fork(name, childSpec, {
79
+ await spawn(parent, childSpec, {
80
80
  prompt: flag(argv, "--prompt"),
81
81
  depth: depthFlag !== void 0 ? Number(depthFlag) : void 0,
82
82
  max: maxFlag !== void 0 ? Number(maxFlag) : void 0,
@@ -86,4 +86,4 @@ const forkCommand = {
86
86
  }
87
87
  };
88
88
  //#endregion
89
- export { forkCommand };
89
+ export { spawnCommand };
@@ -3,20 +3,20 @@ import { t as flag } from "./args-BBPtXttx.mjs";
3
3
  import { t as collectReply } from "./agent-prompt-DeTX84DU.mjs";
4
4
  import { Alineo } from "alineo";
5
5
  import { SQLiteAdapter } from "@alineo-labs/sqlite";
6
- //#region src/commands/spawn.ts
6
+ //#region src/commands/start.ts
7
7
  /**
8
8
  * Start a brand-new, independent agent sandbox from a spec's own snapshot —
9
- * unlike `alineo fork`, which forks a running session's *live* sandbox state
10
- * instead. This is the entry point for a fresh session (e.g. a host-level Pi
11
- * session starting the master of an RLM run); `fork` is what a running
12
- * session uses to fan out its own live state into children.
9
+ * unlike `alineo spawn`, which forks a running session's *live* sandbox state
10
+ * into a child instead. This is the entry point for a fresh session (e.g. a
11
+ * host-level Pi session starting the master of an RLM run); `alineo spawn` is
12
+ * what a running session uses to fan out its own live state into children.
13
13
  */
14
- async function spawn(specPath, opts = {}) {
15
- if (!specPath) throw new Error("Usage: alineo spawn <spec> [--prompt <msg>] [--rebuild] [--depth N] [--max N] [--timeout SECONDS] [--run-id ID] [--json]");
14
+ async function start(specPath, opts = {}) {
15
+ if (!specPath) throw new Error("Usage: alineo start <spec> [--prompt <msg>] [--rebuild] [--depth N] [--max N] [--timeout SECONDS] [--run-id ID] [--json]");
16
16
  const config = await readConfig();
17
17
  const adapter = new SQLiteAdapter(config.adapterPath);
18
18
  const spec = await Bun.file(specPath).json();
19
- const agent = await Alineo.load(spec, {
19
+ const agent = await Alineo.start(spec, {
20
20
  adapter,
21
21
  rebuild: opts.rebuild,
22
22
  spawnDepth: opts.depth,
@@ -42,14 +42,14 @@ async function spawn(specPath, opts = {}) {
42
42
  }
43
43
  }
44
44
  }
45
- const spawnCommand = {
46
- name: "spawn",
45
+ const startCommand = {
46
+ name: "start",
47
47
  group: "agent",
48
48
  variants: [{
49
- usage: "alineo spawn <spec>",
49
+ usage: "alineo start <spec>",
50
50
  summary: "Start a fresh agent sandbox, print its name, exit"
51
51
  }, {
52
- usage: "alineo spawn <spec> --prompt <msg>",
52
+ usage: "alineo start <spec> --prompt <msg>",
53
53
  summary: "Start it, send one prompt, print the reply, exit"
54
54
  }],
55
55
  run: async (argv) => {
@@ -57,7 +57,7 @@ const spawnCommand = {
57
57
  const depthFlag = flag(argv, "--depth");
58
58
  const maxFlag = flag(argv, "--max");
59
59
  const timeoutFlag = flag(argv, "--timeout");
60
- await spawn(specPath, {
60
+ await start(specPath, {
61
61
  prompt: flag(argv, "--prompt"),
62
62
  rebuild: argv.includes("--rebuild"),
63
63
  json: argv.includes("--json"),
@@ -69,4 +69,4 @@ const spawnCommand = {
69
69
  }
70
70
  };
71
71
  //#endregion
72
- export { spawnCommand };
72
+ export { startCommand };
@@ -16,18 +16,18 @@ import { SQLiteAdapter } from "@alineo-labs/sqlite";
16
16
  * there with zero side effects, then a plain ack-only RPC call delivers the message.
17
17
  *
18
18
  * Addressed by sandbox ID only, same reasoning as `prompt.ts`: names aren't unique and a
19
- * name-based lookup can hand back a session that died ungracefully. `alineo fork ... --json`
19
+ * name-based lookup can hand back a session that died ungracefully. `alineo spawn ... --json`
20
20
  * already reports back the child's `sandboxId` — that's what a parent passes here.
21
21
  *
22
22
  * No spec is required — the sandbox's own ledger entry gives us its real name for a readable
23
- * log line; a bare `{ name, cli: "pi" }` stub is otherwise enough for `reattach()` (env/budget
23
+ * log line; a bare `{ name, harness: "pi" }` stub is otherwise enough for `reattach()` (env/budget
24
24
  * resolution only matters for a fresh bridge start, which this never does). Pass `--spec
25
25
  * <path>` only if the child's real spec happens to be on hand locally.
26
26
  *
27
27
  * Timing: `steer` is delivered after the target's CURRENT turn finishes its tool calls, but
28
28
  * before its next LLM call — it does not interrupt a tool call already running (Pi's own RPC
29
29
  * semantics, not alineo's). If you need to cut off a child immediately regardless of what
30
- * it's doing, use `alineo kill <sandbox-id>` instead; steer is for redirecting cleanly, not
30
+ * it's doing, use `alineo stop <sandbox-id>` instead; steer is for redirecting cleanly, not
31
31
  * stopping urgently.
32
32
  */
33
33
  async function steer(sandboxId, message, opts = {}) {
@@ -44,7 +44,7 @@ async function steer(sandboxId, message, opts = {}) {
44
44
  adapter,
45
45
  ...opts.specPath ? { specPath: opts.specPath } : { spec: {
46
46
  name: displayName,
47
- cli: "pi"
47
+ harness: "pi"
48
48
  } }
49
49
  });
50
50
  await agent.steer(message);
@@ -1,15 +1,15 @@
1
1
  import { i as readConfig } from "./index.mjs";
2
2
  import { Sandbox } from "@alineo-labs/sandbox";
3
3
  import { SQLiteAdapter } from "@alineo-labs/sqlite";
4
- //#region src/commands/kill.ts
4
+ //#region src/commands/stop.ts
5
5
  /**
6
6
  * Addressed by sandbox ID, not session name — see prompt.ts for why: names
7
7
  * aren't unique and a name-based ledger lookup can hand back a sandbox that
8
8
  * already died ungracefully. `client.connect()`'s live control-plane check
9
- * is the actual authority on whether it still exists to kill.
9
+ * is the actual authority on whether it still exists to stop.
10
10
  */
11
- async function kill(sandboxId) {
12
- if (!sandboxId) throw new Error("Usage: alineo kill <sandbox-id>");
11
+ async function stop(sandboxId) {
12
+ if (!sandboxId) throw new Error("Usage: alineo stop <sandbox-id>");
13
13
  const config = await readConfig();
14
14
  const adapter = new SQLiteAdapter(config.adapterPath);
15
15
  await (await new Sandbox({
@@ -18,18 +18,18 @@ async function kill(sandboxId) {
18
18
  adapter,
19
19
  useServerProxy: config.useServerProxy
20
20
  }).connect(sandboxId, sandboxId)).close();
21
- console.log(`Killed sandbox ${sandboxId}`);
21
+ console.log(`Stopped sandbox ${sandboxId}`);
22
22
  }
23
- const killCommand = {
24
- name: "kill",
23
+ const stopCommand = {
24
+ name: "stop",
25
25
  group: "agent",
26
26
  variants: [{
27
- usage: "alineo kill <sandbox-id>",
27
+ usage: "alineo stop <sandbox-id>",
28
28
  summary: "Stop a sandbox"
29
29
  }],
30
30
  run: async (argv) => {
31
- await kill(argv[0] ?? "");
31
+ await stop(argv[0] ?? "");
32
32
  }
33
33
  };
34
34
  //#endregion
35
- export { killCommand };
35
+ export { stopCommand };
@@ -1,5 +1,5 @@
1
1
  import { i as readConfig } from "./index.mjs";
2
- import { n as getSessions, t as formatAge } from "./sessions-data-C8XZge-w.mjs";
2
+ import { n as getSessions, t as formatAge } from "./sessions-data-CceSi5Jz.mjs";
3
3
  import { join } from "path";
4
4
  import { existsSync, readdirSync } from "fs";
5
5
  import { Alineo } from "alineo";
@@ -17,7 +17,7 @@ function createDashboardView(renderer, onOpen, onQuit, onNew, onLogs) {
17
17
  });
18
18
  box.add(new TextRenderable(renderer, {
19
19
  id: "dashboard-title",
20
- content: "alineo — sessions (↑/↓ move · enter chat · n new · l logs · k kill · r refresh · q quit)"
20
+ content: "alineo — sessions (↑/↓ move · enter chat · n new · l logs · s stop · r refresh · q quit)"
21
21
  }));
22
22
  const select = new SelectRenderable(renderer, {
23
23
  id: "dashboard-select",
@@ -47,10 +47,10 @@ function createDashboardView(renderer, onOpen, onQuit, onNew, onLogs) {
47
47
  }];
48
48
  status.content = untracked.length > 0 ? `${tracked.length} tracked · ${untracked.length} untracked (agent-spawned) sandboxes running` : `${tracked.length} tracked session(s) running`;
49
49
  }
50
- async function killSelected() {
50
+ async function stopSelected() {
51
51
  const session = select.getSelectedOption()?.value;
52
52
  if (!session) return;
53
- status.content = `killing ${session.name}...`;
53
+ status.content = `stopping ${session.name}...`;
54
54
  try {
55
55
  const config = await readConfig();
56
56
  await (await new Sandbox({
@@ -61,7 +61,7 @@ function createDashboardView(renderer, onOpen, onQuit, onNew, onLogs) {
61
61
  }).connect(session.sandboxId, session.name)).close();
62
62
  await refresh();
63
63
  } catch (err) {
64
- status.content = `failed to kill '${session.name}': ${err instanceof Error ? err.message : String(err)}`;
64
+ status.content = `failed to stop '${session.name}': ${err instanceof Error ? err.message : String(err)}`;
65
65
  }
66
66
  }
67
67
  select.on(SelectRenderableEvents.ITEM_SELECTED, (_index, option) => {
@@ -71,7 +71,7 @@ function createDashboardView(renderer, onOpen, onQuit, onNew, onLogs) {
71
71
  if (event.name === "q") onQuit();
72
72
  else if (event.name === "r") refresh();
73
73
  else if (event.name === "n") onNew();
74
- else if (event.name === "k") killSelected();
74
+ else if (event.name === "s" || event.name === "k") stopSelected();
75
75
  else if (event.name === "l") {
76
76
  const session = select.getSelectedOption()?.value;
77
77
  if (session) onLogs(session);
@@ -97,7 +97,7 @@ function createDashboardView(renderer, onOpen, onQuit, onNew, onLogs) {
97
97
  * scrollbox instead of the DOM — other event types are currently ignored.
98
98
  * Pressing Escape returns to the dashboard without calling `agent.close()` —
99
99
  * the sandbox and Pi session keep running, same detach semantics as the
100
- * `spawn`/`prompt` commands.
100
+ * `start`/`prompt` commands.
101
101
  */
102
102
  function createChatView(renderer, agent, onBack) {
103
103
  const box = new BoxRenderable(renderer, {
@@ -276,7 +276,7 @@ function createNewSessionView(renderer, onLaunch, onCancel) {
276
276
  try {
277
277
  let specPath = entry.specPath;
278
278
  if (!specPath && entry.registryUrl) {
279
- const { add } = await import("./add-B6Xmz48s.mjs");
279
+ const { add } = await import("./add-BdM-DRC1.mjs");
280
280
  await add(entry.registryUrl, { log: (msg) => status.content = msg });
281
281
  const config = await readConfig();
282
282
  specPath = join(config.agentsDir, `${entry.name}.json`);
@@ -426,7 +426,7 @@ async function launchTui() {
426
426
  const adapter = new SQLiteAdapter(config.adapterPath);
427
427
  try {
428
428
  const spec = await Bun.file(specPath).json();
429
- const agent = await Alineo.load(spec, { adapter });
429
+ const agent = await Alineo.start(spec, { adapter });
430
430
  mount(createChatView(renderer, agent, () => {
431
431
  showDashboard();
432
432
  }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "alineo-cli",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -30,11 +30,12 @@
30
30
  },
31
31
  "dependencies": {
32
32
  "@alineo-labs/logger": "0.1.0",
33
- "@alineo-labs/opensandbox": "0.3.1",
34
- "@alineo-labs/sandbox": "0.4.3",
35
- "@alineo-labs/sqlite": "0.2.3",
33
+ "@alineo-labs/opensandbox": "0.3.2",
34
+ "@alineo-labs/sandbox": "0.5.0",
35
+ "@alineo-labs/sqlite": "0.3.0",
36
36
  "@opentui/core": "^0.4.3",
37
- "alineo": "0.6.0"
37
+ "alineo": "0.7.0",
38
+ "zod": "^4.4.3"
38
39
  },
39
40
  "devDependencies": {
40
41
  "@alineo-labs/cli-shared": "0.0.1",
@@ -47,6 +48,6 @@
47
48
  "extensions": [
48
49
  "./pi-extension/alineo.ts"
49
50
  ],
50
- "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."
51
+ "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 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."
51
52
  }
52
53
  }
@@ -5,16 +5,16 @@ import type { ExtensionAPI, ExtensionContext, ExecResult } from "@earendil-works
5
5
  * Kept in place for backward compatibility (the before_agent_start guidance injection and
6
6
  * ensureAlineoReady() bootstrap below still work) — no removal planned yet.
7
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.
8
+ * Used to also register typed tool calls wrapping the CLI's session-lifecycle primitives, so a
9
+ * Pi agent didn't have to hand-roll shell commands for them. Removed (see issue #21 Bug B):
10
+ * `alineo spawn` — the core RLM fan-out primitive — was deliberately never wrapped as a typed
11
+ * tool, on the reasoning that fanning out is a judgment call about how to decompose a task and
12
+ * belongs in a real shell command the model writes itself, not a verbal decision to call a
13
+ * fixed-shape registered tool. That left the rest as typed tools sitting right next to
14
+ * `alineo spawn`'s bash-only form — an asymmetry that measurably steered models toward the wrong
15
+ * primitive in practice (a real run picked the typed start-an-agent tool over the shell command
16
+ * the guidance text recommended for that exact scenario). All five subcommands are bash-only
17
+ * now, with no asymmetry to lean on.
18
18
  *
19
19
  * Install on a host machine (recommended — makes this available in every Pi
20
20
  * session afterward, not just one project):
@@ -35,13 +35,13 @@ export default function (pi: ExtensionAPI) {
35
35
  });
36
36
 
37
37
  // `ALINEO_SANDBOX_ID` is only set inside a sandbox created by an agent-creation
38
- // path (Alineo.load()/resume()/spawn(), see packages/agent/src/agent.ts) — its
38
+ // path (Alineo.start()/resume()/spawn(), see packages/agent/src/agent.ts) — its
39
39
  // presence here means THIS Pi process is itself running inside one, so it has
40
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);
41
+ // spawning children from via `alineo spawn`. A host-level session (a user's own
42
+ // local Pi, no sandbox of its own) has no live state to spawn from — only
43
+ // `alineo start` (start a fresh, independent agent) makes sense there.
44
+ const canSpawn = Boolean(process.env.ALINEO_SANDBOX_ID);
45
45
 
46
46
  // Mechanical CLI guidance (above) is safe to inject unconditionally — it's
47
47
  // just "here's the syntax," true for any session. The RLM *mindset* prompt
@@ -60,33 +60,34 @@ export default function (pi: ExtensionAPI) {
60
60
  : "";
61
61
 
62
62
  pi.on("before_agent_start", (event) => ({
63
- systemPrompt: event.systemPrompt + (canFork ? FORK_GUIDANCE : SPAWN_ONLY_GUIDANCE) + rlmMindset,
63
+ systemPrompt:
64
+ event.systemPrompt + (canSpawn ? SPAWN_GUIDANCE : START_ONLY_GUIDANCE) + rlmMindset,
64
65
  }));
65
66
  }
66
67
 
67
- const FORK_GUIDANCE = `
68
+ const SPAWN_GUIDANCE = `
68
69
 
69
70
  ## Orchestrating sub-agents with alineo
70
71
 
71
72
  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:
73
+ alineo-managed sandbox, so you can spawn children from YOUR OWN live
74
+ filesystem state (installed packages, a checked-out repo, any files already
75
+ on disk):
75
76
 
76
- alineo fork <your-session-name> <child-spec.json> --prompt "<plain-English instruction>" --json
77
+ alineo spawn <your-session-name> <child-spec.json> --prompt "<plain-English instruction>" --json
77
78
 
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
79
+ Each child starts from your exact current state, not a fresh clone — use this
80
+ when children need to see something you've already set up. Run this as an
81
+ actual shell command via your bash tool, not by describing it — you decide how
82
+ many children to spawn and how to split the work; nothing scripts that
83
+ decision for you. Add \`--depth N\` / \`--max N\` to override a spec's own
83
84
  nesting-depth or total-descendant budget if it has one.
84
85
 
85
86
  To start a completely independent agent instead (no shared state needed):
86
- \`alineo spawn <spec.json> --prompt "<msg>" --json\`. Other commands:
87
+ \`alineo start <spec.json> --prompt "<msg>" --json\`. Other commands:
87
88
  \`alineo agents [--json]\` (list running sessions), \`alineo prompt <sandbox-id>
88
89
  <msg>\` (continue talking to one), \`alineo steer <sandbox-id> <msg>\`
89
- (redirect a child that's already working — see below), \`alineo kill
90
+ (redirect a child that's already working — see below), \`alineo stop
90
91
  <sandbox-id>\` (stop one).
91
92
 
92
93
  Steering a child: \`alineo steer\` delivers your message after the child's
@@ -96,37 +97,37 @@ corrupted. Write the message for THAT child specifically (what its new
96
97
  guidance means given what you asked it to do), not a copy of whatever
97
98
  instruction you yourself received — it has its own narrower context, not
98
99
  your full picture. If a child needs to stop immediately rather than finish
99
- and then redirect, use \`alineo kill\` instead; steer is for adjusting
100
+ and then redirect, use \`alineo stop\` instead; steer is for adjusting
100
101
  course, not for an urgent stop.
101
102
 
102
- Only reach for forking when a task genuinely splits into independent pieces
103
+ Only reach for spawning when a task genuinely splits into independent pieces
103
104
  of real size — for something you can finish yourself in a few tool calls,
104
105
  just do it directly.`;
105
106
 
106
- const SPAWN_ONLY_GUIDANCE = `
107
+ const START_ONLY_GUIDANCE = `
107
108
 
108
109
  ## Starting sub-agents with alineo
109
110
 
110
111
  You have the \`alineo\` CLI available to start independent agent sessions in
111
112
  their own sandboxes:
112
113
 
113
- alineo spawn <spec.json> --prompt "<msg>" --json
114
+ alineo start <spec.json> --prompt "<msg>" --json
114
115
 
115
116
  Other commands: \`alineo agents [--json]\` (list running sessions), \`alineo
116
117
  prompt <sandbox-id> <msg>\` (continue talking to one), \`alineo steer
117
118
  <sandbox-id> <msg>\` (redirect one that's already working — delivered after
118
- its current tool call finishes, not an interrupt; use \`alineo kill\` instead
119
- for an immediate stop), \`alineo kill <sandbox-id>\` (stop one). A spawned
120
- agent running inside its own sandbox may itself be able to fork further
121
- sub-agents from its own live state via \`alineo fork\` — that's its own
122
- decision to make, not yours to script for it.`;
119
+ its current tool call finishes, not an interrupt; use \`alineo stop\` instead
120
+ for an immediate stop), \`alineo stop <sandbox-id>\` (stop one). An agent
121
+ running inside its own sandbox may itself be able to spawn further sub-agents
122
+ from its own live state via \`alineo spawn\` — that's its own decision to
123
+ make, not yours to script for it.`;
123
124
 
124
125
  const DEFAULT_RLM_MINDSET = `
125
126
 
126
- ## Your role: RLM orchestrator
127
+ ## How to approach this work: as an RLM orchestrator
127
128
 
128
129
  Think in terms of decompose, delegate, redirect, and collect. When a task is
129
- large enough to genuinely split into independent pieces, prefer forking
130
+ large enough to genuinely split into independent pieces, prefer spawning
130
131
  dedicated sub-agents over doing everything yourself in one long session —
131
132
  each sub-agent should get a clear, bounded slice of the work and report back a
132
133
  concise result, not its full transcript. Keep your own context focused on
@@ -136,7 +137,7 @@ should reflect the task's real shape, not be forced on something that
136
137
  doesn't need it.`;
137
138
 
138
139
  // Runs once per extension load, not once per `session_start` — that event
139
- // also fires on reload/new/resume/fork, and `alineo init` (while itself
140
+ // also fires on reload/new/resume/spawn, and `alineo init` (while itself
140
141
  // idempotent) has a few seconds of Docker-state-check overhead not worth
141
142
  // repeating every time. Reset on failure so a later session_start can retry
142
143
  // instead of a transient failure (no network, Docker not running yet)