alineo 0.5.1 → 0.7.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 CHANGED
@@ -18,7 +18,7 @@ Create an agent spec (`agents/my-agent.json`):
18
18
  {
19
19
  "$schema": "https://registry.alineo.tech/spec/agent.json",
20
20
  "name": "my-agent",
21
- "cli": "pi",
21
+ "harness": "pi",
22
22
  "model": "gemini-flash-latest",
23
23
  "packages": ["python3"],
24
24
  "env": { "GEMINI_API_KEY": "${GEMINI_API_KEY}" },
@@ -32,7 +32,7 @@ import { SQLiteAdapter } from "@alineo-labs/sqlite";
32
32
 
33
33
  const adapter = new SQLiteAdapter("./.alineo/ledger.db");
34
34
  const spec = await Bun.file("./agents/my-agent.json").json();
35
- const agent = await Alineo.load(spec, { adapter });
35
+ const agent = await Alineo.start(spec, { adapter });
36
36
  try {
37
37
  for await (const chunk of textOnly(agent.prompt("Write and run a Python hello world script."))) {
38
38
  process.stdout.write(chunk);
@@ -50,19 +50,19 @@ try {
50
50
 
51
51
  The spec JSON controls the agent's environment, model, and workspace setup.
52
52
 
53
- | Field | Type | Description |
54
- | ------------ | ------------------------ | ---------------------------------------------------------------------------------------------- |
55
- | `name` | `string` | Unique identifier, used as the sandbox session name |
56
- | `cli` | `"pi"` | CLI to run (currently only `"pi"`) |
57
- | `cliVersion` | `string?` | Pin to a specific Pi version, e.g. `"0.80.2"`. Defaults to latest. |
58
- | `model` | `string?` | Model ID passed to Pi via `--model` |
59
- | `provider` | `string?` | AI provider passed via `--provider`. Omit for direct Google API key. |
60
- | `packages` | `string[]?` | APT packages to install before Pi. e.g. `["git", "python3"]` |
61
- | `env` | `Record<string,string>?` | Env vars in the sandbox. Values may reference host env: `"${MY_KEY}"` |
62
- | `resources` | `object?` | CPU/memory limits: `{ cpu: "1000m", memory: "2Gi" }` |
63
- | `setup` | `SetupStep[]?` | Workspace setup steps (see below) |
64
- | `spawnDepth` | `number?` | Nesting-depth budget for `agent.spawn()` — see [Spawning child agents](#spawning-child-agents) |
65
- | `maxAgents` | `number?` | Optional cap on total descendants for this lineage — see below |
53
+ | Field | Type | Description |
54
+ | ---------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
55
+ | `name` | `string` | Unique identifier, used as the sandbox session name |
56
+ | `harness` | `"pi"` | Agent-loop driver to run (currently only `"pi"`) |
57
+ | `harnessVersion` | `string?` | Pin to a specific Pi version, e.g. `"0.80.2"`. Defaults to latest. |
58
+ | `model` | `string?` | Model ID passed to Pi via `--model` |
59
+ | `provider` | `string?` | AI provider passed via `--provider`. Omit for direct Google API key. |
60
+ | `packages` | `string[]?` | APT packages to install before Pi. e.g. `["git", "python3"]` |
61
+ | `env` | `Record<string,string>?` | Env vars in the sandbox. Values may reference host env: `"${MY_KEY}"` |
62
+ | `resources` | `object?` | CPU/memory limits: `{ cpu: "1000m", memory: "2Gi" }` |
63
+ | `setup` | `SetupStep[]?` | Workspace setup steps (see below) |
64
+ | `spawnDepth` | `number?` | Nesting-depth budget for `agent.spawn()` — see [Spawning child agents](#spawning-child-agents) |
65
+ | `maxAgents` | `number?` | Optional cap on total descendants for this lineage — see below |
66
66
 
67
67
  ### Setup steps
68
68
 
@@ -71,7 +71,7 @@ The spec JSON controls the agent's environment, model, and workspace setup.
71
71
  ```json
72
72
  {
73
73
  "name": "my-agent",
74
- "cli": "pi",
74
+ "harness": "pi",
75
75
  "setup": [
76
76
  { "name": "Create workspace", "run": "mkdir -p /workspace" },
77
77
  { "name": "Install deps", "run": "npm install", "cwd": "/workspace" },
@@ -90,7 +90,7 @@ Each step:
90
90
 
91
91
  ### Validation
92
92
 
93
- `Alineo.load()`/`Alineo.resume()` validate the spec (via `validateAgentSpec()`, backed by
93
+ `Alineo.start()`/`Alineo.resume()` validate the spec (via `validateAgentSpec()`, backed by
94
94
  [Zod](https://zod.dev)) before doing anything else. An invalid spec throws
95
95
  `AgentSpecValidationError` — every problem is reported in one throw, not just the first, and
96
96
  `.issues` gives you each one structured (`{ path, message, code }`) instead of having to parse
@@ -101,7 +101,7 @@ import { Alineo, AgentSpecValidationError } from "alineo";
101
101
 
102
102
  try {
103
103
  const spec = await Bun.file("./agent.json").json();
104
- const agent = await Alineo.load(spec, { adapter });
104
+ const agent = await Alineo.start(spec, { adapter });
105
105
  } catch (e) {
106
106
  if (e instanceof AgentSpecValidationError) {
107
107
  for (const issue of e.issues) console.error(`${issue.path.join(".")}: ${issue.message}`);
@@ -114,23 +114,23 @@ try {
114
114
 
115
115
  ## Snapshotting
116
116
 
117
- On first load, `Alineo.load()` installs the Pi CLI and any `setup` steps, then checkpoints the sandbox. Subsequent loads restore from that snapshot — skipping the install entirely.
117
+ On first load, `Alineo.start()` installs the Pi CLI and any `setup` steps, then checkpoints the sandbox. Subsequent loads restore from that snapshot — skipping the install entirely.
118
118
 
119
119
  ```
120
120
  Load 1 (cold): sandbox → Pi install → setup steps → checkpoint → bridge ~50s
121
121
  Load 2 (warm): snapshot restore → bridge ~5s
122
122
  ```
123
123
 
124
- The snapshot is invalidated automatically when `cli`, `cliVersion`, `packages`, or `setup` change.
124
+ The snapshot is invalidated automatically when `harness`, `harnessVersion`, `packages`, or `setup` change.
125
125
 
126
126
  ```ts
127
127
  // adapter: an IStorageAdapter — SQLiteAdapter or PostgresAdapter, see Quickstart
128
128
  const spec = await Bun.file("./agents/my-agent.json").json();
129
- const agent = await Alineo.load(spec, { adapter });
129
+ const agent = await Alineo.start(spec, { adapter });
130
130
  console.log(agent.fromSnapshot); // false on first load, true after
131
131
 
132
132
  // Force a full reinstall:
133
- const agent2 = await Alineo.load(spec, { adapter, rebuild: true });
133
+ const agent2 = await Alineo.start(spec, { adapter, rebuild: true });
134
134
  ```
135
135
 
136
136
  ---
@@ -209,7 +209,7 @@ for await (const ev of agent.prompt("Run /workspace/script.py with python3.")) {
209
209
 
210
210
  ### Loading and lifecycle
211
211
 
212
- #### `Alineo.load(spec, opts)`
212
+ #### `Alineo.start(spec, opts)`
213
213
 
214
214
  Validate `spec`, spin up a sandbox, install Pi, run setup steps, and return a ready `Alineo`. Restores from snapshot on subsequent calls. `opts.adapter` is required (see [Quickstart](#quickstart)).
215
215
 
@@ -217,8 +217,8 @@ Validate `spec`, spin up a sandbox, install Pi, run setup steps, and return a re
217
217
 
218
218
  ```ts
219
219
  const spec = await Bun.file("./agents/my-agent.json").json();
220
- const agent = await Alineo.load(spec, { adapter });
221
- const agent2 = await Alineo.load(spec, { adapter, rebuild: true });
220
+ const agent = await Alineo.start(spec, { adapter });
221
+ const agent2 = await Alineo.start(spec, { adapter, rebuild: true });
222
222
  ```
223
223
 
224
224
  #### `Alineo.resume(sandboxId, opts)`
@@ -240,7 +240,7 @@ const agent3 = await Alineo.resume(savedSandboxId, { adapter, spec });
240
240
 
241
241
  Connect to an already-running sandbox **without** touching its Pi bridge — unlike `resume()`, which kills and restarts the bridge process. Use this when you only need `.spawn()`/`.sandbox`, not `.prompt()`/`.bash()` (the returned `Alineo` has no bridge, so those throw).
242
242
 
243
- The main caller is `alineo fork`: it runs as a fresh CLI process started BY the very Pi bash-tool call it's attaching to (a session forking a child from inside its own turn) — going through `resume()` there would kill the bridge currently running the call itself.
243
+ The main caller is `alineo spawn`: it runs as a fresh CLI process started BY the very Pi bash-tool call it's attaching to (a session forking a child from inside its own turn) — going through `resume()` there would kill the bridge currently running the call itself.
244
244
 
245
245
  ```ts
246
246
  const self = await Alineo.attach(process.env.ALINEO_SANDBOX_ID!, {
@@ -260,7 +260,7 @@ Stop the sandbox container and release all resources. Always call in a `finally`
260
260
 
261
261
  #### `agent.spawn(childSpecPath, opts?)`
262
262
 
263
- Fork **this agent's own live sandbox** — filesystem, installed packages, checked-out state, everything currently on disk — into a brand-new independent sandbox running its own Pi bridge. Unlike `Alineo.load()` (always starts from a spec's own snapshot) or `fork()`/`clone()` (Pi's own conversation-branching — same container, same bridge, new session branch), this is sandbox-level forking: the child sees exactly what this agent's sandbox sees right now, including uncommitted work. No install/setup steps run — the child inherits whatever is already installed on this agent's sandbox.
263
+ Fork **this agent's own live sandbox** — filesystem, installed packages, checked-out state, everything currently on disk — into a brand-new independent sandbox running its own Pi bridge. Unlike `Alineo.start()` (always starts from a spec's own snapshot) or `fork()`/`clone()` (Pi's own conversation-branching — same container, same bridge, new session branch), this is sandbox-level forking: the child sees exactly what this agent's sandbox sees right now, including uncommitted work. No install/setup steps run — the child inherits whatever is already installed on this agent's sandbox.
264
264
 
265
265
  ```ts
266
266
  const child = await agent.spawn("./agents/worker.json", { spawnDepth: 2, maxAgents: 5 });
@@ -331,13 +331,15 @@ Interrupt the current in-progress response immediately.
331
331
 
332
332
  Start a fresh Pi conversation, clearing all context. Filesystem and workspace are unchanged.
333
333
 
334
- #### `agent.clone()`
334
+ #### `agent.duplicateSession()`
335
335
 
336
- Branch the current Pi session at the current position. Returns `{ cancelled: boolean }`.
336
+ Branch the harness conversation at its current position. Returns `{ cancelled: boolean }`.
337
337
 
338
- #### `agent.fork(entryId)`
338
+ #### `agent.branchSession(entryId)`
339
339
 
340
- Branch from a specific message entry in the conversation history. Returns `{ text, cancelled }`.
340
+ Branch the harness conversation from a specific message entry in its history. Returns `{ text, cancelled }`.
341
+
342
+ Both branch a conversation inside the same container. `agent.sandbox.fork()` is the one that copies a filesystem.
341
343
 
342
344
  #### `agent.switchSession(sessionPath)`
343
345
 
@@ -425,7 +427,7 @@ console.log(`${stats.tokens.total} tokens used, $${stats.cost.toFixed(6)} cost`)
425
427
 
426
428
  Retrieve the text of Pi's most recent assistant response without iterating the stream. Returns `null` if Pi hasn't responded yet.
427
429
 
428
- #### `agent.getForkMessages()`
430
+ #### `agent.getBranchPoints()`
429
431
 
430
432
  List the fork entry points available in the current session. Each entry has `entryId` (pass to `fork()`) and `text`.
431
433