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/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 { existsSync } from "fs";
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 src/config.ts
13
- const CONFIG_FILE = "alineo.config.json";
14
- const DEFAULT_CONFIG = {
15
- serverUrl: "http://127.0.0.1:8080",
16
- apiKey: "",
17
- adapterPath: "./.alineo/ledger.db",
18
- useServerProxy: true,
19
- agentsDir: "./agents",
20
- defaults: { resources: {
21
- cpu: "1000m",
22
- memory: "1Gi"
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 `alineo.config.json` from the current working directory and merge it with
27
- * built-in defaults. Missing fields fall back to the defaults — the config file
28
- * is fully optional.
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
- async function readProjectConfig() {
31
- if (!existsSync(CONFIG_FILE)) return DEFAULT_CONFIG;
32
- const data = await Bun.file(CONFIG_FILE).json();
33
- return {
34
- ...DEFAULT_CONFIG,
35
- ...data,
36
- defaults: {
37
- ...DEFAULT_CONFIG.defaults,
38
- ...data.defaults ?? {},
39
- resources: {
40
- ...DEFAULT_CONFIG.defaults.resources,
41
- ...data.defaults?.resources ?? {}
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 fork --prompt` --
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
- * Runtime schema for `SetupStep`/`AgentSpec` above. Kept as a separate Zod schema rather than
96
- * generating the interfaces from it (`z.infer<>`) so the hand-written interfaces above can carry
97
- * full field-level JSDoc — TypeScript doesn't propagate comments through generic type inference,
98
- * and that documentation is load-bearing (it's what IDE hover/autocomplete shows spec authors).
99
- * If you add/change/remove a field on `AgentSpec`/`SetupStep`, update the matching schema field
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
- const CredentialEnvBindingSchema = z$1.object({
103
- credential: z$1.string({ error: "Each credential env binding must have a 'credential' string" }),
104
- host: z$1.string({ error: "Each credential env binding must have a 'host' string" }),
105
- pathPrefix: z$1.string().optional(),
106
- injection: z$1.union([z$1.object({
107
- type: z$1.literal("header"),
108
- name: z$1.string()
109
- }), z$1.object({
110
- type: z$1.literal("substitution"),
111
- placeholder: z$1.string(),
112
- in: z$1.array(z$1.enum([
113
- "path",
114
- "query",
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.cliVersion?.trim();
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
- if (spec.model) piConfig.model = spec.model;
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 fork` on itself, as in examples/rlm-repo-fanout -- produces zero AgentEvents for as
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
- break;
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 agent CLI or rerunning
761
- * setup: cli, cliVersion, packages, and setup. Excludes env (hot-reloadable),
762
- * model/provider (CLI flags only), and cosmetic fields.
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.cli,
767
- cliVersion: spec.cliVersion ?? "latest",
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 ?? childSpec.name;
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.load()`/`Alineo.resume()`. Throws
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.load()` for the public-facing docs.
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 = await readProjectConfig();
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.load()");
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.load()");
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.load() was called without an onEgressRequest handler.`);
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 ?? spec.name,
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 ?? spec.name,
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 = await readProjectConfig();
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
- const sb = await client.connect(sandboxId, spec.name, {
1248
- runId,
1249
- resources: spec.resources ?? config.defaults.resources,
1250
- resourceId: spec.resourceId ?? spec.name,
1251
- teamId: spec.teamId
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: "reject" },
1288
- note: "session resumed — pending approval dropped"
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 = await readProjectConfig();
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
- const sb = await client.connect(sandboxId, spec.name, {
1335
- runId,
1336
- resourceId: spec.resourceId ?? spec.name,
1337
- teamId: spec.teamId,
1338
- resources: spec.resources ?? config.defaults.resources,
1339
- allowPaused: opts.skipReadyCheck === true
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 = await readProjectConfig();
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
- cli: "pi"
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 fork entry points available in the current session.
1633
- * Each entry has `entryId` (pass to `fork()`) and `text` (the message at that point).
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 getForkMessages(a) {
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
- * Fork Pi's session at the given entry ID, creating a new branch.
1662
- * Returns the text of the forked message and whether the fork was cancelled.
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 fork(a, entryId) {
1973
+ async function branchSession(a, entryId) {
1665
1974
  return a.adapter.fork(entryId);
1666
1975
  }
1667
- /** Clone the current Pi session into a new branch at the current position. */
1668
- async function clone(a) {
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.load(spec)`. Always call `close()` when done
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.load(spec, { adapter });
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 `load()`/`resume()`. A child from `.spawn()` (and
1754
- * transitively, `alineo fork`) always inherits its parent's `runId`.
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
- * `load()`/`resume()`/`attach()`. `undefined` unless explicitly configured — `alineo` never
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) — `load()`/`resume()`/`spawn()` also thread both into the
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 ?? spec.name;
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 load the Pi CLI is installed inside a `node:22` sandbox, then
1829
- * the sandbox is checkpointed. Subsequent `load()` calls for the same spec
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 `cliVersion`).
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 load(spec, opts) {
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.load()`.
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
- * `load()`. Takes precedence over `opts.specPath` if both are set.
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 `load()` can't, since a resumed sandbox's original spec may not be
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.load(spec, { adapter });
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.load()`/`.spawn()`.
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 fork`: it runs as a fresh CLI process started BY the
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 fork` running from inside its own container),
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.load()` uses
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.load()` (always
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 getForkMessages() {
2097
- return getForkMessages(this);
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
- * Fork Pi's session at the given entry ID, creating a new branch.
2131
- * Returns the text of the forked message and whether the fork was cancelled.
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 fork(entryId) {
2134
- return fork(this, entryId);
2448
+ async branchSession(entryId) {
2449
+ return branchSession(this, entryId);
2135
2450
  }
2136
- /** Clone the current Pi session into a new branch at the current position. */
2137
- async clone() {
2138
- return clone(this);
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
- export { AgentSnapshotStore, AgentSpecValidationError, Alineo, EgressApprovalGate, PromptTimeoutError, computeSetupHash, isReadOnlyBashCommand, snapshotsPath, textOnly, validateAgentSpec };
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 };