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 CHANGED
@@ -1,176 +1,505 @@
1
1
  # alineo
2
2
 
3
- Sandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.
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 @alineo-labs/sqlite
6
+ bun add alineo
7
7
  ```
8
8
 
9
- **[Full documentation →](https://docs.alineo.tech/docs/core)**
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 client = new Alineo({
20
- baseUrl: "http://localhost:8080",
21
- adapter: new SQLiteAdapter("./ledger.db"),
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
- const sb = await client.sandbox({
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
- const { stdout } = await sb.exec("node --version");
30
- console.log(stdout); // v20.x.x
47
+ ---
31
48
 
32
- await sb.close();
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
- ## Core concepts
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
- **Sandbox as object** — `client.sandbox()` returns a live `Sandbox`. Call exec, file ops, checkpoint, and fork directly on it. No special API needed for multiple sandboxes — just multiple variables.
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
- **ExecHandle** — `sb.exec("cmd")` returns an `ExecHandle` — a `PromiseLike<ExecResult>` with streaming built in.
124
+ The snapshot is invalidated automatically when `cli`, `cliVersion`, `packages`, or `setup` change.
42
125
 
43
126
  ```ts
44
- // Await result
45
- const { stdout, stderr, exitCode } = await sb.exec("npm test");
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
- // Stream to a writable
48
- await sb.exec("npm run build").pipe(process.stdout);
132
+ // Force a full reinstall:
133
+ const agent2 = await Alineo.load(spec, { adapter, rebuild: true });
134
+ ```
49
135
 
50
- // Async iteration
51
- for await (const chunk of sb.exec("npm run build").stdout()) {
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
- **Durable ledger** — every exec is written to the storage adapter. `client.resume(sandboxId)` restores the container and replays cached results from before the last checkpoint.
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
- ## File operations
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 sb.writeFile("/app/main.py", "print('hello')");
64
- const content = await sb.readFile("/app/main.py");
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
- await sb.createDirectory("/app/dist");
67
- const info = await sb.getFileInfo("/app/main.py");
224
+ #### `Alineo.resume(sandboxId, opts)`
68
225
 
69
- // In-place patch
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
- // Search, move, delete
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
- // Copy to another sandbox
78
- await sb.transfer("/app/output.json", anotherSb);
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
- ## Checkpoint and resume
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 sb = await client.sandbox({
85
- image: "ubuntu:22.04",
86
- resources: { cpu: "500m", memory: "512Mi" },
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
- await sb.exec("apt-get install -y curl");
90
- await sb.checkpoint("after-setup");
91
- await sb.close();
253
+ #### `agent.close()`
92
254
 
93
- // Later — or after a crash
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
- ## Environments
257
+ ---
100
258
 
101
- Define a named environment with a setup recipe. Built once, restored from snapshot on every subsequent call.
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 env = client.environment("python-data", {
105
- image: "python:3.11-slim",
106
- resources: { cpu: "1", memory: "1Gi" },
107
- setup: async (sb) => {
108
- await sb.exec("pip install numpy pandas scikit-learn");
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
- const sb = await env.sandbox(); // ~2s after first run
113
- await sb.exec("python3 -c 'import pandas; print(pandas.__version__)'").pipe(process.stdout);
114
- await sb.close();
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
- ## Forking
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 sb.exec("npm ci");
121
- const fork = await sb.fork();
299
+ for await (const chunk of textOnly(agent.bash("ls -la /workspace"))) {
300
+ process.stdout.write(chunk);
301
+ }
302
+ ```
122
303
 
123
- await Promise.all([
124
- sb.exec("npm test").pipe(process.stdout),
125
- fork.exec("npm run build").pipe(process.stdout),
126
- ]);
304
+ ---
305
+
306
+ ### Mid-flight control
307
+
308
+ #### `agent.steer(message)`
127
309
 
128
- await Promise.all([sb.close(), fork.close()]);
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
- ## Error handling
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
- import { CommandError } from "alineo";
351
+ const messages = await agent.getMessages();
352
+ console.log(messages.length, "messages");
353
+ ```
135
354
 
136
- try {
137
- await sb.exec("exit 1"); // strict: true by default
138
- } catch (e) {
139
- if (e instanceof CommandError) {
140
- console.log(e.exitCode, e.command);
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
- // Opt out of strict mode
145
- const { exitCode } = await sb.exec("exit 1", { strict: false });
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
- ## Configuration
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 client = new Alineo({
154
- baseUrl: "http://localhost:8080", // OpenSandbox server URL
155
- apiKey: "", // API key (empty for local dev)
156
- adapter: new SQLiteAdapter("./alineo.db"),
157
- maxConcurrency: 4, // cap simultaneous active sandboxes
158
- useServerProxy: true, // required when server runs in Docker via alineo init
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
- ## Local setup
456
+ ### Advanced control
165
457
 
166
- Requires a running [OpenSandbox](https://open-sandbox.ai) instance:
458
+ #### `agent.setSteeringMode(mode)`
167
459
 
168
- ```bash
169
- bunx alineo-cli init # starts OpenSandbox in Docker, recommended
170
- # or
171
- uvx opensandbox-server # manual, see docs for ~/.sandbox.toml config
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