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 +34 -32
- package/dist/index.d.mts +244 -319
- package/dist/index.mjs +727 -237
- package/package.json +7 -4
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
|
-
"
|
|
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.
|
|
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
|
|
54
|
-
|
|
|
55
|
-
| `name`
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `model`
|
|
59
|
-
| `provider`
|
|
60
|
-
| `packages`
|
|
61
|
-
| `env`
|
|
62
|
-
| `resources`
|
|
63
|
-
| `setup`
|
|
64
|
-
| `spawnDepth`
|
|
65
|
-
| `maxAgents`
|
|
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
|
-
"
|
|
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.
|
|
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.
|
|
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.
|
|
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 `
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
221
|
-
const agent2 = await Alineo.
|
|
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
|
|
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.
|
|
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.
|
|
334
|
+
#### `agent.duplicateSession()`
|
|
335
335
|
|
|
336
|
-
Branch the
|
|
336
|
+
Branch the harness conversation at its current position. Returns `{ cancelled: boolean }`.
|
|
337
337
|
|
|
338
|
-
#### `agent.
|
|
338
|
+
#### `agent.branchSession(entryId)`
|
|
339
339
|
|
|
340
|
-
Branch from a specific message entry in
|
|
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.
|
|
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
|
|