alineo 0.1.0 → 0.3.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 +424 -95
- package/dist/index.d.mts +824 -330
- package/dist/index.mjs +1424 -582
- package/dist/pi-bridge.js +766 -0
- package/package.json +11 -11
package/README.md
CHANGED
|
@@ -1,176 +1,505 @@
|
|
|
1
1
|
# alineo
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Run [Pi](https://pi.ai) coding agents inside isolated [alineo](https://alineo.tech) sandbox containers. Pi can read and write files, run shell commands, and execute scripts — streamed back through a simple TypeScript API.
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
|
-
bun add alineo
|
|
6
|
+
bun add alineo
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
**[Full documentation →](https://docs.alineo.tech/docs/
|
|
9
|
+
**[Full documentation →](https://docs.alineo.tech/docs/agent)**
|
|
10
10
|
|
|
11
11
|
---
|
|
12
12
|
|
|
13
13
|
## Quickstart
|
|
14
14
|
|
|
15
|
+
Create an agent spec (`agents/my-agent.json`):
|
|
16
|
+
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"$schema": "https://registry.alineo.tech/spec/agent.json",
|
|
20
|
+
"name": "my-agent",
|
|
21
|
+
"cli": "pi",
|
|
22
|
+
"model": "gemini-flash-latest",
|
|
23
|
+
"packages": ["python3"],
|
|
24
|
+
"env": { "GEMINI_API_KEY": "${GEMINI_API_KEY}" },
|
|
25
|
+
"resources": { "cpu": "1000m", "memory": "2Gi" }
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
15
29
|
```ts
|
|
16
|
-
import { Alineo } from "alineo";
|
|
30
|
+
import { Alineo, textOnly } from "alineo";
|
|
17
31
|
import { SQLiteAdapter } from "@alineo-labs/sqlite";
|
|
18
32
|
|
|
19
|
-
const
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
33
|
+
const adapter = new SQLiteAdapter("./.alineo/ledger.db");
|
|
34
|
+
const spec = await Bun.file("./agents/my-agent.json").json();
|
|
35
|
+
const agent = await Alineo.load(spec, { adapter });
|
|
36
|
+
try {
|
|
37
|
+
for await (const chunk of textOnly(agent.prompt("Write and run a Python hello world script."))) {
|
|
38
|
+
process.stdout.write(chunk);
|
|
39
|
+
}
|
|
40
|
+
} finally {
|
|
41
|
+
await agent.close();
|
|
42
|
+
}
|
|
43
|
+
```
|
|
23
44
|
|
|
24
|
-
|
|
25
|
-
image: "ubuntu:22.04",
|
|
26
|
-
resources: { cpu: "500m", memory: "512Mi" },
|
|
27
|
-
});
|
|
45
|
+
`opts.adapter` is required — `alineo` has no storage-adapter dependency of its own, so you choose: `new SQLiteAdapter(path)` from `@alineo-labs/sqlite` for local dev, or `new PostgresAdapter(connectionString)` from `@alineo-labs/postgres` for production.
|
|
28
46
|
|
|
29
|
-
|
|
30
|
-
console.log(stdout); // v20.x.x
|
|
47
|
+
---
|
|
31
48
|
|
|
32
|
-
|
|
49
|
+
## Alineo spec
|
|
50
|
+
|
|
51
|
+
The spec JSON controls the agent's environment, model, and workspace setup.
|
|
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 |
|
|
66
|
+
|
|
67
|
+
### Setup steps
|
|
68
|
+
|
|
69
|
+
`setup` runs bash commands after Pi CLI install, before the snapshot is taken. Changes to any step automatically invalidate the snapshot cache.
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"name": "my-agent",
|
|
74
|
+
"cli": "pi",
|
|
75
|
+
"setup": [
|
|
76
|
+
{ "name": "Create workspace", "run": "mkdir -p /workspace" },
|
|
77
|
+
{ "name": "Install deps", "run": "npm install", "cwd": "/workspace" },
|
|
78
|
+
{ "name": "Seed data", "run": "node scripts/seed.js", "cwd": "/workspace" }
|
|
79
|
+
]
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Each step:
|
|
84
|
+
|
|
85
|
+
| Field | Type | Description |
|
|
86
|
+
| ------ | --------- | ----------------------------------------------------------------- |
|
|
87
|
+
| `name` | `string` | Human-readable label shown in logs and included in the setup hash |
|
|
88
|
+
| `run` | `string` | Bash command to execute |
|
|
89
|
+
| `cwd` | `string?` | Working directory. Runs as `cd <cwd> && <run>` |
|
|
90
|
+
|
|
91
|
+
### Validation
|
|
92
|
+
|
|
93
|
+
`Alineo.load()`/`Alineo.resume()` validate the spec (via `validateAgentSpec()`, backed by
|
|
94
|
+
[Zod](https://zod.dev)) before doing anything else. An invalid spec throws
|
|
95
|
+
`AgentSpecValidationError` — every problem is reported in one throw, not just the first, and
|
|
96
|
+
`.issues` gives you each one structured (`{ path, message, code }`) instead of having to parse
|
|
97
|
+
the message string:
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
import { Alineo, AgentSpecValidationError } from "alineo";
|
|
101
|
+
|
|
102
|
+
try {
|
|
103
|
+
const spec = await Bun.file("./agent.json").json();
|
|
104
|
+
const agent = await Alineo.load(spec, { adapter });
|
|
105
|
+
} catch (e) {
|
|
106
|
+
if (e instanceof AgentSpecValidationError) {
|
|
107
|
+
for (const issue of e.issues) console.error(`${issue.path.join(".")}: ${issue.message}`);
|
|
108
|
+
}
|
|
109
|
+
throw e;
|
|
110
|
+
}
|
|
33
111
|
```
|
|
34
112
|
|
|
35
113
|
---
|
|
36
114
|
|
|
37
|
-
##
|
|
115
|
+
## Snapshotting
|
|
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.
|
|
38
118
|
|
|
39
|
-
|
|
119
|
+
```
|
|
120
|
+
Load 1 (cold): sandbox → Pi install → setup steps → checkpoint → bridge ~50s
|
|
121
|
+
Load 2 (warm): snapshot restore → bridge ~5s
|
|
122
|
+
```
|
|
40
123
|
|
|
41
|
-
|
|
124
|
+
The snapshot is invalidated automatically when `cli`, `cliVersion`, `packages`, or `setup` change.
|
|
42
125
|
|
|
43
126
|
```ts
|
|
44
|
-
//
|
|
45
|
-
const
|
|
127
|
+
// adapter: an IStorageAdapter — SQLiteAdapter or PostgresAdapter, see Quickstart
|
|
128
|
+
const spec = await Bun.file("./agents/my-agent.json").json();
|
|
129
|
+
const agent = await Alineo.load(spec, { adapter });
|
|
130
|
+
console.log(agent.fromSnapshot); // false on first load, true after
|
|
46
131
|
|
|
47
|
-
//
|
|
48
|
-
await
|
|
132
|
+
// Force a full reinstall:
|
|
133
|
+
const agent2 = await Alineo.load(spec, { adapter, rebuild: true });
|
|
134
|
+
```
|
|
49
135
|
|
|
50
|
-
|
|
51
|
-
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Streaming
|
|
139
|
+
|
|
140
|
+
`agent.prompt()` and `agent.bash()` return an `AgentStream` — an `AsyncIterable<AgentEvent>`:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
type AgentEvent =
|
|
144
|
+
| { type: "text"; text: string }
|
|
145
|
+
| { type: "tool_start"; toolCallId: string; toolName: string; args: unknown }
|
|
146
|
+
| { type: "tool_update"; toolCallId: string; toolName: string; partialResult: unknown }
|
|
147
|
+
| { type: "tool_end"; toolCallId: string; toolName: string; result: unknown; isError: boolean }
|
|
148
|
+
| { type: "extension_ui"; method: string; params: unknown; isDialog: boolean; requestId?: string }
|
|
149
|
+
| {
|
|
150
|
+
type: "auto_retry_start";
|
|
151
|
+
attempt: number;
|
|
152
|
+
maxAttempts: number;
|
|
153
|
+
delayMs: number;
|
|
154
|
+
errorMessage: string;
|
|
155
|
+
}
|
|
156
|
+
| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
|
|
157
|
+
| { type: "agent_start" }
|
|
158
|
+
| { type: "agent_end"; messages: unknown[] }
|
|
159
|
+
| { type: "turn_start"; turnIndex: number; timestamp: number }
|
|
160
|
+
| { type: "turn_end"; turnIndex: number; message: unknown; toolResults: unknown[] }
|
|
161
|
+
| { type: "message_start"; message: unknown }
|
|
162
|
+
| { type: "message_update"; message: unknown; delta: unknown }
|
|
163
|
+
| { type: "message_end"; message: unknown }
|
|
164
|
+
| { type: "queue_update"; steering: string[]; followUp: string[] }
|
|
165
|
+
| { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
|
|
166
|
+
| {
|
|
167
|
+
type: "compaction_end";
|
|
168
|
+
reason: string;
|
|
169
|
+
result: object | null;
|
|
170
|
+
aborted: boolean;
|
|
171
|
+
willRetry: boolean;
|
|
172
|
+
}
|
|
173
|
+
| { type: "extension_error"; extensionPath: string; event: string; error: string };
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Use `textOnly()` to filter to just the text chunks (equivalent to the old `PromptStream` behavior):
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
import { Alineo, textOnly } from "alineo";
|
|
180
|
+
|
|
181
|
+
for await (const chunk of textOnly(agent.prompt("Summarise this repo."))) {
|
|
52
182
|
process.stdout.write(chunk);
|
|
53
183
|
}
|
|
54
184
|
```
|
|
55
185
|
|
|
56
|
-
|
|
186
|
+
### Tool call observability
|
|
187
|
+
|
|
188
|
+
Iterate the raw stream to see every tool Pi uses:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
for await (const ev of agent.prompt("Run /workspace/script.py with python3.")) {
|
|
192
|
+
switch (ev.type) {
|
|
193
|
+
case "text":
|
|
194
|
+
process.stdout.write(ev.text);
|
|
195
|
+
break;
|
|
196
|
+
case "tool_start":
|
|
197
|
+
console.log(`[tool] ${ev.toolName} args=${JSON.stringify(ev.args)}`);
|
|
198
|
+
break;
|
|
199
|
+
case "tool_end":
|
|
200
|
+
console.log(`[tool] ${ev.toolName} done isError=${ev.isError}`);
|
|
201
|
+
break;
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
```
|
|
57
205
|
|
|
58
206
|
---
|
|
59
207
|
|
|
60
|
-
##
|
|
208
|
+
## API reference
|
|
209
|
+
|
|
210
|
+
### Loading and lifecycle
|
|
211
|
+
|
|
212
|
+
#### `Alineo.load(spec, opts)`
|
|
213
|
+
|
|
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
|
+
|
|
216
|
+
`spec` is an already-parsed object, not a file path — `alineo` doesn't do file I/O itself. Read one from disk yourself (`await Bun.file(path).json()`), fetch it over HTTP, or build it programmatically; it's validated internally regardless, so a raw `JSON.parse()`'d object works fine.
|
|
61
217
|
|
|
62
218
|
```ts
|
|
63
|
-
await
|
|
64
|
-
const
|
|
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 });
|
|
222
|
+
```
|
|
65
223
|
|
|
66
|
-
|
|
67
|
-
const info = await sb.getFileInfo("/app/main.py");
|
|
224
|
+
#### `Alineo.resume(sandboxId, opts)`
|
|
68
225
|
|
|
69
|
-
|
|
70
|
-
await sb.replaceInFiles([{ path: "/app/main.py", old: "hello", new: "world" }]);
|
|
226
|
+
Reconnect to an existing sandbox after the host process has exited. Only restarts the bridge — Pi and the workspace are untouched. `opts.adapter` is required.
|
|
71
227
|
|
|
72
|
-
|
|
73
|
-
const files = await sb.searchFiles("*.py", "/app");
|
|
74
|
-
await sb.moveFile("/tmp/out.txt", "/app/out.txt");
|
|
75
|
-
await sb.deleteFile("/app/main.py");
|
|
228
|
+
Unlike `load()`, `resume()` still accepts a bare path (`opts.specPath`) alongside an already-parsed object (`opts.spec`) — if neither is set, the ledger is queried for the sandbox's name and the spec is read from `./agents/<name>.json`.
|
|
76
229
|
|
|
77
|
-
|
|
78
|
-
|
|
230
|
+
```ts
|
|
231
|
+
// Original process saved agent.sandboxId somewhere...
|
|
232
|
+
const agent = await Alineo.resume(savedSandboxId, { adapter });
|
|
233
|
+
// Or provide the spec path explicitly:
|
|
234
|
+
const agent2 = await Alineo.resume(savedSandboxId, { adapter, specPath: "./agents/my-agent.json" });
|
|
235
|
+
// Or provide an already-parsed spec object:
|
|
236
|
+
const agent3 = await Alineo.resume(savedSandboxId, { adapter, spec });
|
|
79
237
|
```
|
|
80
238
|
|
|
81
|
-
|
|
239
|
+
#### `Alineo.attach(sandboxId, opts)`
|
|
240
|
+
|
|
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
|
+
|
|
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.
|
|
82
244
|
|
|
83
245
|
```ts
|
|
84
|
-
const
|
|
85
|
-
|
|
86
|
-
|
|
246
|
+
const self = await Alineo.attach(process.env.ALINEO_SANDBOX_ID!, {
|
|
247
|
+
adapter,
|
|
248
|
+
name: "my-session",
|
|
87
249
|
});
|
|
250
|
+
const child = await self.spawn("./agents/worker.json");
|
|
251
|
+
```
|
|
88
252
|
|
|
89
|
-
|
|
90
|
-
await sb.checkpoint("after-setup");
|
|
91
|
-
await sb.close();
|
|
253
|
+
#### `agent.close()`
|
|
92
254
|
|
|
93
|
-
|
|
94
|
-
const restored = await client.resume(sb.sandboxId);
|
|
95
|
-
await restored.exec("curl https://example.com").pipe(process.stdout);
|
|
96
|
-
await restored.close();
|
|
97
|
-
```
|
|
255
|
+
Stop the sandbox container and release all resources. Always call in a `finally` block.
|
|
98
256
|
|
|
99
|
-
|
|
257
|
+
---
|
|
100
258
|
|
|
101
|
-
|
|
259
|
+
### Spawning child agents
|
|
260
|
+
|
|
261
|
+
#### `agent.spawn(childSpecPath, opts?)`
|
|
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.
|
|
102
264
|
|
|
103
265
|
```ts
|
|
104
|
-
const
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
266
|
+
const child = await agent.spawn("./agents/worker.json", { spawnDepth: 2, maxAgents: 5 });
|
|
267
|
+
try {
|
|
268
|
+
for await (const chunk of textOnly(child.prompt("Handle the auth module"))) {
|
|
269
|
+
process.stdout.write(chunk);
|
|
270
|
+
}
|
|
271
|
+
} finally {
|
|
272
|
+
await child.close();
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
Refuses immediately unless this agent's own spawn-depth budget (`spawnDepth` in the spec, or `opts.spawnDepth` to override) is a positive integer — `0` means no budget left, `undefined` means spawning was never enabled. Each spawn force-decrements the budget (`current - 1`) into the child's env, regardless of what the child's own spec says.
|
|
277
|
+
|
|
278
|
+
`maxAgents` (spec field or `opts.maxAgents`) is a separate, optional ceiling on total descendants for this lineage, independent of nesting depth. Unset means uncapped for this dimension — only `spawnDepth` gates whether spawning is allowed at all. **Not** coordinated across sibling branches spawned in parallel; it's a per-lineage counter.
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
### Streaming
|
|
283
|
+
|
|
284
|
+
#### `agent.prompt(message, opts?)`
|
|
111
285
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
286
|
+
Send a message to Pi and stream the response as `AgentStream`.
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
for await (const chunk of textOnly(agent.prompt("Explain this file."))) {
|
|
290
|
+
process.stdout.write(chunk);
|
|
291
|
+
}
|
|
115
292
|
```
|
|
116
293
|
|
|
117
|
-
|
|
294
|
+
#### `agent.bash(command)`
|
|
295
|
+
|
|
296
|
+
Run a shell command inside Pi's working context and stream stdout as `AgentStream`.
|
|
118
297
|
|
|
119
298
|
```ts
|
|
120
|
-
await
|
|
121
|
-
|
|
299
|
+
for await (const chunk of textOnly(agent.bash("ls -la /workspace"))) {
|
|
300
|
+
process.stdout.write(chunk);
|
|
301
|
+
}
|
|
302
|
+
```
|
|
122
303
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
### Mid-flight control
|
|
307
|
+
|
|
308
|
+
#### `agent.steer(message)`
|
|
127
309
|
|
|
128
|
-
|
|
310
|
+
Redirect Pi's current response mid-flight. Pi acknowledges and adjusts.
|
|
311
|
+
|
|
312
|
+
```ts
|
|
313
|
+
const stream = textOnly(agent.prompt("Write an essay on every sorting algorithm..."));
|
|
314
|
+
setTimeout(() => agent.steer("Stop — give me 3 bullet points instead."), 1500);
|
|
315
|
+
for await (const chunk of stream) process.stdout.write(chunk);
|
|
129
316
|
```
|
|
130
317
|
|
|
131
|
-
|
|
318
|
+
#### `agent.followUp(message)`
|
|
319
|
+
|
|
320
|
+
Queue a message for Pi to process after it finishes the current task.
|
|
321
|
+
|
|
322
|
+
#### `agent.abort()`
|
|
323
|
+
|
|
324
|
+
Interrupt the current in-progress response immediately.
|
|
325
|
+
|
|
326
|
+
---
|
|
327
|
+
|
|
328
|
+
### Session management
|
|
329
|
+
|
|
330
|
+
#### `agent.newSession()`
|
|
331
|
+
|
|
332
|
+
Start a fresh Pi conversation, clearing all context. Filesystem and workspace are unchanged.
|
|
333
|
+
|
|
334
|
+
#### `agent.clone()`
|
|
335
|
+
|
|
336
|
+
Branch the current Pi session at the current position. Returns `{ cancelled: boolean }`.
|
|
337
|
+
|
|
338
|
+
#### `agent.fork(entryId)`
|
|
339
|
+
|
|
340
|
+
Branch from a specific message entry in the conversation history. Returns `{ text, cancelled }`.
|
|
341
|
+
|
|
342
|
+
#### `agent.switchSession(sessionPath)`
|
|
343
|
+
|
|
344
|
+
Switch Pi to a different session file on disk.
|
|
345
|
+
|
|
346
|
+
#### `agent.getMessages()`
|
|
347
|
+
|
|
348
|
+
Retrieve the full conversation history for the current session.
|
|
132
349
|
|
|
133
350
|
```ts
|
|
134
|
-
|
|
351
|
+
const messages = await agent.getMessages();
|
|
352
|
+
console.log(messages.length, "messages");
|
|
353
|
+
```
|
|
135
354
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
### Model control
|
|
358
|
+
|
|
359
|
+
#### `agent.setModel(provider, modelId)`
|
|
360
|
+
|
|
361
|
+
Switch Pi to a specific model. Returns the activated `PiModel`.
|
|
362
|
+
|
|
363
|
+
#### `agent.cycleModel()`
|
|
364
|
+
|
|
365
|
+
Cycle to the next configured model. Returns `{ model, thinkingLevel, isScoped }` or `null` if only one model is configured.
|
|
143
366
|
|
|
144
|
-
|
|
145
|
-
|
|
367
|
+
#### `agent.getAvailableModels()`
|
|
368
|
+
|
|
369
|
+
List all models available to Pi under the current provider configuration.
|
|
370
|
+
|
|
371
|
+
#### `agent.setThinkingLevel(level)`
|
|
372
|
+
|
|
373
|
+
Set Pi's reasoning level (`"low" | "medium" | "high"`). Only effective on models that support extended thinking.
|
|
374
|
+
|
|
375
|
+
#### `agent.cycleThinkingLevel()`
|
|
376
|
+
|
|
377
|
+
Cycle Pi's thinking level. Returns `{ level }` or `null` if the current model doesn't support thinking.
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
381
|
+
### Context management
|
|
382
|
+
|
|
383
|
+
#### `agent.setAutoCompaction(enabled)`
|
|
384
|
+
|
|
385
|
+
Enable or disable Pi's automatic context compaction.
|
|
386
|
+
|
|
387
|
+
#### `agent.compact(customInstructions?)`
|
|
388
|
+
|
|
389
|
+
Manually trigger Pi's context compaction. Returns `{ tokensBefore, estimatedTokensAfter }`.
|
|
390
|
+
|
|
391
|
+
---
|
|
392
|
+
|
|
393
|
+
### Reliability
|
|
394
|
+
|
|
395
|
+
#### `agent.setAutoRetry(enabled)`
|
|
396
|
+
|
|
397
|
+
Enable or disable Pi's automatic retry on transient errors (429, 500, 502, 503, 504). Auto-retry is **on by default**: 3 attempts with exponential backoff (2 s / 4 s / 8 s). Disable it when you want to handle failures yourself via `auto_retry_start` / `auto_retry_end` events.
|
|
398
|
+
|
|
399
|
+
```ts
|
|
400
|
+
await agent.setAutoRetry(false); // take full control
|
|
146
401
|
```
|
|
147
402
|
|
|
403
|
+
#### `agent.abortRetry()`
|
|
404
|
+
|
|
405
|
+
Abort an in-progress auto-retry immediately. Pi fails the current operation and emits `auto_retry_end` with `success: false`.
|
|
406
|
+
|
|
407
|
+
#### `agent.abortBash()`
|
|
408
|
+
|
|
409
|
+
Abort a currently-executing bash command without cancelling the whole prompt. No-op when no bash is running.
|
|
410
|
+
|
|
148
411
|
---
|
|
149
412
|
|
|
150
|
-
|
|
413
|
+
### Session inspection
|
|
414
|
+
|
|
415
|
+
#### `agent.getSessionStats()`
|
|
416
|
+
|
|
417
|
+
Retrieve token usage, cost, and message counts for the current session. Returns a `SessionStats` object.
|
|
151
418
|
|
|
152
419
|
```ts
|
|
153
|
-
const
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
420
|
+
const stats = await agent.getSessionStats();
|
|
421
|
+
console.log(`${stats.tokens.total} tokens used, $${stats.cost.toFixed(6)} cost`);
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
#### `agent.getLastAssistantText()`
|
|
425
|
+
|
|
426
|
+
Retrieve the text of Pi's most recent assistant response without iterating the stream. Returns `null` if Pi hasn't responded yet.
|
|
427
|
+
|
|
428
|
+
#### `agent.getForkMessages()`
|
|
429
|
+
|
|
430
|
+
List the fork entry points available in the current session. Each entry has `entryId` (pass to `fork()`) and `text`.
|
|
431
|
+
|
|
432
|
+
#### `agent.getCommands()`
|
|
433
|
+
|
|
434
|
+
List Pi's available slash commands, including extensions, prompt templates, and skills. Returns `PiSlashCommand[]`.
|
|
435
|
+
|
|
436
|
+
```ts
|
|
437
|
+
const cmds = await agent.getCommands();
|
|
438
|
+
for (const cmd of cmds) console.log(`/${cmd.name} [${cmd.source}]`);
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
#### `agent.setSessionName(name)`
|
|
442
|
+
|
|
443
|
+
Set a display name for the current Pi session.
|
|
444
|
+
|
|
445
|
+
#### `agent.exportHtml(outputPath?)`
|
|
446
|
+
|
|
447
|
+
Export a static HTML transcript of the session to the sandbox filesystem. Returns `{ path }` — the container path of the file. Use `agent.sandbox.readFile(path)` to retrieve it.
|
|
448
|
+
|
|
449
|
+
```ts
|
|
450
|
+
const { path } = await agent.exportHtml();
|
|
451
|
+
const html = await agent.sandbox.readFile(path);
|
|
160
452
|
```
|
|
161
453
|
|
|
162
454
|
---
|
|
163
455
|
|
|
164
|
-
|
|
456
|
+
### Advanced control
|
|
165
457
|
|
|
166
|
-
|
|
458
|
+
#### `agent.setSteeringMode(mode)`
|
|
167
459
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
460
|
+
Control how Pi processes queued steering messages: `"all"` applies all at once, `"one-at-a-time"` applies them sequentially.
|
|
461
|
+
|
|
462
|
+
#### `agent.setFollowUpMode(mode)`
|
|
463
|
+
|
|
464
|
+
Control how Pi processes queued follow-up messages: `"all"` sends all at once, `"one-at-a-time"` sends them sequentially.
|
|
465
|
+
|
|
466
|
+
---
|
|
467
|
+
|
|
468
|
+
### Environment and debugging
|
|
469
|
+
|
|
470
|
+
#### `agent.setEnv(vars)`
|
|
471
|
+
|
|
472
|
+
Set or update env vars in the running container. Restarts Pi so it picks up the new env.
|
|
473
|
+
|
|
474
|
+
```ts
|
|
475
|
+
await agent.setEnv({ DATABASE_URL: "postgres://..." });
|
|
172
476
|
```
|
|
173
477
|
|
|
478
|
+
#### `agent.getLogs()`
|
|
479
|
+
|
|
480
|
+
Retrieve recent bridge logs (ring-buffered, last 200 entries).
|
|
481
|
+
|
|
482
|
+
#### `agent.sandbox`
|
|
483
|
+
|
|
484
|
+
Direct access to the underlying `SandboxHandle` — run commands, read/write files, or inspect state independently of Pi.
|
|
485
|
+
|
|
486
|
+
```ts
|
|
487
|
+
await agent.sandbox.writeFile("/workspace/input.txt", data);
|
|
488
|
+
const { stdout } = await agent.sandbox.exec("wc -l /workspace/input.txt");
|
|
489
|
+
const result = await agent.sandbox.readFile("/workspace/output.txt");
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
---
|
|
493
|
+
|
|
494
|
+
## Properties
|
|
495
|
+
|
|
496
|
+
| Property | Type | Description |
|
|
497
|
+
| -------------------- | --------------- | ---------------------------------------------- |
|
|
498
|
+
| `agent.sandboxId` | `string` | OpenSandbox container ID |
|
|
499
|
+
| `agent.name` | `string` | Alineo name from the spec |
|
|
500
|
+
| `agent.sandbox` | `SandboxHandle` | Underlying `SandboxHandle` object |
|
|
501
|
+
| `agent.fromSnapshot` | `boolean` | `true` when restored from snapshot (fast path) |
|
|
502
|
+
|
|
174
503
|
---
|
|
175
504
|
|
|
176
505
|
## License
|