alineo 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -32
- package/dist/index.d.mts +244 -319
- package/dist/index.mjs +727 -237
- package/package.json +7 -4
package/dist/index.mjs
CHANGED
|
@@ -1,47 +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
|
-
import {
|
|
5
|
+
import { getLogger } from "@alineo-labs/logger";
|
|
6
|
+
import { homedir } from "node:os";
|
|
7
|
+
import { dirname, join, resolve } from "node:path";
|
|
5
8
|
import * as z$1 from "zod";
|
|
9
|
+
import "zod";
|
|
6
10
|
import { fileURLToPath } from "node:url";
|
|
7
11
|
import { createHash } from "node:crypto";
|
|
8
|
-
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
9
|
-
import { dirname } from "node:path";
|
|
12
|
+
import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
|
|
10
13
|
import { createServer } from "node:http";
|
|
11
|
-
//#region
|
|
12
|
-
|
|
13
|
-
const
|
|
14
|
-
serverUrl: "http://127.0.0.1:8080",
|
|
15
|
-
apiKey: "",
|
|
16
|
-
adapterPath: "./.alineo/ledger.db",
|
|
17
|
-
useServerProxy: true,
|
|
18
|
-
agentsDir: "./agents",
|
|
19
|
-
defaults: { resources: {
|
|
20
|
-
cpu: "1000m",
|
|
21
|
-
memory: "1Gi"
|
|
22
|
-
} }
|
|
23
|
-
};
|
|
14
|
+
//#region ../config-shared/dist/index.mjs
|
|
15
|
+
/** The file name every alineo project config uses. */
|
|
16
|
+
const PROJECT_CONFIG_FILE = "alineo.config.json";
|
|
24
17
|
/**
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
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.
|
|
28
34
|
*/
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
+
}
|
|
52
|
+
/**
|
|
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.
|
|
56
|
+
*/
|
|
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;
|
|
41
148
|
}
|
|
42
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
|
|
43
181
|
};
|
|
44
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
|
+
}
|
|
45
262
|
//#endregion
|
|
46
263
|
//#region src/errors.ts
|
|
47
264
|
/**
|
|
@@ -51,7 +268,7 @@ async function readProjectConfig() {
|
|
|
51
268
|
* about whether Pi itself is making progress) for that long. Previously this surfaced as an
|
|
52
269
|
* indefinite hang with zero visibility: `sseStream()` had no timeout at all, so a genuinely
|
|
53
270
|
* stuck Pi process (e.g. blocked in a credential refresh, or any other silent stall) blocked
|
|
54
|
-
* every caller up the chain -- `Alineo.prompt()`, `collectReply()`, `alineo
|
|
271
|
+
* every caller up the chain -- `Alineo.prompt()`, `collectReply()`, `alineo spawn --prompt` --
|
|
55
272
|
* forever, with no error and no partial output.
|
|
56
273
|
*/
|
|
57
274
|
var PromptTimeoutError = class extends WorkflowError {
|
|
@@ -65,6 +282,24 @@ var PromptTimeoutError = class extends WorkflowError {
|
|
|
65
282
|
}
|
|
66
283
|
};
|
|
67
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
|
+
/**
|
|
68
303
|
* Thrown by `validateAgentSpec()` when a spec object fails schema validation. Carries every
|
|
69
304
|
* failing field in one pass (`.issues`, mirroring `z.ZodIssue[]` shape) rather than surfacing
|
|
70
305
|
* only the first problem found -- see #185. `.message` is a pre-formatted, human-readable
|
|
@@ -81,102 +316,26 @@ var AgentSpecValidationError = class extends WorkflowError {
|
|
|
81
316
|
};
|
|
82
317
|
//#endregion
|
|
83
318
|
//#region src/schema.ts
|
|
84
|
-
/** Renders an arbitrary invalid field value for an error message without risking "[object Object]". */
|
|
85
|
-
function describeValue(value) {
|
|
86
|
-
if (typeof value === "string") return value;
|
|
87
|
-
try {
|
|
88
|
-
const json = JSON.stringify(value);
|
|
89
|
-
if (json !== void 0) return json;
|
|
90
|
-
} catch {}
|
|
91
|
-
return typeof value === "object" && value !== null ? Object.prototype.toString.call(value) : String(value);
|
|
92
|
-
}
|
|
93
319
|
/**
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
* 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.
|
|
100
325
|
*/
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
"header",
|
|
115
|
-
"body"
|
|
116
|
-
])).min(1)
|
|
117
|
-
})]),
|
|
118
|
-
approval: z$1.literal("hold").optional()
|
|
119
|
-
}).loose();
|
|
120
|
-
const SetupStepSchema = z$1.object({
|
|
121
|
-
name: z$1.string({ error: "Each setup step must have a 'name' string" }),
|
|
122
|
-
run: z$1.string({ error: "Each setup step must have a 'run' string" }),
|
|
123
|
-
cwd: z$1.string().optional()
|
|
124
|
-
}).loose();
|
|
125
|
-
const PermissionActionSchema = z$1.enum([
|
|
126
|
-
"allow",
|
|
127
|
-
"ask",
|
|
128
|
-
"deny",
|
|
129
|
-
"rate_limit",
|
|
130
|
-
"classify"
|
|
131
|
-
]);
|
|
132
|
-
const PermissionRuleSchema = z$1.object({
|
|
133
|
-
tool: z$1.string({ error: "Each permission rule must have a 'tool' string" }),
|
|
134
|
-
pattern: z$1.string().optional(),
|
|
135
|
-
action: PermissionActionSchema,
|
|
136
|
-
limit: z$1.object({
|
|
137
|
-
count: z$1.number().int().positive(),
|
|
138
|
-
windowMs: z$1.number().int().positive()
|
|
139
|
-
}).optional()
|
|
140
|
-
}).loose();
|
|
141
|
-
const PermissionPolicySchema = z$1.object({
|
|
142
|
-
default: PermissionActionSchema.optional(),
|
|
143
|
-
rules: z$1.array(PermissionRuleSchema).optional(),
|
|
144
|
-
disabledTools: z$1.array(z$1.string()).optional(),
|
|
145
|
-
restrictToTools: z$1.array(z$1.string()).optional()
|
|
146
|
-
}).loose();
|
|
147
|
-
const PermissionsSchema = z$1.union([z$1.enum([
|
|
148
|
-
"auto",
|
|
149
|
-
"ask",
|
|
150
|
-
"readonly"
|
|
151
|
-
]), PermissionPolicySchema]);
|
|
152
|
-
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();
|
|
153
|
-
const AgentSpecSchema = z$1.object({
|
|
154
|
-
$schema: z$1.string().optional(),
|
|
155
|
-
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"),
|
|
156
|
-
title: z$1.string().optional(),
|
|
157
|
-
description: z$1.string().optional(),
|
|
158
|
-
author: z$1.string().optional(),
|
|
159
|
-
categories: z$1.array(z$1.string()).optional(),
|
|
160
|
-
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` }),
|
|
161
|
-
cliVersion: z$1.string().optional(),
|
|
162
|
-
provider: z$1.string().optional(),
|
|
163
|
-
model: z$1.string().optional(),
|
|
164
|
-
packages: z$1.array(z$1.string()).optional(),
|
|
165
|
-
env: z$1.record(z$1.string(), z$1.union([z$1.string(), CredentialEnvBindingSchema])).optional(),
|
|
166
|
-
resources: z$1.object({
|
|
167
|
-
cpu: z$1.string(),
|
|
168
|
-
memory: z$1.string(),
|
|
169
|
-
gpu: z$1.string().optional()
|
|
170
|
-
}).optional(),
|
|
171
|
-
metadata: z$1.record(z$1.string(), z$1.string()).optional(),
|
|
172
|
-
registryDependencies: z$1.array(z$1.string()).optional(),
|
|
173
|
-
setup: z$1.array(SetupStepSchema).optional(),
|
|
174
|
-
spawnDepth: nonNegativeIntSpecField("spawnDepth"),
|
|
175
|
-
maxAgents: nonNegativeIntSpecField("maxAgents"),
|
|
176
|
-
teamId: z$1.string().optional(),
|
|
177
|
-
resourceId: z$1.string().optional(),
|
|
178
|
-
permissions: PermissionsSchema.optional()
|
|
179
|
-
}).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
|
+
}
|
|
180
339
|
/**
|
|
181
340
|
* Validate an unknown value as an `AgentSpec`, aggregating every problem found in one pass.
|
|
182
341
|
* Throws `AgentSpecValidationError` (with a pre-formatted `.message` and a structured
|
|
@@ -184,7 +343,7 @@ const AgentSpecSchema = z$1.object({
|
|
|
184
343
|
*/
|
|
185
344
|
function validateAgentSpec(data) {
|
|
186
345
|
const result = AgentSpecSchema.safeParse(data);
|
|
187
|
-
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) => ({
|
|
188
347
|
path: issue.path,
|
|
189
348
|
message: issue.message,
|
|
190
349
|
code: issue.code
|
|
@@ -193,6 +352,14 @@ function validateAgentSpec(data) {
|
|
|
193
352
|
}
|
|
194
353
|
//#endregion
|
|
195
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
|
+
*/
|
|
196
363
|
/** Read-only built-in tools — auto-allowed (and the entire toolset) under `"readonly"`. */
|
|
197
364
|
const READ_ONLY_TOOLS = [
|
|
198
365
|
"read",
|
|
@@ -472,7 +639,7 @@ var PiAdapter = class {
|
|
|
472
639
|
async install(sb, spec) {
|
|
473
640
|
const pkgs = [...new Set(spec.packages ?? [])].filter((p) => p !== "nodejs_22" && p !== "nodejs");
|
|
474
641
|
if (pkgs.length > 0) await sb.exec(`apt-get update -qq && apt-get install -y --no-install-recommends ${pkgs.join(" ")}`);
|
|
475
|
-
const versionSpecifier = spec.
|
|
642
|
+
const versionSpecifier = spec.harnessVersion?.trim();
|
|
476
643
|
const pkg = versionSpecifier ? `@earendil-works/pi-coding-agent@${versionSpecifier}` : "@earendil-works/pi-coding-agent";
|
|
477
644
|
await sb.exec(`npm install -g --ignore-scripts ${pkg}`);
|
|
478
645
|
}
|
|
@@ -483,7 +650,7 @@ var PiAdapter = class {
|
|
|
483
650
|
async configure(sb, spec, resolvedEnv, opts) {
|
|
484
651
|
const piConfig = {};
|
|
485
652
|
if (spec.provider) piConfig.provider = spec.provider;
|
|
486
|
-
|
|
653
|
+
piConfig.model = spec.model;
|
|
487
654
|
if (opts?.resume) piConfig.resume = true;
|
|
488
655
|
const permissions = normalizePermissions(spec.permissions);
|
|
489
656
|
if (permissions) piConfig.permissions = permissions;
|
|
@@ -684,7 +851,7 @@ async function rpcGet(bridgeUrl, path) {
|
|
|
684
851
|
* 60s (the original default) was too tight for a common, legitimate pattern: Pi's own `bash`
|
|
685
852
|
* tool is not incrementally streamed (see the `bash()` doc comment in session-control.ts), so
|
|
686
853
|
* a single tool call that spins up a whole child sandbox -- e.g. a master session running
|
|
687
|
-
* `alineo
|
|
854
|
+
* `alineo spawn` on itself, as in examples/rlm-repo-fanout -- produces zero AgentEvents for as
|
|
688
855
|
* long as that tool call takes, which regularly exceeded 60s (child sandbox provisioning +
|
|
689
856
|
* Pi CLI install alone routinely took 30-150s+ in practice) and tripped this timeout mid-run
|
|
690
857
|
* even though the session was making real progress. Raised to 3 minutes as a still-bounded
|
|
@@ -729,7 +896,7 @@ async function* sseStream(bridgeUrl, path, body, pendingStreams, inactivityTimeo
|
|
|
729
896
|
const { done, value } = result;
|
|
730
897
|
if (done) {
|
|
731
898
|
reachedNaturalEnd = true;
|
|
732
|
-
|
|
899
|
+
throw new BridgeDisconnectedError(bridgeUrl);
|
|
733
900
|
}
|
|
734
901
|
buf += decoder.decode(value, { stream: true });
|
|
735
902
|
const lines = buf.split("\n");
|
|
@@ -756,14 +923,20 @@ async function* sseStream(bridgeUrl, path, body, pendingStreams, inactivityTimeo
|
|
|
756
923
|
//#endregion
|
|
757
924
|
//#region src/snapshots.ts
|
|
758
925
|
/**
|
|
759
|
-
* Hash of the fields that require re-installing the
|
|
760
|
-
* setup:
|
|
761
|
-
* 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.
|
|
762
935
|
*/
|
|
763
936
|
function computeSetupHash(spec) {
|
|
764
937
|
return createHash("sha256").update(JSON.stringify({
|
|
765
|
-
cli: spec.
|
|
766
|
-
cliVersion: spec.
|
|
938
|
+
cli: spec.harness,
|
|
939
|
+
cliVersion: spec.harnessVersion ?? "latest",
|
|
767
940
|
packages: [...spec.packages ?? []].sort(),
|
|
768
941
|
setup: spec.setup ?? []
|
|
769
942
|
})).digest("hex").slice(0, 12);
|
|
@@ -812,6 +985,63 @@ var AgentSnapshotStore = class {
|
|
|
812
985
|
}
|
|
813
986
|
};
|
|
814
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
|
|
815
1045
|
//#region src/agent/validation.ts
|
|
816
1046
|
/**
|
|
817
1047
|
* The durable resource identity for a spawned child, frozen from the child spec BEFORE
|
|
@@ -824,7 +1054,7 @@ var AgentSnapshotStore = class {
|
|
|
824
1054
|
* agree on the exact same value — is independently unit-testable.
|
|
825
1055
|
*/
|
|
826
1056
|
function resolveChildResourceId(childSpec) {
|
|
827
|
-
return childSpec.resourceId
|
|
1057
|
+
return resourceRefOf(childSpec).resourceId;
|
|
828
1058
|
}
|
|
829
1059
|
function assertValidSpawnDepth(value, context) {
|
|
830
1060
|
if (!Number.isInteger(value) || value < 0) throw new Error(`${context}: spawnDepth must be a non-negative integer (got ${value})`);
|
|
@@ -835,7 +1065,7 @@ function assertValidMaxAgents(value, context) {
|
|
|
835
1065
|
/**
|
|
836
1066
|
* Resolves and validates the spawn-depth budget available to `Alineo.spawn()` —
|
|
837
1067
|
* `override` (a `--depth` CLI flag) wins if given, else whatever value was
|
|
838
|
-
* materialised into `ALINEO_SPAWN_DEPTH` by `Alineo.
|
|
1068
|
+
* materialised into `ALINEO_SPAWN_DEPTH` by `Alineo.start()`/`Alineo.resume()`. Throws
|
|
839
1069
|
* unless the result is a positive integer: `0` means "no budget left", not "spawn
|
|
840
1070
|
* one more time" — spawning stops one level before the counter would go negative.
|
|
841
1071
|
*/
|
|
@@ -1010,29 +1240,43 @@ function normalizeHost(host) {
|
|
|
1010
1240
|
}
|
|
1011
1241
|
//#endregion
|
|
1012
1242
|
//#region src/agent/factory.ts
|
|
1243
|
+
const agentLog = getLogger("agent");
|
|
1244
|
+
/** Best-effort cleanup that failed: say so — the sandbox may now be leaked. */
|
|
1245
|
+
function cleanupFailed(log, which) {
|
|
1246
|
+
return (err) => {
|
|
1247
|
+
log.warn("cleanup failed: could not close sandbox — it may be leaked", {
|
|
1248
|
+
...which,
|
|
1249
|
+
err
|
|
1250
|
+
});
|
|
1251
|
+
};
|
|
1252
|
+
}
|
|
1013
1253
|
function elapsed(t) {
|
|
1014
1254
|
return `${Date.now() - t}ms`;
|
|
1015
1255
|
}
|
|
1016
1256
|
/**
|
|
1017
1257
|
* Validate `specInput` and return everything needed to construct a fully initialised `Alineo`.
|
|
1018
|
-
* See `Alineo.
|
|
1258
|
+
* See `Alineo.start()` for the public-facing docs.
|
|
1019
1259
|
*/
|
|
1020
1260
|
async function loadAgent(specInput, opts) {
|
|
1021
1261
|
const t0 = Date.now();
|
|
1022
1262
|
const spec = validateAgentSpec(specInput);
|
|
1023
|
-
const config =
|
|
1263
|
+
const config = resolveProjectConfig(opts.config);
|
|
1024
1264
|
const resolvedEnv = resolveEnv(spec.env ?? {});
|
|
1025
1265
|
const effectiveSpawnDepth = opts.spawnDepth ?? spec.spawnDepth;
|
|
1026
1266
|
if (effectiveSpawnDepth !== void 0) {
|
|
1027
|
-
assertValidSpawnDepth(effectiveSpawnDepth, "Alineo.
|
|
1267
|
+
assertValidSpawnDepth(effectiveSpawnDepth, "Alineo.start()");
|
|
1028
1268
|
resolvedEnv.ALINEO_SPAWN_DEPTH = String(effectiveSpawnDepth);
|
|
1029
1269
|
}
|
|
1030
1270
|
const effectiveMaxAgents = opts.maxAgents ?? spec.maxAgents;
|
|
1031
1271
|
if (effectiveMaxAgents !== void 0) {
|
|
1032
|
-
assertValidMaxAgents(effectiveMaxAgents, "Alineo.
|
|
1272
|
+
assertValidMaxAgents(effectiveMaxAgents, "Alineo.start()");
|
|
1033
1273
|
resolvedEnv.ALINEO_MAX_AGENTS = String(effectiveMaxAgents);
|
|
1034
1274
|
}
|
|
1035
1275
|
const runId = opts.runId ?? crypto.randomUUID();
|
|
1276
|
+
const log = agentLog.child(opts.runId ? {
|
|
1277
|
+
name: spec.name,
|
|
1278
|
+
runId
|
|
1279
|
+
} : { name: spec.name });
|
|
1036
1280
|
resolvedEnv.ALINEO_RUN_ID = runId;
|
|
1037
1281
|
const resources = {
|
|
1038
1282
|
...config.defaults.resources,
|
|
@@ -1042,7 +1286,7 @@ async function loadAgent(specInput, opts) {
|
|
|
1042
1286
|
const needsCredentialProxy = credentialBindings.length > 0;
|
|
1043
1287
|
const heldCredentials = credentialBindings.filter((b) => b.approval === "hold");
|
|
1044
1288
|
const heldHosts = [...new Set(heldCredentials.map((b) => b.binding.host.trim().replace(/\.$/, "").toLowerCase()))];
|
|
1045
|
-
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.`);
|
|
1046
1290
|
const networkPolicy = needsCredentialProxy || heldHosts.length > 0 ? {
|
|
1047
1291
|
defaultAction: "allow",
|
|
1048
1292
|
egress: heldHosts.map((target) => ({
|
|
@@ -1078,25 +1322,28 @@ async function loadAgent(specInput, opts) {
|
|
|
1078
1322
|
if (!opts.rebuild) {
|
|
1079
1323
|
const record = await store.get(spec.name, setupHash);
|
|
1080
1324
|
if (record) try {
|
|
1081
|
-
|
|
1325
|
+
log.info("restoring from snapshot");
|
|
1082
1326
|
const t1 = Date.now();
|
|
1083
1327
|
sb = await client.restoreSnapshot(record.snapshotId, spec.name, resources, runId, {
|
|
1084
1328
|
networkPolicy,
|
|
1085
1329
|
...egressEnv.OPENSANDBOX_EGRESS_DENY_WEBHOOK ? { env: egressEnv } : {},
|
|
1086
1330
|
credentialProxy: needsCredentialProxy,
|
|
1087
|
-
resourceId: spec.resourceId
|
|
1331
|
+
resourceId: resourceRefOf(spec).resourceId,
|
|
1088
1332
|
teamId: spec.teamId
|
|
1089
1333
|
});
|
|
1090
|
-
|
|
1334
|
+
log.info("snapshot ready", {
|
|
1335
|
+
elapsed: elapsed(t1),
|
|
1336
|
+
sandboxId: sb.sandboxId
|
|
1337
|
+
});
|
|
1091
1338
|
fromSnapshot = true;
|
|
1092
1339
|
} catch (err) {
|
|
1093
1340
|
const reason = err instanceof Error ? err.message : String(err);
|
|
1094
|
-
|
|
1341
|
+
log.warn("snapshot restore failed, rebuilding", { reason });
|
|
1095
1342
|
await store.delete(spec.name);
|
|
1096
1343
|
}
|
|
1097
1344
|
}
|
|
1098
1345
|
if (!fromSnapshot) {
|
|
1099
|
-
|
|
1346
|
+
log.info("starting sandbox");
|
|
1100
1347
|
const t1 = Date.now();
|
|
1101
1348
|
sb = await client.sandbox({
|
|
1102
1349
|
image: "node:22",
|
|
@@ -1109,24 +1356,30 @@ async function loadAgent(specInput, opts) {
|
|
|
1109
1356
|
runId,
|
|
1110
1357
|
networkPolicy,
|
|
1111
1358
|
credentialProxy: needsCredentialProxy,
|
|
1112
|
-
resourceId: spec.resourceId
|
|
1359
|
+
resourceId: resourceRefOf(spec).resourceId,
|
|
1113
1360
|
teamId: spec.teamId
|
|
1114
1361
|
});
|
|
1115
|
-
|
|
1362
|
+
log.info("sandbox ready", {
|
|
1363
|
+
elapsed: elapsed(t1),
|
|
1364
|
+
sandboxId: sb.sandboxId
|
|
1365
|
+
});
|
|
1116
1366
|
const created = sb;
|
|
1117
1367
|
try {
|
|
1118
|
-
|
|
1368
|
+
log.info("installing Pi CLI");
|
|
1119
1369
|
const t2 = Date.now();
|
|
1120
1370
|
await adapter.install(created, spec);
|
|
1121
|
-
|
|
1371
|
+
log.info("Pi CLI ready", { elapsed: elapsed(t2) });
|
|
1122
1372
|
for (const step of spec.setup ?? []) {
|
|
1123
|
-
|
|
1373
|
+
log.info("setup step", { step: step.name });
|
|
1124
1374
|
const ts = Date.now();
|
|
1125
1375
|
const cmd = step.cwd ? `cd ${step.cwd} && ${step.run}` : step.run;
|
|
1126
1376
|
await created.exec(cmd);
|
|
1127
|
-
|
|
1377
|
+
log.info("setup step done", {
|
|
1378
|
+
step: step.name,
|
|
1379
|
+
elapsed: elapsed(ts)
|
|
1380
|
+
});
|
|
1128
1381
|
}
|
|
1129
|
-
|
|
1382
|
+
log.info("checkpointing");
|
|
1130
1383
|
const t3 = Date.now();
|
|
1131
1384
|
const snapshotId = await created.checkpoint();
|
|
1132
1385
|
await store.save({
|
|
@@ -1135,9 +1388,9 @@ async function loadAgent(specInput, opts) {
|
|
|
1135
1388
|
snapshotId,
|
|
1136
1389
|
createdAt: Date.now()
|
|
1137
1390
|
});
|
|
1138
|
-
|
|
1391
|
+
log.info("checkpoint done", { elapsed: elapsed(t3) });
|
|
1139
1392
|
} catch (err) {
|
|
1140
|
-
await created.close().catch((
|
|
1393
|
+
await created.close().catch(cleanupFailed(log, { sandboxId: created.sandboxId }));
|
|
1141
1394
|
await egressGate?.stop().catch(() => {});
|
|
1142
1395
|
throw err;
|
|
1143
1396
|
}
|
|
@@ -1151,24 +1404,27 @@ async function loadAgent(specInput, opts) {
|
|
|
1151
1404
|
}
|
|
1152
1405
|
resolvedEnv.ALINEO_SANDBOX_ID = sb.sandboxId;
|
|
1153
1406
|
await adapter.configure(sb, spec, resolvedEnv);
|
|
1154
|
-
|
|
1407
|
+
log.info("starting bridge");
|
|
1155
1408
|
const t4 = Date.now();
|
|
1156
1409
|
await adapter.startBridge(sb);
|
|
1157
1410
|
await adapter.waitReady();
|
|
1158
|
-
|
|
1411
|
+
log.info("bridge ready", { elapsed: elapsed(t4) });
|
|
1159
1412
|
} catch (err) {
|
|
1160
|
-
await sb.close().catch((
|
|
1413
|
+
await sb.close().catch(cleanupFailed(log, { sandboxId: sb.sandboxId }));
|
|
1161
1414
|
await egressGate?.stop().catch(() => {});
|
|
1162
1415
|
if (!fromSnapshot) throw err;
|
|
1163
1416
|
const reason = err instanceof Error ? err.message : String(err);
|
|
1164
|
-
|
|
1417
|
+
log.warn("restored snapshot didn't start — discarding it and rebuilding", { reason });
|
|
1165
1418
|
await store.delete(spec.name);
|
|
1166
1419
|
return loadAgent(specInput, {
|
|
1167
1420
|
...opts,
|
|
1168
1421
|
rebuild: true
|
|
1169
1422
|
});
|
|
1170
1423
|
}
|
|
1171
|
-
|
|
1424
|
+
log.info("total", {
|
|
1425
|
+
elapsed: elapsed(t0),
|
|
1426
|
+
fromSnapshot
|
|
1427
|
+
});
|
|
1172
1428
|
return {
|
|
1173
1429
|
sandbox: sb,
|
|
1174
1430
|
spec,
|
|
@@ -1180,12 +1436,54 @@ async function loadAgent(specInput, opts) {
|
|
|
1180
1436
|
};
|
|
1181
1437
|
}
|
|
1182
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
|
+
/**
|
|
1183
1481
|
* Reconnect to a previously-created agent whose host process has exited. See
|
|
1184
1482
|
* `Alineo.resume()` for the public-facing docs.
|
|
1185
1483
|
*/
|
|
1186
1484
|
async function resumeAgent(sandboxId, opts) {
|
|
1187
1485
|
const t0 = Date.now();
|
|
1188
|
-
const config =
|
|
1486
|
+
const config = resolveProjectConfig(opts.config);
|
|
1189
1487
|
const client = new Sandbox({
|
|
1190
1488
|
baseUrl: config.serverUrl,
|
|
1191
1489
|
apiKey: config.apiKey,
|
|
@@ -1210,27 +1508,37 @@ async function resumeAgent(sandboxId, opts) {
|
|
|
1210
1508
|
resolvedEnv.ALINEO_SPAWN_DEPTH = String(spec.spawnDepth);
|
|
1211
1509
|
}
|
|
1212
1510
|
const runId = opts.runId ?? crypto.randomUUID();
|
|
1511
|
+
const log = agentLog.child(opts.runId ? {
|
|
1512
|
+
name: spec.name,
|
|
1513
|
+
runId
|
|
1514
|
+
} : { name: spec.name });
|
|
1213
1515
|
resolvedEnv.ALINEO_RUN_ID = runId;
|
|
1214
|
-
|
|
1516
|
+
log.info("reconnecting", { sandboxId });
|
|
1215
1517
|
const t1 = Date.now();
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
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
|
+
}
|
|
1530
|
+
log.info("connected", { elapsed: elapsed(t1) });
|
|
1223
1531
|
await sb.exec("pkill -f 'node /alineo-bridge.js' 2>/dev/null; sleep 0.1; true", { strict: false });
|
|
1224
1532
|
const adapter = new PiAdapter();
|
|
1225
1533
|
resolvedEnv.ALINEO_SANDBOX_ID = sandboxId;
|
|
1226
1534
|
await adapter.configure(sb, spec, resolvedEnv, { resume: true });
|
|
1227
|
-
|
|
1535
|
+
log.info("starting bridge");
|
|
1228
1536
|
const t2 = Date.now();
|
|
1229
1537
|
await adapter.startBridge(sb);
|
|
1230
1538
|
await adapter.waitReady();
|
|
1231
|
-
|
|
1539
|
+
log.info("bridge ready", { elapsed: elapsed(t2) });
|
|
1232
1540
|
await reconcileDroppedPermissions(opts.adapter, sb, spec.name, sandboxId);
|
|
1233
|
-
|
|
1541
|
+
log.info("total", { elapsed: elapsed(t0) });
|
|
1234
1542
|
return {
|
|
1235
1543
|
sandbox: sb,
|
|
1236
1544
|
spec,
|
|
@@ -1240,6 +1548,21 @@ async function resumeAgent(sandboxId, opts) {
|
|
|
1240
1548
|
runId
|
|
1241
1549
|
};
|
|
1242
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
|
+
*/
|
|
1243
1566
|
async function reconcileDroppedPermissions(adapter, sb, name, sandboxId) {
|
|
1244
1567
|
try {
|
|
1245
1568
|
const events = await adapter.readAll(name, sandboxId);
|
|
@@ -1253,8 +1576,8 @@ async function reconcileDroppedPermissions(adapter, sb, name, sandboxId) {
|
|
|
1253
1576
|
const rid = e.payload?.requestId;
|
|
1254
1577
|
if (rid && !resolved.has(rid)) await sb.emit(LedgerEvent.PermissionResolved, -1, {
|
|
1255
1578
|
requestId: rid,
|
|
1256
|
-
decision: { kind: "
|
|
1257
|
-
note: "session resumed —
|
|
1579
|
+
decision: { kind: "dropped" },
|
|
1580
|
+
note: "session resumed — the tool call this was about is gone; no one answered it"
|
|
1258
1581
|
});
|
|
1259
1582
|
}
|
|
1260
1583
|
} catch {}
|
|
@@ -1267,7 +1590,7 @@ async function reconcileDroppedPermissions(adapter, sb, name, sandboxId) {
|
|
|
1267
1590
|
*/
|
|
1268
1591
|
async function reattachAgent(sandboxId, opts) {
|
|
1269
1592
|
const t0 = Date.now();
|
|
1270
|
-
const config =
|
|
1593
|
+
const config = resolveProjectConfig(opts.config);
|
|
1271
1594
|
const client = new Sandbox({
|
|
1272
1595
|
baseUrl: config.serverUrl,
|
|
1273
1596
|
apiKey: config.apiKey,
|
|
@@ -1292,24 +1615,37 @@ async function reattachAgent(sandboxId, opts) {
|
|
|
1292
1615
|
resolvedEnv.ALINEO_SPAWN_DEPTH = String(spec.spawnDepth);
|
|
1293
1616
|
}
|
|
1294
1617
|
const runId = opts.runId ?? crypto.randomUUID();
|
|
1618
|
+
const log = agentLog.child(opts.runId ? {
|
|
1619
|
+
name: spec.name,
|
|
1620
|
+
runId
|
|
1621
|
+
} : { name: spec.name });
|
|
1295
1622
|
resolvedEnv.ALINEO_RUN_ID = runId;
|
|
1296
1623
|
resolvedEnv.ALINEO_SANDBOX_ID = sandboxId;
|
|
1297
|
-
|
|
1624
|
+
log.info("reattaching", { sandboxId });
|
|
1298
1625
|
const t1 = Date.now();
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
|
-
|
|
1306
|
-
|
|
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
|
+
}
|
|
1639
|
+
log.info("connected", { elapsed: elapsed(t1) });
|
|
1307
1640
|
const adapter = new PiAdapter();
|
|
1308
1641
|
await adapter.reattachBridge(sb);
|
|
1309
1642
|
const t2 = Date.now();
|
|
1310
1643
|
if (!opts.skipReadyCheck) await adapter.waitReady(5e3);
|
|
1311
|
-
|
|
1312
|
-
|
|
1644
|
+
log.info("bridge reattached", {
|
|
1645
|
+
elapsed: elapsed(t2),
|
|
1646
|
+
probed: !opts.skipReadyCheck
|
|
1647
|
+
});
|
|
1648
|
+
log.info("total", { elapsed: elapsed(t0) });
|
|
1313
1649
|
return {
|
|
1314
1650
|
sandbox: sb,
|
|
1315
1651
|
spec,
|
|
@@ -1324,7 +1660,7 @@ async function reattachAgent(sandboxId, opts) {
|
|
|
1324
1660
|
* `Alineo.attach()` for the public-facing docs.
|
|
1325
1661
|
*/
|
|
1326
1662
|
async function attachAgent(sandboxId, opts) {
|
|
1327
|
-
const config =
|
|
1663
|
+
const config = resolveProjectConfig(opts.config);
|
|
1328
1664
|
const client = new Sandbox({
|
|
1329
1665
|
baseUrl: config.serverUrl,
|
|
1330
1666
|
apiKey: config.apiKey,
|
|
@@ -1341,11 +1677,17 @@ async function attachAgent(sandboxId, opts) {
|
|
|
1341
1677
|
}
|
|
1342
1678
|
const env = parseShellExports(envFile);
|
|
1343
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 {}
|
|
1344
1685
|
return {
|
|
1345
1686
|
sandbox: sb,
|
|
1346
1687
|
spec: {
|
|
1347
1688
|
name: opts.name,
|
|
1348
|
-
|
|
1689
|
+
harness: "pi",
|
|
1690
|
+
model
|
|
1349
1691
|
},
|
|
1350
1692
|
env,
|
|
1351
1693
|
adapter: new PiAdapter(),
|
|
@@ -1366,30 +1708,37 @@ async function spawnChild(self, childSpecPath, opts = {}) {
|
|
|
1366
1708
|
childEnv.ALINEO_SPAWN_DEPTH = String(parentDepth - 1);
|
|
1367
1709
|
if (parentMax !== void 0) childEnv.ALINEO_MAX_AGENTS = String(parentMax - 1);
|
|
1368
1710
|
const runId = process.env.ALINEO_RUN_ID ?? crypto.randomUUID();
|
|
1711
|
+
const log = agentLog.child(process.env.ALINEO_RUN_ID ? {
|
|
1712
|
+
name: childSpec.name,
|
|
1713
|
+
runId
|
|
1714
|
+
} : { name: childSpec.name });
|
|
1369
1715
|
childEnv.ALINEO_RUN_ID = runId;
|
|
1370
1716
|
const childCredentialBindings = extractCredentialBindings(childSpec.env ?? {});
|
|
1371
1717
|
if (childCredentialBindings.some((b) => b.approval === "hold")) throw new Error(`Spawned agent "${childSpec.name}" has a credential binding with approval: "hold" — egress approval gating is not supported for spawned agents yet (no handler is wired on the spawn path). Remove approval: "hold" from the child spec.`);
|
|
1372
1718
|
const childResourceId = resolveChildResourceId(childSpec);
|
|
1373
|
-
|
|
1719
|
+
log.info("forking sandbox for spawn");
|
|
1374
1720
|
const t0 = Date.now();
|
|
1375
1721
|
const forkedSb = await self.sandbox.fork(childSpec.name, runId, {
|
|
1376
1722
|
credentialProxy: childCredentialBindings.length > 0,
|
|
1377
1723
|
resourceId: childResourceId,
|
|
1378
1724
|
teamId: childSpec.teamId
|
|
1379
1725
|
});
|
|
1380
|
-
|
|
1726
|
+
log.info("fork ready", {
|
|
1727
|
+
elapsed: elapsed(t0),
|
|
1728
|
+
sandboxId: forkedSb.sandboxId
|
|
1729
|
+
});
|
|
1381
1730
|
const adapter = new PiAdapter();
|
|
1382
1731
|
try {
|
|
1383
1732
|
for (const { name, value, binding, source } of childCredentialBindings) await forkedSb.credentials.set(name, value, binding, source);
|
|
1384
1733
|
childEnv.ALINEO_SANDBOX_ID = forkedSb.sandboxId;
|
|
1385
1734
|
await adapter.configure(forkedSb, childSpec, childEnv);
|
|
1386
|
-
|
|
1735
|
+
log.info("starting bridge");
|
|
1387
1736
|
const t1 = Date.now();
|
|
1388
1737
|
await adapter.startBridge(forkedSb, Object.keys(self.env));
|
|
1389
1738
|
await adapter.waitReady();
|
|
1390
|
-
|
|
1739
|
+
log.info("bridge ready", { elapsed: elapsed(t1) });
|
|
1391
1740
|
} catch (err) {
|
|
1392
|
-
await forkedSb.close().catch((
|
|
1741
|
+
await forkedSb.close().catch(cleanupFailed(log, { sandboxId: forkedSb.sandboxId }));
|
|
1393
1742
|
throw err;
|
|
1394
1743
|
}
|
|
1395
1744
|
return {
|
|
@@ -1425,12 +1774,13 @@ async function forkChildMemory(parentMemory, parentRef, child) {
|
|
|
1425
1774
|
try {
|
|
1426
1775
|
await parentMemory.fork(parentRef, child.resourceRef.resourceId);
|
|
1427
1776
|
} catch (err) {
|
|
1428
|
-
await child.close().catch((
|
|
1777
|
+
await child.close().catch(cleanupFailed(agentLog, { resourceId: child.resourceRef.resourceId }));
|
|
1429
1778
|
throw err;
|
|
1430
1779
|
}
|
|
1431
1780
|
}
|
|
1432
1781
|
//#endregion
|
|
1433
1782
|
//#region src/agent/session-control.ts
|
|
1783
|
+
const log = getLogger("agent");
|
|
1434
1784
|
/**
|
|
1435
1785
|
* Wrap a raw adapter stream so that every permission event is mirrored to the ledger
|
|
1436
1786
|
* (`PermissionRequested` / `PermissionResolved`) and, when `onPermission` is given, each
|
|
@@ -1452,7 +1802,12 @@ async function* instrument(a, stream, onPermission) {
|
|
|
1452
1802
|
target: ev.target,
|
|
1453
1803
|
title: ev.title
|
|
1454
1804
|
};
|
|
1455
|
-
Promise.resolve(onPermission(req)).then((decision) => a.adapter.resolvePermission(ev.requestId, decision)).catch(() => {
|
|
1805
|
+
Promise.resolve(onPermission(req)).then((decision) => a.adapter.resolvePermission(ev.requestId, decision)).catch((err) => {
|
|
1806
|
+
log.warn("onPermission handler failed", {
|
|
1807
|
+
requestId: ev.requestId,
|
|
1808
|
+
err
|
|
1809
|
+
});
|
|
1810
|
+
});
|
|
1456
1811
|
}
|
|
1457
1812
|
} else if (ev.type === "permission_resolved") a.sandbox.emit(LedgerEvent.PermissionResolved, -1, {
|
|
1458
1813
|
requestId: ev.requestId,
|
|
@@ -1578,10 +1933,13 @@ async function getLastAssistantText(a) {
|
|
|
1578
1933
|
return a.adapter.getLastAssistantText();
|
|
1579
1934
|
}
|
|
1580
1935
|
/**
|
|
1581
|
-
* List the
|
|
1582
|
-
* 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.
|
|
1583
1941
|
*/
|
|
1584
|
-
async function
|
|
1942
|
+
async function getBranchPoints(a) {
|
|
1585
1943
|
return a.adapter.getForkMessages();
|
|
1586
1944
|
}
|
|
1587
1945
|
/** List Pi's available slash commands, including extensions, prompt templates, and skills. */
|
|
@@ -1607,14 +1965,16 @@ async function getLogs(a) {
|
|
|
1607
1965
|
//#endregion
|
|
1608
1966
|
//#region src/agent/lifecycle.ts
|
|
1609
1967
|
/**
|
|
1610
|
-
*
|
|
1611
|
-
*
|
|
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.
|
|
1612
1972
|
*/
|
|
1613
|
-
async function
|
|
1973
|
+
async function branchSession(a, entryId) {
|
|
1614
1974
|
return a.adapter.fork(entryId);
|
|
1615
1975
|
}
|
|
1616
|
-
/**
|
|
1617
|
-
async function
|
|
1976
|
+
/** Branch the harness conversation at its current position. */
|
|
1977
|
+
async function duplicateSession(a) {
|
|
1618
1978
|
return a.adapter.clone();
|
|
1619
1979
|
}
|
|
1620
1980
|
/** Switch Pi to a different session file on disk. */
|
|
@@ -1661,7 +2021,7 @@ async function close(a) {
|
|
|
1661
2021
|
* while Pi manages its own tool use, file writes, and code execution inside the
|
|
1662
2022
|
* sandbox.
|
|
1663
2023
|
*
|
|
1664
|
-
* Create an agent with `Alineo.
|
|
2024
|
+
* Create an agent with `Alineo.start(spec)`. Always call `close()` when done
|
|
1665
2025
|
* to release the underlying sandbox container.
|
|
1666
2026
|
*
|
|
1667
2027
|
* @example
|
|
@@ -1669,7 +2029,7 @@ async function close(a) {
|
|
|
1669
2029
|
* import { Alineo } from "alineo";
|
|
1670
2030
|
*
|
|
1671
2031
|
* const spec = await Bun.file("./agents/my-agent.json").json();
|
|
1672
|
-
* const agent = await Alineo.
|
|
2032
|
+
* const agent = await Alineo.start(spec, { adapter });
|
|
1673
2033
|
* try {
|
|
1674
2034
|
* for await (const chunk of agent.prompt("Explain this codebase")) {
|
|
1675
2035
|
* process.stdout.write(chunk);
|
|
@@ -1699,13 +2059,13 @@ var Alineo = class Alineo {
|
|
|
1699
2059
|
/**
|
|
1700
2060
|
* Identifies the logical run this agent's sandbox belongs to — see
|
|
1701
2061
|
* `SandboxDetails.runId`. Always present; a fresh `crypto.randomUUID()` if not
|
|
1702
|
-
* explicitly passed to `
|
|
1703
|
-
* transitively, `alineo
|
|
2062
|
+
* explicitly passed to `start()`/`resume()`. A child from `.spawn()` (and
|
|
2063
|
+
* transitively, `alineo spawn`) always inherits its parent's `runId`.
|
|
1704
2064
|
*/
|
|
1705
2065
|
runId;
|
|
1706
2066
|
/**
|
|
1707
2067
|
* Optional provider-agnostic memory (`@alineo-labs/memory`), wired in via `opts.memory` on
|
|
1708
|
-
* `
|
|
2068
|
+
* `start()`/`resume()`/`attach()`. `undefined` unless explicitly configured — `alineo` never
|
|
1709
2069
|
* constructs a `Memory` on your own behalf, matching this package's "own the pipeline,
|
|
1710
2070
|
* don't assume a backend" design. `spawn()` carries the parent's `memory` (if any) onto the
|
|
1711
2071
|
* child automatically, the same way it force-computes spawn-depth rather than reading it
|
|
@@ -1727,7 +2087,7 @@ var Alineo = class Alineo {
|
|
|
1727
2087
|
/**
|
|
1728
2088
|
* Convenience `ResourceRef` scoping `.memory` calls to this agent. `resourceId`/`teamId`
|
|
1729
2089
|
* come from `AgentSpec.resourceId`/`AgentSpec.teamId` (`resourceId` defaulting to this
|
|
1730
|
-
* agent's `name` when unset) — `
|
|
2090
|
+
* agent's `name` when unset) — `start()`/`resume()`/`spawn()` also thread both into the
|
|
1731
2091
|
* ledger (see each field's own doc comment) so this getter and the agent's own episodic
|
|
1732
2092
|
* history stay consistent, including across a spawned child whose `.name` differs from its
|
|
1733
2093
|
* memory identity.
|
|
@@ -1752,7 +2112,7 @@ var Alineo = class Alineo {
|
|
|
1752
2112
|
this.sandboxId = sandbox.sandboxId;
|
|
1753
2113
|
this.name = spec.name;
|
|
1754
2114
|
this.teamId = spec.teamId;
|
|
1755
|
-
this.resourceId = spec.resourceId
|
|
2115
|
+
this.resourceId = resourceRefOf(spec).resourceId;
|
|
1756
2116
|
this.adapter = adapter;
|
|
1757
2117
|
this.env = env;
|
|
1758
2118
|
this.fromSnapshot = fromSnapshot;
|
|
@@ -1774,21 +2134,22 @@ var Alineo = class Alineo {
|
|
|
1774
2134
|
* don't need to call `validateAgentSpec()` yourself first unless you want validation errors
|
|
1775
2135
|
* to surface before any sandbox/network work starts.
|
|
1776
2136
|
*
|
|
1777
|
-
* On first
|
|
1778
|
-
* 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
|
|
1779
2139
|
* restore from that snapshot — skipping the install and starting in ~3s instead
|
|
1780
2140
|
* of ~90s.
|
|
1781
2141
|
*
|
|
1782
2142
|
* Pass `{ rebuild: true }` to force a full reinstall (e.g. after changing
|
|
1783
|
-
* the spec's `packages` or `
|
|
2143
|
+
* the spec's `packages` or `harnessVersion`).
|
|
1784
2144
|
*
|
|
1785
2145
|
* Pass `{ spawnDepth }` to override the spec's own `spawnDepth` (e.g. a
|
|
1786
2146
|
* `--depth` CLI flag) — standard flag-beats-config precedence. Same for
|
|
1787
2147
|
* `{ maxAgents }` and `--max`.
|
|
1788
2148
|
*
|
|
1789
|
-
*
|
|
2149
|
+
* Reports timing for each phase through `@alineo-labs/logger` (component `agent`, tagged with
|
|
2150
|
+
* the spec `name`). Silent by default — set `ALINEO_LOG_LEVEL=info` to see it.
|
|
1790
2151
|
*/
|
|
1791
|
-
static async
|
|
2152
|
+
static async start(spec, opts) {
|
|
1792
2153
|
const r = await loadAgent(spec, opts);
|
|
1793
2154
|
const agent = new Alineo(r.sandbox, r.spec, r.env, r.adapter, r.fromSnapshot, r.runId, r.egressGate);
|
|
1794
2155
|
agent.memory = opts.memory;
|
|
@@ -1807,20 +2168,20 @@ var Alineo = class Alineo {
|
|
|
1807
2168
|
* first and fall back to this only if it fails (e.g. the whole sandbox — not just this
|
|
1808
2169
|
* process — actually restarted).
|
|
1809
2170
|
*
|
|
1810
|
-
* @param sandboxId The sandbox ID returned by the original `Alineo.
|
|
2171
|
+
* @param sandboxId The sandbox ID returned by the original `Alineo.start()`.
|
|
1811
2172
|
* @param opts.spec An already-parsed agent spec object — skips file I/O entirely, same as
|
|
1812
|
-
* `
|
|
2173
|
+
* `start()`. Takes precedence over `opts.specPath` if both are set.
|
|
1813
2174
|
* @param opts.specPath Path to the agent spec JSON, read and validated internally. If
|
|
1814
2175
|
* neither `opts.spec` nor `opts.specPath` is set, the ledger is queried for the sandbox's
|
|
1815
2176
|
* name and the spec is read from `./agents/<name>.json` — this fallback is the one thing
|
|
1816
|
-
* `resume()` can do that `
|
|
2177
|
+
* `resume()` can do that `start()` can't, since a resumed sandbox's original spec may not be
|
|
1817
2178
|
* in memory anywhere the caller can hand it over.
|
|
1818
2179
|
*
|
|
1819
2180
|
* @example
|
|
1820
2181
|
* ```ts
|
|
1821
2182
|
* // Original process:
|
|
1822
2183
|
* const spec = await Bun.file("./agents/hello-agent.json").json();
|
|
1823
|
-
* const agent = await Alineo.
|
|
2184
|
+
* const agent = await Alineo.start(spec, { adapter });
|
|
1824
2185
|
* console.log(agent.sandboxId); // save this
|
|
1825
2186
|
* // ... process exits ...
|
|
1826
2187
|
*
|
|
@@ -1854,7 +2215,7 @@ var Alineo = class Alineo {
|
|
|
1854
2215
|
* the bridge process inside it has independently died, and this can't distinguish that from
|
|
1855
2216
|
* a slow-to-respond-but-fine bridge on its own. On failure, fall back to `Alineo.resume()`.
|
|
1856
2217
|
*
|
|
1857
|
-
* @param sandboxId The sandbox ID returned by the original `Alineo.
|
|
2218
|
+
* @param sandboxId The sandbox ID returned by the original `Alineo.start()`/`.spawn()`.
|
|
1858
2219
|
* @param opts.spec / opts.specPath Same three-way fallback as `resume()` — see its docs.
|
|
1859
2220
|
*
|
|
1860
2221
|
* @example
|
|
@@ -1878,7 +2239,7 @@ var Alineo = class Alineo {
|
|
|
1878
2239
|
* `resume()`, which kills and restarts the bridge process. Use this when you only
|
|
1879
2240
|
* need `.spawn()`/`.sandbox`, not `.prompt()`/`.bash()`.
|
|
1880
2241
|
*
|
|
1881
|
-
* The main caller is `alineo
|
|
2242
|
+
* The main caller is `alineo spawn`: it runs as a fresh CLI process started BY the
|
|
1882
2243
|
* very Pi bash-tool call it's attaching to (a master agent spawning a child from
|
|
1883
2244
|
* inside its own turn). Going through `resume()` there would `pkill` the bridge
|
|
1884
2245
|
* that's currently running the Pi process making the call — self-destructive.
|
|
@@ -1889,7 +2250,7 @@ var Alineo = class Alineo {
|
|
|
1889
2250
|
* file, which may not even exist inside this particular sandbox.
|
|
1890
2251
|
*
|
|
1891
2252
|
* When `sandboxId` matches `ALINEO_SANDBOX_ID` in this process's own env (true
|
|
1892
|
-
* self-attach, e.g. `alineo
|
|
2253
|
+
* self-attach, e.g. `alineo spawn` running from inside its own container),
|
|
1893
2254
|
* `/etc/alineo-env` is read straight off the local filesystem instead of via
|
|
1894
2255
|
* `sb.readFile()`. A self-referential exec call would need this sandbox to
|
|
1895
2256
|
* reach itself through its own externally-facing bridge IP, which Docker's
|
|
@@ -1900,7 +2261,7 @@ var Alineo = class Alineo {
|
|
|
1900
2261
|
* `opts.resources` sizes a subsequent `.spawn()`'s forked container — the
|
|
1901
2262
|
* control API doesn't echo back a running sandbox's own resource limits, so
|
|
1902
2263
|
* there's no way to discover this agent's *actual* footprint here. Defaults to
|
|
1903
|
-
* `alineo.config.json`'s `defaults.resources`, same fallback `Alineo.
|
|
2264
|
+
* `alineo.config.json`'s `defaults.resources`, same fallback `Alineo.start()` uses
|
|
1904
2265
|
* for a spec that doesn't set its own.
|
|
1905
2266
|
*/
|
|
1906
2267
|
static async attach(sandboxId, opts) {
|
|
@@ -1912,7 +2273,7 @@ var Alineo = class Alineo {
|
|
|
1912
2273
|
/**
|
|
1913
2274
|
* Fork this agent's live sandbox — filesystem, installed packages, checked-out
|
|
1914
2275
|
* state, everything currently on disk — into a brand-new independent sandbox
|
|
1915
|
-
* running its own Pi bridge, per `childSpecPath`. Unlike `Alineo.
|
|
2276
|
+
* running its own Pi bridge, per `childSpecPath`. Unlike `Alineo.start()` (always
|
|
1916
2277
|
* starts from a spec's own snapshot) or `fork()`/`clone()` below (Pi's own
|
|
1917
2278
|
* conversation-branching — same container, same bridge, new session branch),
|
|
1918
2279
|
* this is sandbox-level forking: the child sees exactly what this agent's
|
|
@@ -2041,8 +2402,8 @@ var Alineo = class Alineo {
|
|
|
2041
2402
|
* List the fork entry points available in the current session.
|
|
2042
2403
|
* Each entry has `entryId` (pass to `fork()`) and `text` (the message at that point).
|
|
2043
2404
|
*/
|
|
2044
|
-
async
|
|
2045
|
-
return
|
|
2405
|
+
async getBranchPoints() {
|
|
2406
|
+
return getBranchPoints(this);
|
|
2046
2407
|
}
|
|
2047
2408
|
/** List Pi's available slash commands, including extensions, prompt templates, and skills. */
|
|
2048
2409
|
async getCommands() {
|
|
@@ -2075,15 +2436,21 @@ var Alineo = class Alineo {
|
|
|
2075
2436
|
return exportHtml(this, outputPath);
|
|
2076
2437
|
}
|
|
2077
2438
|
/**
|
|
2078
|
-
*
|
|
2079
|
-
*
|
|
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.
|
|
2080
2447
|
*/
|
|
2081
|
-
async
|
|
2082
|
-
return
|
|
2448
|
+
async branchSession(entryId) {
|
|
2449
|
+
return branchSession(this, entryId);
|
|
2083
2450
|
}
|
|
2084
|
-
/**
|
|
2085
|
-
async
|
|
2086
|
-
return
|
|
2451
|
+
/** Branch the harness conversation at its current position. Same container, same bridge. */
|
|
2452
|
+
async duplicateSession() {
|
|
2453
|
+
return duplicateSession(this);
|
|
2087
2454
|
}
|
|
2088
2455
|
/** Switch Pi to a different session file on disk. */
|
|
2089
2456
|
async switchSession(sessionPath) {
|
|
@@ -2144,4 +2511,127 @@ async function* textOnly(stream) {
|
|
|
2144
2511
|
for await (const ev of stream) if (ev.type === "text") yield ev.text;
|
|
2145
2512
|
}
|
|
2146
2513
|
//#endregion
|
|
2147
|
-
|
|
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 };
|