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/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 { existsSync } from "fs";
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 src/config.ts
12
- const CONFIG_FILE = "alineo.config.json";
13
- const DEFAULT_CONFIG = {
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
- * Read `alineo.config.json` from the current working directory and merge it with
26
- * built-in defaults. Missing fields fall back to the defaults — the config file
27
- * is fully optional.
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
- async function readProjectConfig() {
30
- if (!existsSync(CONFIG_FILE)) return DEFAULT_CONFIG;
31
- const data = await Bun.file(CONFIG_FILE).json();
32
- return {
33
- ...DEFAULT_CONFIG,
34
- ...data,
35
- defaults: {
36
- ...DEFAULT_CONFIG.defaults,
37
- ...data.defaults ?? {},
38
- resources: {
39
- ...DEFAULT_CONFIG.defaults.resources,
40
- ...data.defaults?.resources ?? {}
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 fork --prompt` --
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
- * Runtime schema for `SetupStep`/`AgentSpec` above. Kept as a separate Zod schema rather than
95
- * generating the interfaces from it (`z.infer<>`) so the hand-written interfaces above can carry
96
- * full field-level JSDoc — TypeScript doesn't propagate comments through generic type inference,
97
- * and that documentation is load-bearing (it's what IDE hover/autocomplete shows spec authors).
98
- * If you add/change/remove a field on `AgentSpec`/`SetupStep`, update the matching schema field
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
- const CredentialEnvBindingSchema = z$1.object({
102
- credential: z$1.string({ error: "Each credential env binding must have a 'credential' string" }),
103
- host: z$1.string({ error: "Each credential env binding must have a 'host' string" }),
104
- pathPrefix: z$1.string().optional(),
105
- injection: z$1.union([z$1.object({
106
- type: z$1.literal("header"),
107
- name: z$1.string()
108
- }), z$1.object({
109
- type: z$1.literal("substitution"),
110
- placeholder: z$1.string(),
111
- in: z$1.array(z$1.enum([
112
- "path",
113
- "query",
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.cliVersion?.trim();
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
- if (spec.model) piConfig.model = spec.model;
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 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
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
- break;
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 agent CLI or rerunning
760
- * setup: cli, cliVersion, packages, and setup. Excludes env (hot-reloadable),
761
- * 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.
762
935
  */
763
936
  function computeSetupHash(spec) {
764
937
  return createHash("sha256").update(JSON.stringify({
765
- cli: spec.cli,
766
- cliVersion: spec.cliVersion ?? "latest",
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 ?? childSpec.name;
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.load()`/`Alineo.resume()`. Throws
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.load()` for the public-facing docs.
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 = await readProjectConfig();
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.load()");
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.load()");
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.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.`);
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
- console.log(`[agent] restoring from snapshot...`);
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 ?? spec.name,
1331
+ resourceId: resourceRefOf(spec).resourceId,
1088
1332
  teamId: spec.teamId
1089
1333
  });
1090
- console.log(`[agent] snapshot ready ${elapsed(t1)} (${sb.sandboxId})`);
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
- console.log(`[agent] snapshot restore failed (${reason}), rebuilding...`);
1341
+ log.warn("snapshot restore failed, rebuilding", { reason });
1095
1342
  await store.delete(spec.name);
1096
1343
  }
1097
1344
  }
1098
1345
  if (!fromSnapshot) {
1099
- console.log(`[agent] starting sandbox (${spec.name})...`);
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 ?? spec.name,
1359
+ resourceId: resourceRefOf(spec).resourceId,
1113
1360
  teamId: spec.teamId
1114
1361
  });
1115
- console.log(`[agent] sandbox ready ${elapsed(t1)} (${sb.sandboxId})`);
1362
+ log.info("sandbox ready", {
1363
+ elapsed: elapsed(t1),
1364
+ sandboxId: sb.sandboxId
1365
+ });
1116
1366
  const created = sb;
1117
1367
  try {
1118
- console.log(`[agent] installing Pi CLI...`);
1368
+ log.info("installing Pi CLI");
1119
1369
  const t2 = Date.now();
1120
1370
  await adapter.install(created, spec);
1121
- console.log(`[agent] Pi CLI ready ${elapsed(t2)}`);
1371
+ log.info("Pi CLI ready", { elapsed: elapsed(t2) });
1122
1372
  for (const step of spec.setup ?? []) {
1123
- console.log(`[agent] setup: ${step.name}...`);
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
- console.log(`[agent] setup done ${elapsed(ts)} (${step.name})`);
1377
+ log.info("setup step done", {
1378
+ step: step.name,
1379
+ elapsed: elapsed(ts)
1380
+ });
1128
1381
  }
1129
- console.log(`[agent] checkpointing...`);
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
- console.log(`[agent] checkpoint done ${elapsed(t3)}`);
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
- console.log(`[agent] starting bridge...`);
1407
+ log.info("starting bridge");
1155
1408
  const t4 = Date.now();
1156
1409
  await adapter.startBridge(sb);
1157
1410
  await adapter.waitReady();
1158
- console.log(`[agent] bridge ready ${elapsed(t4)}`);
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
- console.log(`[agent] restored snapshot didn't start (${reason}) — discarding it and rebuilding...`);
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
- console.log(`[agent] total ${elapsed(t0)}${fromSnapshot ? " (from snapshot)" : ""}`);
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 = await readProjectConfig();
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
- console.log(`[agent] reconnecting to ${sandboxId}...`);
1516
+ log.info("reconnecting", { sandboxId });
1215
1517
  const t1 = Date.now();
1216
- const sb = await client.connect(sandboxId, spec.name, {
1217
- runId,
1218
- resources: spec.resources ?? config.defaults.resources,
1219
- resourceId: spec.resourceId ?? spec.name,
1220
- teamId: spec.teamId
1221
- });
1222
- console.log(`[agent] connected ${elapsed(t1)}`);
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
- console.log(`[agent] starting bridge...`);
1535
+ log.info("starting bridge");
1228
1536
  const t2 = Date.now();
1229
1537
  await adapter.startBridge(sb);
1230
1538
  await adapter.waitReady();
1231
- console.log(`[agent] bridge ready ${elapsed(t2)}`);
1539
+ log.info("bridge ready", { elapsed: elapsed(t2) });
1232
1540
  await reconcileDroppedPermissions(opts.adapter, sb, spec.name, sandboxId);
1233
- console.log(`[agent] total ${elapsed(t0)}`);
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: "reject" },
1257
- 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"
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 = await readProjectConfig();
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
- console.log(`[agent] reattaching to ${sandboxId}...`);
1624
+ log.info("reattaching", { sandboxId });
1298
1625
  const t1 = Date.now();
1299
- const sb = await client.connect(sandboxId, spec.name, {
1300
- runId,
1301
- resourceId: spec.resourceId ?? spec.name,
1302
- teamId: spec.teamId,
1303
- resources: spec.resources ?? config.defaults.resources,
1304
- allowPaused: opts.skipReadyCheck === true
1305
- });
1306
- console.log(`[agent] connected ${elapsed(t1)}`);
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
- console.log(`[agent] bridge reattached ${elapsed(t2)}${opts.skipReadyCheck ? " (not probed)" : ""}`);
1312
- console.log(`[agent] total ${elapsed(t0)}`);
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 = await readProjectConfig();
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
- cli: "pi"
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
- console.log(`[agent] forking sandbox for spawn (${childSpec.name})...`);
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
- console.log(`[agent] fork ready ${elapsed(t0)} (${forkedSb.sandboxId})`);
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
- console.log(`[agent] starting bridge...`);
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
- console.log(`[agent] bridge ready ${elapsed(t1)}`);
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 fork entry points available in the current session.
1582
- * 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.
1583
1941
  */
1584
- async function getForkMessages(a) {
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
- * Fork Pi's session at the given entry ID, creating a new branch.
1611
- * 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.
1612
1972
  */
1613
- async function fork(a, entryId) {
1973
+ async function branchSession(a, entryId) {
1614
1974
  return a.adapter.fork(entryId);
1615
1975
  }
1616
- /** Clone the current Pi session into a new branch at the current position. */
1617
- async function clone(a) {
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.load(spec)`. Always call `close()` when done
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.load(spec, { adapter });
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 `load()`/`resume()`. A child from `.spawn()` (and
1703
- * 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`.
1704
2064
  */
1705
2065
  runId;
1706
2066
  /**
1707
2067
  * Optional provider-agnostic memory (`@alineo-labs/memory`), wired in via `opts.memory` on
1708
- * `load()`/`resume()`/`attach()`. `undefined` unless explicitly configured — `alineo` never
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) — `load()`/`resume()`/`spawn()` also thread both into the
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 ?? spec.name;
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 load the Pi CLI is installed inside a `node:22` sandbox, then
1778
- * 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
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 `cliVersion`).
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
- * Logs timing for each phase to stdout via `[agent]` prefixed lines.
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 load(spec, opts) {
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.load()`.
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
- * `load()`. Takes precedence over `opts.specPath` if both are set.
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 `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
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.load(spec, { adapter });
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.load()`/`.spawn()`.
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 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
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 fork` running from inside its own container),
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.load()` uses
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.load()` (always
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 getForkMessages() {
2045
- return getForkMessages(this);
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
- * Fork Pi's session at the given entry ID, creating a new branch.
2079
- * 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.
2080
2447
  */
2081
- async fork(entryId) {
2082
- return fork(this, entryId);
2448
+ async branchSession(entryId) {
2449
+ return branchSession(this, entryId);
2083
2450
  }
2084
- /** Clone the current Pi session into a new branch at the current position. */
2085
- async clone() {
2086
- return clone(this);
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
- 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 };