alineo-cli 0.3.0 → 0.4.1

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,10 +1,15 @@
1
1
  #!/usr/bin/env bun
2
2
  import { installLoggerFromEnv } from "@alineo-labs/logger";
3
- import { join } from "node:path";
3
+ import { errorCodeOf } from "@alineo-labs/errors";
4
+ import { dirname, join, resolve } from "node:path";
4
5
  import { join as join$1 } from "path";
5
6
  import { homedir } from "os";
6
7
  import { existsSync } from "fs";
7
8
  import { mkdir } from "fs/promises";
9
+ import { existsSync as existsSync$1, readFileSync } from "node:fs";
10
+ import { homedir as homedir$1 } from "node:os";
11
+ import * as z$1 from "zod";
12
+ import { z } from "zod";
8
13
  //#region src/commands/registry.ts
9
14
  /**
10
15
  * Every alineo subcommand's name/group/usage/summary, plus a `run` that dynamically
@@ -19,7 +24,10 @@ import { mkdir } from "fs/promises";
19
24
  * the switch statement's actual behavior with no visual signal at all.
20
25
  *
21
26
  * Adding a command: create the command file with its own `xCommand` export (see
22
- * types.ts), then add one entry here whose `variants` matches it.
27
+ * types.ts), then add one entry here whose `variants` matches it. The name has to
28
+ * be a verb from `@alineo-labs/schema`'s `VERBS`, or one of the nouns
29
+ * `scripts/check-vocabulary.ts` allowlists — that check is what keeps this list
30
+ * and the rest of alineo's surfaces speaking the same language.
23
31
  */
24
32
  const commands = [
25
33
  {
@@ -38,7 +46,7 @@ const commands = [
38
46
  usage: "alineo add <url> [--name <n>]",
39
47
  summary: "Fetch and save an agent spec locally"
40
48
  }],
41
- run: async (argv) => (await import("./add-B6Xmz48s.mjs")).addCommand.run(argv)
49
+ run: async (argv) => (await import("./add-BdM-DRC1.mjs")).addCommand.run(argv)
42
50
  },
43
51
  {
44
52
  name: "list",
@@ -47,7 +55,7 @@ const commands = [
47
55
  usage: "alineo list",
48
56
  summary: "List saved agent specs"
49
57
  }],
50
- run: async (argv) => (await import("./list-F4RrPUBT.mjs")).listCommand.run(argv)
58
+ run: async (argv) => (await import("./list-3JgvP7S3.mjs")).listCommand.run(argv)
51
59
  },
52
60
  {
53
61
  name: "remove",
@@ -59,16 +67,16 @@ const commands = [
59
67
  run: async (argv) => (await import("./remove-B_721tl2.mjs")).removeCommand.run(argv)
60
68
  },
61
69
  {
62
- name: "spawn",
70
+ name: "start",
63
71
  group: "agent",
64
72
  variants: [{
65
- usage: "alineo spawn <spec>",
73
+ usage: "alineo start <spec>",
66
74
  summary: "Start a fresh agent sandbox, print its name, exit"
67
75
  }, {
68
- usage: "alineo spawn <spec> --prompt <msg>",
76
+ usage: "alineo start <spec> --prompt <msg>",
69
77
  summary: "Start it, send one prompt, print the reply, exit"
70
78
  }],
71
- run: async (argv) => (await import("./spawn-BRFkN-5J.mjs")).spawnCommand.run(argv)
79
+ run: async (argv) => (await import("./start-Ba4NiDWn.mjs")).startCommand.run(argv)
72
80
  },
73
81
  {
74
82
  name: "prompt",
@@ -77,16 +85,16 @@ const commands = [
77
85
  usage: "alineo prompt <sandbox-id> <msg>",
78
86
  summary: "Send one prompt to a running sandbox, print the reply"
79
87
  }],
80
- run: async (argv) => (await import("./prompt-DoeWivoE.mjs")).promptCommand.run(argv)
88
+ run: async (argv) => (await import("./prompt-DBQLJudG.mjs")).promptCommand.run(argv)
81
89
  },
82
90
  {
83
- name: "fork",
91
+ name: "spawn",
84
92
  group: "agent",
85
93
  variants: [{
86
- usage: "alineo fork <name> <child-spec>",
87
- summary: "Fork a running session's own live sandbox into a new child"
94
+ usage: "alineo spawn <parent> <child-spec>",
95
+ summary: "Spawn a child from a running session's own live sandbox"
88
96
  }],
89
- run: async (argv) => (await import("./fork-Bl-31vNc.mjs")).forkCommand.run(argv)
97
+ run: async (argv) => (await import("./spawn-I360DtxA.mjs")).spawnCommand.run(argv)
90
98
  },
91
99
  {
92
100
  name: "steer",
@@ -95,7 +103,7 @@ const commands = [
95
103
  usage: "alineo steer <sandbox-id> <message>",
96
104
  summary: "Redirect a running session — lands at its next turn boundary, not instantly"
97
105
  }],
98
- run: async (argv) => (await import("./steer-B15HpNnn.mjs")).steerCommand.run(argv)
106
+ run: async (argv) => (await import("./steer-DfVxy4oz.mjs")).steerCommand.run(argv)
99
107
  },
100
108
  {
101
109
  name: "agents",
@@ -104,16 +112,16 @@ const commands = [
104
112
  usage: "alineo agents [--json]",
105
113
  summary: "List running agent sessions"
106
114
  }],
107
- run: async (argv) => (await import("./agents-T17zA9p-.mjs")).agentsCommand.run(argv)
115
+ run: async (argv) => (await import("./agents-D01yG4rU.mjs")).agentsCommand.run(argv)
108
116
  },
109
117
  {
110
- name: "kill",
118
+ name: "stop",
111
119
  group: "agent",
112
120
  variants: [{
113
- usage: "alineo kill <sandbox-id>",
121
+ usage: "alineo stop <sandbox-id>",
114
122
  summary: "Stop a sandbox"
115
123
  }],
116
- run: async (argv) => (await import("./kill-01oM3F4x.mjs")).killCommand.run(argv)
124
+ run: async (argv) => (await import("./stop-D139QjDq.mjs")).stopCommand.run(argv)
117
125
  },
118
126
  {
119
127
  name: "logs",
@@ -122,7 +130,7 @@ const commands = [
122
130
  usage: "alineo logs <name> [--json]",
123
131
  summary: "Print ledger events for a session"
124
132
  }],
125
- run: async (argv) => (await import("./logs-CaLt2Ya0.mjs")).logsCommand.run(argv)
133
+ run: async (argv) => (await import("./logs-1y_vBes2.mjs")).logsCommand.run(argv)
126
134
  },
127
135
  {
128
136
  name: "telemetry",
@@ -145,6 +153,1340 @@ const commands = [
145
153
  }
146
154
  ];
147
155
  //#endregion
156
+ //#region src/format-error.ts
157
+ /**
158
+ * The text the CLI prints for a failure.
159
+ *
160
+ * An alineo error can carry a `hint`: the one sentence that says what to do next. The message
161
+ * says what went wrong, so it is printed first and the hint on its own line after it.
162
+ */
163
+ function formatError(err) {
164
+ const message = err instanceof Error ? err.message : String(err);
165
+ const hint = err?.hint;
166
+ return typeof hint === "string" && hint.length > 0 ? `Error: ${message}\nHint: ${hint}` : `Error: ${message}`;
167
+ }
168
+ //#endregion
169
+ //#region ../schema/dist/agent-spec-BiNRKcYr.mjs
170
+ /**
171
+ * The two lists every alineo surface derives its names from.
172
+ *
173
+ * One user meets the CLI, the SDK, the daemon's HTTP API, the MCP tools and the event
174
+ * stream. Each of those is free to pick its own spelling, and historically each did — which
175
+ * is how `spawn` came to mean "create a root agent" in the CLI and "create a child" in the
176
+ * SDK, and how `fork` came to mean three different operations.
177
+ *
178
+ * Making the vocabulary *data* is what lets CI fail a name rather than a reviewer catch it.
179
+ * The checks that consume these lists land with the surfaces they police (CLI and help
180
+ * strings, MCP tools and HTTP routes, event types); this module is only the source of truth.
181
+ */
182
+ /**
183
+ * The things alineo acts on. A name's first segment is one of these.
184
+ *
185
+ * Ordered by layer rather than alphabetically — control plane, then the agent loop, then the
186
+ * substrate, then the operator-facing objects — because that is how the surfaces group.
187
+ *
188
+ * `event`, `result` and `transcript` are the records a run leaves behind. They joined the list
189
+ * when the HTTP and MCP checks landed and found them already on the wire
190
+ * (`GET /agents/:id/transcript`, `GET /runs/:id/events`): they were vocabulary in use, just not
191
+ * written down.
192
+ *
193
+ * `provider` joined with the `SandboxProvider` interface: the thing a sandbox runs on and is
194
+ * owned by (`sandbox.created` records which one). No event or route is named after it yet; it
195
+ * is registered so the first one is not a surprise.
196
+ *
197
+ * `memory` and `fact` joined with alineod's memory routes (`GET /agents/:id/memory`,
198
+ * `POST /agents/:id/facts`): `memory` is an agent's durable working memory, `fact` one item of
199
+ * its semantic memory.
200
+ */
201
+ const SUBJECTS = [
202
+ "run",
203
+ "agent",
204
+ "sandbox",
205
+ "provider",
206
+ "session",
207
+ "turn",
208
+ "message",
209
+ "tool",
210
+ "handle",
211
+ "wait",
212
+ "inbox",
213
+ "notify",
214
+ "budget",
215
+ "exec",
216
+ "egress",
217
+ "credential",
218
+ "permission",
219
+ "workflow",
220
+ "step",
221
+ "compaction",
222
+ "retry",
223
+ "extension",
224
+ "queue",
225
+ "spec",
226
+ "environment",
227
+ "event",
228
+ "result",
229
+ "transcript",
230
+ "memory",
231
+ "fact"
232
+ ];
233
+ /**
234
+ * What alineo does to a subject. A name's second segment is one of these — in the imperative
235
+ * for a command, method, route or tool, and in the past tense for an event (`agent.spawned`).
236
+ *
237
+ * `branchSession` and `duplicateSession` are camelCase because they exist only as SDK
238
+ * methods; no route, tool or event uses them. They carry `Session` in the name on purpose:
239
+ * unqualified `branch`/`duplicate` read like sandbox operations, and they are not — both stay
240
+ * inside one container and only touch the harness conversation.
241
+ */
242
+ const VERBS = [
243
+ "start",
244
+ "spawn",
245
+ "stop",
246
+ "pause",
247
+ "resume",
248
+ "reattach",
249
+ "attach",
250
+ "prompt",
251
+ "steer",
252
+ "await",
253
+ "checkpoint",
254
+ "fork",
255
+ "branchSession",
256
+ "duplicateSession",
257
+ "add",
258
+ "list",
259
+ "remove",
260
+ "get",
261
+ "watch",
262
+ "init",
263
+ "deliver"
264
+ ];
265
+ const SUBJECT_SET = new Set(SUBJECTS);
266
+ new Set(VERBS);
267
+ function isSubject(value) {
268
+ return SUBJECT_SET.has(value);
269
+ }
270
+ /**
271
+ * Every definition, by type. Populated as a side effect of `defineEvent`, which is why the
272
+ * event files must be imported for the registry to be complete — `index.ts` imports all five.
273
+ */
274
+ const registry = /* @__PURE__ */ new Map();
275
+ /** A `type` that is well-formed but whose subject is not in `SUBJECTS`. */
276
+ const TYPE_SHAPE = /^([a-z]+)\.([a-z][a-z_]*)$/;
277
+ function defineEvent(definition) {
278
+ const match = TYPE_SHAPE.exec(definition.type);
279
+ if (!match) throw new Error(`Event type "${definition.type}" is not "<subject>.<past_tense_verb>" in lower snake case.`);
280
+ if (!isSubject(match[1])) throw new Error(`Event type "${definition.type}" has subject "${match[1]}", which is not in SUBJECTS. Add it to @alineo-labs/schema's vocabulary, or name the event after a subject that is already there.`);
281
+ const existing = registry.get(definition.type);
282
+ if (existing && existing !== definition) throw new Error(`Event type "${definition.type}" is defined twice.`);
283
+ registry.set(definition.type, definition);
284
+ return definition;
285
+ }
286
+ defineEvent({
287
+ type: "sandbox.created",
288
+ durable: true,
289
+ version: 1,
290
+ description: "A sandbox reached Running state.",
291
+ schema: z.object({
292
+ sandboxId: z.string(),
293
+ name: z.string(),
294
+ runId: z.string(),
295
+ resourceId: z.string().optional(),
296
+ teamId: z.string().optional(),
297
+ /** Set when this session came from `sb.fork()`; absent for a top-level `client.sandbox()`. */
298
+ parentSandboxId: z.string().optional(),
299
+ /**
300
+ * The sandbox provider that owns `sandboxId`. Absent on rows written before this field
301
+ * existed, and an absent value means `"opensandbox"` (the only provider there was). Readers
302
+ * apply that default; there is no migration.
303
+ */
304
+ provider: z.string().optional()
305
+ })
306
+ });
307
+ defineEvent({
308
+ type: "sandbox.closed",
309
+ durable: true,
310
+ version: 1,
311
+ description: "A sandbox was closed and its container released.",
312
+ schema: z.object({ sandboxId: z.string() })
313
+ });
314
+ defineEvent({
315
+ type: "sandbox.paused",
316
+ durable: true,
317
+ version: 1,
318
+ description: "pause() froze the container.",
319
+ schema: z.object({ sandboxId: z.string() })
320
+ });
321
+ defineEvent({
322
+ type: "sandbox.resumed",
323
+ durable: true,
324
+ version: 1,
325
+ description: "resume() restored a frozen container to Running.",
326
+ schema: z.object({ sandboxId: z.string() })
327
+ });
328
+ defineEvent({
329
+ type: "sandbox.checkpoint_created",
330
+ durable: true,
331
+ version: 1,
332
+ description: "checkpoint() captured a snapshot.",
333
+ schema: z.object({
334
+ snapshotId: z.string(),
335
+ tag: z.string().optional()
336
+ })
337
+ });
338
+ defineEvent({
339
+ type: "exec.started",
340
+ durable: true,
341
+ version: 1,
342
+ description: "An exec() or execCode() call began.",
343
+ schema: z.object({
344
+ command: z.string().optional(),
345
+ code: z.string().optional()
346
+ })
347
+ });
348
+ defineEvent({
349
+ type: "exec.output",
350
+ durable: false,
351
+ version: 1,
352
+ description: "A streaming output chunk from a running exec.",
353
+ schema: z.object({
354
+ stream: z.enum(["stdout", "stderr"]).optional(),
355
+ text: z.string()
356
+ })
357
+ });
358
+ defineEvent({
359
+ type: "exec.completed",
360
+ durable: true,
361
+ version: 1,
362
+ description: "An exec() or execCode() call finished.",
363
+ schema: z.object({
364
+ exitCode: z.number().int().optional(),
365
+ stdout: z.string().optional(),
366
+ stderr: z.string().optional(),
367
+ /** How long the command ran, in milliseconds, as the client measured it. */
368
+ durationMs: z.number().int().optional(),
369
+ /** Present and true when a signal ended the command. */
370
+ killed: z.boolean().optional(),
371
+ /** The signal, as the server reported it. Set with `killed`. */
372
+ signal: z.string().optional(),
373
+ /** Present and true when the command was killed after running for `timeoutMs`. */
374
+ timedOut: z.boolean().optional()
375
+ })
376
+ });
377
+ defineEvent({
378
+ type: "egress.rule_added",
379
+ durable: true,
380
+ version: 1,
381
+ description: "sb.egress.patch() — the exact rules handed to the sidecar, so a resume can fold a still-wanted allowance back into the new boot policy.",
382
+ schema: z.object({ rules: z.array(z.unknown()) })
383
+ });
384
+ defineEvent({
385
+ type: "egress.rule_removed",
386
+ durable: true,
387
+ version: 1,
388
+ description: "sb.egress.delete().",
389
+ schema: z.object({ targets: z.array(z.string()) })
390
+ });
391
+ defineEvent({
392
+ type: "credential.bound",
393
+ durable: true,
394
+ version: 1,
395
+ description: "sb.credentials.set()/.patch(). Binding metadata only — the credential value is never written to the ledger.",
396
+ schema: z.object({
397
+ name: z.string(),
398
+ host: z.string().optional(),
399
+ injection: z.string().optional()
400
+ })
401
+ });
402
+ defineEvent({
403
+ type: "credential.revoked",
404
+ durable: true,
405
+ version: 1,
406
+ description: "sb.credentials.remove().",
407
+ schema: z.object({ name: z.string() })
408
+ });
409
+ defineEvent({
410
+ type: "permission.requested",
411
+ durable: true,
412
+ version: 1,
413
+ description: "The permission gate paused a tool call for human approval. Metadata only — raw tool arguments can carry secrets in a bash command or a file write, and are never recorded.",
414
+ schema: z.object({
415
+ requestId: z.string(),
416
+ tool: z.string(),
417
+ target: z.string(),
418
+ title: z.string().optional()
419
+ })
420
+ });
421
+ defineEvent({
422
+ type: "permission.resolved",
423
+ durable: true,
424
+ version: 1,
425
+ description: "A permission request was answered — by a caller, a batched always/reject decision, a timeout, or a session resume dropping it.",
426
+ schema: z.object({
427
+ requestId: z.string(),
428
+ decision: z.string()
429
+ })
430
+ });
431
+ defineEvent({
432
+ type: "agent.checkpointed",
433
+ durable: true,
434
+ version: 1,
435
+ description: "A turn-level checkpoint (workspace + session-file tarball) was captured and durably stored, after the tarball itself was confirmed written — a snapshot with no event pointing at it is unreachable garbage. `snapshotRef` is the file on the host. `remoteRef` is the same tarball in object storage and is absent when no store is configured or the upload failed (`uploadError` says why). A checkpoint without `remoteRef` does not survive the loss of the host's disk.",
436
+ schema: z.object({
437
+ turn: z.number(),
438
+ snapshotRef: z.string(),
439
+ remoteRef: z.string().optional(),
440
+ uploadError: z.string().optional()
441
+ })
442
+ });
443
+ defineEvent({
444
+ type: "session.started",
445
+ durable: true,
446
+ version: 1,
447
+ description: "The harness began a session. Was `agent_start`.",
448
+ schema: z.object({})
449
+ });
450
+ defineEvent({
451
+ type: "session.ended",
452
+ durable: true,
453
+ version: 1,
454
+ description: "The harness session finished. Was `agent_end`.",
455
+ schema: z.object({ messages: z.array(z.unknown()).optional() })
456
+ });
457
+ defineEvent({
458
+ type: "turn.started",
459
+ durable: true,
460
+ version: 1,
461
+ schema: z.object({
462
+ turnIndex: z.number().int(),
463
+ timestamp: z.number()
464
+ })
465
+ });
466
+ defineEvent({
467
+ type: "turn.ended",
468
+ durable: true,
469
+ version: 1,
470
+ schema: z.object({
471
+ turnIndex: z.number().int(),
472
+ message: z.unknown().optional(),
473
+ toolResults: z.array(z.unknown()).optional()
474
+ })
475
+ });
476
+ defineEvent({
477
+ type: "tool.started",
478
+ durable: true,
479
+ version: 1,
480
+ schema: z.object({
481
+ toolCallId: z.string(),
482
+ toolName: z.string(),
483
+ args: z.unknown()
484
+ })
485
+ });
486
+ defineEvent({
487
+ type: "tool.updated",
488
+ durable: false,
489
+ version: 1,
490
+ description: "A partial tool result. Superseded by `tool.ended`.",
491
+ schema: z.object({
492
+ toolCallId: z.string(),
493
+ toolName: z.string(),
494
+ partialResult: z.unknown()
495
+ })
496
+ });
497
+ defineEvent({
498
+ type: "tool.ended",
499
+ durable: true,
500
+ version: 1,
501
+ schema: z.object({
502
+ toolCallId: z.string(),
503
+ toolName: z.string(),
504
+ result: z.unknown(),
505
+ isError: z.boolean()
506
+ })
507
+ });
508
+ defineEvent({
509
+ type: "message.started",
510
+ durable: false,
511
+ version: 1,
512
+ schema: z.object({ message: z.unknown() })
513
+ });
514
+ defineEvent({
515
+ type: "message.updated",
516
+ durable: false,
517
+ version: 1,
518
+ description: "A delta on the message being written — including a plain text chunk, which was its own `text` event before. Superseded by `message.ended`.",
519
+ schema: z.object({
520
+ message: z.unknown().optional(),
521
+ delta: z.unknown().optional(),
522
+ /** Set when the delta is plain text and nothing else. */
523
+ text: z.string().optional()
524
+ })
525
+ });
526
+ defineEvent({
527
+ type: "message.ended",
528
+ durable: false,
529
+ version: 1,
530
+ schema: z.object({ message: z.unknown() })
531
+ });
532
+ defineEvent({
533
+ type: "compaction.started",
534
+ durable: true,
535
+ version: 1,
536
+ schema: z.object({ reason: z.enum([
537
+ "manual",
538
+ "threshold",
539
+ "overflow"
540
+ ]) })
541
+ });
542
+ defineEvent({
543
+ type: "compaction.ended",
544
+ durable: true,
545
+ version: 1,
546
+ schema: z.object({
547
+ reason: z.enum([
548
+ "manual",
549
+ "threshold",
550
+ "overflow"
551
+ ]),
552
+ result: z.object({
553
+ summary: z.string(),
554
+ firstKeptEntryId: z.string(),
555
+ tokensBefore: z.number(),
556
+ estimatedTokensAfter: z.number(),
557
+ details: z.unknown()
558
+ }).nullable(),
559
+ aborted: z.boolean(),
560
+ willRetry: z.boolean()
561
+ })
562
+ });
563
+ defineEvent({
564
+ type: "retry.started",
565
+ durable: true,
566
+ version: 1,
567
+ description: "The harness is retrying a failed model call. Was `auto_retry_start`.",
568
+ schema: z.object({
569
+ attempt: z.number().int(),
570
+ maxAttempts: z.number().int(),
571
+ delayMs: z.number(),
572
+ errorMessage: z.string()
573
+ })
574
+ });
575
+ defineEvent({
576
+ type: "retry.ended",
577
+ durable: true,
578
+ version: 1,
579
+ schema: z.object({
580
+ success: z.boolean(),
581
+ attempt: z.number().int(),
582
+ finalError: z.string().optional()
583
+ })
584
+ });
585
+ defineEvent({
586
+ type: "queue.updated",
587
+ durable: false,
588
+ version: 1,
589
+ description: "The steering and follow-up queues changed. A view of current state, not a fact.",
590
+ schema: z.object({
591
+ steering: z.array(z.string()),
592
+ followUp: z.array(z.string())
593
+ })
594
+ });
595
+ defineEvent({
596
+ type: "extension.ui",
597
+ durable: false,
598
+ version: 1,
599
+ description: "An extension asked the host to show something.",
600
+ schema: z.object({
601
+ method: z.string(),
602
+ params: z.unknown(),
603
+ isDialog: z.boolean(),
604
+ requestId: z.string().optional()
605
+ })
606
+ });
607
+ defineEvent({
608
+ type: "extension.error",
609
+ durable: true,
610
+ version: 1,
611
+ schema: z.object({
612
+ extensionPath: z.string(),
613
+ event: z.string(),
614
+ error: z.string()
615
+ })
616
+ });
617
+ defineEvent({
618
+ type: "workflow.started",
619
+ durable: true,
620
+ version: 1,
621
+ description: "A workflow run began, before any step executed. Was `run_started`.",
622
+ schema: z.object({ runId: z.string().optional() })
623
+ });
624
+ defineEvent({
625
+ type: "workflow.completed",
626
+ durable: true,
627
+ version: 1,
628
+ description: "Every step finished without error.",
629
+ schema: z.object({})
630
+ });
631
+ defineEvent({
632
+ type: "workflow.failed",
633
+ durable: true,
634
+ version: 1,
635
+ description: "Rollback completed after a step failure.",
636
+ schema: z.object({ error: z.string().optional() })
637
+ });
638
+ defineEvent({
639
+ type: "step.started",
640
+ durable: true,
641
+ version: 1,
642
+ schema: z.object({ name: z.string().optional() })
643
+ });
644
+ defineEvent({
645
+ type: "step.completed",
646
+ durable: true,
647
+ version: 1,
648
+ schema: z.object({ output: z.unknown().optional() })
649
+ });
650
+ defineEvent({
651
+ type: "step.failed",
652
+ durable: true,
653
+ version: 1,
654
+ schema: z.object({ error: z.string().optional() })
655
+ });
656
+ defineEvent({
657
+ type: "step.rolled_back",
658
+ durable: true,
659
+ version: 1,
660
+ description: "A step's rollback handler completed during saga compensation.",
661
+ schema: z.object({})
662
+ });
663
+ const WaitMode = z.enum([
664
+ "all",
665
+ "any",
666
+ "quorum"
667
+ ]);
668
+ defineEvent({
669
+ type: "run.started",
670
+ durable: true,
671
+ version: 1,
672
+ description: "A swarm run was created. Was `run_started` — the name workflow also used.",
673
+ schema: z.object({
674
+ runId: z.string(),
675
+ closeWhen: z.enum(["explicit", "quiescent"]).default("explicit")
676
+ })
677
+ });
678
+ defineEvent({
679
+ type: "run.closed",
680
+ durable: true,
681
+ version: 1,
682
+ description: "The run finalized — a client deleted it (`explicit`), or it reached quiescence on its own under closeWhen: \"quiescent\". Resources are released; the ledger is kept.",
683
+ schema: z.object({
684
+ agentId: z.string().nullable(),
685
+ reason: z.enum(["explicit", "quiescent"])
686
+ })
687
+ });
688
+ defineEvent({
689
+ type: "run.quiescent",
690
+ durable: true,
691
+ version: 1,
692
+ description: "The subtree rooted at this agent went quiescent. Only tracked while someone is awaiting it. Was `subtree_quiescent`.",
693
+ schema: z.object({
694
+ agentId: z.string().nullable(),
695
+ memberCount: z.number().int(),
696
+ asOf: z.number()
697
+ })
698
+ });
699
+ defineEvent({
700
+ type: "agent.spawned",
701
+ durable: true,
702
+ version: 1,
703
+ schema: z.object({
704
+ agentId: z.string().nullable(),
705
+ parentAgentId: z.string().nullable(),
706
+ runId: z.string(),
707
+ specName: z.string(),
708
+ depth: z.number().int(),
709
+ spawnIndex: z.number().int(),
710
+ sandboxId: z.string().nullable(),
711
+ waitFor: z.array(z.string()).nullable().optional().describe("Persisted rather than left in the spec, so rehydrate() can retry a still-pending spawn instead of losing it."),
712
+ prompt: z.string().nullable().optional()
713
+ })
714
+ });
715
+ defineEvent({
716
+ type: "agent.provisioned",
717
+ durable: true,
718
+ version: 1,
719
+ description: "The sandbox exists and the bridge is up — backfills what `agent.spawned` could not know yet.",
720
+ schema: z.object({
721
+ agentId: z.string().nullable(),
722
+ sandboxId: z.string(),
723
+ /**
724
+ * The sandbox provider that owns `sandboxId`. Absent on events written before this field
725
+ * existed, which all came from OpenSandbox.
726
+ */
727
+ provider: z.string().optional()
728
+ })
729
+ });
730
+ defineEvent({
731
+ type: "agent.restored",
732
+ durable: true,
733
+ version: 1,
734
+ description: "The agent's sandbox was gone, so a fresh one replaced it. `checkpointTurn` is the turn its workspace and session were restored from, or `null` when it had no checkpoint and came back blank. Follows `agent.provisioned`, which carries the new `sandboxId`.",
735
+ schema: z.object({
736
+ agentId: z.string().nullable(),
737
+ oldSandboxId: z.string(),
738
+ checkpointTurn: z.number().int().nullable()
739
+ })
740
+ });
741
+ defineEvent({
742
+ type: "agent.state_changed",
743
+ durable: true,
744
+ version: 1,
745
+ schema: z.object({
746
+ agentId: z.string().nullable(),
747
+ from: z.string(),
748
+ to: z.string(),
749
+ reason: z.string().optional(),
750
+ pausedBy: z.enum(["operator", "cascade"]).optional().describe("On a transition to paused: whether this agent was the target, or was reached by a subtree pause.")
751
+ })
752
+ });
753
+ defineEvent({
754
+ type: "agent.steered",
755
+ durable: true,
756
+ version: 1,
757
+ schema: z.object({
758
+ agentId: z.string().nullable(),
759
+ message: z.string(),
760
+ scope: z.enum(["agent", "subtree"]).optional(),
761
+ roster: z.array(z.string()).optional(),
762
+ deliveredAs: z.enum([
763
+ "steer",
764
+ "turn",
765
+ "queued"
766
+ ]).optional()
767
+ })
768
+ });
769
+ defineEvent({
770
+ type: "agent.released",
771
+ durable: true,
772
+ version: 1,
773
+ description: "A finished agent's still-open sandbox was closed, or a fork landed after its spawn was stopped. The recorded outcome is unchanged.",
774
+ schema: z.object({
775
+ agentId: z.string().nullable(),
776
+ reason: z.string()
777
+ })
778
+ });
779
+ defineEvent({
780
+ type: "agent.ended",
781
+ durable: true,
782
+ version: 1,
783
+ schema: z.object({
784
+ agentId: z.string().nullable(),
785
+ outcome: z.string(),
786
+ endedAt: z.number(),
787
+ error: z.string().optional(),
788
+ /** A stable `ErrorCode` for `error`, when one is known. See `@alineo-labs/errors`. */
789
+ errorCode: z.string().optional()
790
+ })
791
+ });
792
+ defineEvent({
793
+ type: "handle.settled",
794
+ durable: true,
795
+ version: 1,
796
+ schema: z.object({
797
+ agentId: z.string().nullable(),
798
+ outcome: z.string(),
799
+ resultRef: z.string().nullable()
800
+ })
801
+ });
802
+ defineEvent({
803
+ type: "wait.resolved",
804
+ durable: true,
805
+ version: 1,
806
+ description: "A held spawn's waitFor resolved. A depfail or deadline outcome ends the child failed, without ever forking it.",
807
+ schema: z.object({
808
+ agentId: z.string().nullable(),
809
+ mode: WaitMode,
810
+ outcome: z.enum([
811
+ "satisfied",
812
+ "partial",
813
+ "deadline",
814
+ "depfail"
815
+ ]),
816
+ selected: z.array(z.string()),
817
+ settled: z.array(z.object({
818
+ agentId: z.string(),
819
+ outcome: z.string().nullable()
820
+ })),
821
+ pending: z.array(z.string())
822
+ })
823
+ });
824
+ defineEvent({
825
+ type: "wait.blocked",
826
+ durable: true,
827
+ version: 1,
828
+ description: "A held spawn is waiting on a paused dependency — one event per dependency. Was `wait_blocked_on_paused`.",
829
+ schema: z.object({
830
+ agentId: z.string().nullable(),
831
+ blockedOn: z.string()
832
+ })
833
+ });
834
+ defineEvent({
835
+ type: "notify.registered",
836
+ durable: true,
837
+ version: 1,
838
+ description: "This agent asked to be told when each agent in `on` finishes.",
839
+ schema: z.object({
840
+ agentId: z.string().nullable(),
841
+ on: z.array(z.string()),
842
+ wake: z.boolean()
843
+ })
844
+ });
845
+ defineEvent({
846
+ type: "inbox.queued",
847
+ durable: true,
848
+ version: 1,
849
+ description: "Something for this agent to be told — a notification, a steer waiting for it to resume, or a child needing a supervision decision.",
850
+ schema: z.object({
851
+ agentId: z.string().nullable(),
852
+ kind: z.enum([
853
+ "notification",
854
+ "steer",
855
+ "supervision"
856
+ ]),
857
+ aboutAgentId: z.string().nullable().optional(),
858
+ aboutSpec: z.string().nullable().optional(),
859
+ outcome: z.string().nullable().optional(),
860
+ resultRef: z.string().nullable().optional(),
861
+ excerpt: z.string().nullable().optional(),
862
+ again: z.boolean().optional(),
863
+ text: z.string().optional()
864
+ })
865
+ });
866
+ defineEvent({
867
+ type: "inbox.delivered",
868
+ durable: true,
869
+ version: 1,
870
+ schema: z.object({
871
+ agentId: z.string().nullable(),
872
+ seqs: z.array(z.number().int()),
873
+ as: z.enum([
874
+ "steer",
875
+ "turn",
876
+ "prompt"
877
+ ])
878
+ })
879
+ });
880
+ defineEvent({
881
+ type: "inbox.dropped",
882
+ durable: true,
883
+ version: 1,
884
+ schema: z.object({
885
+ agentId: z.string().nullable(),
886
+ seqs: z.array(z.number().int()),
887
+ reason: z.string()
888
+ })
889
+ });
890
+ defineEvent({
891
+ type: "budget.denied",
892
+ durable: true,
893
+ version: 1,
894
+ schema: z.object({
895
+ agentId: z.string().nullable(),
896
+ dimension: z.enum(["spawnDepth", "maxAgents"]),
897
+ remaining: z.number().int()
898
+ })
899
+ });
900
+ defineEvent({
901
+ type: "agent.admission_queued",
902
+ durable: true,
903
+ version: 1,
904
+ description: "No free provisioning slot was available, so the fork is held instead of run immediately. Only emitted when a real wait happens — the common uncontended case emits nothing, to keep this a signal for genuinely stuck spawns, not noise on every spawn.",
905
+ schema: z.object({
906
+ agentId: z.string().nullable(),
907
+ capacity: z.number().int()
908
+ })
909
+ });
910
+ defineEvent({
911
+ type: "agent.admission_granted",
912
+ durable: true,
913
+ version: 1,
914
+ description: "A held provisioning request got its slot and is proceeding.",
915
+ schema: z.object({ agentId: z.string().nullable() })
916
+ });
917
+ defineEvent({
918
+ type: "agent.admission_timeout",
919
+ durable: true,
920
+ version: 1,
921
+ description: "A held provisioning request never got a slot within the bound and failed loudly instead of hanging silently.",
922
+ schema: z.object({
923
+ agentId: z.string().nullable(),
924
+ waitedMs: z.number().int()
925
+ })
926
+ });
927
+ defineEvent({
928
+ type: "agent.turn_failed",
929
+ durable: true,
930
+ version: 1,
931
+ description: "A turn concluded in failure -- recorded before the failure-policy decision (settle, auto-retry, or hold) is made, so the circuit breaker's consecutive-failure count is accurate regardless of what's decided next.",
932
+ schema: z.object({
933
+ agentId: z.string().nullable(),
934
+ error: z.string(),
935
+ /** A stable `ErrorCode` for `error`, when one is known. See `@alineo-labs/errors`. */
936
+ errorCode: z.string().optional(),
937
+ consecutiveFailures: z.number().int()
938
+ })
939
+ });
940
+ defineEvent({
941
+ type: "agent.turn_retried",
942
+ durable: true,
943
+ version: 1,
944
+ description: "A turn failed with a transient model-provider error (a 429 or a 5xx) and alineod is re-sending it after a backoff. This is not a supervision failure: it does not count toward the circuit breaker. After `maxAttempts` the failure is recorded as `agent.turn_failed`.",
945
+ schema: z.object({
946
+ agentId: z.string().nullable(),
947
+ error: z.string(),
948
+ errorCode: z.string(),
949
+ /** 1-based number of this retry. */
950
+ attempt: z.number().int(),
951
+ maxAttempts: z.number().int(),
952
+ /** The wait before the turn is re-sent, in milliseconds. */
953
+ delayMs: z.number().int()
954
+ })
955
+ });
956
+ defineEvent({
957
+ type: "agent.turn_interrupted",
958
+ durable: true,
959
+ version: 1,
960
+ description: "alineod found this agent still `running` on boot — its turn died with the previous process, mid-stream, with no SDK around to report it. Recorded before the catch-up poll that follows (`rehydrate.ts`'s `wasRunning` checks), so a turn a crash interrupted carries an audit trail distinct from one that ran straight through, whatever catch-up later finds. Named under `agent`, not `turn`: `turn.*` is reserved for events the harness itself reports, and the harness has nothing to report here — the same reasoning that renamed `turn.failed` to `agent.turn_failed`.",
961
+ schema: z.object({ agentId: z.string().nullable() })
962
+ });
963
+ defineEvent({
964
+ type: "agent.supervision_needed",
965
+ durable: true,
966
+ version: 1,
967
+ description: "The agent is held (state: blocked) awaiting an operator decision: POST .../prompt to retry (optionally with corrective text), POST .../stop to give up.",
968
+ schema: z.object({
969
+ agentId: z.string().nullable(),
970
+ reason: z.enum([
971
+ "ask",
972
+ "retries-exhausted",
973
+ "circuit-tripped"
974
+ ]),
975
+ error: z.string(),
976
+ /** A stable `ErrorCode` for `error`, when one is known. See `@alineo-labs/errors`. */
977
+ errorCode: z.string().optional()
978
+ })
979
+ });
980
+ /**
981
+ * `AgentSpec` — the JSON an agent is defined by.
982
+ *
983
+ * Both the documented `interface` and the `AgentSpecSchema` that validates it are kept by
984
+ * hand, deliberately: the interface carries doc comments that `z.infer<>` would erase, and
985
+ * they are what a reader sees on hover. `agent-spec.test.ts` asserts at the type level that
986
+ * the two cannot drift apart, which buys the safety of a single source without the DX loss.
987
+ *
988
+ * `validateAgentSpec()` and `AgentSpecValidationError` stay in `@alineo-labs/agent` — they
989
+ * are behaviour, and this package has none.
990
+ *
991
+ * Moved here from `@alineo-labs/agent` so that `apps/alineod` can stop modelling it as
992
+ * `z.record(z.unknown())` and emit a real `AgentSpec` into its OpenAPI spec.
993
+ */
994
+ /** Renders an arbitrary invalid field value for an error message without risking "[object Object]". */
995
+ function describeValue(value) {
996
+ if (typeof value === "string") return value;
997
+ try {
998
+ const json = JSON.stringify(value);
999
+ if (json !== void 0) return json;
1000
+ } catch {}
1001
+ return typeof value === "object" && value !== null ? Object.prototype.toString.call(value) : String(value);
1002
+ }
1003
+ /**
1004
+ * Runtime schema for `SetupStep`/`AgentSpec` above. Kept as a separate Zod schema rather than
1005
+ * generating the interfaces from it (`z.infer<>`) so the hand-written interfaces above can carry
1006
+ * full field-level JSDoc — TypeScript doesn't propagate comments through generic type inference,
1007
+ * and that documentation is load-bearing (it's what IDE hover/autocomplete shows spec authors).
1008
+ * If you add/change/remove a field on `AgentSpec`/`SetupStep`, update the matching schema field
1009
+ * here too — `packages/agent/test/schema.test.ts` is the drift check.
1010
+ */
1011
+ const CredentialEnvBindingSchema = z$1.object({
1012
+ credential: z$1.string({ error: "Each credential env binding must have a 'credential' string" }),
1013
+ host: z$1.string({ error: "Each credential env binding must have a 'host' string" }),
1014
+ pathPrefix: z$1.string().optional(),
1015
+ injection: z$1.union([z$1.object({
1016
+ type: z$1.literal("header"),
1017
+ name: z$1.string()
1018
+ }), z$1.object({
1019
+ type: z$1.literal("substitution"),
1020
+ placeholder: z$1.string(),
1021
+ in: z$1.array(z$1.enum([
1022
+ "path",
1023
+ "query",
1024
+ "header",
1025
+ "body"
1026
+ ])).min(1)
1027
+ })]),
1028
+ approval: z$1.literal("hold").optional()
1029
+ }).loose();
1030
+ const SetupStepSchema = z$1.object({
1031
+ name: z$1.string({ error: "Each setup step must have a 'name' string" }),
1032
+ run: z$1.string({ error: "Each setup step must have a 'run' string" }),
1033
+ cwd: z$1.string().optional()
1034
+ }).loose();
1035
+ const PermissionActionSchema = z$1.enum([
1036
+ "allow",
1037
+ "ask",
1038
+ "deny",
1039
+ "rate_limit",
1040
+ "classify"
1041
+ ]);
1042
+ const PermissionRuleSchema = z$1.object({
1043
+ tool: z$1.string({ error: "Each permission rule must have a 'tool' string" }),
1044
+ pattern: z$1.string().optional(),
1045
+ action: PermissionActionSchema,
1046
+ limit: z$1.object({
1047
+ count: z$1.number().int().positive(),
1048
+ windowMs: z$1.number().int().positive()
1049
+ }).optional()
1050
+ }).loose();
1051
+ const PermissionPolicySchema = z$1.object({
1052
+ default: PermissionActionSchema.optional(),
1053
+ rules: z$1.array(PermissionRuleSchema).optional(),
1054
+ disabledTools: z$1.array(z$1.string()).optional(),
1055
+ restrictToTools: z$1.array(z$1.string()).optional()
1056
+ }).loose();
1057
+ const PermissionsSchema = z$1.union([z$1.enum([
1058
+ "auto",
1059
+ "ask",
1060
+ "readonly"
1061
+ ]), PermissionPolicySchema]);
1062
+ /** The provider a non-Pi harness runs on. A spec that names another one is wrong. */
1063
+ const NATIVE_PROVIDER = {
1064
+ "claude-code": "anthropic",
1065
+ codex: "openai"
1066
+ };
1067
+ /** The harness id inside `{ id }`, so an error names `cursor` and not `{"id":"cursor"}`. */
1068
+ function harnessIdOf(input) {
1069
+ return typeof input === "object" && input !== null && "id" in input ? input.id : input;
1070
+ }
1071
+ const HarnessIdSchema = z$1.enum([
1072
+ "pi",
1073
+ "claude-code",
1074
+ "codex"
1075
+ ], { error: (issue) => issue.input === void 0 ? "Agent spec must have a 'harness' field. Supported values: pi, claude-code, codex" : `Unsupported harness: '${describeValue(harnessIdOf(issue.input))}'. Supported values: pi, claude-code, codex` });
1076
+ 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();
1077
+ z$1.object({
1078
+ $schema: z$1.string().optional(),
1079
+ 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"),
1080
+ title: z$1.string().optional(),
1081
+ description: z$1.string().optional(),
1082
+ author: z$1.string().optional(),
1083
+ categories: z$1.array(z$1.string()).optional(),
1084
+ harness: z$1.union([HarnessIdSchema, z$1.object({
1085
+ id: HarnessIdSchema,
1086
+ version: z$1.string().optional()
1087
+ })], { error: (issue) => issue.input === void 0 ? "Agent spec must have a 'harness' field. Supported values: pi, claude-code, codex" : `Unsupported harness: '${describeValue(harnessIdOf(issue.input))}'. Supported values: pi, claude-code, codex` }),
1088
+ harnessVersion: z$1.string().optional(),
1089
+ provider: z$1.string().optional(),
1090
+ model: z$1.union([z$1.string().min(1, "Agent spec must have a 'model' string — name the model this agent runs on"), z$1.object({
1091
+ provider: z$1.string().optional(),
1092
+ id: z$1.string().min(1, "Agent spec 'model.id' must name the model this agent runs on")
1093
+ })], { error: (issue) => issue.input === void 0 ? "Agent spec must have a 'model' string — name the model this agent runs on" : "Agent spec 'model' must be a string, or an object with an 'id'" }),
1094
+ packages: z$1.array(z$1.string()).optional(),
1095
+ env: z$1.record(z$1.string(), z$1.union([z$1.string(), CredentialEnvBindingSchema])).optional(),
1096
+ resources: z$1.object({
1097
+ cpu: z$1.string(),
1098
+ memory: z$1.string(),
1099
+ gpu: z$1.string().optional()
1100
+ }).optional(),
1101
+ metadata: z$1.record(z$1.string(), z$1.string()).optional(),
1102
+ registryDependencies: z$1.array(z$1.string()).optional(),
1103
+ setup: z$1.array(SetupStepSchema).optional(),
1104
+ spawnDepth: nonNegativeIntSpecField("spawnDepth"),
1105
+ maxAgents: nonNegativeIntSpecField("maxAgents"),
1106
+ teamId: z$1.string().optional(),
1107
+ resourceId: z$1.string().optional(),
1108
+ permissions: PermissionsSchema.optional(),
1109
+ onFailure: z$1.enum([
1110
+ "ask",
1111
+ "retry",
1112
+ "fail"
1113
+ ]).optional(),
1114
+ maxRetries: nonNegativeIntSpecField("maxRetries"),
1115
+ maxConsecutiveFailures: nonNegativeIntSpecField("maxConsecutiveFailures"),
1116
+ checkpoint: z$1.boolean().optional()
1117
+ }).loose().superRefine((spec, ctx) => {
1118
+ const harnessId = typeof spec.harness === "string" ? spec.harness : spec.harness.id;
1119
+ const nested = typeof spec.harness === "string" ? void 0 : spec.harness.version;
1120
+ if (nested !== void 0 && spec.harnessVersion !== void 0 && nested !== spec.harnessVersion) ctx.addIssue({
1121
+ code: "custom",
1122
+ path: ["harnessVersion"],
1123
+ message: `'harnessVersion' (${spec.harnessVersion}) conflicts with 'harness.version' (${nested}). Set only 'harness.version'.`
1124
+ });
1125
+ const modelProvider = typeof spec.model === "string" ? void 0 : spec.model.provider;
1126
+ if (modelProvider !== void 0 && spec.provider !== void 0 && modelProvider !== spec.provider) ctx.addIssue({
1127
+ code: "custom",
1128
+ path: ["provider"],
1129
+ message: `'provider' (${spec.provider}) conflicts with 'model.provider' (${modelProvider}). Set only 'model.provider'.`
1130
+ });
1131
+ const provider = modelProvider ?? spec.provider;
1132
+ const native = NATIVE_PROVIDER[harnessId];
1133
+ if (native !== void 0 && provider !== void 0 && provider !== native) ctx.addIssue({
1134
+ code: "custom",
1135
+ path: ["model", "provider"],
1136
+ message: `The ${harnessId} harness runs on ${native} models, but the provider is '${provider}'. Remove the provider, or use the pi harness.`
1137
+ });
1138
+ });
1139
+ //#endregion
1140
+ //#region ../schema/dist/index.mjs
1141
+ /**
1142
+ * The shape of `alineo.config.json`.
1143
+ *
1144
+ * Three consumers read the same file — `packages/agent`, `packages/cli-shared` and (through
1145
+ * the Docker entrypoint) `apps/alineod` — so it cannot live in any one of them without forcing
1146
+ * the other two to depend on a package for a file none of them owns. It lived in
1147
+ * `config-shared` for that reason, which was the neutral home available at the time.
1148
+ *
1149
+ * Here now because this is the neutral home: shapes, no behaviour, and published, so a user
1150
+ * writing an `alineo.config.json` by hand can get the type from the same place the tooling
1151
+ * does. The mechanism — discovery, precedence, env overlay — stays in `config-shared`.
1152
+ *
1153
+ * Settings specific to a single consumer, such as alineod's timeouts, stay with that consumer
1154
+ * and use `defineEnv`/`loadConfig` directly.
1155
+ */
1156
+ const ProjectConfigObject = z.object({
1157
+ /**
1158
+ * Which sandbox provider to run on. Only `"opensandbox"` exists today, and it is what a file
1159
+ * without this key means, so every config written before the key existed keeps working.
1160
+ * `serverUrl`, `apiKey` and `useServerProxy` below are that provider's settings.
1161
+ */
1162
+ provider: z.string().min(1).default("opensandbox"),
1163
+ /**
1164
+ * 127.0.0.1, not "localhost" — some hosts resolve "localhost" to ::1 first, and OpenSandbox
1165
+ * typically only listens on IPv4.
1166
+ */
1167
+ serverUrl: z.string().min(1).default("http://127.0.0.1:8080"),
1168
+ /** OpenSandbox API key. Empty string for local dev with no auth. */
1169
+ apiKey: z.string().default(""),
1170
+ /**
1171
+ * Route execd and proxy traffic through the OpenSandbox server. Required when the server runs
1172
+ * in Docker (e.g. started by `alineo init`).
1173
+ */
1174
+ useServerProxy: z.boolean().default(true),
1175
+ /**
1176
+ * Anchor path used to derive the agent snapshot store location (`agent-snapshots.json` is
1177
+ * written next to it). Does not select the ledger storage adapter.
1178
+ */
1179
+ adapterPath: z.string().min(1).default("./.alineo/ledger.db"),
1180
+ /** Directory holding agent spec files. */
1181
+ agentsDir: z.string().min(1).default("./agents"),
1182
+ /**
1183
+ * Applied when an agent spec omits the field.
1184
+ *
1185
+ * `.prefault({})` rather than `.default({})`: Zod 4 uses a `default` value as-is, so
1186
+ * `.default({})` on a nested object would yield a literal `{}` and leave `cpu`/`memory`
1187
+ * undefined. `prefault` parses the value through the schema, which fills the inner defaults.
1188
+ */
1189
+ defaults: z.object({ resources: z.object({
1190
+ cpu: z.string().min(1).default("1000m"),
1191
+ memory: z.string().min(1).default("1Gi")
1192
+ }).prefault({}) }).prefault({})
1193
+ });
1194
+ /**
1195
+ * In this file `null` means "not set", exactly as the hand-written reader's `??` chain used to
1196
+ * treat it. The file is hand-editable, an interrupted write can leave `{"defaults": {"resources":
1197
+ * null}}` behind, and no field here has a meaningful null value — so a stray null falls back to
1198
+ * the built-in default instead of failing validation and taking the CLI or the daemon down.
1199
+ */
1200
+ function dropNulls(value) {
1201
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
1202
+ const out = {};
1203
+ for (const [key, inner] of Object.entries(value)) {
1204
+ if (inner === null) continue;
1205
+ out[key] = dropNulls(inner);
1206
+ }
1207
+ return out;
1208
+ }
1209
+ /** The project config schema, with nulls treated as absent. */
1210
+ const ProjectConfigSchema = z.preprocess(dropNulls, ProjectConfigObject);
1211
+ Object.freeze({
1212
+ sandbox_created: "sandbox.created",
1213
+ sandbox_closed: "sandbox.closed",
1214
+ sandbox_paused: "sandbox.paused",
1215
+ sandbox_resumed: "sandbox.resumed",
1216
+ checkpoint_created: "sandbox.checkpoint_created",
1217
+ exec_start: "exec.started",
1218
+ exec_event: "exec.output",
1219
+ exec_complete: "exec.completed",
1220
+ egress_rule_added: "egress.rule_added",
1221
+ egress_rule_removed: "egress.rule_removed",
1222
+ credential_bound: "credential.bound",
1223
+ credential_revoked: "credential.revoked",
1224
+ permission_requested: "permission.requested",
1225
+ permission_resolved: "permission.resolved",
1226
+ permission_request: "permission.requested",
1227
+ workflow_complete: "workflow.completed",
1228
+ workflow_failed: "workflow.failed",
1229
+ step_start: "step.started",
1230
+ step_complete: "step.completed",
1231
+ step_failed: "step.failed",
1232
+ step_rolled_back: "step.rolled_back",
1233
+ snapshot: "sandbox.checkpoint_created",
1234
+ agent_spawned: "agent.spawned",
1235
+ agent_provisioned: "agent.provisioned",
1236
+ agent_state_changed: "agent.state_changed",
1237
+ agent_steered: "agent.steered",
1238
+ agent_released: "agent.released",
1239
+ agent_ended: "agent.ended",
1240
+ handle_settled: "handle.settled",
1241
+ wait_resolved: "wait.resolved",
1242
+ wait_blocked_on_paused: "wait.blocked",
1243
+ inbox_queued: "inbox.queued",
1244
+ inbox_delivered: "inbox.delivered",
1245
+ inbox_dropped: "inbox.dropped",
1246
+ notify_registered: "notify.registered",
1247
+ budget_denied: "budget.denied",
1248
+ subtree_quiescent: "run.quiescent",
1249
+ agent_start: "session.started",
1250
+ agent_end: "session.ended",
1251
+ turn_start: "turn.started",
1252
+ turn_end: "turn.ended",
1253
+ tool_start: "tool.started",
1254
+ tool_update: "tool.updated",
1255
+ tool_end: "tool.ended",
1256
+ message_start: "message.started",
1257
+ message_update: "message.updated",
1258
+ message_end: "message.ended",
1259
+ text: "message.updated",
1260
+ compaction_start: "compaction.started",
1261
+ compaction_end: "compaction.ended",
1262
+ auto_retry_start: "retry.started",
1263
+ auto_retry_end: "retry.ended",
1264
+ queue_update: "queue.updated",
1265
+ extension_ui: "extension.ui",
1266
+ extension_error: "extension.error"
1267
+ });
1268
+ //#endregion
1269
+ //#region ../config-shared/dist/index.mjs
1270
+ /** The file name every alineo project config uses. */
1271
+ const PROJECT_CONFIG_FILE = "alineo.config.json";
1272
+ /**
1273
+ * Walk up from `startDir` looking for `alineo.config.json`.
1274
+ *
1275
+ * Before this existed, `packages/agent` only ever checked `process.cwd()`, so running a script
1276
+ * from a subdirectory silently fell back to built-in defaults — a wrong `serverUrl` looked
1277
+ * exactly like no config at all.
1278
+ *
1279
+ * The walk is **bounded**, which matters as much as the walk itself: an unbounded search would
1280
+ * let an unrelated `alineo.config.json` several levels up configure a run. It stops after
1281
+ * examining:
1282
+ *
1283
+ * - a directory containing `.git` (the project boundary),
1284
+ * - the user's home directory (global config is a separate, explicit source), or
1285
+ * - the filesystem root.
1286
+ *
1287
+ * The stop directory is itself checked before the walk ends, so a config file sitting next to
1288
+ * `.git` is still found.
1289
+ */
1290
+ function findProjectConfig(startDir = process.cwd()) {
1291
+ const home = resolve(homedir$1());
1292
+ let dir = resolve(startDir);
1293
+ for (;;) {
1294
+ const candidate = join(dir, PROJECT_CONFIG_FILE);
1295
+ if (existsSync$1(candidate)) return candidate;
1296
+ if (existsSync$1(join(dir, ".git"))) return null;
1297
+ if (dir === home) return null;
1298
+ const parent = dirname(dir);
1299
+ if (parent === dir) return null;
1300
+ dir = parent;
1301
+ }
1302
+ }
1303
+ /** Absolute path of the user-level config, `~/.config/alineo/config.json`. */
1304
+ function globalConfigPath$1() {
1305
+ return join(homedir$1(), ".config", "alineo", "config.json");
1306
+ }
1307
+ /**
1308
+ * Read and JSON-parse a config file, or return `null` when it isn't there.
1309
+ * A file that exists but is malformed throws — a typo in config should be loud, not silently
1310
+ * ignored in favour of defaults.
1311
+ */
1312
+ function readJsonFile(path) {
1313
+ if (!existsSync$1(path)) return null;
1314
+ const raw = readFileSync(path, "utf8");
1315
+ try {
1316
+ return JSON.parse(raw);
1317
+ } catch (err) {
1318
+ const message = err instanceof Error ? err.message : String(err);
1319
+ throw new Error(`${path} is not valid JSON: ${message}`);
1320
+ }
1321
+ }
1322
+ function isPlainObject(value) {
1323
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
1324
+ const proto = Object.getPrototypeOf(value);
1325
+ return proto === Object.prototype || proto === null;
1326
+ }
1327
+ /**
1328
+ * Merge config sources, lowest precedence first. Plain objects merge key by key; everything
1329
+ * else (arrays, strings, numbers) is replaced wholesale by the later source.
1330
+ *
1331
+ * `undefined` never overwrites — an absent key in a higher-precedence source leaves the lower
1332
+ * one intact, which is what makes "env var not set" mean "don't override" rather than "clear".
1333
+ * An explicit `null` *does* overwrite, so a config file can blank a value on purpose.
1334
+ */
1335
+ function mergeDeep(...sources) {
1336
+ let result = void 0;
1337
+ for (const source of sources) {
1338
+ if (source === void 0) continue;
1339
+ if (isPlainObject(source) && isPlainObject(result)) {
1340
+ const merged = { ...result };
1341
+ for (const [key, value] of Object.entries(source)) {
1342
+ if (value === void 0) continue;
1343
+ merged[key] = key in merged ? mergeDeep(merged[key], value) : value;
1344
+ }
1345
+ result = merged;
1346
+ } else result = source;
1347
+ }
1348
+ return result;
1349
+ }
1350
+ /**
1351
+ * Freeze an object and everything reachable from it, so a resolved config can't be mutated
1352
+ * after validation. Cycles are impossible in JSON-derived data, so no seen-set is needed.
1353
+ */
1354
+ function deepFreeze(value) {
1355
+ if (value === null || typeof value !== "object") return value;
1356
+ if (Object.isFrozen(value)) return value;
1357
+ Object.freeze(value);
1358
+ for (const key of Object.getOwnPropertyNames(value)) deepFreeze(value[key]);
1359
+ return value;
1360
+ }
1361
+ /** Env var holding a whole config document inline, as JSON. */
1362
+ const CONFIG_CONTENT_ENV = "ALINEO_CONFIG_CONTENT";
1363
+ /**
1364
+ * Resolve configuration from every source, lowest precedence first:
1365
+ *
1366
+ * ```
1367
+ * schema defaults
1368
+ * < ~/.config/alineo/config.json (user)
1369
+ * < alineo.config.json (project — found by bounded walk-up)
1370
+ * < ALINEO_CONFIG_CONTENT (inline JSON)
1371
+ * < ALINEO_* env vars (ops)
1372
+ * < overrides (flags / explicit call-site object)
1373
+ * ```
1374
+ *
1375
+ * Validated once, then deep-frozen. **This function is pure with respect to module state** —
1376
+ * nothing is cached here and there is no installed singleton, so two bundled copies of this
1377
+ * package cannot drift apart. Callers hold the result for as long as they need it.
1378
+ */
1379
+ function loadConfigWithSources(options) {
1380
+ const { schema, cwd = process.cwd(), env = process.env, fromEnv, overrides, globalPath = globalConfigPath$1(), discover = true, label = "config" } = options;
1381
+ const sources = {
1382
+ globalFile: null,
1383
+ projectFile: null,
1384
+ inlineEnv: false,
1385
+ envVars: false,
1386
+ overrides: overrides !== void 0
1387
+ };
1388
+ const layers = [];
1389
+ if (discover) {
1390
+ if (globalPath) {
1391
+ const globalData = readJsonFile(globalPath);
1392
+ if (globalData !== null) {
1393
+ layers.push(globalData);
1394
+ sources.globalFile = globalPath;
1395
+ }
1396
+ }
1397
+ const projectFile = findProjectConfig(cwd);
1398
+ if (projectFile) {
1399
+ const projectData = readJsonFile(projectFile);
1400
+ if (projectData !== null) {
1401
+ layers.push(projectData);
1402
+ sources.projectFile = projectFile;
1403
+ }
1404
+ }
1405
+ const inline = env[CONFIG_CONTENT_ENV];
1406
+ if (inline !== void 0 && inline.trim() !== "") {
1407
+ try {
1408
+ layers.push(JSON.parse(inline));
1409
+ } catch (err) {
1410
+ const message = err instanceof Error ? err.message : String(err);
1411
+ throw new Error(`${CONFIG_CONTENT_ENV} is not valid JSON: ${message}`);
1412
+ }
1413
+ sources.inlineEnv = true;
1414
+ }
1415
+ if (fromEnv) {
1416
+ const fromEnvData = fromEnv(env);
1417
+ if (fromEnvData !== void 0) {
1418
+ layers.push(fromEnvData);
1419
+ sources.envVars = true;
1420
+ }
1421
+ }
1422
+ }
1423
+ if (overrides !== void 0) layers.push(overrides);
1424
+ const merged = layers.length > 0 ? mergeDeep(...layers) : {};
1425
+ const parsed = schema.safeParse(merged ?? {});
1426
+ if (!parsed.success) {
1427
+ const details = parsed.error.issues.map((issue) => {
1428
+ return ` ${issue.path.length > 0 ? issue.path.join(".") : "(root)"}: ${issue.message}`;
1429
+ }).join("\n");
1430
+ const from = describeSources(sources);
1431
+ throw new Error(`Invalid ${label}${from}:\n${details}`);
1432
+ }
1433
+ return {
1434
+ config: deepFreeze(parsed.data),
1435
+ sources
1436
+ };
1437
+ }
1438
+ /** `loadConfigWithSources` without the provenance — the common case. */
1439
+ function loadConfig(options) {
1440
+ return loadConfigWithSources(options).config;
1441
+ }
1442
+ function describeSources(sources) {
1443
+ const parts = [];
1444
+ if (sources.globalFile) parts.push(sources.globalFile);
1445
+ if (sources.projectFile) parts.push(sources.projectFile);
1446
+ if (sources.inlineEnv) parts.push(CONFIG_CONTENT_ENV);
1447
+ if (sources.envVars) parts.push("environment");
1448
+ if (sources.overrides) parts.push("explicit options");
1449
+ return parts.length > 0 ? ` (from ${parts.join(", ")})` : "";
1450
+ }
1451
+ function parseBoolean(raw, name) {
1452
+ const value = raw.trim().toLowerCase();
1453
+ if ([
1454
+ "true",
1455
+ "1",
1456
+ "yes",
1457
+ "on"
1458
+ ].includes(value)) return true;
1459
+ if ([
1460
+ "false",
1461
+ "0",
1462
+ "no",
1463
+ "off"
1464
+ ].includes(value)) return false;
1465
+ throw new Error(`${name}=${JSON.stringify(raw)} is not a boolean (use true or false)`);
1466
+ }
1467
+ /**
1468
+ * Project-config fields settable from the environment. These are what
1469
+ * `apps/alineod/docker-entrypoint.sh` writes into a generated config file before starting the
1470
+ * server; reading them directly means the container no longer has to write a file at all.
1471
+ */
1472
+ function projectConfigFromEnv(env) {
1473
+ const out = {};
1474
+ if (env.ALINEO_PROVIDER !== void 0) out.provider = env.ALINEO_PROVIDER;
1475
+ if (env.ALINEO_SERVER_URL !== void 0) out.serverUrl = env.ALINEO_SERVER_URL;
1476
+ if (env.ALINEO_API_KEY !== void 0) out.apiKey = env.ALINEO_API_KEY;
1477
+ if (env.ALINEO_USE_SERVER_PROXY !== void 0) out.useServerProxy = parseBoolean(env.ALINEO_USE_SERVER_PROXY, "ALINEO_USE_SERVER_PROXY");
1478
+ return Object.keys(out).length > 0 ? out : void 0;
1479
+ }
1480
+ /** Resolve `alineo.config.json` from every source. Validated once, then frozen. */
1481
+ function loadProjectConfig(options = {}) {
1482
+ return loadConfig({
1483
+ schema: ProjectConfigSchema,
1484
+ fromEnv: projectConfigFromEnv,
1485
+ label: "alineo config",
1486
+ ...options
1487
+ });
1488
+ }
1489
+ //#endregion
148
1490
  //#region ../cli-shared/dist/index.mjs
149
1491
  async function spawn(cmd) {
150
1492
  let proc;
@@ -212,6 +1554,20 @@ async function removeContainer(name) {
212
1554
  ]);
213
1555
  if (!ok) throw new Error(`Failed to remove container '${name}': ${stderr.trim()}`);
214
1556
  }
1557
+ /**
1558
+ * Set a container's restart policy in place (`docker update`, no recreate). Used so containers
1559
+ * created before `init` started passing `--restart` still come back after a reboot.
1560
+ */
1561
+ async function setRestartPolicy(name, policy) {
1562
+ const { ok, stderr } = await spawn([
1563
+ "docker",
1564
+ "update",
1565
+ "--restart",
1566
+ policy,
1567
+ name
1568
+ ]);
1569
+ if (!ok) throw new Error(`Failed to set restart policy on '${name}': ${stderr.trim()}`);
1570
+ }
215
1571
  async function runContainer(args, label = "container") {
216
1572
  const { ok, stderr } = await spawn([
217
1573
  "docker",
@@ -256,53 +1612,42 @@ async function isReachable(url, isHealthy, timeoutMs = 1e4) {
256
1612
  }
257
1613
  }
258
1614
  const CONFIG_DIR = ".alineo";
259
- const CONFIG_FILE = "alineo.config.json";
260
1615
  function configPath() {
261
- return CONFIG_FILE;
1616
+ return PROJECT_CONFIG_FILE;
262
1617
  }
263
1618
  function globalConfigPath() {
264
1619
  return join$1(serverConfigDir(), "config.json");
265
1620
  }
266
- function fillDefaults(data) {
267
- return {
268
- serverUrl: data.serverUrl ?? "http://127.0.0.1:8080",
269
- useServerProxy: data.useServerProxy ?? true,
270
- apiKey: data.apiKey ?? "",
271
- adapterPath: data.adapterPath ?? "./.alineo/ledger.db",
272
- agentsDir: data.agentsDir ?? "./agents",
273
- defaults: { resources: {
274
- cpu: data.defaults?.resources?.cpu ?? "1000m",
275
- memory: data.defaults?.resources?.memory ?? "1Gi"
276
- } }
277
- };
278
- }
279
1621
  /**
280
- * Resolves, in order: a project-local `alineo.config.json` (written by `alineo init`
281
- * for repos that want their own agents dir / ledger), then a global
282
- * `~/.config/alineo/config.json`. If neither exists yet, bootstraps the global
283
- * one so a fresh `bunx alineo-cli` works without requiring `init` in every directory.
1622
+ * Resolve the CLI's configuration.
1623
+ *
1624
+ * Sources are merged lowest-first — `~/.config/alineo/config.json`, then the nearest
1625
+ * `alineo.config.json` (found by walking up from the working directory), then `ALINEO_*`
1626
+ * environment variables. Two things changed when this moved onto `@alineo-labs/config-shared`:
1627
+ * a project config is now found from a subdirectory rather than only from the exact working
1628
+ * directory, and a global config no longer disappears entirely just because a project config
1629
+ * exists — the project file overrides key by key.
1630
+ *
1631
+ * When neither file exists, the global one is bootstrapped so a fresh `bunx alineo-cli` works
1632
+ * without an `init` in every directory.
284
1633
  */
285
1634
  async function readConfig() {
286
- const localFile = Bun.file(configPath());
287
- if (await localFile.exists()) return fillDefaults(await localFile.json());
1635
+ const hasProject = findProjectConfig() !== null;
288
1636
  const globalPath = globalConfigPath();
289
- const globalFile = Bun.file(globalPath);
290
- if (await globalFile.exists()) return fillDefaults(await globalFile.json());
291
- const dir = serverConfigDir();
292
- if (!existsSync(dir)) await mkdir(dir, { recursive: true });
293
- const config = {
294
- serverUrl: "http://127.0.0.1:8080",
295
- useServerProxy: true,
296
- apiKey: "",
297
- adapterPath: join$1(dir, "ledger.db"),
298
- agentsDir: join$1(dir, "agents"),
299
- defaults: { resources: {
300
- cpu: "1000m",
301
- memory: "1Gi"
302
- } }
303
- };
304
- await Bun.write(globalPath, JSON.stringify(config, null, 2) + "\n");
305
- return config;
1637
+ if (!hasProject && !existsSync(globalPath)) {
1638
+ const dir = serverConfigDir();
1639
+ if (!existsSync(dir)) await mkdir(dir, { recursive: true });
1640
+ const bootstrapped = loadProjectConfig({
1641
+ discover: false,
1642
+ overrides: {
1643
+ adapterPath: join$1(dir, "ledger.db"),
1644
+ agentsDir: join$1(dir, "agents")
1645
+ }
1646
+ });
1647
+ await Bun.write(globalPath, JSON.stringify(bootstrapped, null, 2) + "\n");
1648
+ return bootstrapped;
1649
+ }
1650
+ return loadProjectConfig({ globalPath });
306
1651
  }
307
1652
  async function writeConfig(config) {
308
1653
  if (!existsSync(CONFIG_DIR)) await mkdir(CONFIG_DIR, { recursive: true });
@@ -322,7 +1667,7 @@ function serverConfigPath() {
322
1667
  * only as good as where the db file actually lives: without this mount, it sits in the
323
1668
  * `alineo-opensandbox` container's own writable layer, so restart is fine but any time the
324
1669
  * container itself is recreated (host reboot with no restart policy, `docker system prune`,
325
- * a stray `docker rm`) silently loses every cached snapshot record — every `Alineo.load()`
1670
+ * a stray `docker rm`) silently loses every cached snapshot record — every `Alineo.start()`
326
1671
  * snapshot fast path pays a full cold rebuild next time, indistinguishable from a genuinely
327
1672
  * changed spec (see issue #20). Bind-mounting this directory makes that data outlive the
328
1673
  * container's own lifecycle, matching OpenSandbox's own intent.
@@ -331,13 +1676,45 @@ function serverDataDir() {
331
1676
  return join$1(serverConfigDir(), "opensandbox-data");
332
1677
  }
333
1678
  /**
334
- * v1.0.19 (the previous pin) predates cached bwrap-archive support, so every sandbox logged
335
- * "bwrap archive not cached for linux/amd64 -- isolation will be unavailable" and isolation
336
- * sessions (and anything that depends on them, e.g. pause()/resume()) hung indefinitely
337
- * instead of failing cleanly. OpenSandbox's own docs: >=v1.0.20 has base isolation-session
338
- * support, >=v1.0.21 is recommended for full functionality -- the "v1.1.0+" the warning
339
- * message itself suggests does not exist as a published tag. v1.0.22 is the latest.
1679
+ * The execd image the generated server config pins.
1680
+ *
1681
+ * `release-1.1.1`, not `v1.0.22`. Two reasons, both measured:
1682
+ *
1683
+ * - **Newlines.** `v1.0.22` emits one stdout event per line with the newline stripped, so
1684
+ * `ExecResult.stdout` of `echo one; echo two` was `"onetwo"`. From `release-1.1.1` the event
1685
+ * text keeps its newline (`"one\n"`), which is what `ExecHandle` assumes when it joins events.
1686
+ * `tests/contract` fails three exec cases on `v1.0.22` and passes all twenty on `release-1.1.1`.
1687
+ * - **Post-completion delay.** `/command` holds the stream open for 1.00 s after
1688
+ * `execution_complete` on `v1.0.22` and 0.20 s from 1.1.1 (opensandbox-group/OpenSandbox#1277).
1689
+ *
1690
+ * History: v1.0.19 predates cached bwrap-archive support, so every sandbox logged "bwrap archive
1691
+ * not cached for linux/amd64 -- isolation will be unavailable" and isolation sessions (and
1692
+ * anything that depends on them, e.g. pause()/resume()) hung instead of failing cleanly.
1693
+ *
1694
+ * Tags are `v1.0.x` up to v1.0.22 and `release-1.x.y` from 1.1.1. Re-run `tests/contract`
1695
+ * against a server on the new tag before changing this.
1696
+ */
1697
+ const EXECD_IMAGE = "opensandbox/execd:release-1.1.1";
1698
+ /**
1699
+ * Where the OpenSandbox server, running in its own container, reaches the ports it publishes on
1700
+ * the host (`[docker].host_ip`). Without it the server falls back to `127.0.0.1` — its own
1701
+ * loopback — so the readiness probe for an egress sidecar gets "connection refused" from a
1702
+ * sidecar that is healthy, and every sandbox with a `networkPolicy` fails to start
1703
+ * ("Egress sidecar did not become ready within 30s"). `init` adds
1704
+ * `--add-host host.docker.internal:host-gateway` to the container so the name resolves on native
1705
+ * Linux Docker as well as Docker Desktop.
1706
+ */
1707
+ const DOCKER_HOST_IP = "host.docker.internal";
1708
+ /**
1709
+ * Adds `host_ip` to an existing `server.toml` that has none, leaving everything else (including
1710
+ * hand edits) alone. Returns `null` when nothing needs to change: a `host_ip` is already set, or
1711
+ * there is no `[docker]` table to put it in.
340
1712
  */
1713
+ function withDockerHostIp(toml) {
1714
+ if (/^host_ip\s*=/m.test(toml)) return null;
1715
+ if (!/^\[docker\]/m.test(toml)) return null;
1716
+ return toml.replace(/^\[docker\][^\n]*\n/m, (header) => `${header}host_ip = "${DOCKER_HOST_IP}"\n`);
1717
+ }
341
1718
  /**
342
1719
  * `egress.image`/`egress.mode` are configured unconditionally, not opt-in. Per OpenSandbox's
343
1720
  * own control flow, a configured `egress.image` is inert for any sandbox created without a
@@ -356,10 +1733,11 @@ eip = "${eip}"
356
1733
 
357
1734
  [runtime]
358
1735
  type = "docker"
359
- execd_image = "opensandbox/execd:v1.0.22"
1736
+ execd_image = "${EXECD_IMAGE}"
360
1737
 
361
1738
  [docker]
362
1739
  network_mode = "bridge"
1740
+ host_ip = "${DOCKER_HOST_IP}"
363
1741
 
364
1742
  [store]
365
1743
  type = "sqlite"
@@ -375,7 +1753,7 @@ mode = "dns+nft"
375
1753
  * `envMap` in earendil-works/pi's `packages/ai/src/env-api-keys.ts` (plus Anthropic's three,
376
1754
  * handled separately there). An `AgentSpec`'s env map (`{ NVIDIA_API_KEY: "${NVIDIA_API_KEY}" }`,
377
1755
  * see `packages/agent/src/schema.ts`) is resolved from `process.env` inside whatever process
378
- * calls `Alineo.load()`/`.spawn()` — for a swarm run through alineod, that's alineod's own
1756
+ * calls `Alineo.start()`/`.spawn()` — for a swarm run through alineod, that's alineod's own
379
1757
  * container. `alineo init` forwards whichever of these are set in the operator's shell into
380
1758
  * that container so any Pi-supported model works, not just NVIDIA's free tier.
381
1759
  *
@@ -426,7 +1804,7 @@ const PI_MODEL_API_KEY_ENV_VARS = [
426
1804
  "COPILOT_GITHUB_TOKEN"
427
1805
  ];
428
1806
  /**
429
- * `alineo init` / `alineo_init` — starts OpenSandbox + alineod locally via Docker and writes
1807
+ * `alineo init` / `init` — starts OpenSandbox + alineod locally via Docker and writes
430
1808
  * `alineo.config.json`. Shared verbatim by `alineo-cli` (`packages/cli/src/commands/init.ts`,
431
1809
  * which logs to stdout) and `alineo-mcp` (`packages/mcp/src/init.ts`, which collects a log array
432
1810
  * instead — an MCP stdio server's stdout is the JSON-RPC channel, so tool handlers must never
@@ -434,6 +1812,7 @@ const PI_MODEL_API_KEY_ENV_VARS = [
434
1812
  * hand-copied files did before.
435
1813
  */
436
1814
  const OPENSANDBOX_CONTAINER_NAME = "alineo-opensandbox";
1815
+ const OPENSANDBOX_IMAGE = "opensandbox/server:latest";
437
1816
  const SERVER_URL = "http://127.0.0.1:8080";
438
1817
  const ALINEOD_CONTAINER_NAME = "alineo-alineod";
439
1818
  const ALINEOD_IMAGE = "ghcr.io/drejt/alineod:latest";
@@ -441,6 +1820,13 @@ const ALINEOD_URL = "http://127.0.0.1:4600";
441
1820
  const isAlineodHealthy = (body) => body?.ok === true;
442
1821
  const HOST_DOCKER_INTERNAL_SERVER_URL = "http://host.docker.internal:8080";
443
1822
  /**
1823
+ * Both containers come back after a reboot or a Docker daemon restart. Without this, a host
1824
+ * reboot left OpenSandbox down, so nothing worked until someone ran `init` again — and alineod's
1825
+ * crash recovery only helps if something restarts alineod. `unless-stopped` rather than
1826
+ * `always`, so a deliberate `docker stop` sticks.
1827
+ */
1828
+ const RESTART_ARGS = ["--restart", "unless-stopped"];
1829
+ /**
444
1830
  * `--network host` (which makes alineod see `127.0.0.1` exactly as the host does, matching
445
1831
  * OpenSandbox's configured `eip` — see `ensureAlineod`'s doc comment) only works out of the box
446
1832
  * on native Linux Docker. Docker Desktop for Windows/Mac ships it behind an opt-in "Enable host
@@ -459,8 +1845,14 @@ async function runInit(log) {
459
1845
  log("Checking Docker...");
460
1846
  await checkDocker();
461
1847
  const openSandboxConfigChanged = await ensureServerConfig();
1848
+ const hostIpAdded = await ensureServerHostIp();
462
1849
  await ensureServerDataDir();
463
- const state = await getContainerState(OPENSANDBOX_CONTAINER_NAME);
1850
+ let state = await getContainerState(OPENSANDBOX_CONTAINER_NAME);
1851
+ if (hostIpAdded && state !== "missing") {
1852
+ log("OpenSandbox config gained host_ip — recreating the container to match...");
1853
+ await removeContainer(OPENSANDBOX_CONTAINER_NAME);
1854
+ state = "missing";
1855
+ }
464
1856
  if (state === "running") {
465
1857
  if (openSandboxConfigChanged) {
466
1858
  log("OpenSandbox networking config changed — restarting to apply it...");
@@ -474,13 +1866,18 @@ async function runInit(log) {
474
1866
  log("Waiting for OpenSandbox to be ready...");
475
1867
  await pollHealth(`${SERVER_URL}/health`);
476
1868
  } else {
1869
+ log(`Pulling ${OPENSANDBOX_IMAGE}...`);
1870
+ await pullImage(OPENSANDBOX_IMAGE);
477
1871
  log("Starting OpenSandbox in Docker...");
478
1872
  await runContainer([
479
1873
  "-d",
480
1874
  "--name",
481
1875
  OPENSANDBOX_CONTAINER_NAME,
1876
+ ...RESTART_ARGS,
482
1877
  "-p",
483
1878
  "8080:8080",
1879
+ "--add-host",
1880
+ "host.docker.internal:host-gateway",
484
1881
  "-v",
485
1882
  "/var/run/docker.sock:/var/run/docker.sock",
486
1883
  "-v",
@@ -491,12 +1888,14 @@ async function runInit(log) {
491
1888
  "SANDBOX_CONFIG_PATH=/etc/opensandbox/config.toml",
492
1889
  "-e",
493
1890
  "OPENSANDBOX_INSECURE_SERVER=YES",
494
- "opensandbox/server:latest"
1891
+ OPENSANDBOX_IMAGE
495
1892
  ], "OpenSandbox container");
496
1893
  log("Waiting for OpenSandbox to be ready...");
497
1894
  await pollHealth(`${SERVER_URL}/health`);
498
1895
  }
499
1896
  await ensureAlineod(log, openSandboxConfigChanged);
1897
+ await setRestartPolicy(OPENSANDBOX_CONTAINER_NAME, "unless-stopped");
1898
+ await setRestartPolicy(ALINEOD_CONTAINER_NAME, "unless-stopped");
500
1899
  await ensureProjectConfig(log);
501
1900
  log(`OpenSandbox running at ${SERVER_URL}, alineod running at ${ALINEOD_URL} — ready.`);
502
1901
  return {
@@ -579,6 +1978,7 @@ function startAlineodContainer(useHostNetworking, modelKeyArgs) {
579
1978
  "-d",
580
1979
  "--name",
581
1980
  ALINEOD_CONTAINER_NAME,
1981
+ ...RESTART_ARGS,
582
1982
  ...networkArgs,
583
1983
  "-e",
584
1984
  `ALINEO_SERVER_URL=${alineodServerUrl}`,
@@ -619,6 +2019,17 @@ async function ensureServerEip(eip) {
619
2019
  return true;
620
2020
  }
621
2021
  /**
2022
+ * Adds `[docker].host_ip` to a `server.toml` written before `init` set it (see `DOCKER_HOST_IP`).
2023
+ * A fresh file already has it from `serverConfigContent`. Returns whether the file changed.
2024
+ */
2025
+ async function ensureServerHostIp() {
2026
+ const path = serverConfigPath();
2027
+ const updated = withDockerHostIp(await Bun.file(path).text());
2028
+ if (updated === null) return false;
2029
+ await Bun.write(path, updated);
2030
+ return true;
2031
+ }
2032
+ /**
622
2033
  * Host-side half of the `serverDataDir()` bind mount. `docker run -v` would auto-create
623
2034
  * a missing host path anyway, but doing it explicitly here matches `ensureServerConfig()`'s
624
2035
  * pattern and keeps directory creation in one place rather than relying on Docker's
@@ -631,6 +2042,7 @@ async function ensureServerDataDir() {
631
2042
  async function ensureProjectConfig(log) {
632
2043
  if (!existsSync(configPath())) {
633
2044
  await writeConfig({
2045
+ provider: "opensandbox",
634
2046
  serverUrl: SERVER_URL,
635
2047
  useServerProxy: true,
636
2048
  apiKey: "",
@@ -721,7 +2133,7 @@ async function sendTelemetryEvent(event, endpointUrl = process.env.ALINEO_TELEME
721
2133
  /** Per-command allowlist of flags safe to record *presence of* -- never their values, never raw
722
2134
  * argv. A flag not listed here is invisible to telemetry until someone deliberately adds it;
723
2135
  * under-collecting is the only failure mode. Keys match each command's own `flag(argv, "--x")`/
724
- * `argv.includes("--x")` calls (see commands/spawn.ts, fork.ts, prompt.ts, agents.ts, logs.ts). */
2136
+ * `argv.includes("--x")` calls (see commands/start.ts, spawn.ts, prompt.ts, agents.ts, logs.ts). */
725
2137
  const FLAG_ALLOWLIST = {
726
2138
  spawn: [
727
2139
  "--prompt",
@@ -760,23 +2172,36 @@ function extractAllowedFlags(commandName, argv) {
760
2172
  for (const flagName of allowed) flags[flagName.replace(/^--/, "")] = argv.includes(flagName);
761
2173
  return flags;
762
2174
  }
763
- /** `spawn`/`fork` take a spec file as their first non-flag argv token -- reads just its own
764
- * `provider` field (a small, closed, non-identifying set like `"nvidia"`/`"google"`) to answer
765
- * "which providers actually get used." Deliberately not `model` (closer to free text, not needed
766
- * for that question) and nothing else from the spec. Never throws -- a missing/unreadable spec
767
- * file must never surface through telemetry into the real command. */
2175
+ /** `start <spec>` and `spawn <parent> <child-spec>` take a spec file as a non-flag argv token --
2176
+ * reads just its own provider (a small, closed, non-identifying set like `"nvidia"`/`"google"`)
2177
+ * to answer "which providers actually get used." Deliberately not `model` itself (closer to free
2178
+ * text, not needed for that question) and nothing else from the spec. Never throws -- a
2179
+ * missing/unreadable spec file must never surface through telemetry into the real command.
2180
+ *
2181
+ * The token is found the way `start.ts` and `spawn.ts` find it: the first non-flag token for
2182
+ * `start`, the first one after the parent for `spawn`. This once keyed off the verbs from before
2183
+ * the rename (`spawn`/`fork`), so `start` sent no provider and `spawn` read the parent id as a
2184
+ * path. */
768
2185
  async function extractSpecProvider(commandName, argv) {
769
- if (commandName !== "spawn" && commandName !== "fork") return void 0;
770
- const specPath = (commandName === "fork" ? argv.slice(1) : argv).find((a) => !a.startsWith("--"));
2186
+ const nonFlag = (a) => !a.startsWith("--");
2187
+ const specPath = commandName === "start" ? argv.find(nonFlag) : commandName === "spawn" ? argv.slice(1).find(nonFlag) : void 0;
771
2188
  if (!specPath) return void 0;
772
2189
  try {
773
2190
  const spec = await Bun.file(specPath).json();
774
- return typeof spec.provider === "string" ? spec.provider : void 0;
2191
+ const provider = (typeof spec.model === "object" && spec.model !== null ? spec.model.provider : void 0) ?? spec.provider;
2192
+ return typeof provider === "string" ? provider : void 0;
775
2193
  } catch {
776
2194
  return;
777
2195
  }
778
2196
  }
2197
+ /**
2198
+ * What the telemetry event calls a failure. The stable alineo code when the error carries one
2199
+ * (`EXEC_NOT_READY`), so failures group by cause and survive a class rename or minification.
2200
+ * Otherwise the class name, as before. Never a message: those can hold paths and ids.
2201
+ */
779
2202
  function errorClassOf(err) {
2203
+ const code = errorCodeOf(err);
2204
+ if (code) return code;
780
2205
  return err instanceof Error ? err.constructor.name : "UnknownError";
781
2206
  }
782
2207
  /**
@@ -809,7 +2234,7 @@ async function withTelemetry(commandName, argv, run) {
809
2234
  errorClass = errorClassOf(err);
810
2235
  throw err;
811
2236
  } finally {
812
- const { version } = await import("./package-oshZF9Gd.mjs");
2237
+ const { version } = await import("./package-D-x3nFQp.mjs");
813
2238
  await sendTelemetryEvent({
814
2239
  command: commandName,
815
2240
  flags,
@@ -834,7 +2259,7 @@ async function recordTuiLaunch() {
834
2259
  const config = await readTelemetryConfig();
835
2260
  if (!config.enabled) return;
836
2261
  await maybePrintFirstRunNotice(config);
837
- const { version } = await import("./package-oshZF9Gd.mjs");
2262
+ const { version } = await import("./package-D-x3nFQp.mjs");
838
2263
  await sendTelemetryEvent({
839
2264
  command: "tui",
840
2265
  flags: {},
@@ -851,15 +2276,15 @@ async function recordTuiLaunch() {
851
2276
  //#endregion
852
2277
  //#region src/index.ts
853
2278
  const [, , cmd, ...argv] = process.argv;
854
- const HELP_NOTES = ` Add --json to spawn/prompt/fork/agents/logs for machine-readable output.
855
- Add --depth <n> to spawn/fork to override the spec's "spawnDepth" — the
856
- nesting-depth budget for further forks.
857
- Add --max <n> to spawn/fork to override the spec's "maxAgents" — a separate,
2279
+ const HELP_NOTES = ` Add --json to start/prompt/spawn/agents/logs for machine-readable output.
2280
+ Add --depth <n> to start/spawn to override the spec's "spawnDepth" — the
2281
+ nesting-depth budget for further spawns.
2282
+ Add --max <n> to start/spawn to override the spec's "maxAgents" — a separate,
858
2283
  optional ceiling on total descendants for this lineage (not coordinated
859
2284
  across sibling branches spawned in parallel).
860
2285
  Add --spec <path> to prompt to skip the ledger lookup for the spec file
861
2286
  (needed when the sandbox's own creation event lives in a different ledger,
862
- e.g. a child spawned via 'alineo fork' from inside another sandbox).`;
2287
+ e.g. a child spawned via 'alineo spawn' from inside another sandbox).`;
863
2288
  const GROUPS = [{
864
2289
  key: "sdk",
865
2290
  label: "SDK — OpenSandbox config and the local spec cache:"
@@ -882,12 +2307,12 @@ function printHelp() {
882
2307
  async function main() {
883
2308
  if (!cmd && process.stdout.isTTY) {
884
2309
  await recordTuiLaunch();
885
- const { launchTui } = await import("./tui-CFEiWbe1.mjs");
2310
+ const { launchTui } = await import("./tui-LtXuxtba.mjs");
886
2311
  await launchTui();
887
2312
  return;
888
2313
  }
889
2314
  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
890
- const { version } = await import("./package-oshZF9Gd.mjs");
2315
+ const { version } = await import("./package-D-x3nFQp.mjs");
891
2316
  console.log(version);
892
2317
  return;
893
2318
  }
@@ -901,7 +2326,7 @@ async function main() {
901
2326
  if (cmd) process.exit(1);
902
2327
  }
903
2328
  main().catch((err) => {
904
- console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
2329
+ console.error(formatError(err));
905
2330
  process.exit(1);
906
2331
  });
907
2332
  //#endregion