alineo 0.6.0 → 0.8.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 +35 -33
- package/dist/claude-bridge.cjs +633 -0
- package/dist/codex-bridge.cjs +855 -0
- package/dist/index.d.mts +1170 -390
- package/dist/index.mjs +2096 -488
- package/dist/pi-bridge.cjs +905 -0
- package/dist/pi-permission-gate.mjs +288 -0
- package/package.json +8 -5
- package/dist/pi-bridge.js +0 -999
- package/dist/pi-permission-gate.js +0 -337
package/dist/index.d.mts
CHANGED
|
@@ -1,278 +1,8 @@
|
|
|
1
|
-
import { CredentialBinding, CredentialSource, ExecOptions, ExecResult, IStorageAdapter, SandboxHandle, WorkflowError } from "@alineo-labs/core";
|
|
1
|
+
import { CredentialBinding, CredentialSource, DEFAULT_PROVIDER_ID, ExecOptions, ExecResult, IStorageAdapter, SandboxHandle, WorkflowError } from "@alineo-labs/core";
|
|
2
|
+
import { AgentSpec, AgentSpec as AgentSpec$1, AgentSpecInput, HarnessId, HarnessRef, ModelRef, PermissionAction, PermissionMode, PermissionPolicy, PermissionRule, ProjectConfig, SetupStep } from "@alineo-labs/schema";
|
|
2
3
|
import { z } from "zod";
|
|
3
4
|
import { Memory, ResourceRef } from "@alineo-labs/memory";
|
|
4
5
|
//#endregion
|
|
5
|
-
//#region src/permissions.d.ts
|
|
6
|
-
/**
|
|
7
|
-
* Human-in-the-loop tool-call policy — the host-side half.
|
|
8
|
-
*
|
|
9
|
-
* `AgentSpec.permissions` (a mode string or a full policy) is normalized here into a
|
|
10
|
-
* `NormalizedPermissionPolicy`, written into the sandbox at `/etc/alineo-pi.json`, and read
|
|
11
|
-
* by the bundled Pi gate extension (`adapters/pi-permission-gate.js`), which re-implements
|
|
12
|
-
* the tiny matcher below inline (same duplication tradeoff `pi-bridge.js` already makes —
|
|
13
|
-
* the gate can't import from a published package it runs beside via jiti). Keep the two
|
|
14
|
-
* matchers in sync; `test/permissions.test.ts` covers this one.
|
|
15
|
-
*/
|
|
16
|
-
/**
|
|
17
|
-
* Shorthand for the common cases:
|
|
18
|
-
* - `"auto"` — never ask (the default; identical to not setting `permissions` at all)
|
|
19
|
-
* - `"ask"` — ask before every tool call
|
|
20
|
-
* - `"readonly"` — auto-allow the read-only tools (`read`/`grep`/`find`/`ls`), ask before
|
|
21
|
-
* `write`/`edit`/`bash`/`powershell`. Pi has no network tool — an agent reaches the
|
|
22
|
-
* network through `bash`, so `"readonly"` gates that by gating `bash`, not as a category.
|
|
23
|
-
*/
|
|
24
|
-
type PermissionMode = "auto" | "ask" | "readonly";
|
|
25
|
-
/**
|
|
26
|
-
* What happens when a rule (or the policy default) matches a tool call:
|
|
27
|
-
* - `allow` — run it, no prompt
|
|
28
|
-
* - `ask` — pause, surface a `permission_request`, wait for a human decision
|
|
29
|
-
* - `deny` — refuse, with a reason the model reads and can adjust to
|
|
30
|
-
* - `rate_limit` — allow up to `limit.count` matching calls per `limit.windowMs`, then deny
|
|
31
|
-
* - `classify` — best-effort read-vs-write triage of the call (today: `bash`/`powershell`
|
|
32
|
-
* only, splitting on `&&`/`||`/`;`/`|`/newline and checking each sub-command against a
|
|
33
|
-
* built-in safe-reader list). All sub-commands look read-only → `allow`; anything
|
|
34
|
-
* unrecognised or a redirect/`sudo`/`rm` → falls through to `ask`. For any other tool,
|
|
35
|
-
* `classify` is treated as `ask`.
|
|
36
|
-
*/
|
|
37
|
-
type PermissionAction = "allow" | "ask" | "deny" | "rate_limit" | "classify";
|
|
38
|
-
interface PermissionRule {
|
|
39
|
-
/** Tool name or glob (`*` = any run of chars, `?` = one), e.g. `"bash"`, `"write"`, `"*"`. */
|
|
40
|
-
tool: string;
|
|
41
|
-
/**
|
|
42
|
-
* Glob matched against a tool-specific target string, extracted from Pi's typed
|
|
43
|
-
* `event.input` — the command for `bash`, the path for `read`/`write`/`edit`, the query
|
|
44
|
-
* for `grep`. Anchored: `"git *"` matches `"git status"` but not `"x && git status"` —
|
|
45
|
-
* use `"*git*"` for a substring match. Omit to match any call to `tool`.
|
|
46
|
-
*/
|
|
47
|
-
pattern?: string;
|
|
48
|
-
action: PermissionAction;
|
|
49
|
-
/** `rate_limit` only: the ceiling and rolling window. */
|
|
50
|
-
limit?: {
|
|
51
|
-
count: number;
|
|
52
|
-
windowMs: number;
|
|
53
|
-
};
|
|
54
|
-
}
|
|
55
|
-
interface PermissionPolicy {
|
|
56
|
-
/** Action when no rule matches. Default `"ask"`. */
|
|
57
|
-
default?: PermissionAction;
|
|
58
|
-
/** Evaluated in order; the **last** matching rule wins (opencode semantics). */
|
|
59
|
-
rules?: PermissionRule[];
|
|
60
|
-
/**
|
|
61
|
-
* Tools the agent may never call. The gate strips these from the model's tool list at
|
|
62
|
-
* session start (via Pi's `setActiveTools`) so the model never attempts them, and also
|
|
63
|
-
* keeps an unconditional `deny` as a backstop for any tool registered after startup
|
|
64
|
-
* (SDK / MCP tools).
|
|
65
|
-
*/
|
|
66
|
-
disabledTools?: string[];
|
|
67
|
-
/**
|
|
68
|
-
* If set, the ONLY tools the model may see — the gate calls Pi's `setActiveTools` with
|
|
69
|
-
* this list at session start. `"readonly"` mode expands to this (the read-only tools).
|
|
70
|
-
* Distinct from `disabledTools` (a denylist); this is an allowlist for the toolset.
|
|
71
|
-
*/
|
|
72
|
-
restrictToTools?: string[];
|
|
73
|
-
}
|
|
74
|
-
/**
|
|
75
|
-
* Best-effort read-vs-write triage of a shell command. `true` = every sub-command is a
|
|
76
|
-
* recognised pure reader with no output redirection; `false` = something needs a human.
|
|
77
|
-
* Mirrored verbatim in `adapters/pi-permission-gate.js`.
|
|
78
|
-
*/
|
|
79
|
-
export declare function isReadOnlyBashCommand(command: string): boolean;
|
|
80
|
-
//#endregion
|
|
81
|
-
//#region src/schema.d.ts
|
|
82
|
-
/**
|
|
83
|
-
* Opt-in alternative to a plain `AgentSpec.env` string value — instead of interpolating
|
|
84
|
-
* straight into the container's environment, `credential` is registered with the sandbox's
|
|
85
|
-
* `CredentialBroker` via `sb.credentials.set()` and injected transparently into outbound
|
|
86
|
-
* requests to `host`. The sandbox process never sees the resolved value at all. Requires the
|
|
87
|
-
* agent's sandbox to be created with `credentialProxy: true` — `Alineo.load()`/`.resume()`/
|
|
88
|
-
* `.spawn()` set this automatically whenever `env` contains at least one binding like this.
|
|
89
|
-
*/
|
|
90
|
-
interface CredentialEnvBinding {
|
|
91
|
-
/** Host env var reference to resolve the real value from, e.g. `"${OPENAI_API_KEY}"`. */
|
|
92
|
-
credential: string;
|
|
93
|
-
/** FQDN or wildcard domain this credential is injected for. */
|
|
94
|
-
host: string;
|
|
95
|
-
/** Narrows the binding to requests whose path starts with this prefix. */
|
|
96
|
-
pathPrefix?: string;
|
|
97
|
-
/**
|
|
98
|
-
* How the credential reaches the request. `header` adds `name: <value>`. `substitution`
|
|
99
|
-
* replaces every literal `placeholder` in the listed request surfaces with the value — the
|
|
100
|
-
* request must already contain `placeholder` verbatim (put it in a base URL, say). Mirrors
|
|
101
|
-
* `@alineo-labs/core`'s `CredentialInjection`; `packages/agent/test/schema.test.ts` is the
|
|
102
|
-
* drift check.
|
|
103
|
-
*/
|
|
104
|
-
injection: {
|
|
105
|
-
type: "header";
|
|
106
|
-
name: string;
|
|
107
|
-
} | {
|
|
108
|
-
type: "substitution";
|
|
109
|
-
placeholder: string;
|
|
110
|
-
in: Array<"path" | "query" | "header" | "body">;
|
|
111
|
-
};
|
|
112
|
-
/**
|
|
113
|
-
* `"hold"` gates outbound egress to `host` behind a human decision: the agent's sandbox
|
|
114
|
-
* starts with `host` denied at the egress sidecar, the first request to it pauses and
|
|
115
|
-
* raises an approval request, and the host is allowed only once someone approves. Requires
|
|
116
|
-
* an `onEgressRequest` handler on `Alineo.load()`. Omit for the default (the host is
|
|
117
|
-
* reachable as soon as the credential is bound).
|
|
118
|
-
*/
|
|
119
|
-
approval?: "hold";
|
|
120
|
-
}
|
|
121
|
-
/**
|
|
122
|
-
* A single named setup step run inside the sandbox after Pi CLI install,
|
|
123
|
-
* before the snapshot is taken. The step is a bash shell command.
|
|
124
|
-
*/
|
|
125
|
-
interface SetupStep {
|
|
126
|
-
/** Human-readable label shown in logs and included in the setup hash. */
|
|
127
|
-
name: string;
|
|
128
|
-
/** Shell command to run (bash). */
|
|
129
|
-
run: string;
|
|
130
|
-
/** If set, the command runs as `cd <cwd> && <run>`. */
|
|
131
|
-
cwd?: string;
|
|
132
|
-
}
|
|
133
|
-
/**
|
|
134
|
-
* JSON spec for an agent — typically loaded from an `agent.json` file on disk.
|
|
135
|
-
* Pass it to `Alineo.load(spec)` — read it from disk yourself first (e.g.
|
|
136
|
-
* `await Bun.file(path).json()`) if it's not already an in-memory object.
|
|
137
|
-
*
|
|
138
|
-
* Environment variable references in `env` values are interpolated from
|
|
139
|
-
* `process.env` at load time: `"${MY_API_KEY}"` → `process.env.MY_API_KEY`.
|
|
140
|
-
*/
|
|
141
|
-
interface AgentSpec {
|
|
142
|
-
$schema?: string;
|
|
143
|
-
/** Unique identifier for this agent. Used as the sandbox session name. */
|
|
144
|
-
name: string;
|
|
145
|
-
/** Human-readable display name. */
|
|
146
|
-
title?: string;
|
|
147
|
-
description?: string;
|
|
148
|
-
author?: string;
|
|
149
|
-
categories?: string[];
|
|
150
|
-
/** CLI to run inside the sandbox. Currently only `"pi"` is supported. */
|
|
151
|
-
cli: "pi";
|
|
152
|
-
/**
|
|
153
|
-
* npm version specifier for the Pi CLI, e.g. `"1.2.3"`, `"^1.2.0"`, or a
|
|
154
|
-
* dist-tag like `"latest"`. Passed directly to
|
|
155
|
-
* `npm install -g @earendil-works/pi-coding-agent@<cliVersion>`. When
|
|
156
|
-
* omitted, `install()` runs the bare package name and npm resolves
|
|
157
|
-
* whatever it considers latest. Included in the setup-hash cache key, so
|
|
158
|
-
* changing it forces a fresh snapshot rebuild.
|
|
159
|
-
*/
|
|
160
|
-
cliVersion?: string;
|
|
161
|
-
/**
|
|
162
|
-
* AI provider passed to the CLI via `--provider`. For Pi with a direct Google
|
|
163
|
-
* API key, omit this (Pi defaults to the Google Generative AI endpoint).
|
|
164
|
-
*/
|
|
165
|
-
provider?: string;
|
|
166
|
-
/**
|
|
167
|
-
* Model ID passed to the CLI via `--model`.
|
|
168
|
-
* For Pi 0.80.x with a free Google AI Studio key, use `"gemini-flash-latest"`
|
|
169
|
-
* (Pi's alias for gemini-3.5-flash via the direct Google Generative AI API).
|
|
170
|
-
*/
|
|
171
|
-
model?: string;
|
|
172
|
-
/**
|
|
173
|
-
* APT packages to install in the sandbox before starting the CLI.
|
|
174
|
-
* Example: `["python3", "git"]`. `nodejs_22` and `nodejs` are silently ignored
|
|
175
|
-
* since the base image is `node:22`.
|
|
176
|
-
*/
|
|
177
|
-
packages?: string[];
|
|
178
|
-
/**
|
|
179
|
-
* Environment variables available inside the sandbox.
|
|
180
|
-
* Values may reference host env vars: `{ GEMINI_API_KEY: "${GEMINI_API_KEY}" }`.
|
|
181
|
-
*
|
|
182
|
-
* A value can instead be a `CredentialEnvBinding` to opt that one key out of plain env-var
|
|
183
|
-
* interpolation entirely — the key never becomes a container env var; its value is injected
|
|
184
|
-
* transparently into matching outbound requests instead. See `CredentialEnvBinding`.
|
|
185
|
-
*/
|
|
186
|
-
env?: Record<string, string | CredentialEnvBinding>;
|
|
187
|
-
/**
|
|
188
|
-
* CPU/memory/GPU resource limits for the sandbox container.
|
|
189
|
-
* Falls back to defaults in `alineo.config.json` if omitted.
|
|
190
|
-
*/
|
|
191
|
-
resources?: {
|
|
192
|
-
cpu: string;
|
|
193
|
-
memory: string;
|
|
194
|
-
gpu?: string;
|
|
195
|
-
};
|
|
196
|
-
/** Not read anywhere in `alineo`; has no effect on the sandbox. */
|
|
197
|
-
metadata?: Record<string, string>;
|
|
198
|
-
/**
|
|
199
|
-
* Not read by `alineo` itself — used by `alineo add`, which fetches
|
|
200
|
-
* and saves each dependency spec first, depth-first.
|
|
201
|
-
*/
|
|
202
|
-
registryDependencies?: string[];
|
|
203
|
-
/**
|
|
204
|
-
* Setup steps run inside the sandbox after Pi CLI install, before the snapshot.
|
|
205
|
-
* Baked into the snapshot — any change to a step invalidates the cache automatically.
|
|
206
|
-
* Example: create directories, write seed files, install project dependencies.
|
|
207
|
-
*/
|
|
208
|
-
setup?: SetupStep[];
|
|
209
|
-
/**
|
|
210
|
-
* Remaining budget for `Alineo.spawn()` calls made from inside this agent's sandbox.
|
|
211
|
-
* Translated by `Alineo.load()`/`Alineo.resume()` into the `ALINEO_SPAWN_DEPTH` env var.
|
|
212
|
-
* `Alineo.spawn()` reads that value, refuses unless it's a positive integer, and
|
|
213
|
-
* force-injects `value - 1` into the spawned child — a tamper-resistant counter,
|
|
214
|
-
* not something a spec or the model can hand-propagate. Omit to disable spawning
|
|
215
|
-
* entirely (the default — most agents never need it).
|
|
216
|
-
*/
|
|
217
|
-
spawnDepth?: number;
|
|
218
|
-
/**
|
|
219
|
-
* Remaining budget for total agents this lineage may spawn — a resource
|
|
220
|
-
* ceiling, distinct from `spawnDepth`'s nesting-depth limit. Translated by
|
|
221
|
-
* `Alineo.load()`/`Alineo.resume()` into the `ALINEO_MAX_AGENTS` env var and
|
|
222
|
-
* force-decremented into each spawned child, the same tamper-resistant
|
|
223
|
-
* pattern as `spawnDepth`. Unlike `spawnDepth`, omitting this means
|
|
224
|
-
* "uncapped" for this dimension, not "spawning disabled" — `spawnDepth`
|
|
225
|
-
* alone still gates whether spawning is allowed at all. Enforced
|
|
226
|
-
* per-lineage only: sibling branches spawned in parallel don't share or
|
|
227
|
-
* coordinate this budget with each other.
|
|
228
|
-
*/
|
|
229
|
-
maxAgents?: number;
|
|
230
|
-
/**
|
|
231
|
-
* Durable team identity for this agent's `.resourceRef` — see `@alineo-labs/memory`'s
|
|
232
|
-
* `ResourceRef.teamId`. Unset by default (unlike `resourceId`, which always gets
|
|
233
|
-
* `spec.name` as its own default) — most agents aren't tied to a team-scoped memory.
|
|
234
|
-
* `Alineo.load()`/`.resume()` also thread this into `SandboxOptions.teamId`/
|
|
235
|
-
* `RestoreSnapshotOptions.teamId` so it stays consistent with the ledger, not just
|
|
236
|
-
* `.resourceRef` — otherwise a team-scoped agent's own episodic history would be
|
|
237
|
-
* unreachable through its own `resourceRef`, since `episodicRecall()` enforces `teamId`
|
|
238
|
-
* strictly. `Alineo.spawn()` passes `SandboxHandle.fork()`'s `resourceId`/`teamId` override
|
|
239
|
-
* (see its own doc comment) so a spawned child's ledger record matches its
|
|
240
|
-
* `.resourceRef` too, rather than silently inheriting the parent's.
|
|
241
|
-
*/
|
|
242
|
-
teamId?: string;
|
|
243
|
-
/**
|
|
244
|
-
* Durable resource identity for this agent's `.resourceRef` — see `@alineo-labs/memory`'s
|
|
245
|
-
* `ResourceRef.resourceId`. Defaults to `spec.name` when unset, same as the implicit
|
|
246
|
-
* behavior before this field existed.
|
|
247
|
-
*
|
|
248
|
-
* Exists as its own field, separate from `name`, specifically for `Alineo.spawn()`: a
|
|
249
|
-
* spawned child's `.name` is overwritten to the forked sandbox's auto-generated ledger name
|
|
250
|
-
* (`fork-<parent>-<id>`, used for `alineo agents` display and future fork labeling) — not
|
|
251
|
-
* `childSpec.name`. Without a separate `resourceId` field, a spawned child's memory scope
|
|
252
|
-
* would silently become that auto-generated name instead of the identity the spec author
|
|
253
|
-
* actually declared. `Alineo.spawn()` freezes this to `childSpec.resourceId ?? childSpec.name`
|
|
254
|
-
* before the rename happens, so a spawned child's memory scope is stable and predictable
|
|
255
|
-
* regardless of what the ledger ends up calling the forked sandbox.
|
|
256
|
-
*/
|
|
257
|
-
resourceId?: string;
|
|
258
|
-
/**
|
|
259
|
-
* Human-in-the-loop tool-call policy, enforced by a bundled Pi extension that runs on
|
|
260
|
-
* every tool call before it executes. Either a mode shorthand (`"auto"` — the default,
|
|
261
|
-
* never ask; `"ask"` — ask before every call; `"readonly"` — auto-allow reads, ask before
|
|
262
|
-
* writes/exec) or a full `PermissionPolicy` with ordered per-tool / per-pattern rules
|
|
263
|
-
* (last match wins). When set to anything other than `"auto"`, a `permission_request`
|
|
264
|
-
* event is emitted on the agent stream for each gated call; resolve it with
|
|
265
|
-
* `agent.resolvePermission(requestId, decision)`.
|
|
266
|
-
*/
|
|
267
|
-
permissions?: PermissionMode | PermissionPolicy;
|
|
268
|
-
}
|
|
269
|
-
/**
|
|
270
|
-
* Validate an unknown value as an `AgentSpec`, aggregating every problem found in one pass.
|
|
271
|
-
* Throws `AgentSpecValidationError` (with a pre-formatted `.message` and a structured
|
|
272
|
-
* `.issues` array) rather than a bare `Error` — see #185.
|
|
273
|
-
*/
|
|
274
|
-
export declare function validateAgentSpec(data: unknown): AgentSpec;
|
|
275
|
-
//#endregion
|
|
276
6
|
//#region src/types.d.ts
|
|
277
7
|
/**
|
|
278
8
|
* A single event emitted by an agent stream. Discriminated on `type`.
|
|
@@ -532,49 +262,431 @@ interface PiSessionState {
|
|
|
532
262
|
pendingMessageCount: number;
|
|
533
263
|
}
|
|
534
264
|
//#endregion
|
|
535
|
-
//#region src/
|
|
536
|
-
/**
|
|
537
|
-
*
|
|
538
|
-
|
|
265
|
+
//#region src/harness/events.d.ts
|
|
266
|
+
/**
|
|
267
|
+
* What a harness turn yields, whichever harness runs it (Pi, Claude Code, Codex).
|
|
268
|
+
*
|
|
269
|
+
* The set is small on purpose. An event every harness can produce has its own `type`. A
|
|
270
|
+
* thing only one harness has goes in `vendor`, so a new harness never widens this union.
|
|
271
|
+
* Anything a harness reports that this union cannot hold stays in `raw`.
|
|
272
|
+
*
|
|
273
|
+
* Contract: a turn ends with exactly one `done`, including after an abort.
|
|
274
|
+
*
|
|
275
|
+
* @experimental The harness layer is being built. Expect changes before it is stable.
|
|
276
|
+
*/
|
|
277
|
+
type HarnessEvent = HarnessEventBody & {
|
|
278
|
+
/** The harness's own event this one came from, untouched. For debugging and `vendor` use. */
|
|
279
|
+
raw?: unknown;
|
|
280
|
+
};
|
|
281
|
+
type HarnessEventBody =
|
|
282
|
+
/**
|
|
283
|
+
* The run began. Pi: `agent_start`. `sessionRef` is the id to resume this conversation
|
|
284
|
+
* with, when the harness has one.
|
|
285
|
+
*/
|
|
286
|
+
{
|
|
287
|
+
type: "run_start";
|
|
288
|
+
sessionRef?: string;
|
|
289
|
+
} |
|
|
290
|
+
/** A chunk of assistant prose. */
|
|
291
|
+
{
|
|
292
|
+
type: "text";
|
|
293
|
+
text: string;
|
|
294
|
+
} |
|
|
295
|
+
/** A chunk of the model's reasoning, for harnesses that expose it. */
|
|
296
|
+
{
|
|
297
|
+
type: "reasoning";
|
|
298
|
+
text: string;
|
|
299
|
+
} | {
|
|
300
|
+
type: "turn_start";
|
|
301
|
+
turnIndex: number;
|
|
302
|
+
} | {
|
|
303
|
+
type: "turn_end";
|
|
304
|
+
turnIndex: number;
|
|
305
|
+
} |
|
|
306
|
+
/**
|
|
307
|
+
* An assistant message began. `messageId` is the id to hand back when forking at this
|
|
308
|
+
* message. It is `null` when the harness gives none. A caller must never invent one.
|
|
309
|
+
*/
|
|
310
|
+
{
|
|
311
|
+
type: "message_start";
|
|
312
|
+
messageId: string | null;
|
|
313
|
+
} | {
|
|
314
|
+
type: "message_end";
|
|
315
|
+
messageId: string | null;
|
|
316
|
+
} | {
|
|
317
|
+
type: "tool_start";
|
|
318
|
+
toolCallId: string;
|
|
319
|
+
toolName: string;
|
|
320
|
+
args: unknown;
|
|
321
|
+
} | {
|
|
322
|
+
type: "tool_update";
|
|
323
|
+
toolCallId: string;
|
|
324
|
+
toolName: string;
|
|
325
|
+
partial: unknown;
|
|
326
|
+
} | {
|
|
327
|
+
type: "tool_end";
|
|
328
|
+
toolCallId: string;
|
|
329
|
+
toolName: string;
|
|
330
|
+
result: unknown;
|
|
331
|
+
isError: boolean;
|
|
332
|
+
} | {
|
|
333
|
+
type: "permission_request";
|
|
334
|
+
requestId: string;
|
|
335
|
+
tool: string;
|
|
336
|
+
target: string;
|
|
337
|
+
title: string;
|
|
338
|
+
} | {
|
|
339
|
+
type: "permission_resolved";
|
|
340
|
+
requestId: string;
|
|
341
|
+
decision: PermissionDecision;
|
|
342
|
+
} | {
|
|
343
|
+
type: "compaction";
|
|
344
|
+
phase: "start" | "end";
|
|
345
|
+
reason: string;
|
|
346
|
+
/** Only on `end`. */
|
|
347
|
+
aborted?: boolean;
|
|
348
|
+
/** Only on `end`. */
|
|
349
|
+
willRetry?: boolean;
|
|
350
|
+
} | {
|
|
351
|
+
type: "retry";
|
|
352
|
+
phase: "start" | "end";
|
|
353
|
+
attempt: number;
|
|
354
|
+
/** Only on `start`. */
|
|
355
|
+
maxAttempts?: number;
|
|
356
|
+
/** Only on `start`. */
|
|
357
|
+
delayMs?: number;
|
|
358
|
+
/** Only on `end`. */
|
|
359
|
+
success?: boolean;
|
|
360
|
+
/** The error that caused the retry (`start`) or ended it (`end`). */
|
|
361
|
+
error?: string;
|
|
362
|
+
} |
|
|
363
|
+
/** The steering and follow-up queues changed. */
|
|
364
|
+
{
|
|
365
|
+
type: "queue";
|
|
366
|
+
steering: string[];
|
|
367
|
+
followUp: string[];
|
|
368
|
+
} |
|
|
369
|
+
/** Something only this harness has. Callers who do not know `harness` ignore it. */
|
|
370
|
+
{
|
|
371
|
+
type: "vendor";
|
|
372
|
+
harness: string;
|
|
373
|
+
name: string;
|
|
374
|
+
data: unknown;
|
|
375
|
+
} |
|
|
376
|
+
/** The harness failed. A `done` with `reason: "error"` follows. */
|
|
377
|
+
{
|
|
378
|
+
type: "error";
|
|
379
|
+
message: string;
|
|
380
|
+
} |
|
|
381
|
+
/** The one terminal event of a turn. */
|
|
382
|
+
{
|
|
383
|
+
type: "done";
|
|
384
|
+
reason: "completed" | "aborted" | "error";
|
|
385
|
+
};
|
|
386
|
+
//#endregion
|
|
387
|
+
//#region src/harness/capabilities.d.ts
|
|
388
|
+
/**
|
|
389
|
+
* What a harness can do. Declared by the adapter, never probed. A method behind a
|
|
390
|
+
* capability the adapter declares `false` is never called: the SDK refuses first.
|
|
391
|
+
*
|
|
392
|
+
* `false` means "does not do it". A harness that cannot say whether it does must declare
|
|
393
|
+
* `false` too. It must never claim `true` to be safe.
|
|
394
|
+
*
|
|
395
|
+
* @experimental The harness layer is being built. Expect changes before it is stable.
|
|
396
|
+
*/
|
|
397
|
+
interface HarnessCapabilities {
|
|
398
|
+
/** Inject a message into the turn that is running now. */
|
|
399
|
+
steer: boolean;
|
|
400
|
+
/** Queue a message to run after the current turn. */
|
|
401
|
+
followUp: boolean;
|
|
402
|
+
/** Continue a prior session by its `sessionRef`. */
|
|
403
|
+
resume: boolean;
|
|
404
|
+
/** Start a new session from a point in an old one, by `messageId`. */
|
|
405
|
+
fork: boolean;
|
|
406
|
+
/** Compact the context on request. */
|
|
407
|
+
compact: boolean;
|
|
408
|
+
/** Change the model of a live session. */
|
|
409
|
+
setModel: boolean;
|
|
410
|
+
/** The harness asks before running a tool, through `permission_request`. */
|
|
411
|
+
permissions: boolean;
|
|
412
|
+
/** The harness exposes the model's reasoning as `reasoning` events. */
|
|
413
|
+
reasoning: boolean;
|
|
414
|
+
}
|
|
415
|
+
type HarnessCapability = keyof HarnessCapabilities;
|
|
416
|
+
/**
|
|
417
|
+
* What Pi declares. Each value is what `PiAdapter` and `pi-bridge.ts` do today:
|
|
418
|
+
* `/steer`, `/follow-up`, `/fork`, `/compact`, `/set-model`, the permission gate, and
|
|
419
|
+
* `thinking_delta` events.
|
|
420
|
+
*/
|
|
421
|
+
export declare const PI_CAPABILITIES: HarnessCapabilities;
|
|
422
|
+
//#endregion
|
|
423
|
+
//#region src/harness/pi-events.d.ts
|
|
424
|
+
/**
|
|
425
|
+
* Map one event of Pi's bridge stream to harness events. Zero, one or more come back.
|
|
426
|
+
*
|
|
427
|
+
* Every Pi event maps to exactly one harness event, and that event carries the Pi event as
|
|
428
|
+
* `raw`. Nothing is dropped. A `thinking_delta` inside `message_update` is `reasoning`.
|
|
429
|
+
* Every other `message_update` delta (text, tool-call, and so on) is a `vendor` event
|
|
430
|
+
* named `message_update`: the text of a `text_delta` already arrives as its own `text`
|
|
431
|
+
* event, so a neutral consumer ignores the vendor one.
|
|
432
|
+
*
|
|
433
|
+
* `agent_end` becomes `done`. The bridge ends a turn with `agent_end`. The error path
|
|
434
|
+
* (a bridge `{error}` frame, a timeout, an abort) is not an event on this stream. The
|
|
435
|
+
* adapter that reads the stream must emit `done` with `reason: "error"` or `"aborted"`.
|
|
436
|
+
*/
|
|
437
|
+
export declare function fromPiEvent(ev: AgentEvent): HarnessEvent[];
|
|
438
|
+
//#endregion
|
|
439
|
+
//#region src/harness/sandbox.d.ts
|
|
440
|
+
/**
|
|
441
|
+
* The slice of `SandboxHandle` a harness adapter calls. `exec` only needs to be awaitable,
|
|
442
|
+
* so callers (and tests) do not have to supply a full `ExecHandle`. It keeps the harness
|
|
443
|
+
* layer testable with a stub.
|
|
444
|
+
*
|
|
445
|
+
* @experimental The harness layer is being built. Expect changes before it is stable.
|
|
446
|
+
*/
|
|
447
|
+
interface HarnessSandbox {
|
|
539
448
|
exec(cmd: string, opts?: ExecOptions): PromiseLike<ExecResult>;
|
|
540
449
|
proxy: SandboxHandle["proxy"];
|
|
541
450
|
writeFile: SandboxHandle["writeFile"];
|
|
542
451
|
}
|
|
543
|
-
|
|
452
|
+
//#endregion
|
|
453
|
+
//#region src/schema.d.ts
|
|
454
|
+
/**
|
|
455
|
+
* Validate an unknown value as an `AgentSpec`, aggregating every problem found in one pass.
|
|
456
|
+
* Throws `AgentSpecValidationError` (with a pre-formatted `.message` and a structured
|
|
457
|
+
* `.issues` array) rather than a bare `Error` — see #185.
|
|
458
|
+
*/
|
|
459
|
+
export declare function validateAgentSpec(data: unknown): AgentSpec$1;
|
|
460
|
+
//#endregion
|
|
461
|
+
//#region src/harness/adapter.d.ts
|
|
462
|
+
/** One turn to run. */
|
|
463
|
+
interface TurnInput {
|
|
464
|
+
message: string;
|
|
465
|
+
/**
|
|
466
|
+
* How long a turn may go without a real event before it fails. Keep-alive pings do not
|
|
467
|
+
* count. Unset means the adapter's default.
|
|
468
|
+
*/
|
|
469
|
+
inactivityTimeoutMs?: number;
|
|
470
|
+
/**
|
|
471
|
+
* Send `message` into the turn that is running, or queue it, instead of starting a turn.
|
|
472
|
+
* Needs the matching capability (`steer` or `followUp`). The returned stream ends with
|
|
473
|
+
* `done` once the harness has accepted the message.
|
|
474
|
+
*/
|
|
475
|
+
streamingBehavior?: "steer" | "followUp";
|
|
476
|
+
}
|
|
477
|
+
/**
|
|
478
|
+
* One harness (Pi, Claude Code, Codex) driven inside a sandbox the SDK provisions.
|
|
479
|
+
*
|
|
480
|
+
* An adapter is created per agent and holds that agent's connection, so one instance
|
|
481
|
+
* serves one sandbox. Create it with `createHarness()`.
|
|
482
|
+
*
|
|
483
|
+
* Contract:
|
|
484
|
+
* - A turn yields exactly one `done` event, last, including after `abort()` and after a
|
|
485
|
+
* failure. A failure is an `error` event then `done`. `runTurn` does not throw for it.
|
|
486
|
+
* - `steer`, `followUp`, `compact` and `forkAt` exist only when the matching capability is `true`. Calling
|
|
487
|
+
* `steer` between turns throws. It never queues for the next turn.
|
|
488
|
+
* - A capability declared `false` is never called. Use `requireHarnessCapability()`.
|
|
489
|
+
*
|
|
490
|
+
* @experimental The harness layer is being built. Expect changes before it is stable.
|
|
491
|
+
*/
|
|
492
|
+
interface HarnessAdapter {
|
|
493
|
+
/** A label for logs and errors. Never branch on it: branch on `capabilities`. */
|
|
494
|
+
readonly id: string;
|
|
495
|
+
/** Declared by the adapter, never probed. */
|
|
496
|
+
readonly capabilities: HarnessCapabilities;
|
|
497
|
+
/** Install the harness and spec packages. Slow. The result is captured by a snapshot. */
|
|
498
|
+
install(sb: HarnessSandbox, spec: AgentSpec): Promise<void>;
|
|
499
|
+
/**
|
|
500
|
+
* Write config, env and the in-sandbox bridge. Runs on every start, fresh install and
|
|
501
|
+
* snapshot resume alike, so env, model and bridge code stay current.
|
|
502
|
+
*/
|
|
503
|
+
configure(sb: HarnessSandbox, spec: AgentSpec, resolvedEnv: Record<string, string>, opts?: {
|
|
504
|
+
resume?: boolean;
|
|
505
|
+
}): Promise<void>;
|
|
506
|
+
/**
|
|
507
|
+
* Start the in-sandbox process. `unsetVars` are cleared in the same command that starts it,
|
|
508
|
+
* so a forked sandbox's baked-in env does not leak into the harness.
|
|
509
|
+
*/
|
|
510
|
+
start(sb: HarnessSandbox, opts?: {
|
|
511
|
+
unsetVars?: string[];
|
|
512
|
+
}): Promise<void>;
|
|
513
|
+
/** Bind to a process that is already running. Starts nothing. Follow with `waitReady()`. */
|
|
514
|
+
reattach(sb: Pick<HarnessSandbox, "proxy">): Promise<void>;
|
|
515
|
+
/** Resolve once the process answers, or throw after `timeoutMs`. */
|
|
516
|
+
waitReady(timeoutMs?: number): Promise<void>;
|
|
517
|
+
/** Run one turn. See the contract above. */
|
|
518
|
+
runTurn(input: TurnInput): AsyncIterable<HarnessEvent>;
|
|
519
|
+
/** Stop the turn that is running. Its stream ends with `done` and reason `aborted`. */
|
|
520
|
+
abort(): Promise<void>;
|
|
521
|
+
/** Inject a message into the running turn. Present iff `capabilities.steer`. */
|
|
522
|
+
steer?(message: string): Promise<void>;
|
|
523
|
+
/** Queue a message for after the running turn. Present iff `capabilities.followUp`. */
|
|
524
|
+
followUp?(message: string): Promise<void>;
|
|
525
|
+
/**
|
|
526
|
+
* Compact the context now. Present iff `capabilities.compact`. `instructions` steers what
|
|
527
|
+
* the summary keeps, where the harness takes them. The result is harness-specific.
|
|
528
|
+
*/
|
|
529
|
+
compact?(instructions?: string): Promise<unknown>;
|
|
530
|
+
/**
|
|
531
|
+
* Continue from an earlier point as a new session, by the `messageId` of a `message_start`.
|
|
532
|
+
* Present iff `capabilities.fork`. The id must come from this adapter's own events: a
|
|
533
|
+
* harness's fork point is not always the id of the message a user sees.
|
|
534
|
+
* `sessionRef` is the id to resume the new session with, or `null` when the harness has none.
|
|
535
|
+
*/
|
|
536
|
+
forkAt?(messageId: string): Promise<{
|
|
537
|
+
sessionRef: string | null;
|
|
538
|
+
}>;
|
|
539
|
+
/** Answer a `permission_request`. */
|
|
540
|
+
resolvePermission(requestId: string, decision: PermissionDecision): Promise<void>;
|
|
541
|
+
/** Tool calls paused awaiting a decision. */
|
|
542
|
+
listPendingPermissions(): Promise<PendingPermission[]>;
|
|
543
|
+
/** Close the connections this adapter left open. Call once, as the agent closes. */
|
|
544
|
+
dispose(): void;
|
|
545
|
+
}
|
|
546
|
+
//#endregion
|
|
547
|
+
//#region src/harness/bridge.d.ts
|
|
548
|
+
/**
|
|
549
|
+
* What every harness that runs behind an in-sandbox HTTP bridge shares: finding the bridge,
|
|
550
|
+
* waiting for it, streaming a turn from it, closing the streams it leaves open, and the
|
|
551
|
+
* permission endpoints. A subclass adds its own install, configure and turn mapping.
|
|
552
|
+
*
|
|
553
|
+
* The bridge contract (what a bridge script must serve):
|
|
554
|
+
* - `GET /health` returns `{ ok: true }` once it can take a turn.
|
|
555
|
+
* - `POST /abort` ends the running turn.
|
|
556
|
+
* - `POST /permission-response` takes `{ requestId, decision }`.
|
|
557
|
+
* - `GET /pending-permissions` returns `{ ok, data: { pending: PendingPermission[] } }`.
|
|
558
|
+
* - A turn is an SSE stream of JSON frames, ended by `data: [DONE]`. A frame `{ error }` fails it.
|
|
559
|
+
*/
|
|
560
|
+
declare abstract class BridgeHarness<E extends {
|
|
561
|
+
type?: string;
|
|
562
|
+
requestId?: string;
|
|
563
|
+
}> {
|
|
564
|
+
/** The path the bridge script is written to in the sandbox. */
|
|
565
|
+
protected abstract readonly bridgeScriptPath: string;
|
|
544
566
|
private _bridgeUrl;
|
|
545
567
|
/**
|
|
546
|
-
* Controllers for
|
|
547
|
-
*
|
|
548
|
-
*
|
|
549
|
-
*
|
|
550
|
-
*
|
|
551
|
-
*
|
|
552
|
-
* long-lived, heartbeat-pinged connections (unlike execd's exec/code streams, which
|
|
553
|
-
* self-resolve within execd's own bounded post-completion sleep either way — see
|
|
554
|
-
* disposeConnections() below).
|
|
568
|
+
* Controllers for streams `sseStream` deliberately left open (its early return on `[DONE]`,
|
|
569
|
+
* to dodge the same OpenSandbox proxy behavior `ExecClient.parseSSE` documents).
|
|
570
|
+
* `AbortController.abort()`, not `reader.cancel()`: Bun's `fetch()` tears down the
|
|
571
|
+
* underlying connection reliably on an abort signal, but was observed to leave the socket
|
|
572
|
+
* referenced after `reader.cancel()` on the bridge's long-lived, heartbeat-pinged
|
|
573
|
+
* connections.
|
|
555
574
|
*
|
|
556
|
-
* Known limitation:
|
|
557
|
-
*
|
|
558
|
-
*
|
|
559
|
-
*
|
|
560
|
-
* opensandbox-group/OpenSandbox#1277 (execd's chunked-SSE termination confusing the
|
|
561
|
-
* OpenSandbox control server's own proxy relay, which is what `bridgeUrl` is proxied
|
|
562
|
-
* through). Tracked in our own #189; not fixable from this file alone.
|
|
575
|
+
* Known limitation: a script making two or more such calls before close() can still hang
|
|
576
|
+
* even though every controller here aborts cleanly on the client side. Root cause is the
|
|
577
|
+
* same class of bug as opensandbox-group/OpenSandbox#1277 (execd's chunked-SSE termination
|
|
578
|
+
* confusing the control server's proxy relay). Tracked in our own #189.
|
|
563
579
|
*/
|
|
564
|
-
|
|
565
|
-
|
|
580
|
+
protected readonly pendingStreams: Set<AbortController>;
|
|
581
|
+
abstract readonly id: string;
|
|
582
|
+
protected get bridgeUrl(): string;
|
|
566
583
|
/**
|
|
567
|
-
*
|
|
568
|
-
*
|
|
569
|
-
*
|
|
570
|
-
*
|
|
571
|
-
* execd's exec/code streams (see `ExecClient.disposeConnections()`), the bridge's own
|
|
572
|
-
* `: ping` heartbeat (every 3s, see pi-bridge.js) means there's no bounded server-side
|
|
573
|
-
* timeout to eventually resolve a dangling one on its own. Call this once the agent is
|
|
574
|
-
* being torn down anyway (from `agent.close()`) instead of leaving the process to hang
|
|
575
|
-
* forever on whichever stream's `[DONE]` arrived last.
|
|
584
|
+
* Start the bridge. `unsetVars`, when given, is prefixed as `unset A B C; ` on the *same*
|
|
585
|
+
* exec command that starts `node`, which a forked sandbox needs: the container's OS-level
|
|
586
|
+
* env still carries whatever the parent had baked in at snapshot time. A plain
|
|
587
|
+
* `sb.exec("unset ...")` beforehand would not work: each `exec()` is its own shell session.
|
|
576
588
|
*/
|
|
577
|
-
|
|
589
|
+
start(sb: HarnessSandbox, opts?: {
|
|
590
|
+
unsetVars?: string[];
|
|
591
|
+
}): Promise<void>;
|
|
592
|
+
/**
|
|
593
|
+
* Rebind to a bridge that is already running. `sb.proxy(port)` is a pure URL lookup: it
|
|
594
|
+
* starts nothing, so nothing in the sandbox changes. Follow with `waitReady()`, because the
|
|
595
|
+
* container can be alive while the bridge process inside it is not.
|
|
596
|
+
*/
|
|
597
|
+
reattach(sb: Pick<HarnessSandbox, "proxy">): Promise<void>;
|
|
598
|
+
waitReady(timeoutMs?: number): Promise<void>;
|
|
599
|
+
/**
|
|
600
|
+
* Force-close the streams left open (see `pendingStreams`). They sit ESTABLISHED, keeping
|
|
601
|
+
* the event loop alive, because the bridge's own `: ping` heartbeat means no server-side
|
|
602
|
+
* timeout ever ends a dangling one. Call once, as the agent closes.
|
|
603
|
+
*/
|
|
604
|
+
dispose(): void;
|
|
605
|
+
abort(): Promise<void>;
|
|
606
|
+
resolvePermission(requestId: string, decision: PermissionDecision): Promise<void>;
|
|
607
|
+
listPendingPermissions(): Promise<PendingPermission[]>;
|
|
608
|
+
/** Open a turn stream on the bridge. */
|
|
609
|
+
protected stream(path: string, body: unknown, inactivityTimeoutMs?: number): AsyncGenerator<E>;
|
|
610
|
+
}
|
|
611
|
+
//#endregion
|
|
612
|
+
//#region src/adapters/claude-code.d.ts
|
|
613
|
+
/**
|
|
614
|
+
* What Claude Code declares. Each `false` is a thing the bridge does not do today, not a
|
|
615
|
+
* limit of the SDK: `steer` and `followUp` have no mid-turn injection in single-prompt mode,
|
|
616
|
+
* `compact` and `setModel` are not wired, and `reasoning` needs extended thinking turned on.
|
|
617
|
+
*/
|
|
618
|
+
export declare const CLAUDE_CODE_CAPABILITIES: HarnessCapabilities;
|
|
619
|
+
/**
|
|
620
|
+
* Claude Code, driven through the Claude Agent SDK by a bridge in the sandbox. The bridge's
|
|
621
|
+
* frames are already `HarnessEvent`s, so `runTurn` forwards them.
|
|
622
|
+
*
|
|
623
|
+
* @experimental The harness layer is being built. Expect changes before it is stable.
|
|
624
|
+
*/
|
|
625
|
+
export declare class ClaudeCodeAdapter extends BridgeHarness<HarnessEvent & {
|
|
626
|
+
requestId?: string;
|
|
627
|
+
}> implements HarnessAdapter {
|
|
628
|
+
readonly id = "claude-code";
|
|
629
|
+
readonly capabilities: HarnessCapabilities;
|
|
630
|
+
protected readonly bridgeScriptPath = "/alineo-bridge.js";
|
|
631
|
+
/** Install the Agent SDK globally, and any spec packages. Slow: a snapshot captures it. */
|
|
632
|
+
install(sb: HarnessSandbox, spec: AgentSpec): Promise<void>;
|
|
633
|
+
configure(sb: HarnessSandbox, spec: AgentSpec, resolvedEnv: Record<string, string>, opts?: {
|
|
634
|
+
resume?: boolean;
|
|
635
|
+
}): Promise<void>;
|
|
636
|
+
/**
|
|
637
|
+
* One turn as harness events. The bridge already speaks `HarnessEvent`, so the frames pass
|
|
638
|
+
* through. A bridge error frame, timeout or dropped stream is an `error` then `done`, and
|
|
639
|
+
* does not throw. A stream that ends with no `done` is `aborted`.
|
|
640
|
+
*/
|
|
641
|
+
runTurn(input: TurnInput): AsyncGenerator<HarnessEvent>;
|
|
642
|
+
forkAt(messageId: string): Promise<{
|
|
643
|
+
sessionRef: string | null;
|
|
644
|
+
}>;
|
|
645
|
+
}
|
|
646
|
+
//#endregion
|
|
647
|
+
//#region src/adapters/codex.d.ts
|
|
648
|
+
/**
|
|
649
|
+
* What Codex declares, each backed by an `app-server` method: `turn/steer`,
|
|
650
|
+
* `thread/compact/start`, `thread/fork`, the approval requests, and reasoning deltas.
|
|
651
|
+
* `followUp` and `setModel` are not wired.
|
|
652
|
+
*/
|
|
653
|
+
export declare const CODEX_CAPABILITIES: HarnessCapabilities;
|
|
654
|
+
/**
|
|
655
|
+
* Codex, driven through `codex app-server` (JSON-RPC over stdio) by a bridge in the sandbox.
|
|
656
|
+
* The bridge's frames are already `HarnessEvent`s, so `runTurn` forwards them.
|
|
657
|
+
*
|
|
658
|
+
* Fork granularity is the turn: every message of a turn has the turn id as its `messageId`,
|
|
659
|
+
* because `thread/fork` takes `lastTurnId`.
|
|
660
|
+
*
|
|
661
|
+
* @experimental The harness layer is being built. Expect changes before it is stable.
|
|
662
|
+
*/
|
|
663
|
+
export declare class CodexAdapter extends BridgeHarness<HarnessEvent & {
|
|
664
|
+
requestId?: string;
|
|
665
|
+
}> implements HarnessAdapter {
|
|
666
|
+
readonly id = "codex";
|
|
667
|
+
readonly capabilities: HarnessCapabilities;
|
|
668
|
+
protected readonly bridgeScriptPath = "/alineo-bridge.js";
|
|
669
|
+
install(sb: HarnessSandbox, spec: AgentSpec): Promise<void>;
|
|
670
|
+
configure(sb: HarnessSandbox, spec: AgentSpec, resolvedEnv: Record<string, string>, opts?: {
|
|
671
|
+
resume?: boolean;
|
|
672
|
+
}): Promise<void>;
|
|
673
|
+
runTurn(input: TurnInput): AsyncGenerator<HarnessEvent>;
|
|
674
|
+
/** `turn/steer` into the running turn. Refused with `no turn in progress` between turns. */
|
|
675
|
+
steer(message: string): Promise<void>;
|
|
676
|
+
compact(): Promise<unknown>;
|
|
677
|
+
/** `thread/fork`. `messageId` is a turn id, from a `message_start` of this adapter. */
|
|
678
|
+
forkAt(messageId: string): Promise<{
|
|
679
|
+
sessionRef: string | null;
|
|
680
|
+
}>;
|
|
681
|
+
}
|
|
682
|
+
//#endregion
|
|
683
|
+
//#region src/adapters/pi.d.ts
|
|
684
|
+
/** The subset of `SandboxHandle` that `PiAdapter` calls. Kept as an alias of `HarnessSandbox`. */
|
|
685
|
+
type PiSandbox = HarnessSandbox;
|
|
686
|
+
declare class PiAdapter extends BridgeHarness<AgentEvent> implements HarnessAdapter {
|
|
687
|
+
readonly id = "pi";
|
|
688
|
+
readonly capabilities: HarnessCapabilities;
|
|
689
|
+
protected readonly bridgeScriptPath = "/alineo-bridge.js";
|
|
578
690
|
/** Install Pi CLI and any spec packages. Slow — result is captured by checkpoint(). */
|
|
579
691
|
install(sb: PiSandbox, spec: AgentSpec): Promise<void>;
|
|
580
692
|
/**
|
|
@@ -584,41 +696,32 @@ declare class PiAdapter {
|
|
|
584
696
|
configure(sb: PiSandbox, spec: AgentSpec, resolvedEnv: Record<string, string>, opts?: {
|
|
585
697
|
resume?: boolean;
|
|
586
698
|
}): Promise<void>;
|
|
587
|
-
/**
|
|
588
|
-
* Start the bridge. `unsetVars`, when given, is prefixed as `unset A B C; ` on the
|
|
589
|
-
* *same* exec command that starts `node` — required for `Alineo.spawn()`'s forked
|
|
590
|
-
* sandboxes, where the container's OS-level env still carries whatever the parent
|
|
591
|
-
* had baked into it at snapshot time (`env` passed to `createSandbox` at fork time
|
|
592
|
-
* has no effect on this — verified live, see `plans/alineo-rlm-substrate.md`). A
|
|
593
|
-
* plain `sb.exec("unset ...")` beforehand would not work: `unset` only clears the
|
|
594
|
-
* shell session it runs in, and each `exec()` call is its own session — it has to
|
|
595
|
-
* be part of the exact command that spawns the bridge process so the bridge (and
|
|
596
|
-
* everything it in turn spawns, including Pi itself) inherits the already-clean env.
|
|
597
|
-
*/
|
|
699
|
+
/** `start()` under its older name. */
|
|
598
700
|
startBridge(sb: PiSandbox, unsetVars?: string[]): Promise<void>;
|
|
701
|
+
/** `fork(entryId)` in the harness-neutral shape. Pi switches its own session in place. */
|
|
702
|
+
forkAt(messageId: string): Promise<{
|
|
703
|
+
sessionRef: string | null;
|
|
704
|
+
}>;
|
|
705
|
+
/** `reattach()` under its older name. */
|
|
706
|
+
reattachBridge(sb: Pick<HarnessSandbox, "proxy">): Promise<void>;
|
|
707
|
+
/** `dispose()` under its older name. */
|
|
708
|
+
disposeConnections(): void;
|
|
599
709
|
/**
|
|
600
|
-
*
|
|
601
|
-
*
|
|
602
|
-
*
|
|
603
|
-
* itself: no killed process, no dropped in-flight turn, no reset Pi conversation state.
|
|
710
|
+
* One turn as harness events, ending in exactly one `done`. A failure (the bridge sends an
|
|
711
|
+
* error frame, the stream times out or drops) becomes an `error` event then `done`: it
|
|
712
|
+
* does not throw, and the `error` event's `raw` is the original error.
|
|
604
713
|
*
|
|
605
|
-
*
|
|
606
|
-
*
|
|
607
|
-
*
|
|
714
|
+
* A stream that ends with no `agent_end` is `aborted`. The bridge ends a stream that way
|
|
715
|
+
* only when someone called `/abort`, from this process or another. A message sent with
|
|
716
|
+
* `streamingBehavior` also ends with no `agent_end`: that is `completed`.
|
|
608
717
|
*/
|
|
609
|
-
|
|
610
|
-
waitReady(timeoutMs?: number): Promise<void>;
|
|
718
|
+
runTurn(input: TurnInput): AsyncGenerator<HarnessEvent>;
|
|
611
719
|
prompt(message: string, opts?: {
|
|
612
720
|
streamingBehavior?: "steer" | "followUp";
|
|
613
721
|
inactivityTimeoutMs?: number;
|
|
614
722
|
}): AgentStream;
|
|
615
723
|
bash(command: string): AgentStream;
|
|
616
724
|
steer(message: string): Promise<void>;
|
|
617
|
-
abort(): Promise<void>;
|
|
618
|
-
/** Resolve a pending `permission_request` (see `AgentEvent`'s `permission_request`). */
|
|
619
|
-
resolvePermission(requestId: string, decision: PermissionDecision): Promise<void>;
|
|
620
|
-
/** Tool calls currently paused awaiting a human decision. */
|
|
621
|
-
listPendingPermissions(): Promise<PendingPermission[]>;
|
|
622
725
|
followUp(message: string): Promise<void>;
|
|
623
726
|
newSession(): Promise<void>;
|
|
624
727
|
setThinkingLevel(level: ThinkingLevel): Promise<void>;
|
|
@@ -666,34 +769,197 @@ declare class PiAdapter {
|
|
|
666
769
|
getLogs(): Promise<string>;
|
|
667
770
|
}
|
|
668
771
|
//#endregion
|
|
669
|
-
//#region src/
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
772
|
+
//#region src/harness/registry.d.ts
|
|
773
|
+
/**
|
|
774
|
+
* Every harness the SDK can drive, by id, and the concrete adapter class for each.
|
|
775
|
+
*
|
|
776
|
+
* The concrete type is here, not just `HarnessAdapter`, because `Alineo` still calls Pi-only
|
|
777
|
+
* methods. When those move behind `agent.harness<"pi">()`, this map is what types that call.
|
|
778
|
+
*/
|
|
779
|
+
interface HarnessRegistry {
|
|
780
|
+
pi: PiAdapter;
|
|
781
|
+
"claude-code": ClaudeCodeAdapter;
|
|
782
|
+
codex: CodexAdapter;
|
|
676
783
|
}
|
|
784
|
+
/** The ids `createHarness()` accepts. */
|
|
785
|
+
export declare function registeredHarnesses(): string[];
|
|
677
786
|
/**
|
|
678
|
-
*
|
|
679
|
-
*
|
|
680
|
-
* model/provider (CLI flags only), and cosmetic fields.
|
|
787
|
+
* Create the adapter for a harness id. The only place an adapter class is constructed.
|
|
788
|
+
* Throws `SPEC_INVALID` for an id nothing registered.
|
|
681
789
|
*/
|
|
682
|
-
export declare function
|
|
683
|
-
/**
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
790
|
+
export declare function createHarness<K extends keyof HarnessRegistry>(id: K): HarnessRegistry[K];
|
|
791
|
+
/**
|
|
792
|
+
* Refuse a call the harness declared it cannot do, before anything is sent. Same idea as
|
|
793
|
+
* `requireCapability` for sandbox providers.
|
|
794
|
+
*/
|
|
795
|
+
export declare function requireHarnessCapability(adapter: Pick<HarnessAdapter, "id" | "capabilities">, capability: HarnessCapability): void;
|
|
796
|
+
//#endregion
|
|
797
|
+
//#region src/harness/fake.d.ts
|
|
798
|
+
/** What a `FakeHarness` does on its next turn. */
|
|
799
|
+
type FakeScenario = {
|
|
800
|
+
kind: "text";
|
|
801
|
+
text: string;
|
|
802
|
+
} | {
|
|
803
|
+
kind: "tool";
|
|
804
|
+
toolName: string;
|
|
805
|
+
result: string;
|
|
806
|
+
} |
|
|
807
|
+
/** Starts, then waits until `abort()`. */
|
|
808
|
+
{
|
|
809
|
+
kind: "hang";
|
|
810
|
+
} | {
|
|
811
|
+
kind: "fail";
|
|
812
|
+
message: string;
|
|
813
|
+
} |
|
|
814
|
+
/** Asks for permission to run `tool`, then runs it only if the answer allows. */
|
|
815
|
+
{
|
|
816
|
+
kind: "permission";
|
|
817
|
+
tool: string;
|
|
818
|
+
target: string;
|
|
819
|
+
};
|
|
820
|
+
/**
|
|
821
|
+
* A harness that runs no process: it plays a `FakeScenario` in memory. For tests that need
|
|
822
|
+
* a `HarnessAdapter` and for proving the conformance suite itself is satisfiable. It is not
|
|
823
|
+
* registered, so a spec cannot select it.
|
|
824
|
+
*
|
|
825
|
+
* @experimental The harness layer is being built. Expect changes before it is stable.
|
|
826
|
+
*/
|
|
827
|
+
export declare class FakeHarness implements HarnessAdapter {
|
|
828
|
+
private readonly scenario;
|
|
829
|
+
readonly id = "fake";
|
|
830
|
+
readonly capabilities: HarnessCapabilities;
|
|
831
|
+
/** Lifecycle calls in order, for assertions. */
|
|
832
|
+
readonly calls: string[];
|
|
833
|
+
/** Messages `steer` and `followUp` accepted. */
|
|
834
|
+
readonly received: string[];
|
|
835
|
+
steer?: (message: string) => Promise<void>;
|
|
836
|
+
followUp?: (message: string) => Promise<void>;
|
|
837
|
+
forkAt?: (messageId: string) => Promise<{
|
|
838
|
+
sessionRef: string | null;
|
|
839
|
+
}>;
|
|
840
|
+
compact?: (instructions?: string) => Promise<unknown>;
|
|
841
|
+
private turnActive;
|
|
842
|
+
private release;
|
|
843
|
+
private pending;
|
|
844
|
+
constructor(scenario: FakeScenario, capabilities?: Partial<HarnessCapabilities>);
|
|
845
|
+
install(_sb: HarnessSandbox, _spec: AgentSpec): Promise<void>;
|
|
846
|
+
configure(): Promise<void>;
|
|
847
|
+
start(): Promise<void>;
|
|
848
|
+
reattach(): Promise<void>;
|
|
849
|
+
waitReady(): Promise<void>;
|
|
850
|
+
runTurn(_input: TurnInput): AsyncGenerator<HarnessEvent>;
|
|
851
|
+
abort(): Promise<void>;
|
|
852
|
+
resolvePermission(requestId: string, decision: PermissionDecision): Promise<void>;
|
|
853
|
+
listPendingPermissions(): Promise<PendingPermission[]>;
|
|
854
|
+
dispose(): void;
|
|
855
|
+
}
|
|
856
|
+
//#endregion
|
|
857
|
+
//#region src/config.d.ts
|
|
858
|
+
/**
|
|
859
|
+
* Shape of `alineo.config.json`, merged with built-in defaults.
|
|
860
|
+
*
|
|
861
|
+
* The schema and the merge live in `@alineo-labs/config-shared` because three consumers read
|
|
862
|
+
* this same file (this package, `@alineo-labs/cli-shared`, and alineod through its Docker
|
|
863
|
+
* entrypoint). That package is private and bundled at build time, so nothing new is resolved at
|
|
864
|
+
* runtime for anyone installing `alineo`.
|
|
865
|
+
*/
|
|
866
|
+
type AlineoAgentConfig = ProjectConfig;
|
|
867
|
+
//#endregion
|
|
868
|
+
//#region src/blob-store.d.ts
|
|
869
|
+
/**
|
|
870
|
+
* Where a checkpoint tarball (or any backup file) lives when it is not on the host's disk.
|
|
871
|
+
*
|
|
872
|
+
* durability-roadmap M4, 4.1. A checkpoint on the host disk survives a lost container. It does not
|
|
873
|
+
* survive a lost disk. `BlobStore` is the small surface the checkpoint and restore code needs from
|
|
874
|
+
* object storage, so the S3 client stays behind one interface: another store, or a fake in a test,
|
|
875
|
+
* is one class.
|
|
876
|
+
*
|
|
877
|
+
* Keys are relative to the store. A store may sit under a prefix in its bucket, and `refOf()` /
|
|
878
|
+
* `keyOf()` convert between a key and the full reference written to the ledger.
|
|
879
|
+
*/
|
|
880
|
+
interface BlobInfo {
|
|
881
|
+
/** Relative to the store, the same key `put()` took. */
|
|
882
|
+
key: string;
|
|
883
|
+
/** Unix ms. */
|
|
884
|
+
lastModified: number;
|
|
885
|
+
}
|
|
886
|
+
interface BlobStore {
|
|
887
|
+
/** `string` is the path of a local file, streamed from disk. Bytes are sent as they are. */
|
|
888
|
+
put(key: string, body: string | Uint8Array): Promise<void>;
|
|
889
|
+
/** Throws if the key does not exist. */
|
|
890
|
+
get(key: string): Promise<Uint8Array>;
|
|
891
|
+
/** Not an error when the key is already gone. */
|
|
892
|
+
delete(key: string): Promise<void>;
|
|
893
|
+
/** Every blob whose key starts with `prefix`, in no particular order. */
|
|
894
|
+
list(prefix: string): Promise<BlobInfo[]>;
|
|
895
|
+
/** The reference recorded in the ledger for `key`. Stable across processes and hosts. */
|
|
896
|
+
refOf(key: string): string;
|
|
897
|
+
/** The inverse of `refOf()`, or `undefined` when this store did not produce `ref`. */
|
|
898
|
+
keyOf(ref: string): string | undefined;
|
|
899
|
+
}
|
|
900
|
+
/**
|
|
901
|
+
* The slice of `Bun.S3Client` that `S3BlobStore` calls. A test passes a fake instead of a bucket.
|
|
902
|
+
*/
|
|
903
|
+
interface S3ClientLike {
|
|
904
|
+
file(key: string): {
|
|
905
|
+
write(data: Blob | Uint8Array | string): Promise<number>;
|
|
906
|
+
bytes(): Promise<Uint8Array>;
|
|
907
|
+
};
|
|
908
|
+
delete(key: string): Promise<void>;
|
|
909
|
+
list(options: {
|
|
910
|
+
prefix?: string;
|
|
911
|
+
continuationToken?: string;
|
|
912
|
+
}): Promise<{
|
|
913
|
+
contents?: Array<{
|
|
914
|
+
key: string;
|
|
915
|
+
lastModified?: string;
|
|
916
|
+
}>;
|
|
917
|
+
isTruncated?: boolean;
|
|
918
|
+
nextContinuationToken?: string;
|
|
919
|
+
}>;
|
|
920
|
+
}
|
|
921
|
+
interface S3BlobStoreOptions {
|
|
922
|
+
bucket: string;
|
|
923
|
+
/** Everything this store writes goes under it. No leading or trailing slash needed. */
|
|
924
|
+
prefix?: string;
|
|
925
|
+
/** For R2, MinIO and other S3-compatible services. Leave out for AWS. */
|
|
926
|
+
endpoint?: string;
|
|
927
|
+
region?: string;
|
|
928
|
+
accessKeyId?: string;
|
|
929
|
+
secretAccessKey?: string;
|
|
930
|
+
/** A fake in tests. Production code leaves it out and gets a `Bun.S3Client`. */
|
|
931
|
+
client?: S3ClientLike;
|
|
932
|
+
}
|
|
933
|
+
/** S3, R2, MinIO: anything `Bun.S3Client` talks to. Runs under Bun only. */
|
|
934
|
+
export declare class S3BlobStore implements BlobStore {
|
|
935
|
+
private readonly client;
|
|
936
|
+
private readonly bucket;
|
|
937
|
+
private readonly prefix;
|
|
938
|
+
constructor(opts: S3BlobStoreOptions);
|
|
939
|
+
private full;
|
|
940
|
+
put(key: string, body: string | Uint8Array): Promise<void>;
|
|
941
|
+
get(key: string): Promise<Uint8Array>;
|
|
942
|
+
delete(key: string): Promise<void>;
|
|
943
|
+
list(prefix: string): Promise<BlobInfo[]>;
|
|
944
|
+
refOf(key: string): string;
|
|
945
|
+
keyOf(ref: string): string | undefined;
|
|
946
|
+
}
|
|
947
|
+
/**
|
|
948
|
+
* Keeps blobs in a Map. The store the unit tests use, and a reference for what a `BlobStore` must
|
|
949
|
+
* do. `now` lets a test age a blob without waiting.
|
|
950
|
+
*/
|
|
951
|
+
export declare class MemoryBlobStore implements BlobStore {
|
|
952
|
+
private readonly now;
|
|
953
|
+
private readonly blobs;
|
|
954
|
+
constructor(now?: () => number);
|
|
955
|
+
put(key: string, body: string | Uint8Array): Promise<void>;
|
|
956
|
+
get(key: string): Promise<Uint8Array>;
|
|
957
|
+
delete(key: string): Promise<void>;
|
|
958
|
+
list(prefix: string): Promise<BlobInfo[]>;
|
|
959
|
+
refOf(key: string): string;
|
|
960
|
+
keyOf(ref: string): string | undefined;
|
|
961
|
+
/** Test seam: every key, so a test can assert what was written or deleted. */
|
|
962
|
+
keys(): string[];
|
|
697
963
|
}
|
|
698
964
|
//#endregion
|
|
699
965
|
//#region src/agent/egress-approval.d.ts
|
|
@@ -794,12 +1060,163 @@ export declare class EgressApprovalGate {
|
|
|
794
1060
|
* exported interface within the package.
|
|
795
1061
|
*/
|
|
796
1062
|
interface AgentInternal {
|
|
797
|
-
readonly adapter:
|
|
1063
|
+
readonly adapter: HarnessAdapter;
|
|
798
1064
|
readonly sandbox: SandboxHandle;
|
|
799
1065
|
env: Record<string, string>;
|
|
800
1066
|
/** Present when the spec has `approval: "hold"` credential bindings. */
|
|
801
1067
|
readonly egressGate?: EgressApprovalGate;
|
|
802
1068
|
}
|
|
1069
|
+
declare namespace factory_d_exports {
|
|
1070
|
+
export { AgentConstructorArgs, AgentRestore, attachAgent, forkChildMemory, loadAgent, reattachAgent, reconcileDroppedPermissions, resumeAgent, spawnChild };
|
|
1071
|
+
}
|
|
1072
|
+
/** Constructor arguments for `Alineo` — returned by each factory function below so the actual
|
|
1073
|
+
* `new Alineo(...)` call stays inside `Alineo`'s own static methods, which alone have access to
|
|
1074
|
+
* its private constructor. */
|
|
1075
|
+
interface AgentConstructorArgs {
|
|
1076
|
+
sandbox: SandboxHandle;
|
|
1077
|
+
spec: AgentSpec;
|
|
1078
|
+
env: Record<string, string>;
|
|
1079
|
+
adapter: HarnessAdapter;
|
|
1080
|
+
fromSnapshot: boolean;
|
|
1081
|
+
/** Run-correlation ID for this agent's sandbox — see `SandboxDetails.runId`. */
|
|
1082
|
+
runId: string;
|
|
1083
|
+
/** Started when the spec has `approval: "hold"` bindings; stopped by `agent.close()`. */
|
|
1084
|
+
egressGate?: EgressApprovalGate;
|
|
1085
|
+
/**
|
|
1086
|
+
* Set only when the sandbox was gone and a fresh one replaced it (`restoreFromCheckpoint`).
|
|
1087
|
+
* `checkpointTurn` is the turn restored from, or `null` when there was no checkpoint and the
|
|
1088
|
+
* agent came back blank.
|
|
1089
|
+
*/
|
|
1090
|
+
restore?: AgentRestore;
|
|
1091
|
+
}
|
|
1092
|
+
interface AgentRestore {
|
|
1093
|
+
checkpointTurn: number | null;
|
|
1094
|
+
}
|
|
1095
|
+
/**
|
|
1096
|
+
* Validate `specInput` and return everything needed to construct a fully initialised `Alineo`.
|
|
1097
|
+
* See `Alineo.start()` for the public-facing docs.
|
|
1098
|
+
*/
|
|
1099
|
+
declare function loadAgent(specInput: AgentSpec | Record<string, unknown>, opts: {
|
|
1100
|
+
adapter: IStorageAdapter;
|
|
1101
|
+
/**
|
|
1102
|
+
* Skip `alineo.config.json` discovery and use this instead — for embedded callers and
|
|
1103
|
+
* tests that must not depend on the working directory.
|
|
1104
|
+
*/
|
|
1105
|
+
config?: AlineoAgentConfig;
|
|
1106
|
+
rebuild?: boolean;
|
|
1107
|
+
spawnDepth?: number;
|
|
1108
|
+
maxAgents?: number;
|
|
1109
|
+
runId?: string;
|
|
1110
|
+
/** Required when the spec has `approval: "hold"` credential bindings — decides each
|
|
1111
|
+
* first outbound request to a held host. See `EgressApprovalGate`. */
|
|
1112
|
+
onEgressRequest?: EgressRequestHandler;
|
|
1113
|
+
}): Promise<AgentConstructorArgs>;
|
|
1114
|
+
/**
|
|
1115
|
+
* Reconnect to a previously-created agent whose host process has exited. See
|
|
1116
|
+
* `Alineo.resume()` for the public-facing docs.
|
|
1117
|
+
*/
|
|
1118
|
+
declare function resumeAgent(sandboxId: string, opts: {
|
|
1119
|
+
adapter: IStorageAdapter;
|
|
1120
|
+
spec?: AgentSpec | Record<string, unknown>;
|
|
1121
|
+
specPath?: string;
|
|
1122
|
+
runId?: string;
|
|
1123
|
+
/**
|
|
1124
|
+
* Skip `alineo.config.json` discovery and use this instead — for embedded callers and
|
|
1125
|
+
* tests that must not depend on the working directory.
|
|
1126
|
+
*/
|
|
1127
|
+
config?: AlineoAgentConfig;
|
|
1128
|
+
/**
|
|
1129
|
+
* Where off-box checkpoints are fetched from when the sandbox is gone and the host's own
|
|
1130
|
+
* checkpoint file is too (a new machine after a disk loss). Without it, only checkpoints on
|
|
1131
|
+
* this host's disk can be restored.
|
|
1132
|
+
*/
|
|
1133
|
+
blobStore?: BlobStore;
|
|
1134
|
+
}): Promise<AgentConstructorArgs>;
|
|
1135
|
+
/**
|
|
1136
|
+
* durability-roadmap.md M1.3: this used to resolve a dropped request with
|
|
1137
|
+
* `decision: { kind: "reject" }` — `PermissionDecision`'s `"reject"` is documented as *a
|
|
1138
|
+
* human's answer*, and no human answered this one. Nobody could: the tool call it was about
|
|
1139
|
+
* died with the old Pi process (OpenSandbox restore is rootfs-only, so it isn't still parked
|
|
1140
|
+
* anywhere to answer). `"dropped"` says what actually happened instead of fabricating a
|
|
1141
|
+
* decision nobody made.
|
|
1142
|
+
*
|
|
1143
|
+
* This is the narrow fix — an honest ledger, not a re-opened decision. The better path forward
|
|
1144
|
+
* is giving a human an actual chance to weigh in: alineod has no live route to answer a
|
|
1145
|
+
* permission request at all today (`driveTurn` calls `agent.prompt()` with no `onPermission`),
|
|
1146
|
+
* so there's nothing yet for a "re-issue this to an operator" version of this function to
|
|
1147
|
+
* re-issue *into*. Once that live path exists, this should queue the same way
|
|
1148
|
+
* `agent.supervision_needed` already does, instead of resolving anything here.
|
|
1149
|
+
*/
|
|
1150
|
+
declare function reconcileDroppedPermissions(adapter: IStorageAdapter, sb: SandboxHandle, name: string, sandboxId: string): Promise<void>;
|
|
1151
|
+
/**
|
|
1152
|
+
* Reconnect to a previously-created agent WITHOUT restarting its bridge. See
|
|
1153
|
+
* `Alineo.reattach()` for the public-facing docs. Structurally `resumeAgent()` minus its two
|
|
1154
|
+
* destructive steps (the `pkill` and the fresh `startBridge()`) — everything else (spec
|
|
1155
|
+
* resolution, env, `client.connect()`) is identical.
|
|
1156
|
+
*/
|
|
1157
|
+
declare function reattachAgent(sandboxId: string, opts: {
|
|
1158
|
+
adapter: IStorageAdapter;
|
|
1159
|
+
spec?: AgentSpec | Record<string, unknown>;
|
|
1160
|
+
specPath?: string;
|
|
1161
|
+
runId?: string;
|
|
1162
|
+
skipReadyCheck?: boolean;
|
|
1163
|
+
/**
|
|
1164
|
+
* Skip `alineo.config.json` discovery and use this instead — for embedded callers and
|
|
1165
|
+
* tests that must not depend on the working directory.
|
|
1166
|
+
*/
|
|
1167
|
+
config?: AlineoAgentConfig;
|
|
1168
|
+
/**
|
|
1169
|
+
* Where off-box checkpoints are fetched from when the sandbox is gone and the host's own
|
|
1170
|
+
* checkpoint file is too (a new machine after a disk loss). Without it, only checkpoints on
|
|
1171
|
+
* this host's disk can be restored.
|
|
1172
|
+
*/
|
|
1173
|
+
blobStore?: BlobStore;
|
|
1174
|
+
}): Promise<AgentConstructorArgs>;
|
|
1175
|
+
/**
|
|
1176
|
+
* Connect to an already-running sandbox WITHOUT touching its Pi bridge. See
|
|
1177
|
+
* `Alineo.attach()` for the public-facing docs.
|
|
1178
|
+
*/
|
|
1179
|
+
declare function attachAgent(sandboxId: string, opts: {
|
|
1180
|
+
adapter: IStorageAdapter;
|
|
1181
|
+
name: string;
|
|
1182
|
+
resources?: {
|
|
1183
|
+
cpu: string;
|
|
1184
|
+
memory: string;
|
|
1185
|
+
gpu?: string;
|
|
1186
|
+
};
|
|
1187
|
+
/**
|
|
1188
|
+
* Skip `alineo.config.json` discovery and use this instead — for embedded callers and
|
|
1189
|
+
* tests that must not depend on the working directory.
|
|
1190
|
+
*/
|
|
1191
|
+
config?: AlineoAgentConfig;
|
|
1192
|
+
}): Promise<AgentConstructorArgs>;
|
|
1193
|
+
/**
|
|
1194
|
+
* Fork `self`'s live sandbox into a brand-new independent sandbox running its
|
|
1195
|
+
* own Pi bridge, per `childSpecPath`. See `Alineo.spawn()` for the public-facing docs.
|
|
1196
|
+
*/
|
|
1197
|
+
declare function spawnChild(self: AgentInternal, childSpecPath: string, opts?: {
|
|
1198
|
+
spawnDepth?: number;
|
|
1199
|
+
maxAgents?: number;
|
|
1200
|
+
}): Promise<AgentConstructorArgs>;
|
|
1201
|
+
/**
|
|
1202
|
+
* Seed a just-constructed spawn child's memory from its parent — the memory-layer
|
|
1203
|
+
* counterpart to `spawnChild()`'s sandbox-level fork above. Called from `Alineo.spawn()`
|
|
1204
|
+
* after the child is constructed (not from `spawnChild()` itself, which runs before the
|
|
1205
|
+
* child exists and so has no `child.resourceRef` to fork into yet).
|
|
1206
|
+
*
|
|
1207
|
+
* A no-op when `parentMemory` is `undefined` — most agents don't have `.memory` configured.
|
|
1208
|
+
* Otherwise forks an independent snapshot copy the child can mutate on its own, not a live
|
|
1209
|
+
* share of the parent's scope (`child.resourceRef` already names a different resource — the
|
|
1210
|
+
* child spec's own name — so this seeds that scope rather than overwriting the parent's).
|
|
1211
|
+
*
|
|
1212
|
+
* The sandbox fork has already succeeded by the time this runs (`child.sandbox` is live) —
|
|
1213
|
+
* if the memory-layer fork throws, close the child sandbox before rethrowing rather than
|
|
1214
|
+
* leaving it orphaned with nothing left to close it.
|
|
1215
|
+
*/
|
|
1216
|
+
declare function forkChildMemory(parentMemory: Memory | undefined, parentRef: ResourceRef, child: {
|
|
1217
|
+
resourceRef: ResourceRef;
|
|
1218
|
+
close: () => Promise<void>;
|
|
1219
|
+
}): Promise<void>;
|
|
803
1220
|
declare namespace session_control_d_exports {
|
|
804
1221
|
export { PermissionHandler, abort, abortBash, abortRetry, bash, followUp, listPendingPermissions, newSession, prompt, resolvePermission, setAutoCompaction, setAutoRetry, setFollowUpMode, setSessionName, setSteeringMode, steer };
|
|
805
1222
|
}
|
|
@@ -875,7 +1292,7 @@ declare function setSessionName(a: AgentInternal, name: string): Promise<void>;
|
|
|
875
1292
|
* while Pi manages its own tool use, file writes, and code execution inside the
|
|
876
1293
|
* sandbox.
|
|
877
1294
|
*
|
|
878
|
-
* Create an agent with `Alineo.
|
|
1295
|
+
* Create an agent with `Alineo.start(spec)`. Always call `close()` when done
|
|
879
1296
|
* to release the underlying sandbox container.
|
|
880
1297
|
*
|
|
881
1298
|
* @example
|
|
@@ -883,7 +1300,7 @@ declare function setSessionName(a: AgentInternal, name: string): Promise<void>;
|
|
|
883
1300
|
* import { Alineo } from "alineo";
|
|
884
1301
|
*
|
|
885
1302
|
* const spec = await Bun.file("./agents/my-agent.json").json();
|
|
886
|
-
* const agent = await Alineo.
|
|
1303
|
+
* const agent = await Alineo.start(spec, { adapter });
|
|
887
1304
|
* try {
|
|
888
1305
|
* for await (const chunk of agent.prompt("Explain this codebase")) {
|
|
889
1306
|
* process.stdout.write(chunk);
|
|
@@ -908,18 +1325,22 @@ export declare class Alineo {
|
|
|
908
1325
|
* `false` on the first load for a given spec, or after `{ rebuild: true }`.
|
|
909
1326
|
*/
|
|
910
1327
|
readonly fromSnapshot: boolean;
|
|
911
|
-
|
|
1328
|
+
/**
|
|
1329
|
+
* The harness this agent runs, as the harness-neutral interface. For a harness's own
|
|
1330
|
+
* methods use `harness()`.
|
|
1331
|
+
*/
|
|
1332
|
+
readonly adapter: HarnessAdapter;
|
|
912
1333
|
env: Record<string, string>;
|
|
913
1334
|
/**
|
|
914
1335
|
* Identifies the logical run this agent's sandbox belongs to — see
|
|
915
1336
|
* `SandboxDetails.runId`. Always present; a fresh `crypto.randomUUID()` if not
|
|
916
|
-
* explicitly passed to `
|
|
917
|
-
* transitively, `alineo
|
|
1337
|
+
* explicitly passed to `start()`/`resume()`. A child from `.spawn()` (and
|
|
1338
|
+
* transitively, `alineo spawn`) always inherits its parent's `runId`.
|
|
918
1339
|
*/
|
|
919
1340
|
readonly runId: string;
|
|
920
1341
|
/**
|
|
921
1342
|
* Optional provider-agnostic memory (`@alineo-labs/memory`), wired in via `opts.memory` on
|
|
922
|
-
* `
|
|
1343
|
+
* `start()`/`resume()`/`attach()`. `undefined` unless explicitly configured — `alineo` never
|
|
923
1344
|
* constructs a `Memory` on your own behalf, matching this package's "own the pipeline,
|
|
924
1345
|
* don't assume a backend" design. `spawn()` carries the parent's `memory` (if any) onto the
|
|
925
1346
|
* child automatically, the same way it force-computes spawn-depth rather than reading it
|
|
@@ -941,7 +1362,7 @@ export declare class Alineo {
|
|
|
941
1362
|
/**
|
|
942
1363
|
* Convenience `ResourceRef` scoping `.memory` calls to this agent. `resourceId`/`teamId`
|
|
943
1364
|
* come from `AgentSpec.resourceId`/`AgentSpec.teamId` (`resourceId` defaulting to this
|
|
944
|
-
* agent's `name` when unset) — `
|
|
1365
|
+
* agent's `name` when unset) — `start()`/`resume()`/`spawn()` also thread both into the
|
|
945
1366
|
* ledger (see each field's own doc comment) so this getter and the agent's own episodic
|
|
946
1367
|
* history stay consistent, including across a spawned child whose `.name` differs from its
|
|
947
1368
|
* memory identity.
|
|
@@ -956,6 +1377,12 @@ export declare class Alineo {
|
|
|
956
1377
|
* Stopped by `close()`.
|
|
957
1378
|
*/
|
|
958
1379
|
readonly egressGate?: EgressApprovalGate;
|
|
1380
|
+
/**
|
|
1381
|
+
* Set when `resume()` or `reattach()` found the sandbox gone and returned an agent on a fresh
|
|
1382
|
+
* one. `checkpointTurn` is the turn it was restored from, or `null` when there was no
|
|
1383
|
+
* checkpoint and the session is blank. Absent on every other agent.
|
|
1384
|
+
*/
|
|
1385
|
+
readonly restore?: AgentRestore;
|
|
959
1386
|
private constructor();
|
|
960
1387
|
/** Egress requests currently awaiting a decision (see `AgentSpec.env` `approval: "hold"`). */
|
|
961
1388
|
pendingEgressRequests(): EgressRequest[];
|
|
@@ -970,13 +1397,13 @@ export declare class Alineo {
|
|
|
970
1397
|
* don't need to call `validateAgentSpec()` yourself first unless you want validation errors
|
|
971
1398
|
* to surface before any sandbox/network work starts.
|
|
972
1399
|
*
|
|
973
|
-
* On first
|
|
974
|
-
* the sandbox is checkpointed. Subsequent `
|
|
1400
|
+
* On first start the Pi CLI is installed inside a `node:22` sandbox, then
|
|
1401
|
+
* the sandbox is checkpointed. Subsequent `start()` calls for the same spec
|
|
975
1402
|
* restore from that snapshot — skipping the install and starting in ~3s instead
|
|
976
1403
|
* of ~90s.
|
|
977
1404
|
*
|
|
978
1405
|
* Pass `{ rebuild: true }` to force a full reinstall (e.g. after changing
|
|
979
|
-
* the spec's `packages` or `
|
|
1406
|
+
* the spec's `packages` or `harnessVersion`).
|
|
980
1407
|
*
|
|
981
1408
|
* Pass `{ spawnDepth }` to override the spec's own `spawnDepth` (e.g. a
|
|
982
1409
|
* `--depth` CLI flag) — standard flag-beats-config precedence. Same for
|
|
@@ -985,7 +1412,7 @@ export declare class Alineo {
|
|
|
985
1412
|
* Reports timing for each phase through `@alineo-labs/logger` (component `agent`, tagged with
|
|
986
1413
|
* the spec `name`). Silent by default — set `ALINEO_LOG_LEVEL=info` to see it.
|
|
987
1414
|
*/
|
|
988
|
-
static
|
|
1415
|
+
static start(spec: AgentSpec | Record<string, unknown>, opts: {
|
|
989
1416
|
adapter: IStorageAdapter;
|
|
990
1417
|
rebuild?: boolean;
|
|
991
1418
|
spawnDepth?: number;
|
|
@@ -993,6 +1420,11 @@ export declare class Alineo {
|
|
|
993
1420
|
runId?: string;
|
|
994
1421
|
/** Wire a `Memory` instance onto the returned agent — see `Alineo.memory`. */
|
|
995
1422
|
memory?: Memory;
|
|
1423
|
+
/**
|
|
1424
|
+
* Skip `alineo.config.json` discovery and use this instead — for embedded callers and
|
|
1425
|
+
* tests that must not depend on the working directory.
|
|
1426
|
+
*/
|
|
1427
|
+
config?: AlineoAgentConfig;
|
|
996
1428
|
/**
|
|
997
1429
|
* Required when the spec has `approval: "hold"` credential bindings — decides each
|
|
998
1430
|
* first outbound request to a held host: return `"allow-once"` (reverts at turn end),
|
|
@@ -1014,20 +1446,20 @@ export declare class Alineo {
|
|
|
1014
1446
|
* first and fall back to this only if it fails (e.g. the whole sandbox — not just this
|
|
1015
1447
|
* process — actually restarted).
|
|
1016
1448
|
*
|
|
1017
|
-
* @param sandboxId The sandbox ID returned by the original `Alineo.
|
|
1449
|
+
* @param sandboxId The sandbox ID returned by the original `Alineo.start()`.
|
|
1018
1450
|
* @param opts.spec An already-parsed agent spec object — skips file I/O entirely, same as
|
|
1019
|
-
* `
|
|
1451
|
+
* `start()`. Takes precedence over `opts.specPath` if both are set.
|
|
1020
1452
|
* @param opts.specPath Path to the agent spec JSON, read and validated internally. If
|
|
1021
1453
|
* neither `opts.spec` nor `opts.specPath` is set, the ledger is queried for the sandbox's
|
|
1022
1454
|
* name and the spec is read from `./agents/<name>.json` — this fallback is the one thing
|
|
1023
|
-
* `resume()` can do that `
|
|
1455
|
+
* `resume()` can do that `start()` can't, since a resumed sandbox's original spec may not be
|
|
1024
1456
|
* in memory anywhere the caller can hand it over.
|
|
1025
1457
|
*
|
|
1026
1458
|
* @example
|
|
1027
1459
|
* ```ts
|
|
1028
1460
|
* // Original process:
|
|
1029
1461
|
* const spec = await Bun.file("./agents/hello-agent.json").json();
|
|
1030
|
-
* const agent = await Alineo.
|
|
1462
|
+
* const agent = await Alineo.start(spec, { adapter });
|
|
1031
1463
|
* console.log(agent.sandboxId); // save this
|
|
1032
1464
|
* // ... process exits ...
|
|
1033
1465
|
*
|
|
@@ -1046,6 +1478,16 @@ export declare class Alineo {
|
|
|
1046
1478
|
runId?: string;
|
|
1047
1479
|
/** Wire a `Memory` instance onto the returned agent — see `Alineo.memory`. */
|
|
1048
1480
|
memory?: Memory;
|
|
1481
|
+
/**
|
|
1482
|
+
* Skip `alineo.config.json` discovery and use this instead — for embedded callers and
|
|
1483
|
+
* tests that must not depend on the working directory.
|
|
1484
|
+
*/
|
|
1485
|
+
config?: AlineoAgentConfig;
|
|
1486
|
+
/**
|
|
1487
|
+
* Where off-box checkpoints are fetched from when the sandbox is gone and this host's own
|
|
1488
|
+
* checkpoint file is too (a new machine after a disk loss). See `BlobStore`.
|
|
1489
|
+
*/
|
|
1490
|
+
blobStore?: BlobStore;
|
|
1049
1491
|
}): Promise<Alineo>;
|
|
1050
1492
|
/**
|
|
1051
1493
|
* Reconnect to a previously-created agent WITHOUT restarting its bridge — the crash-only
|
|
@@ -1063,7 +1505,7 @@ export declare class Alineo {
|
|
|
1063
1505
|
* the bridge process inside it has independently died, and this can't distinguish that from
|
|
1064
1506
|
* a slow-to-respond-but-fine bridge on its own. On failure, fall back to `Alineo.resume()`.
|
|
1065
1507
|
*
|
|
1066
|
-
* @param sandboxId The sandbox ID returned by the original `Alineo.
|
|
1508
|
+
* @param sandboxId The sandbox ID returned by the original `Alineo.start()`/`.spawn()`.
|
|
1067
1509
|
* @param opts.spec / opts.specPath Same three-way fallback as `resume()` — see its docs.
|
|
1068
1510
|
*
|
|
1069
1511
|
* @example
|
|
@@ -1083,6 +1525,16 @@ export declare class Alineo {
|
|
|
1083
1525
|
runId?: string;
|
|
1084
1526
|
/** Wire a `Memory` instance onto the returned agent — see `Alineo.memory`. */
|
|
1085
1527
|
memory?: Memory;
|
|
1528
|
+
/**
|
|
1529
|
+
* Skip `alineo.config.json` discovery and use this instead — for embedded callers and
|
|
1530
|
+
* tests that must not depend on the working directory.
|
|
1531
|
+
*/
|
|
1532
|
+
config?: AlineoAgentConfig;
|
|
1533
|
+
/**
|
|
1534
|
+
* Where off-box checkpoints are fetched from when the sandbox is gone and this host's own
|
|
1535
|
+
* checkpoint file is too (a new machine after a disk loss). See `BlobStore`.
|
|
1536
|
+
*/
|
|
1537
|
+
blobStore?: BlobStore;
|
|
1086
1538
|
/**
|
|
1087
1539
|
* Don't probe the bridge before returning, and accept a Paused sandbox. For a paused
|
|
1088
1540
|
* sandbox, whose frozen bridge can't answer until `agent.sandbox.resume()` — check it
|
|
@@ -1096,7 +1548,7 @@ export declare class Alineo {
|
|
|
1096
1548
|
* `resume()`, which kills and restarts the bridge process. Use this when you only
|
|
1097
1549
|
* need `.spawn()`/`.sandbox`, not `.prompt()`/`.bash()`.
|
|
1098
1550
|
*
|
|
1099
|
-
* The main caller is `alineo
|
|
1551
|
+
* The main caller is `alineo spawn`: it runs as a fresh CLI process started BY the
|
|
1100
1552
|
* very Pi bash-tool call it's attaching to (a master agent spawning a child from
|
|
1101
1553
|
* inside its own turn). Going through `resume()` there would `pkill` the bridge
|
|
1102
1554
|
* that's currently running the Pi process making the call — self-destructive.
|
|
@@ -1107,7 +1559,7 @@ export declare class Alineo {
|
|
|
1107
1559
|
* file, which may not even exist inside this particular sandbox.
|
|
1108
1560
|
*
|
|
1109
1561
|
* When `sandboxId` matches `ALINEO_SANDBOX_ID` in this process's own env (true
|
|
1110
|
-
* self-attach, e.g. `alineo
|
|
1562
|
+
* self-attach, e.g. `alineo spawn` running from inside its own container),
|
|
1111
1563
|
* `/etc/alineo-env` is read straight off the local filesystem instead of via
|
|
1112
1564
|
* `sb.readFile()`. A self-referential exec call would need this sandbox to
|
|
1113
1565
|
* reach itself through its own externally-facing bridge IP, which Docker's
|
|
@@ -1118,7 +1570,7 @@ export declare class Alineo {
|
|
|
1118
1570
|
* `opts.resources` sizes a subsequent `.spawn()`'s forked container — the
|
|
1119
1571
|
* control API doesn't echo back a running sandbox's own resource limits, so
|
|
1120
1572
|
* there's no way to discover this agent's *actual* footprint here. Defaults to
|
|
1121
|
-
* `alineo.config.json`'s `defaults.resources`, same fallback `Alineo.
|
|
1573
|
+
* `alineo.config.json`'s `defaults.resources`, same fallback `Alineo.start()` uses
|
|
1122
1574
|
* for a spec that doesn't set its own.
|
|
1123
1575
|
*/
|
|
1124
1576
|
static attach(sandboxId: string, opts: {
|
|
@@ -1131,11 +1583,16 @@ export declare class Alineo {
|
|
|
1131
1583
|
};
|
|
1132
1584
|
/** Wire a `Memory` instance onto the returned agent — see `Alineo.memory`. */
|
|
1133
1585
|
memory?: Memory;
|
|
1586
|
+
/**
|
|
1587
|
+
* Skip `alineo.config.json` discovery and use this instead — for embedded callers and
|
|
1588
|
+
* tests that must not depend on the working directory.
|
|
1589
|
+
*/
|
|
1590
|
+
config?: AlineoAgentConfig;
|
|
1134
1591
|
}): Promise<Alineo>;
|
|
1135
1592
|
/**
|
|
1136
1593
|
* Fork this agent's live sandbox — filesystem, installed packages, checked-out
|
|
1137
1594
|
* state, everything currently on disk — into a brand-new independent sandbox
|
|
1138
|
-
* running its own Pi bridge, per `childSpecPath`. Unlike `Alineo.
|
|
1595
|
+
* running its own Pi bridge, per `childSpecPath`. Unlike `Alineo.start()` (always
|
|
1139
1596
|
* starts from a spec's own snapshot) or `fork()`/`clone()` below (Pi's own
|
|
1140
1597
|
* conversation-branching — same container, same bridge, new session branch),
|
|
1141
1598
|
* this is sandbox-level forking: the child sees exactly what this agent's
|
|
@@ -1169,6 +1626,17 @@ export declare class Alineo {
|
|
|
1169
1626
|
spawnDepth?: number;
|
|
1170
1627
|
maxAgents?: number;
|
|
1171
1628
|
}): Promise<Alineo>;
|
|
1629
|
+
/**
|
|
1630
|
+
* The harness's own adapter, typed for that harness, for what it has and the others do not.
|
|
1631
|
+
* `agent.harness("pi")` gives Pi's `exportHtml()`, `cycleModel()`, `getCommands()` and the
|
|
1632
|
+
* rest. Throws `CAPABILITY_UNSUPPORTED` when this agent runs a different harness.
|
|
1633
|
+
*
|
|
1634
|
+
* Prefer the methods on `Alineo` itself where they exist: they work on every harness
|
|
1635
|
+
* that declares the capability.
|
|
1636
|
+
*
|
|
1637
|
+
* @experimental The harness layer is being built. Expect changes before it is stable.
|
|
1638
|
+
*/
|
|
1639
|
+
harness<K extends keyof HarnessRegistry>(id: K): HarnessRegistry[K];
|
|
1172
1640
|
/** Send a prompt to Pi and stream the response. Pi manages its own session context. */
|
|
1173
1641
|
prompt(message: string, opts?: {
|
|
1174
1642
|
streamingBehavior?: "steer" | "followUp";
|
|
@@ -1184,6 +1652,8 @@ export declare class Alineo {
|
|
|
1184
1652
|
* Run a shell command inside Pi's working context. Not incrementally
|
|
1185
1653
|
* streamed — Pi returns bash output synchronously, so the full output
|
|
1186
1654
|
* arrives as a single `text` event once the command completes.
|
|
1655
|
+
*
|
|
1656
|
+
* @deprecated Use `agent.harness("pi").bash()`. Moves off `Alineo` because only Pi has it.
|
|
1187
1657
|
*/
|
|
1188
1658
|
bash(command: string): AgentStream;
|
|
1189
1659
|
/** Steer Pi's current response mid-flight. Waits for Pi's RPC acknowledgment. */
|
|
@@ -1216,21 +1686,31 @@ export declare class Alineo {
|
|
|
1216
1686
|
newSession(): Promise<void>;
|
|
1217
1687
|
/** Set Pi's reasoning level (for models that support extended thinking). */
|
|
1218
1688
|
setThinkingLevel(level: ThinkingLevel): Promise<void>;
|
|
1219
|
-
/** Enable or disable Pi's automatic context compaction.
|
|
1689
|
+
/** Enable or disable Pi's automatic context compaction.
|
|
1690
|
+
*
|
|
1691
|
+
* @deprecated Use `agent.harness("pi").setAutoCompaction()`. Moves off `Alineo` because only Pi has it.
|
|
1692
|
+
*/
|
|
1220
1693
|
setAutoCompaction(enabled: boolean): Promise<void>;
|
|
1221
1694
|
/**
|
|
1222
1695
|
* Enable or disable Pi's automatic retry on transient errors (429, 500, 502, 503, 504).
|
|
1223
1696
|
* Auto-retry is ON by default: 3 attempts with exponential backoff (2 s / 4 s / 8 s).
|
|
1224
1697
|
* Disable it when you want to handle errors yourself via `auto_retry_start`/`auto_retry_end`
|
|
1225
1698
|
* events in the stream.
|
|
1699
|
+
*
|
|
1700
|
+
* @deprecated Use `agent.harness("pi").setAutoRetry()`. Moves off `Alineo` because only Pi has it.
|
|
1226
1701
|
*/
|
|
1227
1702
|
setAutoRetry(enabled: boolean): Promise<void>;
|
|
1228
1703
|
/**
|
|
1229
1704
|
* Abort an in-progress auto-retry immediately. Pi stops waiting and fails the current
|
|
1230
1705
|
* operation, emitting `auto_retry_end` with `success: false`.
|
|
1706
|
+
*
|
|
1707
|
+
* @deprecated Use `agent.harness("pi").abortRetry()`. Moves off `Alineo` because only Pi has it.
|
|
1231
1708
|
*/
|
|
1232
1709
|
abortRetry(): Promise<void>;
|
|
1233
|
-
/** Abort a currently-executing bash command without cancelling the whole prompt.
|
|
1710
|
+
/** Abort a currently-executing bash command without cancelling the whole prompt.
|
|
1711
|
+
*
|
|
1712
|
+
* @deprecated Use `agent.harness("pi").abortBash()`. Moves off `Alineo` because only Pi has it.
|
|
1713
|
+
*/
|
|
1234
1714
|
abortBash(): Promise<void>;
|
|
1235
1715
|
/** Retrieve token usage, cost, and message counts for the current session. */
|
|
1236
1716
|
getSessionStats(): Promise<SessionStats>;
|
|
@@ -1240,42 +1720,60 @@ export declare class Alineo {
|
|
|
1240
1720
|
* List the fork entry points available in the current session.
|
|
1241
1721
|
* Each entry has `entryId` (pass to `fork()`) and `text` (the message at that point).
|
|
1242
1722
|
*/
|
|
1243
|
-
|
|
1723
|
+
getBranchPoints(): Promise<{
|
|
1244
1724
|
entryId: string;
|
|
1245
1725
|
text: string;
|
|
1246
1726
|
}[]>;
|
|
1247
|
-
/** List Pi's available slash commands, including extensions, prompt templates, and skills.
|
|
1727
|
+
/** List Pi's available slash commands, including extensions, prompt templates, and skills.
|
|
1728
|
+
*
|
|
1729
|
+
* @deprecated Use `agent.harness("pi").getCommands()`. Moves off `Alineo` because only Pi has it.
|
|
1730
|
+
*/
|
|
1248
1731
|
getCommands(): Promise<PiSlashCommand[]>;
|
|
1249
|
-
/** Set a display name for the current Pi session.
|
|
1732
|
+
/** Set a display name for the current Pi session.
|
|
1733
|
+
*
|
|
1734
|
+
* @deprecated Use `agent.harness("pi").setSessionName()`. Moves off `Alineo` because only Pi has it.
|
|
1735
|
+
*/
|
|
1250
1736
|
setSessionName(name: string): Promise<void>;
|
|
1251
1737
|
/**
|
|
1252
1738
|
* Control how Pi processes queued steering messages.
|
|
1253
1739
|
* `"all"` applies all queued steers at once; `"one-at-a-time"` applies them sequentially.
|
|
1740
|
+
*
|
|
1741
|
+
* @deprecated Use `agent.harness("pi").setSteeringMode()`. Moves off `Alineo` because only Pi has it.
|
|
1254
1742
|
*/
|
|
1255
1743
|
setSteeringMode(mode: "all" | "one-at-a-time"): Promise<void>;
|
|
1256
1744
|
/**
|
|
1257
1745
|
* Control how Pi processes queued follow-up messages.
|
|
1258
1746
|
* `"all"` sends all queued follow-ups at once; `"one-at-a-time"` sends them sequentially.
|
|
1747
|
+
*
|
|
1748
|
+
* @deprecated Use `agent.harness("pi").setFollowUpMode()`. Moves off `Alineo` because only Pi has it.
|
|
1259
1749
|
*/
|
|
1260
1750
|
setFollowUpMode(mode: "all" | "one-at-a-time"): Promise<void>;
|
|
1261
1751
|
/**
|
|
1262
1752
|
* Export a static HTML transcript of the current session to the sandbox filesystem.
|
|
1263
1753
|
* Returns the container path of the generated file — use `agent.sandbox.readFile(path)`
|
|
1264
1754
|
* to retrieve it.
|
|
1755
|
+
*
|
|
1756
|
+
* @deprecated Use `agent.harness("pi").exportHtml()`. Moves off `Alineo` because only Pi has it.
|
|
1265
1757
|
*/
|
|
1266
1758
|
exportHtml(outputPath?: string): Promise<{
|
|
1267
1759
|
path: string;
|
|
1268
1760
|
}>;
|
|
1269
1761
|
/**
|
|
1270
|
-
*
|
|
1271
|
-
*
|
|
1762
|
+
* Branch the harness conversation at the given entry ID.
|
|
1763
|
+
*
|
|
1764
|
+
* Named for what it touches. This never leaves the container: it is the harness's own
|
|
1765
|
+
* session that branches, not the sandbox — `agent.sandbox.fork()` is the one that copies a
|
|
1766
|
+
* filesystem. Unqualified `fork` meant both for a while, which is the confusion this name
|
|
1767
|
+
* exists to end.
|
|
1768
|
+
*
|
|
1769
|
+
* Returns the text of the branched message and whether the branch was cancelled.
|
|
1272
1770
|
*/
|
|
1273
|
-
|
|
1771
|
+
branchSession(entryId: string): Promise<{
|
|
1274
1772
|
text: string;
|
|
1275
1773
|
cancelled: boolean;
|
|
1276
1774
|
}>;
|
|
1277
|
-
/**
|
|
1278
|
-
|
|
1775
|
+
/** Branch the harness conversation at its current position. Same container, same bridge. */
|
|
1776
|
+
duplicateSession(): Promise<{
|
|
1279
1777
|
cancelled: boolean;
|
|
1280
1778
|
}>;
|
|
1281
1779
|
/** Switch Pi to a different session file on disk. */
|
|
@@ -1284,13 +1782,19 @@ export declare class Alineo {
|
|
|
1284
1782
|
}>;
|
|
1285
1783
|
/** Switch Pi to a specific model. Returns the activated model. */
|
|
1286
1784
|
setModel(provider: string, modelId: string): Promise<PiModel>;
|
|
1287
|
-
/** Cycle Pi to the next available model. Returns null if only one model is configured.
|
|
1785
|
+
/** Cycle Pi to the next available model. Returns null if only one model is configured.
|
|
1786
|
+
*
|
|
1787
|
+
* @deprecated Use `agent.harness("pi").cycleModel()`. Moves off `Alineo` because only Pi has it.
|
|
1788
|
+
*/
|
|
1288
1789
|
cycleModel(): Promise<{
|
|
1289
1790
|
model: PiModel;
|
|
1290
1791
|
thinkingLevel: ThinkingLevel;
|
|
1291
1792
|
isScoped: boolean;
|
|
1292
1793
|
} | null>;
|
|
1293
|
-
/** Cycle Pi's thinking level. Returns null if the current model doesn't support thinking.
|
|
1794
|
+
/** Cycle Pi's thinking level. Returns null if the current model doesn't support thinking.
|
|
1795
|
+
*
|
|
1796
|
+
* @deprecated Use `agent.harness("pi").cycleThinkingLevel()`. Moves off `Alineo` because only Pi has it.
|
|
1797
|
+
*/
|
|
1294
1798
|
cycleThinkingLevel(): Promise<{
|
|
1295
1799
|
level: ThinkingLevel;
|
|
1296
1800
|
} | null>;
|
|
@@ -1317,6 +1821,69 @@ export declare class Alineo {
|
|
|
1317
1821
|
close(): Promise<void>;
|
|
1318
1822
|
}
|
|
1319
1823
|
//#endregion
|
|
1824
|
+
//#region src/permissions.d.ts
|
|
1825
|
+
/**
|
|
1826
|
+
* Best-effort read-vs-write triage of a shell command. `true` = every sub-command is a
|
|
1827
|
+
* recognised pure reader with no output redirection; `false` = something needs a human.
|
|
1828
|
+
* Mirrored verbatim in `bridge/pi-permission-gate.ts`.
|
|
1829
|
+
*/
|
|
1830
|
+
export declare function isReadOnlyBashCommand(command: string): boolean;
|
|
1831
|
+
//#endregion
|
|
1832
|
+
//#region src/snapshots.d.ts
|
|
1833
|
+
interface AgentSnapshotRecord {
|
|
1834
|
+
specName: string;
|
|
1835
|
+
setupHash: string;
|
|
1836
|
+
/**
|
|
1837
|
+
* The sandbox provider that owns `snapshotId`. A snapshot id is meaningless to any other
|
|
1838
|
+
* provider, so it is part of the cache key. Absent on records written before this field
|
|
1839
|
+
* existed, which all came from OpenSandbox.
|
|
1840
|
+
*/
|
|
1841
|
+
provider?: string;
|
|
1842
|
+
/** OpenSandbox snapshot ID returned by `sb.checkpoint()`. Pass to `client.restoreSnapshot()`. */
|
|
1843
|
+
snapshotId: string;
|
|
1844
|
+
createdAt: number;
|
|
1845
|
+
}
|
|
1846
|
+
/**
|
|
1847
|
+
* Hash of the fields that require re-installing the harness or rerunning
|
|
1848
|
+
* setup: harness, harnessVersion, packages, and setup. Excludes env (hot-reloadable),
|
|
1849
|
+
* model/provider (harness flags only), and cosmetic fields.
|
|
1850
|
+
*
|
|
1851
|
+
* The hashed object deliberately keeps the **old** key names. This is a cache key, not a
|
|
1852
|
+
* vocabulary surface — nobody reads it — and changing the keys would change every existing
|
|
1853
|
+
* snapshot's hash, so the `harness` rename would silently cost every user a ~90s rebuild of
|
|
1854
|
+
* every agent instead of a ~3s snapshot restore. The values are what identify the install;
|
|
1855
|
+
* the key spelling is incidental.
|
|
1856
|
+
*/
|
|
1857
|
+
export declare function computeSetupHash(spec: AgentSpec): string;
|
|
1858
|
+
/** Derive the agent-snapshots.json path from the ledger adapter path. */
|
|
1859
|
+
export declare function snapshotsPath(adapterPath: string): string;
|
|
1860
|
+
/** File-backed store for agent snapshot records, keyed by specName + setupHash. */
|
|
1861
|
+
export declare class AgentSnapshotStore {
|
|
1862
|
+
private readonly path;
|
|
1863
|
+
constructor(path: string);
|
|
1864
|
+
private _read;
|
|
1865
|
+
private _write;
|
|
1866
|
+
/**
|
|
1867
|
+
* OpenSandbox keeps the key it always had, so every existing file keeps working. Another
|
|
1868
|
+
* provider's records get its id as a prefix, so two providers sharing one file never read
|
|
1869
|
+
* or replace each other's snapshot ids.
|
|
1870
|
+
*/
|
|
1871
|
+
private _key;
|
|
1872
|
+
get(specName: string, setupHash: string, provider?: string): Promise<AgentSnapshotRecord | null>;
|
|
1873
|
+
/**
|
|
1874
|
+
* Writes are read-modify-write on one file. Two at once (several specs finishing their setup
|
|
1875
|
+
* together, as when alineod restores a whole swarm onto a new machine) would each read the old
|
|
1876
|
+
* file and the second write would drop the first record. This chain runs them one at a time.
|
|
1877
|
+
* It guards one process: a second process on the same file is not supported.
|
|
1878
|
+
*/
|
|
1879
|
+
private writing;
|
|
1880
|
+
private serialized;
|
|
1881
|
+
save(record: AgentSnapshotRecord): Promise<void>;
|
|
1882
|
+
/** Remove all snapshot records for the given spec name. */
|
|
1883
|
+
delete(specName: string): Promise<void>;
|
|
1884
|
+
list(): Promise<AgentSnapshotRecord[]>;
|
|
1885
|
+
}
|
|
1886
|
+
//#endregion
|
|
1320
1887
|
//#region src/errors.d.ts
|
|
1321
1888
|
/**
|
|
1322
1889
|
* Thrown when a prompt/bash SSE stream from a sandbox's Pi bridge goes quiet for longer than
|
|
@@ -1325,7 +1892,7 @@ export declare class Alineo {
|
|
|
1325
1892
|
* about whether Pi itself is making progress) for that long. Previously this surfaced as an
|
|
1326
1893
|
* indefinite hang with zero visibility: `sseStream()` had no timeout at all, so a genuinely
|
|
1327
1894
|
* stuck Pi process (e.g. blocked in a credential refresh, or any other silent stall) blocked
|
|
1328
|
-
* every caller up the chain -- `Alineo.prompt()`, `collectReply()`, `alineo
|
|
1895
|
+
* every caller up the chain -- `Alineo.prompt()`, `collectReply()`, `alineo spawn --prompt` --
|
|
1329
1896
|
* forever, with no error and no partial output.
|
|
1330
1897
|
*/
|
|
1331
1898
|
export declare class PromptTimeoutError extends WorkflowError {
|
|
@@ -1333,6 +1900,20 @@ export declare class PromptTimeoutError extends WorkflowError {
|
|
|
1333
1900
|
readonly bridgeUrl: string;
|
|
1334
1901
|
constructor(timeoutMs: number, bridgeUrl: string);
|
|
1335
1902
|
}
|
|
1903
|
+
/**
|
|
1904
|
+
* Thrown when a prompt/bash SSE stream's underlying connection closes (`reader.read()` reports
|
|
1905
|
+
* `done: true`) without the bridge ever having sent its own `[DONE]` sentinel first -- the
|
|
1906
|
+
* signal that the bridge process died mid-stream (e.g. a crash, an OOM kill), not that Pi
|
|
1907
|
+
* actually finished the turn. Previously `sseStream()` treated this exactly like a clean finish
|
|
1908
|
+
* (durability-roadmap M2.1, verified live on `my-vps` 2026-10-03: `kill -9`ing the bridge process
|
|
1909
|
+
* mid-tool-call settled the turn as a false `success` with no text, in under 20s, instead of
|
|
1910
|
+
* ever reaching the inactivity-timeout/catch-up path at all) -- a TCP-level EOF and an
|
|
1911
|
+
* application-level `[DONE]` are indistinguishable to a bare `for await` without this.
|
|
1912
|
+
*/
|
|
1913
|
+
export declare class BridgeDisconnectedError extends WorkflowError {
|
|
1914
|
+
readonly bridgeUrl: string;
|
|
1915
|
+
constructor(bridgeUrl: string);
|
|
1916
|
+
}
|
|
1336
1917
|
/**
|
|
1337
1918
|
* Thrown by `validateAgentSpec()` when a spec object fails schema validation. Carries every
|
|
1338
1919
|
* failing field in one pass (`.issues`, mirroring `z.ZodIssue[]` shape) rather than surfacing
|
|
@@ -1345,4 +1926,203 @@ export declare class AgentSpecValidationError extends WorkflowError {
|
|
|
1345
1926
|
constructor(message: string, issues: readonly Pick<z.core.$ZodIssue, "path" | "message" | "code">[]);
|
|
1346
1927
|
}
|
|
1347
1928
|
//#endregion
|
|
1348
|
-
|
|
1929
|
+
//#region src/checkpoint.d.ts
|
|
1930
|
+
/**
|
|
1931
|
+
* Turn-level checkpointing (durability-roadmap.md M3, 3.2) — deliberately NOT
|
|
1932
|
+
* `sb.checkpoint()`. That method calls OpenSandbox's own snapshot primitive, which on the
|
|
1933
|
+
* Docker runtime is literally `docker commit` (confirmed against OpenSandbox's own source,
|
|
1934
|
+
* M3's 3.1 research) — measured at 44.3s for a 236MB container, re-exporting the whole
|
|
1935
|
+
* filesystem every time regardless of how much actually changed. Calling that every turn would
|
|
1936
|
+
* silently reintroduce the exact cost 3.1 ruled out. This module tars a few directories via
|
|
1937
|
+
* `sb.exec()` instead — measured at well under 2s even unfiltered.
|
|
1938
|
+
*
|
|
1939
|
+
* This is a different mechanism from the agent SDK's other "snapshot" concept, the setup
|
|
1940
|
+
* snapshot (`./snapshots.ts`'s `AgentSnapshotStore`) — that one is taken once per unique
|
|
1941
|
+
* `(specName, setupHash)` to skip reinstalling Pi/packages on every `Alineo.start()`. This one
|
|
1942
|
+
* is taken after every completed turn, captures that specific conversation's state (not a
|
|
1943
|
+
* shared install), and is what `Alineo.resume()` restores from when the container itself is
|
|
1944
|
+
* gone (3.3) — the setup snapshot only gets a fresh, *empty* container, not this agent's actual
|
|
1945
|
+
* conversation.
|
|
1946
|
+
*/
|
|
1947
|
+
/** Directories/globs left out of every checkpoint tarball by default — universally-safe
|
|
1948
|
+
* package/toolchain caches, nothing else (3.1's decision: err toward inclusion, since the
|
|
1949
|
+
* measured unfiltered cost is already cheap — losing real workspace state by over-excluding is
|
|
1950
|
+
* a worse mistake than a few extra seconds). Paths are relative to `CHECKPOINT_ROOT`. */
|
|
1951
|
+
export declare const DEFAULT_CHECKPOINT_EXCLUDES: string[];
|
|
1952
|
+
/**
|
|
1953
|
+
* The directory tarred into every checkpoint — Pi's home directory, where its session file
|
|
1954
|
+
* (`.pi/agent/sessions/...`) and whatever the agent wrote both live. Every sandbox measured for
|
|
1955
|
+
* 3.1 ran Pi as root; a spec that runs as a different user is a known simplification this
|
|
1956
|
+
* chunk doesn't yet handle (no portable way to ask a sandbox its $HOME without an extra exec
|
|
1957
|
+
* round trip on every checkpoint, and nothing in the current fleet needs it).
|
|
1958
|
+
*/
|
|
1959
|
+
export declare const CHECKPOINT_ROOT = "root";
|
|
1960
|
+
/**
|
|
1961
|
+
* durability-roadmap M3, 3.5: restore (3.3) only ever reads the *latest* checkpoint — an older
|
|
1962
|
+
* one is slack for debugging/manual rollback, not a live requirement. 3 was decided without
|
|
1963
|
+
* real usage data to justify more (measured sizes are sub-30MB, typically far less once the
|
|
1964
|
+
* exclusion list applies), and is cheap to revisit if real retention pressure ever shows up.
|
|
1965
|
+
*/
|
|
1966
|
+
export declare const DEFAULT_CHECKPOINT_RETENTION = 3;
|
|
1967
|
+
/**
|
|
1968
|
+
* durability-roadmap M4, 4.1: an off-box blob is deleted only when it is both beyond the retention
|
|
1969
|
+
* count AND at least this old. The ledger can be restored from a replica that trails the live one
|
|
1970
|
+
* by a few seconds, so after a disk loss it may name a checkpoint that is no longer the newest. The
|
|
1971
|
+
* margin keeps that older blob alive long enough to be found. The restore also falls back from a
|
|
1972
|
+
* missing blob to the next older checkpoint, so this is a second line of defence.
|
|
1973
|
+
*/
|
|
1974
|
+
export declare const DEFAULT_REMOTE_PRUNE_MIN_AGE_MS: number;
|
|
1975
|
+
interface CheckpointRecord {
|
|
1976
|
+
/** Monotonic within this `Alineo` instance's lifetime — an ordinal for humans reading
|
|
1977
|
+
* `alineo logs`, not the mechanism restore uses to find the latest one (that's ledger
|
|
1978
|
+
* append order, via `AgentCheckpointed` events). Resets to 0 across a resume/reattach — a
|
|
1979
|
+
* fresh process starting its own count at 0 again causes no restore-correctness issue. */
|
|
1980
|
+
turn: number;
|
|
1981
|
+
/** A path on the host filesystem. Always set: the local copy is kept (M4 decision D5). */
|
|
1982
|
+
snapshotRef: string;
|
|
1983
|
+
/**
|
|
1984
|
+
* Where the same tarball lives off the box (M4, 4.1), when a `BlobStore` was given and the
|
|
1985
|
+
* upload worked. `undefined` means this checkpoint exists on the host disk only.
|
|
1986
|
+
*/
|
|
1987
|
+
remoteRef?: string;
|
|
1988
|
+
/** Why the upload failed, when a `BlobStore` was given and it did. */
|
|
1989
|
+
uploadError?: string;
|
|
1990
|
+
createdAt: number;
|
|
1991
|
+
}
|
|
1992
|
+
/** Derive the checkpoints directory from the ledger adapter's own path, same convention as
|
|
1993
|
+
* `./snapshots.ts`'s `snapshotsPath()`. */
|
|
1994
|
+
export declare function checkpointsPath(adapterPath: string): string;
|
|
1995
|
+
/**
|
|
1996
|
+
* Delete this sandbox's old off-box checkpoints: all but the newest `retain`, and only those older
|
|
1997
|
+
* than `minAgeMs`. Best-effort like the local prune: a failure is returned to the caller to log and
|
|
1998
|
+
* never thrown, because the checkpoint it follows already succeeded.
|
|
1999
|
+
*/
|
|
2000
|
+
export declare function pruneRemoteCheckpoints(store: BlobStore, sandboxId: string, opts: {
|
|
2001
|
+
retain: number;
|
|
2002
|
+
minAgeMs: number;
|
|
2003
|
+
now?: number;
|
|
2004
|
+
}): Promise<string[]>;
|
|
2005
|
+
/**
|
|
2006
|
+
* Tar `CHECKPOINT_ROOT` (minus the default excludes) inside the sandbox, pull the bytes out
|
|
2007
|
+
* byte-safe (`sb.readFileBytes()`, never `readFile()`'s UTF-8 path — a gzip tarball is not
|
|
2008
|
+
* valid UTF-8), write them to `checkpointsDir`, and record `AgentCheckpointed` on the sandbox's
|
|
2009
|
+
* own ledger — in that order, snapshot-then-event, so a checkpoint event is never written
|
|
2010
|
+
* pointing at a tarball that doesn't actually exist on disk.
|
|
2011
|
+
*
|
|
2012
|
+
* Throws on any step's failure (tar inside the sandbox, the byte-safe download, or the host
|
|
2013
|
+
* write) — the caller decides whether a failed checkpoint should interrupt the turn it was
|
|
2014
|
+
* taken after (3.2's own call site treats it as best-effort and logs rather than throws
|
|
2015
|
+
* further, since a checkpoint failing is not the same failure as the turn itself failing).
|
|
2016
|
+
* Retention (3.5) runs only after a successful write+event, pruning this sandbox's own
|
|
2017
|
+
* directory down to `opts.retain` (default `DEFAULT_CHECKPOINT_RETENTION`). A pruning failure
|
|
2018
|
+
* is swallowed, not thrown — the checkpoint this call was actually for already succeeded, and
|
|
2019
|
+
* a cleanup failure must never retroactively turn that into an error.
|
|
2020
|
+
*/
|
|
2021
|
+
export declare function takeCheckpoint(sb: SandboxHandle, checkpointsDir: string, opts: {
|
|
2022
|
+
turn: number;
|
|
2023
|
+
excludeGlobs?: string[];
|
|
2024
|
+
retain?: number;
|
|
2025
|
+
/**
|
|
2026
|
+
* Also send the tarball to this store (M4, 4.1). The host copy is still written and still
|
|
2027
|
+
* pruned. A failed upload does not fail the checkpoint: it is recorded as `uploadError` and the
|
|
2028
|
+
* checkpoint stays local-only, which is what M3 did.
|
|
2029
|
+
*/
|
|
2030
|
+
blobStore?: BlobStore;
|
|
2031
|
+
/** Override `DEFAULT_REMOTE_PRUNE_MIN_AGE_MS`. */
|
|
2032
|
+
remoteMinAgeMs?: number;
|
|
2033
|
+
}): Promise<CheckpointRecord>;
|
|
2034
|
+
//#endregion
|
|
2035
|
+
//#region src/sandbox-gone.d.ts
|
|
2036
|
+
/**
|
|
2037
|
+
* Classifies an error from `client.connect()` (or any other sandbox-control call) as "no live
|
|
2038
|
+
* container to reattach or resume into" — as opposed to a transient failure that might clear on
|
|
2039
|
+
* retry. Shared between `resumeAgent()`/`reattachAgent()` (M3, 3.3 — falls through to
|
|
2040
|
+
* restore-from-checkpoint on this) and `apps/alineod/src/engine/rehydrate.ts`'s restore ladder
|
|
2041
|
+
* (M3, 3.4 — same question, same answer), which previously had its own private copy covering
|
|
2042
|
+
* only the first case below.
|
|
2043
|
+
*
|
|
2044
|
+
* The stable signal is an alineo error code: `SANDBOX_NOT_FOUND`, or `SANDBOX_NOT_RUNNING` with
|
|
2045
|
+
* `details.state` of `Terminated` or `Failed`. The message and `.code` string checks below are a
|
|
2046
|
+
* fallback for errors that carry no alineo code, and may go once every thrower sets one.
|
|
2047
|
+
*
|
|
2048
|
+
* Two distinct ways a sandbox can be "gone," both confirmed against OpenSandbox's actual
|
|
2049
|
+
* behavior (DeepWiki, not just its higher-level docs — same discipline M1.4/M2's research used):
|
|
2050
|
+
*
|
|
2051
|
+
* 1. Truly deleted/unknown (`docker rm -f`, expired and reaped): a 404, surfaced as
|
|
2052
|
+
* `<RUNTIME>::SANDBOX_NOT_FOUND` on the error's `code` or in its message.
|
|
2053
|
+
* 2. `Exited` after a host reboot or Docker daemon restart (durability-roadmap's former M2
|
|
2054
|
+
* 2.3, moved here): **not** a 404 — a `200 OK` with `state: "Terminated"`/`"Failed"`.
|
|
2055
|
+
* `@alineo-labs/sandbox`'s `client.connect()` (`packages/sdks/typescript/src/client.ts`)
|
|
2056
|
+
* already surfaces this as a `SandboxClientError` with `status: 409` and a message of the
|
|
2057
|
+
* shape `"SandboxHandle <id> is <state> — can only connect to Running sandboxes"` — this
|
|
2058
|
+
* classifier matches that message shape rather than re-deriving the state check itself, so
|
|
2059
|
+
* it stays correct if `connect()`'s own wording ever changes without this file knowing.
|
|
2060
|
+
*/
|
|
2061
|
+
export declare function isSandboxGone(err: unknown): boolean;
|
|
2062
|
+
//#endregion
|
|
2063
|
+
//#region src/restore.d.ts
|
|
2064
|
+
/**
|
|
2065
|
+
* durability-roadmap M3, 3.3 — the other half of `./checkpoint.ts`. Finds the latest
|
|
2066
|
+
* `AgentCheckpointed` record for a sandbox from its own ledger (the same `IStorageAdapter` the
|
|
2067
|
+
* sandbox already writes to via `sb.emit()` — this works whether that sandbox still exists or
|
|
2068
|
+
* not, since the ledger is exactly what's supposed to survive it) and extracts the tarball
|
|
2069
|
+
* into a *different*, already-running container — the one a fresh snapshot restore just
|
|
2070
|
+
* provisioned, per `resumeAgent()`'s fallback in `./agent/factory.ts`.
|
|
2071
|
+
*
|
|
2072
|
+
* M4, 4.1: a checkpoint may also carry a `remoteRef` into object storage. On the same host the
|
|
2073
|
+
* local file is read first. After a disk loss the local file is gone and the blob is fetched.
|
|
2074
|
+
*/
|
|
2075
|
+
interface LatestCheckpoint {
|
|
2076
|
+
turn: number;
|
|
2077
|
+
/** A path on the host that took the checkpoint. */
|
|
2078
|
+
snapshotRef: string;
|
|
2079
|
+
/** The same tarball in object storage, when the upload worked (M4, 4.1). */
|
|
2080
|
+
remoteRef?: string;
|
|
2081
|
+
}
|
|
2082
|
+
/**
|
|
2083
|
+
* Every checkpoint recorded for this sandbox, newest first. Restore tries them in this order, so
|
|
2084
|
+
* one lost or unreadable tarball costs a turn of history and not the whole conversation.
|
|
2085
|
+
*/
|
|
2086
|
+
export declare function findCheckpoints(adapter: IStorageAdapter, name: string, sandboxId: string): Promise<LatestCheckpoint[]>;
|
|
2087
|
+
/** `undefined` if this sandbox was never checkpointed — not an error; the caller falls back
|
|
2088
|
+
* to whatever state a bare snapshot restore already produced. */
|
|
2089
|
+
export declare function findLatestCheckpoint(adapter: IStorageAdapter, name: string, sandboxId: string): Promise<LatestCheckpoint | undefined>;
|
|
2090
|
+
interface RestoreOptions {
|
|
2091
|
+
/** Where a `remoteRef` is fetched from. Without it, only the local file can be used. */
|
|
2092
|
+
blobStore?: BlobStore;
|
|
2093
|
+
}
|
|
2094
|
+
/**
|
|
2095
|
+
* The bytes of one checkpoint. Local file first, because it needs no network. If that is gone (a
|
|
2096
|
+
* new host, a wiped disk) and the checkpoint has a `remoteRef` the store recognises, download it.
|
|
2097
|
+
*
|
|
2098
|
+
* @throws if neither source has it. The message names both attempts.
|
|
2099
|
+
*/
|
|
2100
|
+
export declare function fetchCheckpoint(checkpoint: LatestCheckpoint, opts?: RestoreOptions): Promise<Uint8Array>;
|
|
2101
|
+
/**
|
|
2102
|
+
* The newest checkpoint whose tarball can be read, with its bytes, or `undefined` when none can.
|
|
2103
|
+
* `skipped` lists what was passed over and why, for the caller to log.
|
|
2104
|
+
*/
|
|
2105
|
+
export declare function pickRestorable(candidates: LatestCheckpoint[], opts?: RestoreOptions): Promise<{
|
|
2106
|
+
checkpoint: LatestCheckpoint;
|
|
2107
|
+
bytes: Uint8Array;
|
|
2108
|
+
skipped: Array<{
|
|
2109
|
+
turn: number;
|
|
2110
|
+
reason: string;
|
|
2111
|
+
}>;
|
|
2112
|
+
} | null>;
|
|
2113
|
+
/**
|
|
2114
|
+
* Extract checkpoint bytes into `sb`, overwriting whatever a fresh container's own setup left in
|
|
2115
|
+
* place at the same paths. Byte-safe on both ends (`writeFileBytes`/raw `tar xzf`) — the same
|
|
2116
|
+
* corruption risk `takeCheckpoint()`'s doc comment already covers on the capture side applies
|
|
2117
|
+
* symmetrically here on restore.
|
|
2118
|
+
*/
|
|
2119
|
+
export declare function extractCheckpoint(sb: SandboxHandle, bytes: Uint8Array): Promise<void>;
|
|
2120
|
+
/**
|
|
2121
|
+
* Extract a checkpoint tarball into `sb`. `snapshotRef` is the host path `takeCheckpoint()` stored
|
|
2122
|
+
* it at. Pass `remoteRef` and `blobStore` to fall back to object storage when that file is gone.
|
|
2123
|
+
*/
|
|
2124
|
+
export declare function restoreCheckpoint(sb: SandboxHandle, snapshotRef: string, opts?: RestoreOptions & {
|
|
2125
|
+
remoteRef?: string;
|
|
2126
|
+
}): Promise<void>;
|
|
2127
|
+
//#endregion
|
|
2128
|
+
export { type AgentEvent, type AgentRestore, type AgentSnapshotRecord, type AgentSpec, type AgentSpecInput, type AgentStream, type BlobInfo, type BlobStore, type CheckpointRecord, type CompactResult, DEFAULT_PROVIDER_ID, type EgressApprovalGateOptions, type EgressDecision, type EgressRequest, type EgressRequestHandler, type FakeScenario, type HarnessAdapter, type HarnessCapabilities, type HarnessCapability, type HarnessEvent, type HarnessEventBody, type HarnessId, type HarnessRef, type HarnessRegistry, type HarnessSandbox, type HeldCredential, type LatestCheckpoint, type ModelRef, type PendingPermission, type PermissionAction, type PermissionDecision, type PermissionHandler, type PermissionMode, type PermissionPolicy, type PermissionRequest, type PermissionRule, type PiMessage, type PiModel, type PiSessionState, type PiSlashCommand, type PromptStream, type RestoreOptions, type S3BlobStoreOptions, type S3ClientLike, type SessionStats, type SetupStep, type ThinkingLevel, type TurnInput };
|