alineo 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -32
- package/dist/index.d.mts +242 -318
- package/dist/index.mjs +641 -203
- package/package.json +6 -4
package/dist/index.mjs
CHANGED
|
@@ -1,48 +1,264 @@
|
|
|
1
|
+
import { AgentSpecSchema, ProjectConfigSchema, resourceRefOf } from "@alineo-labs/schema";
|
|
1
2
|
import { Sandbox } from "@alineo-labs/sandbox";
|
|
2
|
-
import { readFileSync } from "node:fs";
|
|
3
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
3
4
|
import { LedgerEvent, WorkflowError } from "@alineo-labs/core";
|
|
4
5
|
import { getLogger } from "@alineo-labs/logger";
|
|
5
|
-
import {
|
|
6
|
+
import { homedir } from "node:os";
|
|
7
|
+
import { dirname, join, resolve } from "node:path";
|
|
6
8
|
import * as z$1 from "zod";
|
|
9
|
+
import "zod";
|
|
7
10
|
import { fileURLToPath } from "node:url";
|
|
8
11
|
import { createHash } from "node:crypto";
|
|
9
|
-
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
10
|
-
import { dirname } from "node:path";
|
|
12
|
+
import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
|
|
11
13
|
import { createServer } from "node:http";
|
|
12
|
-
//#region
|
|
13
|
-
|
|
14
|
-
const
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
14
|
+
//#region ../config-shared/dist/index.mjs
|
|
15
|
+
/** The file name every alineo project config uses. */
|
|
16
|
+
const PROJECT_CONFIG_FILE = "alineo.config.json";
|
|
17
|
+
/**
|
|
18
|
+
* Walk up from `startDir` looking for `alineo.config.json`.
|
|
19
|
+
*
|
|
20
|
+
* Before this existed, `packages/agent` only ever checked `process.cwd()`, so running a script
|
|
21
|
+
* from a subdirectory silently fell back to built-in defaults — a wrong `serverUrl` looked
|
|
22
|
+
* exactly like no config at all.
|
|
23
|
+
*
|
|
24
|
+
* The walk is **bounded**, which matters as much as the walk itself: an unbounded search would
|
|
25
|
+
* let an unrelated `alineo.config.json` several levels up configure a run. It stops after
|
|
26
|
+
* examining:
|
|
27
|
+
*
|
|
28
|
+
* - a directory containing `.git` (the project boundary),
|
|
29
|
+
* - the user's home directory (global config is a separate, explicit source), or
|
|
30
|
+
* - the filesystem root.
|
|
31
|
+
*
|
|
32
|
+
* The stop directory is itself checked before the walk ends, so a config file sitting next to
|
|
33
|
+
* `.git` is still found.
|
|
34
|
+
*/
|
|
35
|
+
function findProjectConfig(startDir = process.cwd()) {
|
|
36
|
+
const home = resolve(homedir());
|
|
37
|
+
let dir = resolve(startDir);
|
|
38
|
+
for (;;) {
|
|
39
|
+
const candidate = join(dir, PROJECT_CONFIG_FILE);
|
|
40
|
+
if (existsSync(candidate)) return candidate;
|
|
41
|
+
if (existsSync(join(dir, ".git"))) return null;
|
|
42
|
+
if (dir === home) return null;
|
|
43
|
+
const parent = dirname(dir);
|
|
44
|
+
if (parent === dir) return null;
|
|
45
|
+
dir = parent;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
/** Absolute path of the user-level config, `~/.config/alineo/config.json`. */
|
|
49
|
+
function globalConfigPath() {
|
|
50
|
+
return join(homedir(), ".config", "alineo", "config.json");
|
|
51
|
+
}
|
|
25
52
|
/**
|
|
26
|
-
* Read
|
|
27
|
-
*
|
|
28
|
-
*
|
|
53
|
+
* Read and JSON-parse a config file, or return `null` when it isn't there.
|
|
54
|
+
* A file that exists but is malformed throws — a typo in config should be loud, not silently
|
|
55
|
+
* ignored in favour of defaults.
|
|
29
56
|
*/
|
|
30
|
-
|
|
31
|
-
if (!existsSync(
|
|
32
|
-
const
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
57
|
+
function readJsonFile(path) {
|
|
58
|
+
if (!existsSync(path)) return null;
|
|
59
|
+
const raw = readFileSync(path, "utf8");
|
|
60
|
+
try {
|
|
61
|
+
return JSON.parse(raw);
|
|
62
|
+
} catch (err) {
|
|
63
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
64
|
+
throw new Error(`${path} is not valid JSON: ${message}`);
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
function isPlainObject(value) {
|
|
68
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
|
|
69
|
+
const proto = Object.getPrototypeOf(value);
|
|
70
|
+
return proto === Object.prototype || proto === null;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Merge config sources, lowest precedence first. Plain objects merge key by key; everything
|
|
74
|
+
* else (arrays, strings, numbers) is replaced wholesale by the later source.
|
|
75
|
+
*
|
|
76
|
+
* `undefined` never overwrites — an absent key in a higher-precedence source leaves the lower
|
|
77
|
+
* one intact, which is what makes "env var not set" mean "don't override" rather than "clear".
|
|
78
|
+
* An explicit `null` *does* overwrite, so a config file can blank a value on purpose.
|
|
79
|
+
*/
|
|
80
|
+
function mergeDeep(...sources) {
|
|
81
|
+
let result = void 0;
|
|
82
|
+
for (const source of sources) {
|
|
83
|
+
if (source === void 0) continue;
|
|
84
|
+
if (isPlainObject(source) && isPlainObject(result)) {
|
|
85
|
+
const merged = { ...result };
|
|
86
|
+
for (const [key, value] of Object.entries(source)) {
|
|
87
|
+
if (value === void 0) continue;
|
|
88
|
+
merged[key] = key in merged ? mergeDeep(merged[key], value) : value;
|
|
89
|
+
}
|
|
90
|
+
result = merged;
|
|
91
|
+
} else result = source;
|
|
92
|
+
}
|
|
93
|
+
return result;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Freeze an object and everything reachable from it, so a resolved config can't be mutated
|
|
97
|
+
* after validation. Cycles are impossible in JSON-derived data, so no seen-set is needed.
|
|
98
|
+
*/
|
|
99
|
+
function deepFreeze(value) {
|
|
100
|
+
if (value === null || typeof value !== "object") return value;
|
|
101
|
+
if (Object.isFrozen(value)) return value;
|
|
102
|
+
Object.freeze(value);
|
|
103
|
+
for (const key of Object.getOwnPropertyNames(value)) deepFreeze(value[key]);
|
|
104
|
+
return value;
|
|
105
|
+
}
|
|
106
|
+
/** Env var holding a whole config document inline, as JSON. */
|
|
107
|
+
const CONFIG_CONTENT_ENV = "ALINEO_CONFIG_CONTENT";
|
|
108
|
+
/**
|
|
109
|
+
* Resolve configuration from every source, lowest precedence first:
|
|
110
|
+
*
|
|
111
|
+
* ```
|
|
112
|
+
* schema defaults
|
|
113
|
+
* < ~/.config/alineo/config.json (user)
|
|
114
|
+
* < alineo.config.json (project — found by bounded walk-up)
|
|
115
|
+
* < ALINEO_CONFIG_CONTENT (inline JSON)
|
|
116
|
+
* < ALINEO_* env vars (ops)
|
|
117
|
+
* < overrides (flags / explicit call-site object)
|
|
118
|
+
* ```
|
|
119
|
+
*
|
|
120
|
+
* Validated once, then deep-frozen. **This function is pure with respect to module state** —
|
|
121
|
+
* nothing is cached here and there is no installed singleton, so two bundled copies of this
|
|
122
|
+
* package cannot drift apart. Callers hold the result for as long as they need it.
|
|
123
|
+
*/
|
|
124
|
+
function loadConfigWithSources(options) {
|
|
125
|
+
const { schema, cwd = process.cwd(), env = process.env, fromEnv, overrides, globalPath = globalConfigPath(), discover = true, label = "config" } = options;
|
|
126
|
+
const sources = {
|
|
127
|
+
globalFile: null,
|
|
128
|
+
projectFile: null,
|
|
129
|
+
inlineEnv: false,
|
|
130
|
+
envVars: false,
|
|
131
|
+
overrides: overrides !== void 0
|
|
132
|
+
};
|
|
133
|
+
const layers = [];
|
|
134
|
+
if (discover) {
|
|
135
|
+
if (globalPath) {
|
|
136
|
+
const globalData = readJsonFile(globalPath);
|
|
137
|
+
if (globalData !== null) {
|
|
138
|
+
layers.push(globalData);
|
|
139
|
+
sources.globalFile = globalPath;
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
const projectFile = findProjectConfig(cwd);
|
|
143
|
+
if (projectFile) {
|
|
144
|
+
const projectData = readJsonFile(projectFile);
|
|
145
|
+
if (projectData !== null) {
|
|
146
|
+
layers.push(projectData);
|
|
147
|
+
sources.projectFile = projectFile;
|
|
42
148
|
}
|
|
43
149
|
}
|
|
150
|
+
const inline = env[CONFIG_CONTENT_ENV];
|
|
151
|
+
if (inline !== void 0 && inline.trim() !== "") {
|
|
152
|
+
try {
|
|
153
|
+
layers.push(JSON.parse(inline));
|
|
154
|
+
} catch (err) {
|
|
155
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
156
|
+
throw new Error(`${CONFIG_CONTENT_ENV} is not valid JSON: ${message}`);
|
|
157
|
+
}
|
|
158
|
+
sources.inlineEnv = true;
|
|
159
|
+
}
|
|
160
|
+
if (fromEnv) {
|
|
161
|
+
const fromEnvData = fromEnv(env);
|
|
162
|
+
if (fromEnvData !== void 0) {
|
|
163
|
+
layers.push(fromEnvData);
|
|
164
|
+
sources.envVars = true;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
if (overrides !== void 0) layers.push(overrides);
|
|
169
|
+
const merged = layers.length > 0 ? mergeDeep(...layers) : {};
|
|
170
|
+
const parsed = schema.safeParse(merged ?? {});
|
|
171
|
+
if (!parsed.success) {
|
|
172
|
+
const details = parsed.error.issues.map((issue) => {
|
|
173
|
+
return ` ${issue.path.length > 0 ? issue.path.join(".") : "(root)"}: ${issue.message}`;
|
|
174
|
+
}).join("\n");
|
|
175
|
+
const from = describeSources(sources);
|
|
176
|
+
throw new Error(`Invalid ${label}${from}:\n${details}`);
|
|
177
|
+
}
|
|
178
|
+
return {
|
|
179
|
+
config: deepFreeze(parsed.data),
|
|
180
|
+
sources
|
|
44
181
|
};
|
|
45
182
|
}
|
|
183
|
+
/** `loadConfigWithSources` without the provenance — the common case. */
|
|
184
|
+
function loadConfig(options) {
|
|
185
|
+
return loadConfigWithSources(options).config;
|
|
186
|
+
}
|
|
187
|
+
function describeSources(sources) {
|
|
188
|
+
const parts = [];
|
|
189
|
+
if (sources.globalFile) parts.push(sources.globalFile);
|
|
190
|
+
if (sources.projectFile) parts.push(sources.projectFile);
|
|
191
|
+
if (sources.inlineEnv) parts.push(CONFIG_CONTENT_ENV);
|
|
192
|
+
if (sources.envVars) parts.push("environment");
|
|
193
|
+
if (sources.overrides) parts.push("explicit options");
|
|
194
|
+
return parts.length > 0 ? ` (from ${parts.join(", ")})` : "";
|
|
195
|
+
}
|
|
196
|
+
function parseBoolean(raw, name) {
|
|
197
|
+
const value = raw.trim().toLowerCase();
|
|
198
|
+
if ([
|
|
199
|
+
"true",
|
|
200
|
+
"1",
|
|
201
|
+
"yes",
|
|
202
|
+
"on"
|
|
203
|
+
].includes(value)) return true;
|
|
204
|
+
if ([
|
|
205
|
+
"false",
|
|
206
|
+
"0",
|
|
207
|
+
"no",
|
|
208
|
+
"off"
|
|
209
|
+
].includes(value)) return false;
|
|
210
|
+
throw new Error(`${name}=${JSON.stringify(raw)} is not a boolean (use true or false)`);
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Project-config fields settable from the environment. These are what
|
|
214
|
+
* `apps/alineod/docker-entrypoint.sh` writes into a generated config file before starting the
|
|
215
|
+
* server; reading them directly means the container no longer has to write a file at all.
|
|
216
|
+
*/
|
|
217
|
+
function projectConfigFromEnv(env) {
|
|
218
|
+
const out = {};
|
|
219
|
+
if (env.ALINEO_SERVER_URL !== void 0) out.serverUrl = env.ALINEO_SERVER_URL;
|
|
220
|
+
if (env.ALINEO_API_KEY !== void 0) out.apiKey = env.ALINEO_API_KEY;
|
|
221
|
+
if (env.ALINEO_USE_SERVER_PROXY !== void 0) out.useServerProxy = parseBoolean(env.ALINEO_USE_SERVER_PROXY, "ALINEO_USE_SERVER_PROXY");
|
|
222
|
+
return Object.keys(out).length > 0 ? out : void 0;
|
|
223
|
+
}
|
|
224
|
+
/** Resolve `alineo.config.json` from every source. Validated once, then frozen. */
|
|
225
|
+
function loadProjectConfig(options = {}) {
|
|
226
|
+
return loadConfig({
|
|
227
|
+
schema: ProjectConfigSchema,
|
|
228
|
+
fromEnv: projectConfigFromEnv,
|
|
229
|
+
label: "alineo config",
|
|
230
|
+
...options
|
|
231
|
+
});
|
|
232
|
+
}
|
|
233
|
+
//#endregion
|
|
234
|
+
//#region src/config.ts
|
|
235
|
+
/**
|
|
236
|
+
* Resolved configs, keyed by the directory they were resolved from.
|
|
237
|
+
*
|
|
238
|
+
* The previous implementation re-read the file on every `load`/`resume`/`attach`/`spawn`. The
|
|
239
|
+
* cache lives here rather than in `config-shared` on purpose: that package is bundled separately
|
|
240
|
+
* into each consumer, so a cache inside it would be a different cache per copy. Keeping the
|
|
241
|
+
* state here means one cache per process that actually uses it.
|
|
242
|
+
*/
|
|
243
|
+
const cache = /* @__PURE__ */ new Map();
|
|
244
|
+
/**
|
|
245
|
+
* Resolve the project config once per working directory.
|
|
246
|
+
*
|
|
247
|
+
* Unlike the old reader, this walks up from the current directory to find
|
|
248
|
+
* `alineo.config.json` (bounded by a `.git` directory, `$HOME`, or the filesystem root), so
|
|
249
|
+
* running a script from a subdirectory no longer silently falls back to defaults. Pass
|
|
250
|
+
* `override` — `opts.config` on the public methods — to skip file and environment discovery
|
|
251
|
+
* entirely, which is what an embedded caller or a test wants.
|
|
252
|
+
*/
|
|
253
|
+
function resolveProjectConfig(override) {
|
|
254
|
+
if (override) return override;
|
|
255
|
+
const cwd = process.cwd();
|
|
256
|
+
const cached = cache.get(cwd);
|
|
257
|
+
if (cached) return cached;
|
|
258
|
+
const config = loadProjectConfig({ cwd });
|
|
259
|
+
cache.set(cwd, config);
|
|
260
|
+
return config;
|
|
261
|
+
}
|
|
46
262
|
//#endregion
|
|
47
263
|
//#region src/errors.ts
|
|
48
264
|
/**
|
|
@@ -52,7 +268,7 @@ async function readProjectConfig() {
|
|
|
52
268
|
* about whether Pi itself is making progress) for that long. Previously this surfaced as an
|
|
53
269
|
* indefinite hang with zero visibility: `sseStream()` had no timeout at all, so a genuinely
|
|
54
270
|
* stuck Pi process (e.g. blocked in a credential refresh, or any other silent stall) blocked
|
|
55
|
-
* every caller up the chain -- `Alineo.prompt()`, `collectReply()`, `alineo
|
|
271
|
+
* every caller up the chain -- `Alineo.prompt()`, `collectReply()`, `alineo spawn --prompt` --
|
|
56
272
|
* forever, with no error and no partial output.
|
|
57
273
|
*/
|
|
58
274
|
var PromptTimeoutError = class extends WorkflowError {
|
|
@@ -66,6 +282,24 @@ var PromptTimeoutError = class extends WorkflowError {
|
|
|
66
282
|
}
|
|
67
283
|
};
|
|
68
284
|
/**
|
|
285
|
+
* Thrown when a prompt/bash SSE stream's underlying connection closes (`reader.read()` reports
|
|
286
|
+
* `done: true`) without the bridge ever having sent its own `[DONE]` sentinel first -- the
|
|
287
|
+
* signal that the bridge process died mid-stream (e.g. a crash, an OOM kill), not that Pi
|
|
288
|
+
* actually finished the turn. Previously `sseStream()` treated this exactly like a clean finish
|
|
289
|
+
* (durability-roadmap M2.1, verified live on `my-vps` 2026-10-03: `kill -9`ing the bridge process
|
|
290
|
+
* mid-tool-call settled the turn as a false `success` with no text, in under 20s, instead of
|
|
291
|
+
* ever reaching the inactivity-timeout/catch-up path at all) -- a TCP-level EOF and an
|
|
292
|
+
* application-level `[DONE]` are indistinguishable to a bare `for await` without this.
|
|
293
|
+
*/
|
|
294
|
+
var BridgeDisconnectedError = class extends WorkflowError {
|
|
295
|
+
bridgeUrl;
|
|
296
|
+
constructor(bridgeUrl) {
|
|
297
|
+
super(`Bridge connection closed (${bridgeUrl}) before signalling the turn was done -- the underlying agent process likely died`);
|
|
298
|
+
this.bridgeUrl = bridgeUrl;
|
|
299
|
+
this.name = "BridgeDisconnectedError";
|
|
300
|
+
}
|
|
301
|
+
};
|
|
302
|
+
/**
|
|
69
303
|
* Thrown by `validateAgentSpec()` when a spec object fails schema validation. Carries every
|
|
70
304
|
* failing field in one pass (`.issues`, mirroring `z.ZodIssue[]` shape) rather than surfacing
|
|
71
305
|
* only the first problem found -- see #185. `.message` is a pre-formatted, human-readable
|
|
@@ -82,102 +316,26 @@ var AgentSpecValidationError = class extends WorkflowError {
|
|
|
82
316
|
};
|
|
83
317
|
//#endregion
|
|
84
318
|
//#region src/schema.ts
|
|
85
|
-
/** Renders an arbitrary invalid field value for an error message without risking "[object Object]". */
|
|
86
|
-
function describeValue(value) {
|
|
87
|
-
if (typeof value === "string") return value;
|
|
88
|
-
try {
|
|
89
|
-
const json = JSON.stringify(value);
|
|
90
|
-
if (json !== void 0) return json;
|
|
91
|
-
} catch {}
|
|
92
|
-
return typeof value === "object" && value !== null ? Object.prototype.toString.call(value) : String(value);
|
|
93
|
-
}
|
|
94
319
|
/**
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
* here too — `packages/agent/test/schema.test.ts` is the drift check.
|
|
320
|
+
* Validation for `AgentSpec` — the behaviour half.
|
|
321
|
+
*
|
|
322
|
+
* The shapes themselves (`AgentSpec`, `AgentSpecSchema`, `SetupStep`, `CredentialEnvBinding`)
|
|
323
|
+
* live in `@alineo-labs/schema` and are re-exported here, so every existing import keeps
|
|
324
|
+
* working. What stays is what actually does something: validation, and the error it throws.
|
|
101
325
|
*/
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
"header",
|
|
116
|
-
"body"
|
|
117
|
-
])).min(1)
|
|
118
|
-
})]),
|
|
119
|
-
approval: z$1.literal("hold").optional()
|
|
120
|
-
}).loose();
|
|
121
|
-
const SetupStepSchema = z$1.object({
|
|
122
|
-
name: z$1.string({ error: "Each setup step must have a 'name' string" }),
|
|
123
|
-
run: z$1.string({ error: "Each setup step must have a 'run' string" }),
|
|
124
|
-
cwd: z$1.string().optional()
|
|
125
|
-
}).loose();
|
|
126
|
-
const PermissionActionSchema = z$1.enum([
|
|
127
|
-
"allow",
|
|
128
|
-
"ask",
|
|
129
|
-
"deny",
|
|
130
|
-
"rate_limit",
|
|
131
|
-
"classify"
|
|
132
|
-
]);
|
|
133
|
-
const PermissionRuleSchema = z$1.object({
|
|
134
|
-
tool: z$1.string({ error: "Each permission rule must have a 'tool' string" }),
|
|
135
|
-
pattern: z$1.string().optional(),
|
|
136
|
-
action: PermissionActionSchema,
|
|
137
|
-
limit: z$1.object({
|
|
138
|
-
count: z$1.number().int().positive(),
|
|
139
|
-
windowMs: z$1.number().int().positive()
|
|
140
|
-
}).optional()
|
|
141
|
-
}).loose();
|
|
142
|
-
const PermissionPolicySchema = z$1.object({
|
|
143
|
-
default: PermissionActionSchema.optional(),
|
|
144
|
-
rules: z$1.array(PermissionRuleSchema).optional(),
|
|
145
|
-
disabledTools: z$1.array(z$1.string()).optional(),
|
|
146
|
-
restrictToTools: z$1.array(z$1.string()).optional()
|
|
147
|
-
}).loose();
|
|
148
|
-
const PermissionsSchema = z$1.union([z$1.enum([
|
|
149
|
-
"auto",
|
|
150
|
-
"ask",
|
|
151
|
-
"readonly"
|
|
152
|
-
]), PermissionPolicySchema]);
|
|
153
|
-
const nonNegativeIntSpecField = (fieldName) => z$1.number({ error: `Agent spec '${fieldName}' must be a non-negative integer if set` }).int(`Agent spec '${fieldName}' must be a non-negative integer if set`).nonnegative(`Agent spec '${fieldName}' must be a non-negative integer if set`).optional();
|
|
154
|
-
const AgentSpecSchema = z$1.object({
|
|
155
|
-
$schema: z$1.string().optional(),
|
|
156
|
-
name: z$1.string({ error: (issue) => issue.input === void 0 ? "Agent spec must have a 'name' string" : "Agent spec 'name' must be a string" }).min(1, "Agent spec must have a 'name' string"),
|
|
157
|
-
title: z$1.string().optional(),
|
|
158
|
-
description: z$1.string().optional(),
|
|
159
|
-
author: z$1.string().optional(),
|
|
160
|
-
categories: z$1.array(z$1.string()).optional(),
|
|
161
|
-
cli: z$1.literal("pi", { error: (issue) => issue.input === void 0 ? "Agent spec must have a 'cli' field. Supported values: pi" : `Unsupported CLI: '${describeValue(issue.input)}'. Supported values: pi` }),
|
|
162
|
-
cliVersion: z$1.string().optional(),
|
|
163
|
-
provider: z$1.string().optional(),
|
|
164
|
-
model: z$1.string().optional(),
|
|
165
|
-
packages: z$1.array(z$1.string()).optional(),
|
|
166
|
-
env: z$1.record(z$1.string(), z$1.union([z$1.string(), CredentialEnvBindingSchema])).optional(),
|
|
167
|
-
resources: z$1.object({
|
|
168
|
-
cpu: z$1.string(),
|
|
169
|
-
memory: z$1.string(),
|
|
170
|
-
gpu: z$1.string().optional()
|
|
171
|
-
}).optional(),
|
|
172
|
-
metadata: z$1.record(z$1.string(), z$1.string()).optional(),
|
|
173
|
-
registryDependencies: z$1.array(z$1.string()).optional(),
|
|
174
|
-
setup: z$1.array(SetupStepSchema).optional(),
|
|
175
|
-
spawnDepth: nonNegativeIntSpecField("spawnDepth"),
|
|
176
|
-
maxAgents: nonNegativeIntSpecField("maxAgents"),
|
|
177
|
-
teamId: z$1.string().optional(),
|
|
178
|
-
resourceId: z$1.string().optional(),
|
|
179
|
-
permissions: PermissionsSchema.optional()
|
|
180
|
-
}).loose();
|
|
326
|
+
/**
|
|
327
|
+
* The old spec field names, and what each became. There is no alias — an old spec is
|
|
328
|
+
* rejected — but "must have a 'harness' field" is an unhelpful thing to read while looking
|
|
329
|
+
* at a spec that plainly has a `cli` field. Name the rename instead.
|
|
330
|
+
*/
|
|
331
|
+
const RENAMED_FIELDS = [["cli", "harness"], ["cliVersion", "harnessVersion"]];
|
|
332
|
+
function renamedFieldHint(data) {
|
|
333
|
+
if (typeof data !== "object" || data === null) return "";
|
|
334
|
+
const stale = RENAMED_FIELDS.filter(([from, to]) => from in data && !(to in data));
|
|
335
|
+
if (stale.length === 0) return "";
|
|
336
|
+
const list = (pick) => stale.map((pair) => `'${pair[pick]}'`).join(" and ");
|
|
337
|
+
return `\n\nThis spec uses ${list(0)}, renamed to ${list(1)}: the field names the agent-loop driver, which is not always a CLI.`;
|
|
338
|
+
}
|
|
181
339
|
/**
|
|
182
340
|
* Validate an unknown value as an `AgentSpec`, aggregating every problem found in one pass.
|
|
183
341
|
* Throws `AgentSpecValidationError` (with a pre-formatted `.message` and a structured
|
|
@@ -185,7 +343,7 @@ const AgentSpecSchema = z$1.object({
|
|
|
185
343
|
*/
|
|
186
344
|
function validateAgentSpec(data) {
|
|
187
345
|
const result = AgentSpecSchema.safeParse(data);
|
|
188
|
-
if (!result.success) throw new AgentSpecValidationError(`Invalid agent spec:\n${z$1.prettifyError(result.error)}`, result.error.issues.map((issue) => ({
|
|
346
|
+
if (!result.success) throw new AgentSpecValidationError(`Invalid agent spec:\n${z$1.prettifyError(result.error)}${renamedFieldHint(data)}`, result.error.issues.map((issue) => ({
|
|
189
347
|
path: issue.path,
|
|
190
348
|
message: issue.message,
|
|
191
349
|
code: issue.code
|
|
@@ -194,6 +352,14 @@ function validateAgentSpec(data) {
|
|
|
194
352
|
}
|
|
195
353
|
//#endregion
|
|
196
354
|
//#region src/permissions.ts
|
|
355
|
+
/**
|
|
356
|
+
* Shorthand for the common cases:
|
|
357
|
+
* - `"auto"` — never ask (the default; identical to not setting `permissions` at all)
|
|
358
|
+
* - `"ask"` — ask before every tool call
|
|
359
|
+
* - `"readonly"` — auto-allow the read-only tools (`read`/`grep`/`find`/`ls`), ask before
|
|
360
|
+
* `write`/`edit`/`bash`/`powershell`. Pi has no network tool — an agent reaches the
|
|
361
|
+
* network through `bash`, so `"readonly"` gates that by gating `bash`, not as a category.
|
|
362
|
+
*/
|
|
197
363
|
/** Read-only built-in tools — auto-allowed (and the entire toolset) under `"readonly"`. */
|
|
198
364
|
const READ_ONLY_TOOLS = [
|
|
199
365
|
"read",
|
|
@@ -473,7 +639,7 @@ var PiAdapter = class {
|
|
|
473
639
|
async install(sb, spec) {
|
|
474
640
|
const pkgs = [...new Set(spec.packages ?? [])].filter((p) => p !== "nodejs_22" && p !== "nodejs");
|
|
475
641
|
if (pkgs.length > 0) await sb.exec(`apt-get update -qq && apt-get install -y --no-install-recommends ${pkgs.join(" ")}`);
|
|
476
|
-
const versionSpecifier = spec.
|
|
642
|
+
const versionSpecifier = spec.harnessVersion?.trim();
|
|
477
643
|
const pkg = versionSpecifier ? `@earendil-works/pi-coding-agent@${versionSpecifier}` : "@earendil-works/pi-coding-agent";
|
|
478
644
|
await sb.exec(`npm install -g --ignore-scripts ${pkg}`);
|
|
479
645
|
}
|
|
@@ -484,7 +650,7 @@ var PiAdapter = class {
|
|
|
484
650
|
async configure(sb, spec, resolvedEnv, opts) {
|
|
485
651
|
const piConfig = {};
|
|
486
652
|
if (spec.provider) piConfig.provider = spec.provider;
|
|
487
|
-
|
|
653
|
+
piConfig.model = spec.model;
|
|
488
654
|
if (opts?.resume) piConfig.resume = true;
|
|
489
655
|
const permissions = normalizePermissions(spec.permissions);
|
|
490
656
|
if (permissions) piConfig.permissions = permissions;
|
|
@@ -685,7 +851,7 @@ async function rpcGet(bridgeUrl, path) {
|
|
|
685
851
|
* 60s (the original default) was too tight for a common, legitimate pattern: Pi's own `bash`
|
|
686
852
|
* tool is not incrementally streamed (see the `bash()` doc comment in session-control.ts), so
|
|
687
853
|
* a single tool call that spins up a whole child sandbox -- e.g. a master session running
|
|
688
|
-
* `alineo
|
|
854
|
+
* `alineo spawn` on itself, as in examples/rlm-repo-fanout -- produces zero AgentEvents for as
|
|
689
855
|
* long as that tool call takes, which regularly exceeded 60s (child sandbox provisioning +
|
|
690
856
|
* Pi CLI install alone routinely took 30-150s+ in practice) and tripped this timeout mid-run
|
|
691
857
|
* even though the session was making real progress. Raised to 3 minutes as a still-bounded
|
|
@@ -730,7 +896,7 @@ async function* sseStream(bridgeUrl, path, body, pendingStreams, inactivityTimeo
|
|
|
730
896
|
const { done, value } = result;
|
|
731
897
|
if (done) {
|
|
732
898
|
reachedNaturalEnd = true;
|
|
733
|
-
|
|
899
|
+
throw new BridgeDisconnectedError(bridgeUrl);
|
|
734
900
|
}
|
|
735
901
|
buf += decoder.decode(value, { stream: true });
|
|
736
902
|
const lines = buf.split("\n");
|
|
@@ -757,14 +923,20 @@ async function* sseStream(bridgeUrl, path, body, pendingStreams, inactivityTimeo
|
|
|
757
923
|
//#endregion
|
|
758
924
|
//#region src/snapshots.ts
|
|
759
925
|
/**
|
|
760
|
-
* Hash of the fields that require re-installing the
|
|
761
|
-
* setup:
|
|
762
|
-
* model/provider (
|
|
926
|
+
* Hash of the fields that require re-installing the harness or rerunning
|
|
927
|
+
* setup: harness, harnessVersion, packages, and setup. Excludes env (hot-reloadable),
|
|
928
|
+
* model/provider (harness flags only), and cosmetic fields.
|
|
929
|
+
*
|
|
930
|
+
* The hashed object deliberately keeps the **old** key names. This is a cache key, not a
|
|
931
|
+
* vocabulary surface — nobody reads it — and changing the keys would change every existing
|
|
932
|
+
* snapshot's hash, so the `harness` rename would silently cost every user a ~90s rebuild of
|
|
933
|
+
* every agent instead of a ~3s snapshot restore. The values are what identify the install;
|
|
934
|
+
* the key spelling is incidental.
|
|
763
935
|
*/
|
|
764
936
|
function computeSetupHash(spec) {
|
|
765
937
|
return createHash("sha256").update(JSON.stringify({
|
|
766
|
-
cli: spec.
|
|
767
|
-
cliVersion: spec.
|
|
938
|
+
cli: spec.harness,
|
|
939
|
+
cliVersion: spec.harnessVersion ?? "latest",
|
|
768
940
|
packages: [...spec.packages ?? []].sort(),
|
|
769
941
|
setup: spec.setup ?? []
|
|
770
942
|
})).digest("hex").slice(0, 12);
|
|
@@ -813,6 +985,63 @@ var AgentSnapshotStore = class {
|
|
|
813
985
|
}
|
|
814
986
|
};
|
|
815
987
|
//#endregion
|
|
988
|
+
//#region src/sandbox-gone.ts
|
|
989
|
+
/**
|
|
990
|
+
* Classifies an error from `client.connect()` (or any other sandbox-control call) as "no live
|
|
991
|
+
* container to reattach or resume into" — as opposed to a transient failure that might clear on
|
|
992
|
+
* retry. Shared between `resumeAgent()`/`reattachAgent()` (M3, 3.3 — falls through to
|
|
993
|
+
* restore-from-checkpoint on this) and `apps/alineod/src/engine/rehydrate.ts`'s restore ladder
|
|
994
|
+
* (M3, 3.4 — same question, same answer), which previously had its own private copy covering
|
|
995
|
+
* only the first case below.
|
|
996
|
+
*
|
|
997
|
+
* Two distinct ways a sandbox can be "gone," both confirmed against OpenSandbox's actual
|
|
998
|
+
* behavior (DeepWiki, not just its higher-level docs — same discipline M1.4/M2's research used):
|
|
999
|
+
*
|
|
1000
|
+
* 1. Truly deleted/unknown (`docker rm -f`, expired and reaped): a 404, surfaced as
|
|
1001
|
+
* `<RUNTIME>::SANDBOX_NOT_FOUND` on the error's `code` or in its message.
|
|
1002
|
+
* 2. `Exited` after a host reboot or Docker daemon restart (durability-roadmap's former M2
|
|
1003
|
+
* 2.3, moved here): **not** a 404 — a `200 OK` with `state: "Terminated"`/`"Failed"`.
|
|
1004
|
+
* `@alineo-labs/sandbox`'s `client.connect()` (`packages/sdks/typescript/src/client.ts`)
|
|
1005
|
+
* already surfaces this as a `SandboxClientError` with `status: 409` and a message of the
|
|
1006
|
+
* shape `"SandboxHandle <id> is <state> — can only connect to Running sandboxes"` — this
|
|
1007
|
+
* classifier matches that message shape rather than re-deriving the state check itself, so
|
|
1008
|
+
* it stays correct if `connect()`'s own wording ever changes without this file knowing.
|
|
1009
|
+
*/
|
|
1010
|
+
function isSandboxGone(err) {
|
|
1011
|
+
if (!err || typeof err !== "object") return false;
|
|
1012
|
+
const code = err.code;
|
|
1013
|
+
if (typeof code === "string" && code.endsWith("SANDBOX_NOT_FOUND")) return true;
|
|
1014
|
+
const message = err.message;
|
|
1015
|
+
if (typeof message !== "string") return false;
|
|
1016
|
+
if (message.includes("SANDBOX_NOT_FOUND")) return true;
|
|
1017
|
+
return /is (?:Terminated|Failed) — can only connect to Running sandboxes/.test(message);
|
|
1018
|
+
}
|
|
1019
|
+
//#endregion
|
|
1020
|
+
//#region src/restore.ts
|
|
1021
|
+
/** `undefined` if this sandbox was never checkpointed — not an error; the caller falls back
|
|
1022
|
+
* to whatever state a bare snapshot restore already produced. */
|
|
1023
|
+
async function findLatestCheckpoint(adapter, name, sandboxId) {
|
|
1024
|
+
return (await adapter.readAll(name, sandboxId)).findLast((e) => e.event === LedgerEvent.AgentCheckpointed)?.payload;
|
|
1025
|
+
}
|
|
1026
|
+
/**
|
|
1027
|
+
* Extract a checkpoint tarball (from the host path `takeCheckpoint()` stored it at) into `sb`,
|
|
1028
|
+
* overwriting whatever a fresh container's own setup left in place at the same paths. Byte-safe
|
|
1029
|
+
* on both ends (`writeFileBytes`/raw `tar xzf`) — the same corruption risk `takeCheckpoint()`'s
|
|
1030
|
+
* doc comment already covers on the capture side applies symmetrically here on restore.
|
|
1031
|
+
*/
|
|
1032
|
+
async function restoreCheckpoint(sb, snapshotRef) {
|
|
1033
|
+
const bytes = await readFile(snapshotRef);
|
|
1034
|
+
const tmpTarPath = `/tmp/alineo-restore-${crypto.randomUUID()}.tar.gz`;
|
|
1035
|
+
try {
|
|
1036
|
+
await sb.writeFileBytes(tmpTarPath, bytes);
|
|
1037
|
+
await sb.exec(`tar xzf ${tmpTarPath} -C /`);
|
|
1038
|
+
} finally {
|
|
1039
|
+
try {
|
|
1040
|
+
await sb.exec(`rm -f ${tmpTarPath}`, { strict: false });
|
|
1041
|
+
} catch {}
|
|
1042
|
+
}
|
|
1043
|
+
}
|
|
1044
|
+
//#endregion
|
|
816
1045
|
//#region src/agent/validation.ts
|
|
817
1046
|
/**
|
|
818
1047
|
* The durable resource identity for a spawned child, frozen from the child spec BEFORE
|
|
@@ -825,7 +1054,7 @@ var AgentSnapshotStore = class {
|
|
|
825
1054
|
* agree on the exact same value — is independently unit-testable.
|
|
826
1055
|
*/
|
|
827
1056
|
function resolveChildResourceId(childSpec) {
|
|
828
|
-
return childSpec.resourceId
|
|
1057
|
+
return resourceRefOf(childSpec).resourceId;
|
|
829
1058
|
}
|
|
830
1059
|
function assertValidSpawnDepth(value, context) {
|
|
831
1060
|
if (!Number.isInteger(value) || value < 0) throw new Error(`${context}: spawnDepth must be a non-negative integer (got ${value})`);
|
|
@@ -836,7 +1065,7 @@ function assertValidMaxAgents(value, context) {
|
|
|
836
1065
|
/**
|
|
837
1066
|
* Resolves and validates the spawn-depth budget available to `Alineo.spawn()` —
|
|
838
1067
|
* `override` (a `--depth` CLI flag) wins if given, else whatever value was
|
|
839
|
-
* materialised into `ALINEO_SPAWN_DEPTH` by `Alineo.
|
|
1068
|
+
* materialised into `ALINEO_SPAWN_DEPTH` by `Alineo.start()`/`Alineo.resume()`. Throws
|
|
840
1069
|
* unless the result is a positive integer: `0` means "no budget left", not "spawn
|
|
841
1070
|
* one more time" — spawning stops one level before the counter would go negative.
|
|
842
1071
|
*/
|
|
@@ -1026,21 +1255,21 @@ function elapsed(t) {
|
|
|
1026
1255
|
}
|
|
1027
1256
|
/**
|
|
1028
1257
|
* Validate `specInput` and return everything needed to construct a fully initialised `Alineo`.
|
|
1029
|
-
* See `Alineo.
|
|
1258
|
+
* See `Alineo.start()` for the public-facing docs.
|
|
1030
1259
|
*/
|
|
1031
1260
|
async function loadAgent(specInput, opts) {
|
|
1032
1261
|
const t0 = Date.now();
|
|
1033
1262
|
const spec = validateAgentSpec(specInput);
|
|
1034
|
-
const config =
|
|
1263
|
+
const config = resolveProjectConfig(opts.config);
|
|
1035
1264
|
const resolvedEnv = resolveEnv(spec.env ?? {});
|
|
1036
1265
|
const effectiveSpawnDepth = opts.spawnDepth ?? spec.spawnDepth;
|
|
1037
1266
|
if (effectiveSpawnDepth !== void 0) {
|
|
1038
|
-
assertValidSpawnDepth(effectiveSpawnDepth, "Alineo.
|
|
1267
|
+
assertValidSpawnDepth(effectiveSpawnDepth, "Alineo.start()");
|
|
1039
1268
|
resolvedEnv.ALINEO_SPAWN_DEPTH = String(effectiveSpawnDepth);
|
|
1040
1269
|
}
|
|
1041
1270
|
const effectiveMaxAgents = opts.maxAgents ?? spec.maxAgents;
|
|
1042
1271
|
if (effectiveMaxAgents !== void 0) {
|
|
1043
|
-
assertValidMaxAgents(effectiveMaxAgents, "Alineo.
|
|
1272
|
+
assertValidMaxAgents(effectiveMaxAgents, "Alineo.start()");
|
|
1044
1273
|
resolvedEnv.ALINEO_MAX_AGENTS = String(effectiveMaxAgents);
|
|
1045
1274
|
}
|
|
1046
1275
|
const runId = opts.runId ?? crypto.randomUUID();
|
|
@@ -1057,7 +1286,7 @@ async function loadAgent(specInput, opts) {
|
|
|
1057
1286
|
const needsCredentialProxy = credentialBindings.length > 0;
|
|
1058
1287
|
const heldCredentials = credentialBindings.filter((b) => b.approval === "hold");
|
|
1059
1288
|
const heldHosts = [...new Set(heldCredentials.map((b) => b.binding.host.trim().replace(/\.$/, "").toLowerCase()))];
|
|
1060
|
-
if (heldCredentials.length > 0 && !opts.onEgressRequest) throw new Error(`AgentSpec.env has ${heldCredentials.length} credential binding(s) with approval: "hold" (${heldHosts.join(", ")}) but Alineo.
|
|
1289
|
+
if (heldCredentials.length > 0 && !opts.onEgressRequest) throw new Error(`AgentSpec.env has ${heldCredentials.length} credential binding(s) with approval: "hold" (${heldHosts.join(", ")}) but Alineo.start() was called without an onEgressRequest handler.`);
|
|
1061
1290
|
const networkPolicy = needsCredentialProxy || heldHosts.length > 0 ? {
|
|
1062
1291
|
defaultAction: "allow",
|
|
1063
1292
|
egress: heldHosts.map((target) => ({
|
|
@@ -1099,7 +1328,7 @@ async function loadAgent(specInput, opts) {
|
|
|
1099
1328
|
networkPolicy,
|
|
1100
1329
|
...egressEnv.OPENSANDBOX_EGRESS_DENY_WEBHOOK ? { env: egressEnv } : {},
|
|
1101
1330
|
credentialProxy: needsCredentialProxy,
|
|
1102
|
-
resourceId: spec.resourceId
|
|
1331
|
+
resourceId: resourceRefOf(spec).resourceId,
|
|
1103
1332
|
teamId: spec.teamId
|
|
1104
1333
|
});
|
|
1105
1334
|
log.info("snapshot ready", {
|
|
@@ -1127,7 +1356,7 @@ async function loadAgent(specInput, opts) {
|
|
|
1127
1356
|
runId,
|
|
1128
1357
|
networkPolicy,
|
|
1129
1358
|
credentialProxy: needsCredentialProxy,
|
|
1130
|
-
resourceId: spec.resourceId
|
|
1359
|
+
resourceId: resourceRefOf(spec).resourceId,
|
|
1131
1360
|
teamId: spec.teamId
|
|
1132
1361
|
});
|
|
1133
1362
|
log.info("sandbox ready", {
|
|
@@ -1207,12 +1436,54 @@ async function loadAgent(specInput, opts) {
|
|
|
1207
1436
|
};
|
|
1208
1437
|
}
|
|
1209
1438
|
/**
|
|
1439
|
+
* durability-roadmap M3, 3.3: `resumeAgent()`/`reattachAgent()`'s fallback when the sandbox
|
|
1440
|
+
* itself is gone (`isSandboxGone`), not merely unreachable — provisions a fresh container from
|
|
1441
|
+
* the cached setup snapshot (`loadAgent()`'s own fast path, the same mechanism a first
|
|
1442
|
+
* `Alineo.start()` cache hit already uses) and, if this agent was ever checkpointed, restores
|
|
1443
|
+
* the latest one into it before returning — continuing the conversation instead of starting
|
|
1444
|
+
* blank. If it was never checkpointed, returns the fresh (blank) agent rather than failing —
|
|
1445
|
+
* losing the conversation is still better than losing the agent entirely.
|
|
1446
|
+
*
|
|
1447
|
+
* Known gap, not this chunk's scope: `loadAgent()` throws if the spec has `approval: "hold"`
|
|
1448
|
+
* credential bindings and no `onEgressRequest` is given, which neither `resumeAgent()` nor
|
|
1449
|
+
* `reattachAgent()` accepts today — restoring such a spec from a fully-gone container isn't
|
|
1450
|
+
* handled yet.
|
|
1451
|
+
*/
|
|
1452
|
+
async function restoreFromCheckpoint(originalSandboxId, spec, opts, runId, log) {
|
|
1453
|
+
log.warn("sandbox is gone — provisioning a fresh one and restoring from checkpoint", { originalSandboxId });
|
|
1454
|
+
const fresh = await loadAgent(spec, {
|
|
1455
|
+
adapter: opts.adapter,
|
|
1456
|
+
config: opts.config,
|
|
1457
|
+
runId
|
|
1458
|
+
});
|
|
1459
|
+
const latest = await findLatestCheckpoint(opts.adapter, spec.name, originalSandboxId);
|
|
1460
|
+
if (!latest) {
|
|
1461
|
+
log.warn("no checkpoint found for this agent — continuing with a blank session", { originalSandboxId });
|
|
1462
|
+
return fresh;
|
|
1463
|
+
}
|
|
1464
|
+
log.info("restoring checkpoint", {
|
|
1465
|
+
turn: latest.turn,
|
|
1466
|
+
sandboxId: fresh.sandbox.sandboxId
|
|
1467
|
+
});
|
|
1468
|
+
try {
|
|
1469
|
+
await fresh.sandbox.exec("pkill -f 'node /alineo-bridge.js' 2>/dev/null; sleep 0.1; true", { strict: false });
|
|
1470
|
+
await restoreCheckpoint(fresh.sandbox, latest.snapshotRef);
|
|
1471
|
+
await fresh.adapter.configure(fresh.sandbox, spec, fresh.env, { resume: true });
|
|
1472
|
+
await fresh.adapter.startBridge(fresh.sandbox);
|
|
1473
|
+
await fresh.adapter.waitReady();
|
|
1474
|
+
return fresh;
|
|
1475
|
+
} catch (err) {
|
|
1476
|
+
await fresh.sandbox.close().catch(cleanupFailed(log, { sandboxId: fresh.sandbox.sandboxId }));
|
|
1477
|
+
throw err;
|
|
1478
|
+
}
|
|
1479
|
+
}
|
|
1480
|
+
/**
|
|
1210
1481
|
* Reconnect to a previously-created agent whose host process has exited. See
|
|
1211
1482
|
* `Alineo.resume()` for the public-facing docs.
|
|
1212
1483
|
*/
|
|
1213
1484
|
async function resumeAgent(sandboxId, opts) {
|
|
1214
1485
|
const t0 = Date.now();
|
|
1215
|
-
const config =
|
|
1486
|
+
const config = resolveProjectConfig(opts.config);
|
|
1216
1487
|
const client = new Sandbox({
|
|
1217
1488
|
baseUrl: config.serverUrl,
|
|
1218
1489
|
apiKey: config.apiKey,
|
|
@@ -1244,12 +1515,18 @@ async function resumeAgent(sandboxId, opts) {
|
|
|
1244
1515
|
resolvedEnv.ALINEO_RUN_ID = runId;
|
|
1245
1516
|
log.info("reconnecting", { sandboxId });
|
|
1246
1517
|
const t1 = Date.now();
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1518
|
+
let sb;
|
|
1519
|
+
try {
|
|
1520
|
+
sb = await client.connect(sandboxId, spec.name, {
|
|
1521
|
+
runId,
|
|
1522
|
+
resources: spec.resources ?? config.defaults.resources,
|
|
1523
|
+
resourceId: resourceRefOf(spec).resourceId,
|
|
1524
|
+
teamId: spec.teamId
|
|
1525
|
+
});
|
|
1526
|
+
} catch (err) {
|
|
1527
|
+
if (isSandboxGone(err)) return restoreFromCheckpoint(sandboxId, spec, opts, runId, log);
|
|
1528
|
+
throw err;
|
|
1529
|
+
}
|
|
1253
1530
|
log.info("connected", { elapsed: elapsed(t1) });
|
|
1254
1531
|
await sb.exec("pkill -f 'node /alineo-bridge.js' 2>/dev/null; sleep 0.1; true", { strict: false });
|
|
1255
1532
|
const adapter = new PiAdapter();
|
|
@@ -1271,6 +1548,21 @@ async function resumeAgent(sandboxId, opts) {
|
|
|
1271
1548
|
runId
|
|
1272
1549
|
};
|
|
1273
1550
|
}
|
|
1551
|
+
/**
|
|
1552
|
+
* durability-roadmap.md M1.3: this used to resolve a dropped request with
|
|
1553
|
+
* `decision: { kind: "reject" }` — `PermissionDecision`'s `"reject"` is documented as *a
|
|
1554
|
+
* human's answer*, and no human answered this one. Nobody could: the tool call it was about
|
|
1555
|
+
* died with the old Pi process (OpenSandbox restore is rootfs-only, so it isn't still parked
|
|
1556
|
+
* anywhere to answer). `"dropped"` says what actually happened instead of fabricating a
|
|
1557
|
+
* decision nobody made.
|
|
1558
|
+
*
|
|
1559
|
+
* This is the narrow fix — an honest ledger, not a re-opened decision. The better path forward
|
|
1560
|
+
* is giving a human an actual chance to weigh in: alineod has no live route to answer a
|
|
1561
|
+
* permission request at all today (`driveTurn` calls `agent.prompt()` with no `onPermission`),
|
|
1562
|
+
* so there's nothing yet for a "re-issue this to an operator" version of this function to
|
|
1563
|
+
* re-issue *into*. Once that live path exists, this should queue the same way
|
|
1564
|
+
* `agent.supervision_needed` already does, instead of resolving anything here.
|
|
1565
|
+
*/
|
|
1274
1566
|
async function reconcileDroppedPermissions(adapter, sb, name, sandboxId) {
|
|
1275
1567
|
try {
|
|
1276
1568
|
const events = await adapter.readAll(name, sandboxId);
|
|
@@ -1284,8 +1576,8 @@ async function reconcileDroppedPermissions(adapter, sb, name, sandboxId) {
|
|
|
1284
1576
|
const rid = e.payload?.requestId;
|
|
1285
1577
|
if (rid && !resolved.has(rid)) await sb.emit(LedgerEvent.PermissionResolved, -1, {
|
|
1286
1578
|
requestId: rid,
|
|
1287
|
-
decision: { kind: "
|
|
1288
|
-
note: "session resumed —
|
|
1579
|
+
decision: { kind: "dropped" },
|
|
1580
|
+
note: "session resumed — the tool call this was about is gone; no one answered it"
|
|
1289
1581
|
});
|
|
1290
1582
|
}
|
|
1291
1583
|
} catch {}
|
|
@@ -1298,7 +1590,7 @@ async function reconcileDroppedPermissions(adapter, sb, name, sandboxId) {
|
|
|
1298
1590
|
*/
|
|
1299
1591
|
async function reattachAgent(sandboxId, opts) {
|
|
1300
1592
|
const t0 = Date.now();
|
|
1301
|
-
const config =
|
|
1593
|
+
const config = resolveProjectConfig(opts.config);
|
|
1302
1594
|
const client = new Sandbox({
|
|
1303
1595
|
baseUrl: config.serverUrl,
|
|
1304
1596
|
apiKey: config.apiKey,
|
|
@@ -1331,13 +1623,19 @@ async function reattachAgent(sandboxId, opts) {
|
|
|
1331
1623
|
resolvedEnv.ALINEO_SANDBOX_ID = sandboxId;
|
|
1332
1624
|
log.info("reattaching", { sandboxId });
|
|
1333
1625
|
const t1 = Date.now();
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1626
|
+
let sb;
|
|
1627
|
+
try {
|
|
1628
|
+
sb = await client.connect(sandboxId, spec.name, {
|
|
1629
|
+
runId,
|
|
1630
|
+
resourceId: resourceRefOf(spec).resourceId,
|
|
1631
|
+
teamId: spec.teamId,
|
|
1632
|
+
resources: spec.resources ?? config.defaults.resources,
|
|
1633
|
+
allowPaused: opts.skipReadyCheck === true
|
|
1634
|
+
});
|
|
1635
|
+
} catch (err) {
|
|
1636
|
+
if (isSandboxGone(err)) return restoreFromCheckpoint(sandboxId, spec, opts, runId, log);
|
|
1637
|
+
throw err;
|
|
1638
|
+
}
|
|
1341
1639
|
log.info("connected", { elapsed: elapsed(t1) });
|
|
1342
1640
|
const adapter = new PiAdapter();
|
|
1343
1641
|
await adapter.reattachBridge(sb);
|
|
@@ -1362,7 +1660,7 @@ async function reattachAgent(sandboxId, opts) {
|
|
|
1362
1660
|
* `Alineo.attach()` for the public-facing docs.
|
|
1363
1661
|
*/
|
|
1364
1662
|
async function attachAgent(sandboxId, opts) {
|
|
1365
|
-
const config =
|
|
1663
|
+
const config = resolveProjectConfig(opts.config);
|
|
1366
1664
|
const client = new Sandbox({
|
|
1367
1665
|
baseUrl: config.serverUrl,
|
|
1368
1666
|
apiKey: config.apiKey,
|
|
@@ -1379,11 +1677,17 @@ async function attachAgent(sandboxId, opts) {
|
|
|
1379
1677
|
}
|
|
1380
1678
|
const env = parseShellExports(envFile);
|
|
1381
1679
|
const runId = env.ALINEO_RUN_ID ?? crypto.randomUUID();
|
|
1680
|
+
let model = "unknown";
|
|
1681
|
+
try {
|
|
1682
|
+
const piConfig = JSON.parse(await sb.readFile("/etc/alineo-pi.json"));
|
|
1683
|
+
if (piConfig.model) model = piConfig.model;
|
|
1684
|
+
} catch {}
|
|
1382
1685
|
return {
|
|
1383
1686
|
sandbox: sb,
|
|
1384
1687
|
spec: {
|
|
1385
1688
|
name: opts.name,
|
|
1386
|
-
|
|
1689
|
+
harness: "pi",
|
|
1690
|
+
model
|
|
1387
1691
|
},
|
|
1388
1692
|
env,
|
|
1389
1693
|
adapter: new PiAdapter(),
|
|
@@ -1629,10 +1933,13 @@ async function getLastAssistantText(a) {
|
|
|
1629
1933
|
return a.adapter.getLastAssistantText();
|
|
1630
1934
|
}
|
|
1631
1935
|
/**
|
|
1632
|
-
* List the
|
|
1633
|
-
* Each entry has `entryId` (pass to `
|
|
1936
|
+
* List the points in the current session a conversation can be branched from.
|
|
1937
|
+
* Each entry has `entryId` (pass to `branchSession()`) and `text` (the message there).
|
|
1938
|
+
*
|
|
1939
|
+
* `a.adapter.getForkMessages` keeps Pi's own name — the adapter speaks the harness's
|
|
1940
|
+
* vocabulary, alineo speaks its own on the way out.
|
|
1634
1941
|
*/
|
|
1635
|
-
async function
|
|
1942
|
+
async function getBranchPoints(a) {
|
|
1636
1943
|
return a.adapter.getForkMessages();
|
|
1637
1944
|
}
|
|
1638
1945
|
/** List Pi's available slash commands, including extensions, prompt templates, and skills. */
|
|
@@ -1658,14 +1965,16 @@ async function getLogs(a) {
|
|
|
1658
1965
|
//#endregion
|
|
1659
1966
|
//#region src/agent/lifecycle.ts
|
|
1660
1967
|
/**
|
|
1661
|
-
*
|
|
1662
|
-
*
|
|
1968
|
+
* Branch the harness conversation at the given entry ID.
|
|
1969
|
+
*
|
|
1970
|
+
* `a.adapter.fork` keeps Pi's own name: the adapter speaks the harness's vocabulary (its
|
|
1971
|
+
* bridge endpoint is literally `/fork`), and alineo speaks its own on the way out.
|
|
1663
1972
|
*/
|
|
1664
|
-
async function
|
|
1973
|
+
async function branchSession(a, entryId) {
|
|
1665
1974
|
return a.adapter.fork(entryId);
|
|
1666
1975
|
}
|
|
1667
|
-
/**
|
|
1668
|
-
async function
|
|
1976
|
+
/** Branch the harness conversation at its current position. */
|
|
1977
|
+
async function duplicateSession(a) {
|
|
1669
1978
|
return a.adapter.clone();
|
|
1670
1979
|
}
|
|
1671
1980
|
/** Switch Pi to a different session file on disk. */
|
|
@@ -1712,7 +2021,7 @@ async function close(a) {
|
|
|
1712
2021
|
* while Pi manages its own tool use, file writes, and code execution inside the
|
|
1713
2022
|
* sandbox.
|
|
1714
2023
|
*
|
|
1715
|
-
* Create an agent with `Alineo.
|
|
2024
|
+
* Create an agent with `Alineo.start(spec)`. Always call `close()` when done
|
|
1716
2025
|
* to release the underlying sandbox container.
|
|
1717
2026
|
*
|
|
1718
2027
|
* @example
|
|
@@ -1720,7 +2029,7 @@ async function close(a) {
|
|
|
1720
2029
|
* import { Alineo } from "alineo";
|
|
1721
2030
|
*
|
|
1722
2031
|
* const spec = await Bun.file("./agents/my-agent.json").json();
|
|
1723
|
-
* const agent = await Alineo.
|
|
2032
|
+
* const agent = await Alineo.start(spec, { adapter });
|
|
1724
2033
|
* try {
|
|
1725
2034
|
* for await (const chunk of agent.prompt("Explain this codebase")) {
|
|
1726
2035
|
* process.stdout.write(chunk);
|
|
@@ -1750,13 +2059,13 @@ var Alineo = class Alineo {
|
|
|
1750
2059
|
/**
|
|
1751
2060
|
* Identifies the logical run this agent's sandbox belongs to — see
|
|
1752
2061
|
* `SandboxDetails.runId`. Always present; a fresh `crypto.randomUUID()` if not
|
|
1753
|
-
* explicitly passed to `
|
|
1754
|
-
* transitively, `alineo
|
|
2062
|
+
* explicitly passed to `start()`/`resume()`. A child from `.spawn()` (and
|
|
2063
|
+
* transitively, `alineo spawn`) always inherits its parent's `runId`.
|
|
1755
2064
|
*/
|
|
1756
2065
|
runId;
|
|
1757
2066
|
/**
|
|
1758
2067
|
* Optional provider-agnostic memory (`@alineo-labs/memory`), wired in via `opts.memory` on
|
|
1759
|
-
* `
|
|
2068
|
+
* `start()`/`resume()`/`attach()`. `undefined` unless explicitly configured — `alineo` never
|
|
1760
2069
|
* constructs a `Memory` on your own behalf, matching this package's "own the pipeline,
|
|
1761
2070
|
* don't assume a backend" design. `spawn()` carries the parent's `memory` (if any) onto the
|
|
1762
2071
|
* child automatically, the same way it force-computes spawn-depth rather than reading it
|
|
@@ -1778,7 +2087,7 @@ var Alineo = class Alineo {
|
|
|
1778
2087
|
/**
|
|
1779
2088
|
* Convenience `ResourceRef` scoping `.memory` calls to this agent. `resourceId`/`teamId`
|
|
1780
2089
|
* come from `AgentSpec.resourceId`/`AgentSpec.teamId` (`resourceId` defaulting to this
|
|
1781
|
-
* agent's `name` when unset) — `
|
|
2090
|
+
* agent's `name` when unset) — `start()`/`resume()`/`spawn()` also thread both into the
|
|
1782
2091
|
* ledger (see each field's own doc comment) so this getter and the agent's own episodic
|
|
1783
2092
|
* history stay consistent, including across a spawned child whose `.name` differs from its
|
|
1784
2093
|
* memory identity.
|
|
@@ -1803,7 +2112,7 @@ var Alineo = class Alineo {
|
|
|
1803
2112
|
this.sandboxId = sandbox.sandboxId;
|
|
1804
2113
|
this.name = spec.name;
|
|
1805
2114
|
this.teamId = spec.teamId;
|
|
1806
|
-
this.resourceId = spec.resourceId
|
|
2115
|
+
this.resourceId = resourceRefOf(spec).resourceId;
|
|
1807
2116
|
this.adapter = adapter;
|
|
1808
2117
|
this.env = env;
|
|
1809
2118
|
this.fromSnapshot = fromSnapshot;
|
|
@@ -1825,13 +2134,13 @@ var Alineo = class Alineo {
|
|
|
1825
2134
|
* don't need to call `validateAgentSpec()` yourself first unless you want validation errors
|
|
1826
2135
|
* to surface before any sandbox/network work starts.
|
|
1827
2136
|
*
|
|
1828
|
-
* On first
|
|
1829
|
-
* the sandbox is checkpointed. Subsequent `
|
|
2137
|
+
* On first start the Pi CLI is installed inside a `node:22` sandbox, then
|
|
2138
|
+
* the sandbox is checkpointed. Subsequent `start()` calls for the same spec
|
|
1830
2139
|
* restore from that snapshot — skipping the install and starting in ~3s instead
|
|
1831
2140
|
* of ~90s.
|
|
1832
2141
|
*
|
|
1833
2142
|
* Pass `{ rebuild: true }` to force a full reinstall (e.g. after changing
|
|
1834
|
-
* the spec's `packages` or `
|
|
2143
|
+
* the spec's `packages` or `harnessVersion`).
|
|
1835
2144
|
*
|
|
1836
2145
|
* Pass `{ spawnDepth }` to override the spec's own `spawnDepth` (e.g. a
|
|
1837
2146
|
* `--depth` CLI flag) — standard flag-beats-config precedence. Same for
|
|
@@ -1840,7 +2149,7 @@ var Alineo = class Alineo {
|
|
|
1840
2149
|
* Reports timing for each phase through `@alineo-labs/logger` (component `agent`, tagged with
|
|
1841
2150
|
* the spec `name`). Silent by default — set `ALINEO_LOG_LEVEL=info` to see it.
|
|
1842
2151
|
*/
|
|
1843
|
-
static async
|
|
2152
|
+
static async start(spec, opts) {
|
|
1844
2153
|
const r = await loadAgent(spec, opts);
|
|
1845
2154
|
const agent = new Alineo(r.sandbox, r.spec, r.env, r.adapter, r.fromSnapshot, r.runId, r.egressGate);
|
|
1846
2155
|
agent.memory = opts.memory;
|
|
@@ -1859,20 +2168,20 @@ var Alineo = class Alineo {
|
|
|
1859
2168
|
* first and fall back to this only if it fails (e.g. the whole sandbox — not just this
|
|
1860
2169
|
* process — actually restarted).
|
|
1861
2170
|
*
|
|
1862
|
-
* @param sandboxId The sandbox ID returned by the original `Alineo.
|
|
2171
|
+
* @param sandboxId The sandbox ID returned by the original `Alineo.start()`.
|
|
1863
2172
|
* @param opts.spec An already-parsed agent spec object — skips file I/O entirely, same as
|
|
1864
|
-
* `
|
|
2173
|
+
* `start()`. Takes precedence over `opts.specPath` if both are set.
|
|
1865
2174
|
* @param opts.specPath Path to the agent spec JSON, read and validated internally. If
|
|
1866
2175
|
* neither `opts.spec` nor `opts.specPath` is set, the ledger is queried for the sandbox's
|
|
1867
2176
|
* name and the spec is read from `./agents/<name>.json` — this fallback is the one thing
|
|
1868
|
-
* `resume()` can do that `
|
|
2177
|
+
* `resume()` can do that `start()` can't, since a resumed sandbox's original spec may not be
|
|
1869
2178
|
* in memory anywhere the caller can hand it over.
|
|
1870
2179
|
*
|
|
1871
2180
|
* @example
|
|
1872
2181
|
* ```ts
|
|
1873
2182
|
* // Original process:
|
|
1874
2183
|
* const spec = await Bun.file("./agents/hello-agent.json").json();
|
|
1875
|
-
* const agent = await Alineo.
|
|
2184
|
+
* const agent = await Alineo.start(spec, { adapter });
|
|
1876
2185
|
* console.log(agent.sandboxId); // save this
|
|
1877
2186
|
* // ... process exits ...
|
|
1878
2187
|
*
|
|
@@ -1906,7 +2215,7 @@ var Alineo = class Alineo {
|
|
|
1906
2215
|
* the bridge process inside it has independently died, and this can't distinguish that from
|
|
1907
2216
|
* a slow-to-respond-but-fine bridge on its own. On failure, fall back to `Alineo.resume()`.
|
|
1908
2217
|
*
|
|
1909
|
-
* @param sandboxId The sandbox ID returned by the original `Alineo.
|
|
2218
|
+
* @param sandboxId The sandbox ID returned by the original `Alineo.start()`/`.spawn()`.
|
|
1910
2219
|
* @param opts.spec / opts.specPath Same three-way fallback as `resume()` — see its docs.
|
|
1911
2220
|
*
|
|
1912
2221
|
* @example
|
|
@@ -1930,7 +2239,7 @@ var Alineo = class Alineo {
|
|
|
1930
2239
|
* `resume()`, which kills and restarts the bridge process. Use this when you only
|
|
1931
2240
|
* need `.spawn()`/`.sandbox`, not `.prompt()`/`.bash()`.
|
|
1932
2241
|
*
|
|
1933
|
-
* The main caller is `alineo
|
|
2242
|
+
* The main caller is `alineo spawn`: it runs as a fresh CLI process started BY the
|
|
1934
2243
|
* very Pi bash-tool call it's attaching to (a master agent spawning a child from
|
|
1935
2244
|
* inside its own turn). Going through `resume()` there would `pkill` the bridge
|
|
1936
2245
|
* that's currently running the Pi process making the call — self-destructive.
|
|
@@ -1941,7 +2250,7 @@ var Alineo = class Alineo {
|
|
|
1941
2250
|
* file, which may not even exist inside this particular sandbox.
|
|
1942
2251
|
*
|
|
1943
2252
|
* When `sandboxId` matches `ALINEO_SANDBOX_ID` in this process's own env (true
|
|
1944
|
-
* self-attach, e.g. `alineo
|
|
2253
|
+
* self-attach, e.g. `alineo spawn` running from inside its own container),
|
|
1945
2254
|
* `/etc/alineo-env` is read straight off the local filesystem instead of via
|
|
1946
2255
|
* `sb.readFile()`. A self-referential exec call would need this sandbox to
|
|
1947
2256
|
* reach itself through its own externally-facing bridge IP, which Docker's
|
|
@@ -1952,7 +2261,7 @@ var Alineo = class Alineo {
|
|
|
1952
2261
|
* `opts.resources` sizes a subsequent `.spawn()`'s forked container — the
|
|
1953
2262
|
* control API doesn't echo back a running sandbox's own resource limits, so
|
|
1954
2263
|
* there's no way to discover this agent's *actual* footprint here. Defaults to
|
|
1955
|
-
* `alineo.config.json`'s `defaults.resources`, same fallback `Alineo.
|
|
2264
|
+
* `alineo.config.json`'s `defaults.resources`, same fallback `Alineo.start()` uses
|
|
1956
2265
|
* for a spec that doesn't set its own.
|
|
1957
2266
|
*/
|
|
1958
2267
|
static async attach(sandboxId, opts) {
|
|
@@ -1964,7 +2273,7 @@ var Alineo = class Alineo {
|
|
|
1964
2273
|
/**
|
|
1965
2274
|
* Fork this agent's live sandbox — filesystem, installed packages, checked-out
|
|
1966
2275
|
* state, everything currently on disk — into a brand-new independent sandbox
|
|
1967
|
-
* running its own Pi bridge, per `childSpecPath`. Unlike `Alineo.
|
|
2276
|
+
* running its own Pi bridge, per `childSpecPath`. Unlike `Alineo.start()` (always
|
|
1968
2277
|
* starts from a spec's own snapshot) or `fork()`/`clone()` below (Pi's own
|
|
1969
2278
|
* conversation-branching — same container, same bridge, new session branch),
|
|
1970
2279
|
* this is sandbox-level forking: the child sees exactly what this agent's
|
|
@@ -2093,8 +2402,8 @@ var Alineo = class Alineo {
|
|
|
2093
2402
|
* List the fork entry points available in the current session.
|
|
2094
2403
|
* Each entry has `entryId` (pass to `fork()`) and `text` (the message at that point).
|
|
2095
2404
|
*/
|
|
2096
|
-
async
|
|
2097
|
-
return
|
|
2405
|
+
async getBranchPoints() {
|
|
2406
|
+
return getBranchPoints(this);
|
|
2098
2407
|
}
|
|
2099
2408
|
/** List Pi's available slash commands, including extensions, prompt templates, and skills. */
|
|
2100
2409
|
async getCommands() {
|
|
@@ -2127,15 +2436,21 @@ var Alineo = class Alineo {
|
|
|
2127
2436
|
return exportHtml(this, outputPath);
|
|
2128
2437
|
}
|
|
2129
2438
|
/**
|
|
2130
|
-
*
|
|
2131
|
-
*
|
|
2439
|
+
* Branch the harness conversation at the given entry ID.
|
|
2440
|
+
*
|
|
2441
|
+
* Named for what it touches. This never leaves the container: it is the harness's own
|
|
2442
|
+
* session that branches, not the sandbox — `agent.sandbox.fork()` is the one that copies a
|
|
2443
|
+
* filesystem. Unqualified `fork` meant both for a while, which is the confusion this name
|
|
2444
|
+
* exists to end.
|
|
2445
|
+
*
|
|
2446
|
+
* Returns the text of the branched message and whether the branch was cancelled.
|
|
2132
2447
|
*/
|
|
2133
|
-
async
|
|
2134
|
-
return
|
|
2448
|
+
async branchSession(entryId) {
|
|
2449
|
+
return branchSession(this, entryId);
|
|
2135
2450
|
}
|
|
2136
|
-
/**
|
|
2137
|
-
async
|
|
2138
|
-
return
|
|
2451
|
+
/** Branch the harness conversation at its current position. Same container, same bridge. */
|
|
2452
|
+
async duplicateSession() {
|
|
2453
|
+
return duplicateSession(this);
|
|
2139
2454
|
}
|
|
2140
2455
|
/** Switch Pi to a different session file on disk. */
|
|
2141
2456
|
async switchSession(sessionPath) {
|
|
@@ -2196,4 +2511,127 @@ async function* textOnly(stream) {
|
|
|
2196
2511
|
for await (const ev of stream) if (ev.type === "text") yield ev.text;
|
|
2197
2512
|
}
|
|
2198
2513
|
//#endregion
|
|
2199
|
-
|
|
2514
|
+
//#region src/checkpoint.ts
|
|
2515
|
+
/**
|
|
2516
|
+
* Turn-level checkpointing (durability-roadmap.md M3, 3.2) — deliberately NOT
|
|
2517
|
+
* `sb.checkpoint()`. That method calls OpenSandbox's own snapshot primitive, which on the
|
|
2518
|
+
* Docker runtime is literally `docker commit` (confirmed against OpenSandbox's own source,
|
|
2519
|
+
* M3's 3.1 research) — measured at 44.3s for a 236MB container, re-exporting the whole
|
|
2520
|
+
* filesystem every time regardless of how much actually changed. Calling that every turn would
|
|
2521
|
+
* silently reintroduce the exact cost 3.1 ruled out. This module tars a few directories via
|
|
2522
|
+
* `sb.exec()` instead — measured at well under 2s even unfiltered.
|
|
2523
|
+
*
|
|
2524
|
+
* This is a different mechanism from the agent SDK's other "snapshot" concept, the setup
|
|
2525
|
+
* snapshot (`./snapshots.ts`'s `AgentSnapshotStore`) — that one is taken once per unique
|
|
2526
|
+
* `(specName, setupHash)` to skip reinstalling Pi/packages on every `Alineo.start()`. This one
|
|
2527
|
+
* is taken after every completed turn, captures that specific conversation's state (not a
|
|
2528
|
+
* shared install), and is what `Alineo.resume()` restores from when the container itself is
|
|
2529
|
+
* gone (3.3) — the setup snapshot only gets a fresh, *empty* container, not this agent's actual
|
|
2530
|
+
* conversation.
|
|
2531
|
+
*/
|
|
2532
|
+
/** Directories/globs left out of every checkpoint tarball by default — universally-safe
|
|
2533
|
+
* package/toolchain caches, nothing else (3.1's decision: err toward inclusion, since the
|
|
2534
|
+
* measured unfiltered cost is already cheap — losing real workspace state by over-excluding is
|
|
2535
|
+
* a worse mistake than a few extra seconds). Paths are relative to `CHECKPOINT_ROOT`. */
|
|
2536
|
+
const DEFAULT_CHECKPOINT_EXCLUDES = [
|
|
2537
|
+
".npm",
|
|
2538
|
+
".cache",
|
|
2539
|
+
".cargo/registry/cache",
|
|
2540
|
+
"go/pkg/mod/cache/download"
|
|
2541
|
+
];
|
|
2542
|
+
/** Matched at any depth, not just directly under `CHECKPOINT_ROOT` — unlike the excludes
|
|
2543
|
+
* above, these can recur inside a workspace's own subdirectories (e.g. a cloned repo's own
|
|
2544
|
+
* `__pycache__`), not only at the top level. */
|
|
2545
|
+
const DEFAULT_CHECKPOINT_EXCLUDE_GLOBS = ["__pycache__", ".pytest_cache"];
|
|
2546
|
+
/**
|
|
2547
|
+
* The directory tarred into every checkpoint — Pi's home directory, where its session file
|
|
2548
|
+
* (`.pi/agent/sessions/...`) and whatever the agent wrote both live. Every sandbox measured for
|
|
2549
|
+
* 3.1 ran Pi as root; a spec that runs as a different user is a known simplification this
|
|
2550
|
+
* chunk doesn't yet handle (no portable way to ask a sandbox its $HOME without an extra exec
|
|
2551
|
+
* round trip on every checkpoint, and nothing in the current fleet needs it).
|
|
2552
|
+
*/
|
|
2553
|
+
const CHECKPOINT_ROOT = "root";
|
|
2554
|
+
/**
|
|
2555
|
+
* durability-roadmap M3, 3.5: restore (3.3) only ever reads the *latest* checkpoint — an older
|
|
2556
|
+
* one is slack for debugging/manual rollback, not a live requirement. 3 was decided without
|
|
2557
|
+
* real usage data to justify more (measured sizes are sub-30MB, typically far less once the
|
|
2558
|
+
* exclusion list applies), and is cheap to revisit if real retention pressure ever shows up.
|
|
2559
|
+
*/
|
|
2560
|
+
const DEFAULT_CHECKPOINT_RETENTION = 3;
|
|
2561
|
+
/** Derive the checkpoints directory from the ledger adapter's own path, same convention as
|
|
2562
|
+
* `./snapshots.ts`'s `snapshotsPath()`. */
|
|
2563
|
+
function checkpointsPath(adapterPath) {
|
|
2564
|
+
return join(dirname(adapterPath), "checkpoints");
|
|
2565
|
+
}
|
|
2566
|
+
/**
|
|
2567
|
+
* Keep only the newest `retain` checkpoint files in `dir`, deleting the rest — called after
|
|
2568
|
+
* every successful `takeCheckpoint()` so disk use stays bounded across a long-running agent
|
|
2569
|
+
* instead of growing forever. Sorted by file mtime (set at write time, monotonic regardless of
|
|
2570
|
+
* process restarts), not by the `turn` number embedded in the filename — `turn` resets to 0
|
|
2571
|
+
* across a resume/reattach (see `CheckpointRecord.turn`'s doc comment), so two checkpoints
|
|
2572
|
+
* from different process lifetimes can share the same `turn` without actually being the same
|
|
2573
|
+
* age. Best-effort: a failure here (e.g. a concurrent delete) is logged by the caller, not
|
|
2574
|
+
* thrown — pruning old checkpoints is cleanup, never allowed to fail the checkpoint that just
|
|
2575
|
+
* succeeded.
|
|
2576
|
+
*/
|
|
2577
|
+
async function pruneOldCheckpoints(dir, retain) {
|
|
2578
|
+
const names = await readdir(dir);
|
|
2579
|
+
if (names.length <= retain) return;
|
|
2580
|
+
const withTimes = await Promise.all(names.map(async (name) => ({
|
|
2581
|
+
name,
|
|
2582
|
+
mtimeMs: (await stat(join(dir, name))).mtimeMs
|
|
2583
|
+
})));
|
|
2584
|
+
withTimes.sort((a, b) => b.mtimeMs - a.mtimeMs);
|
|
2585
|
+
await Promise.all(withTimes.slice(retain).map((f) => rm(join(dir, f.name), { force: true })));
|
|
2586
|
+
}
|
|
2587
|
+
/**
|
|
2588
|
+
* Tar `CHECKPOINT_ROOT` (minus the default excludes) inside the sandbox, pull the bytes out
|
|
2589
|
+
* byte-safe (`sb.readFileBytes()`, never `readFile()`'s UTF-8 path — a gzip tarball is not
|
|
2590
|
+
* valid UTF-8), write them to `checkpointsDir`, and record `AgentCheckpointed` on the sandbox's
|
|
2591
|
+
* own ledger — in that order, snapshot-then-event, so a checkpoint event is never written
|
|
2592
|
+
* pointing at a tarball that doesn't actually exist on disk.
|
|
2593
|
+
*
|
|
2594
|
+
* Throws on any step's failure (tar inside the sandbox, the byte-safe download, or the host
|
|
2595
|
+
* write) — the caller decides whether a failed checkpoint should interrupt the turn it was
|
|
2596
|
+
* taken after (3.2's own call site treats it as best-effort and logs rather than throws
|
|
2597
|
+
* further, since a checkpoint failing is not the same failure as the turn itself failing).
|
|
2598
|
+
* Retention (3.5) runs only after a successful write+event, pruning this sandbox's own
|
|
2599
|
+
* directory down to `opts.retain` (default `DEFAULT_CHECKPOINT_RETENTION`). A pruning failure
|
|
2600
|
+
* is swallowed, not thrown — the checkpoint this call was actually for already succeeded, and
|
|
2601
|
+
* a cleanup failure must never retroactively turn that into an error.
|
|
2602
|
+
*/
|
|
2603
|
+
async function takeCheckpoint(sb, checkpointsDir, opts) {
|
|
2604
|
+
const tmpTarPath = `/tmp/alineo-checkpoint-${crypto.randomUUID()}.tar.gz`;
|
|
2605
|
+
const excludeArgs = [
|
|
2606
|
+
...DEFAULT_CHECKPOINT_EXCLUDES.map((p) => `--exclude=${CHECKPOINT_ROOT}/${p}`),
|
|
2607
|
+
...DEFAULT_CHECKPOINT_EXCLUDE_GLOBS.map((p) => `--exclude=*/${p}`),
|
|
2608
|
+
...(opts.excludeGlobs ?? []).map((p) => `--exclude=${p}`)
|
|
2609
|
+
];
|
|
2610
|
+
try {
|
|
2611
|
+
await sb.exec(`tar czf ${tmpTarPath} -C / ${excludeArgs.join(" ")} ${CHECKPOINT_ROOT}`);
|
|
2612
|
+
const bytes = await sb.readFileBytes(tmpTarPath);
|
|
2613
|
+
const createdAt = Date.now();
|
|
2614
|
+
const dir = join(checkpointsDir, sb.sandboxId);
|
|
2615
|
+
await mkdir(dir, { recursive: true });
|
|
2616
|
+
const snapshotRef = join(dir, `${opts.turn}-${createdAt}.tar.gz`);
|
|
2617
|
+
await writeFile(snapshotRef, bytes);
|
|
2618
|
+
await sb.emit(LedgerEvent.AgentCheckpointed, -1, {
|
|
2619
|
+
turn: opts.turn,
|
|
2620
|
+
snapshotRef
|
|
2621
|
+
});
|
|
2622
|
+
try {
|
|
2623
|
+
await pruneOldCheckpoints(dir, opts.retain ?? 3);
|
|
2624
|
+
} catch {}
|
|
2625
|
+
return {
|
|
2626
|
+
turn: opts.turn,
|
|
2627
|
+
snapshotRef,
|
|
2628
|
+
createdAt
|
|
2629
|
+
};
|
|
2630
|
+
} finally {
|
|
2631
|
+
try {
|
|
2632
|
+
await sb.exec(`rm -f ${tmpTarPath}`, { strict: false });
|
|
2633
|
+
} catch {}
|
|
2634
|
+
}
|
|
2635
|
+
}
|
|
2636
|
+
//#endregion
|
|
2637
|
+
export { AgentSnapshotStore, AgentSpecValidationError, Alineo, BridgeDisconnectedError, CHECKPOINT_ROOT, DEFAULT_CHECKPOINT_EXCLUDES, DEFAULT_CHECKPOINT_RETENTION, EgressApprovalGate, PromptTimeoutError, checkpointsPath, computeSetupHash, findLatestCheckpoint, isReadOnlyBashCommand, isSandboxGone, restoreCheckpoint, snapshotsPath, takeCheckpoint, textOnly, validateAgentSpec };
|