@alineo-labs/core 0.1.0 → 0.2.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.d.mts CHANGED
@@ -23,7 +23,7 @@ interface SandboxDetails {
23
23
  * `crypto.randomUUID()` if the caller didn't supply one via `SandboxOptions.runId`.
24
24
  * A resumed, forked, or restored-from-snapshot sandbox always inherits its origin's
25
25
  * `runId` rather than getting a new one, so every sandbox descended from the same
26
- * root call (directly or via `sb.fork()`/`Agent.spawn()`/`alineo fork`) shares it —
26
+ * root call (directly or via `sb.fork()`/`Alineo.spawn()`/`alineo fork`) shares it —
27
27
  * the mechanism `client.sandboxes.list({ runId })` correlates on.
28
28
  */
29
29
  runId: string;
@@ -79,7 +79,7 @@ declare enum LedgerEvent {
79
79
  interface LedgerEntry {
80
80
  /** Unix timestamp in milliseconds. */
81
81
  ts: number;
82
- /** Sandbox session name. */
82
+ /** SandboxHandle session name. */
83
83
  name: string;
84
84
  sandboxId: string;
85
85
  /** Zero-based index of the step that produced this event. `-1` for session-level events. */
@@ -125,7 +125,7 @@ interface EnvironmentRecord {
125
125
  * @example
126
126
  * ```ts
127
127
  * import { SQLiteAdapter } from "@alineo-labs/sqlite";
128
- * const client = new Alineo({ baseUrl, adapter: new SQLiteAdapter("./alineo.db") });
128
+ * const client = new Sandbox({ baseUrl, adapter: new SQLiteAdapter("./alineo.db") });
129
129
  * ```
130
130
  */
131
131
  interface IStorageAdapter {
@@ -211,7 +211,7 @@ interface PtyControls {
211
211
  close(): void;
212
212
  }
213
213
  /**
214
- * Returned by `Sandbox.exec()` and `Sandbox.execCode()`.
214
+ * Returned by `SandboxHandle.exec()` and `SandboxHandle.execCode()`.
215
215
  *
216
216
  * Implements `PromiseLike<ExecResult>` so `await sb.exec(...)` works naturally.
217
217
  * Also exposes `pipe()`, `stdout()`, and `result()` for streaming output.
@@ -255,7 +255,7 @@ interface AttachableSource {
255
255
  off(event: "data", listener: (chunk: Buffer | string) => void): unknown;
256
256
  }
257
257
  /**
258
- * Returned by `Sandbox.exec(cmd, { interactive: true })`.
258
+ * Returned by `SandboxHandle.exec(cmd, { interactive: true })`.
259
259
  *
260
260
  * Extends `ExecHandle` with the input/control side of a live PTY session:
261
261
  * `write()` sends input, `resize()`/`signal()` control the terminal, `close()`
@@ -327,7 +327,7 @@ interface ExecOptions {
327
327
  */
328
328
  interactive?: boolean;
329
329
  }
330
- /** A session still open at the last checkpoint — reconstructed on resume. See `Alineo.resume()`. */
330
+ /** A session still open at the last checkpoint — reconstructed on resume. See `Sandbox.resume()`. */
331
331
  interface PendingInteractiveExec {
332
332
  cmd: string;
333
333
  cwd?: string;
@@ -355,22 +355,22 @@ interface SandboxHooks {
355
355
  onSandboxPaused?(sandboxId: string): void;
356
356
  onSandboxResumed?(sandboxId: string): void;
357
357
  }
358
- /** Internal dependencies injected by `Alineo`. */
358
+ /** Internal dependencies injected by `Sandbox`. */
359
359
  interface SandboxDeps {
360
360
  control: ControlClient;
361
361
  adapter: IStorageAdapter;
362
362
  hooks?: SandboxHooks;
363
- /** Called when `close()` completes — used by `Alineo` for concurrency accounting. */
363
+ /** Called when `close()` completes — used by `Sandbox` for concurrency accounting. */
364
364
  onClose?: () => void;
365
365
  /** Default shell for all `exec()` calls on this sandbox. Defaults to `"/bin/sh"`. */
366
366
  shell?: string;
367
367
  /**
368
- * Called by `fork()` to create a new Sandbox from a snapshot — injected by `Alineo`.
368
+ * Called by `fork()` to create a new SandboxHandle from a snapshot — injected by `Sandbox`.
369
369
  * `runId`, if passed, overrides whatever run-correlation ID this closure would otherwise
370
370
  * default to (see `fork()`'s own docs in `lifecycle.ts` for why an explicit override is
371
371
  * needed across a process boundary).
372
372
  */
373
- fork?: (snapshotId: string, tag?: string, runId?: string) => Promise<Sandbox>;
373
+ fork?: (snapshotId: string, tag?: string, runId?: string) => Promise<SandboxHandle>;
374
374
  /** Route execd and proxy calls through the OpenSandbox server. Required when the server runs in Docker. */
375
375
  useServerProxy?: boolean;
376
376
  }
@@ -441,16 +441,16 @@ declare class BashSession {
441
441
  /**
442
442
  * Owns all private sandbox state (exec sequencing, ledger queue, pause/close
443
443
  * flags) plus the exec-stream methods that are most tightly coupled to it.
444
- * `Sandbox` (in `sandbox.ts`) extends this and adds the file/lifecycle/
444
+ * `SandboxHandle` (in `sandbox.ts`) extends this and adds the file/lifecycle/
445
445
  * observability methods as thin delegators to sibling modules.
446
446
  */
447
447
  declare class SandboxCore implements SandboxInternal {
448
448
  readonly sandboxId: string;
449
449
  readonly name: string;
450
450
  readonly deps: SandboxDeps;
451
- /** Cached exec results for replay mode (populated by `Alineo.resume()`). */
451
+ /** Cached exec results for replay mode (populated by `Sandbox.resume()`). */
452
452
  readonly replayCache: Map<number, ExecResult>;
453
- /** Interactive sessions still open at the last checkpoint (populated by `Alineo.resume()`). */
453
+ /** Interactive sessions still open at the last checkpoint (populated by `Sandbox.resume()`). */
454
454
  readonly pendingInteractive: Map<number, PendingInteractiveExec>;
455
455
  readonly openSessionClosers: Set<() => Promise<void>>;
456
456
  private _execClient;
@@ -570,7 +570,7 @@ declare class SandboxCore implements SandboxInternal {
570
570
  //#endregion
571
571
  //#region src/sandbox/sandbox.d.ts
572
572
  /**
573
- * A live sandbox container. Returned by `Alineo.sandbox()` and `Alineo.resume()`.
573
+ * A live sandbox container. Returned by `Sandbox.sandbox()` and `Sandbox.resume()`.
574
574
  *
575
575
  * Call `exec()` to run commands, `checkpoint()` to snapshot state, and `close()`
576
576
  * when done. Multiple sandboxes can be held simultaneously — just assign to
@@ -585,7 +585,7 @@ declare class SandboxCore implements SandboxInternal {
585
585
  * await sb.close();
586
586
  * ```
587
587
  */
588
- declare class Sandbox extends SandboxCore {
588
+ declare class SandboxHandle extends SandboxCore {
589
589
  /** Write a file into the sandbox. */
590
590
  writeFile(path: string, content: string): Promise<void>;
591
591
  /** Read a file from the sandbox as a UTF-8 string. */
@@ -632,7 +632,7 @@ declare class Sandbox extends SandboxCore {
632
632
  * await sb.transfer("/app/output.json", fork);
633
633
  * ```
634
634
  */
635
- transfer(path: string, target: Sandbox): Promise<void>;
635
+ transfer(path: string, target: SandboxHandle): Promise<void>;
636
636
  /**
637
637
  * Return a proxied URL and auth headers for a port inside the sandbox.
638
638
  *
@@ -692,10 +692,10 @@ declare class Sandbox extends SandboxCore {
692
692
  /** Return all checkpoints for this sandbox in creation order. */
693
693
  listCheckpoints(): Promise<CheckpointInfo[]>;
694
694
  /**
695
- * Snapshot the current sandbox and return a new independent `Sandbox` from that state.
695
+ * Snapshot the current sandbox and return a new independent `SandboxHandle` from that state.
696
696
  *
697
697
  * The original sandbox keeps running. Both operate on separate containers restored
698
- * from the same snapshot. Equivalent to `checkpoint()` followed by `Alineo.restoreSnapshot()`
698
+ * from the same snapshot. Equivalent to `checkpoint()` followed by `Sandbox.restoreSnapshot()`
699
699
  * into a new sandbox, but without closing the original.
700
700
  *
701
701
  * @example
@@ -710,13 +710,13 @@ declare class Sandbox extends SandboxCore {
710
710
  * @param runId Override the forked sandbox's run-correlation ID (see `SandboxDetails.runId`)
711
711
  * instead of inheriting this sandbox's own default.
712
712
  */
713
- fork(tag?: string, runId?: string): Promise<Sandbox>;
713
+ fork(tag?: string, runId?: string): Promise<SandboxHandle>;
714
714
  /**
715
715
  * Capture a snapshot of the sandbox's current filesystem state.
716
716
  *
717
717
  * Writes a `checkpoint_created` event to the ledger with the snapshot ID and
718
- * returns the snapshot ID. Use `Alineo.resume(sandboxId)` to restore from
719
- * the latest checkpoint, or pass the returned ID to `Alineo.restoreSnapshot()`.
718
+ * returns the snapshot ID. Use `Sandbox.resume(sandboxId)` to restore from
719
+ * the latest checkpoint, or pass the returned ID to `Sandbox.restoreSnapshot()`.
720
720
  */
721
721
  checkpoint(name?: string): Promise<string>;
722
722
  /**
@@ -809,7 +809,7 @@ declare class ExecConnectionError extends WorkflowError {
809
809
  }
810
810
  /**
811
811
  * Thrown when a command exits with a non-zero exit code. Carries the exit
812
- * code and original command. For `Sandbox.exec()`, only thrown when `strict`
812
+ * code and original command. For `SandboxHandle.exec()`, only thrown when `strict`
813
813
  * is enabled (the default — pass `{ strict: false }` to opt out). For
814
814
  * `BashSession.exec()` (a persistent session from `createSession()`), always
815
815
  * thrown on non-zero exit; there is no `strict` option for session execs.
@@ -831,4 +831,4 @@ declare class StepTimeoutError extends WorkflowError {
831
831
  constructor(stepId: string, timeoutMs: number);
832
832
  }
833
833
  //#endregion
834
- export { type AttachableSource, BashSession, type CheckpointInfo, CommandError, type ComposeHooksOptions, ConsoleLogger, type DiagnosticEvent, type DiagnosticLog, type EnvironmentRecord, type ExecCodeOptions, ExecConnectionError, ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type ILogger, type IStorageAdapter, InteractiveExecHandle, type LedgerEntry, LedgerEvent, type ListSandboxOptions, LogLevel, type Metrics, type PendingInteractiveExec, type PtyControls, Sandbox, type SandboxDeps, type SandboxDetails, SandboxError, type SandboxHooks, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, resolveExecClient };
834
+ export { type AttachableSource, BashSession, type CheckpointInfo, CommandError, type ComposeHooksOptions, ConsoleLogger, type DiagnosticEvent, type DiagnosticLog, type EnvironmentRecord, type ExecCodeOptions, ExecConnectionError, ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type ILogger, type IStorageAdapter, InteractiveExecHandle, type LedgerEntry, LedgerEvent, type ListSandboxOptions, LogLevel, type Metrics, type PendingInteractiveExec, type PtyControls, type SandboxDeps, type SandboxDetails, SandboxError, SandboxHandle, type SandboxHooks, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, resolveExecClient };
package/dist/index.mjs CHANGED
@@ -121,7 +121,7 @@ var ExecConnectionError = class extends WorkflowError {
121
121
  };
122
122
  /**
123
123
  * Thrown when a command exits with a non-zero exit code. Carries the exit
124
- * code and original command. For `Sandbox.exec()`, only thrown when `strict`
124
+ * code and original command. For `SandboxHandle.exec()`, only thrown when `strict`
125
125
  * is enabled (the default — pass `{ strict: false }` to opt out). For
126
126
  * `BashSession.exec()` (a persistent session from `createSession()`), always
127
127
  * thrown on non-zero exit; there is no `strict` option for session execs.
@@ -156,7 +156,7 @@ var StepTimeoutError = class extends WorkflowError {
156
156
  //#endregion
157
157
  //#region src/exec-handle.ts
158
158
  /**
159
- * Returned by `Sandbox.exec()` and `Sandbox.execCode()`.
159
+ * Returned by `SandboxHandle.exec()` and `SandboxHandle.execCode()`.
160
160
  *
161
161
  * Implements `PromiseLike<ExecResult>` so `await sb.exec(...)` works naturally.
162
162
  * Also exposes `pipe()`, `stdout()`, and `result()` for streaming output.
@@ -283,7 +283,7 @@ var ExecHandle = class {
283
283
  }
284
284
  };
285
285
  /**
286
- * Returned by `Sandbox.exec(cmd, { interactive: true })`.
286
+ * Returned by `SandboxHandle.exec(cmd, { interactive: true })`.
287
287
  *
288
288
  * Extends `ExecHandle` with the input/control side of a live PTY session:
289
289
  * `write()` sends input, `resize()`/`signal()` control the terminal, `close()`
@@ -423,16 +423,16 @@ var BashSession = class {
423
423
  /**
424
424
  * Owns all private sandbox state (exec sequencing, ledger queue, pause/close
425
425
  * flags) plus the exec-stream methods that are most tightly coupled to it.
426
- * `Sandbox` (in `sandbox.ts`) extends this and adds the file/lifecycle/
426
+ * `SandboxHandle` (in `sandbox.ts`) extends this and adds the file/lifecycle/
427
427
  * observability methods as thin delegators to sibling modules.
428
428
  */
429
429
  var SandboxCore = class {
430
430
  sandboxId;
431
431
  name;
432
432
  deps;
433
- /** Cached exec results for replay mode (populated by `Alineo.resume()`). */
433
+ /** Cached exec results for replay mode (populated by `Sandbox.resume()`). */
434
434
  replayCache;
435
- /** Interactive sessions still open at the last checkpoint (populated by `Alineo.resume()`). */
435
+ /** Interactive sessions still open at the last checkpoint (populated by `Sandbox.resume()`). */
436
436
  pendingInteractive;
437
437
  openSessionClosers = /* @__PURE__ */ new Set();
438
438
  _execClient = null;
@@ -502,11 +502,11 @@ var SandboxCore = class {
502
502
  while (Date.now() < deadline) {
503
503
  const s = await this.deps.control.getSandbox(this.sandboxId);
504
504
  if (s.status.state === SandboxState.Running) return;
505
- if (s.status.state === SandboxState.Failed || s.status.state === SandboxState.Terminated) throw new SandboxError(`Sandbox entered ${s.status.state}: ${s.status.message ?? ""}`, this.sandboxId);
505
+ if (s.status.state === SandboxState.Failed || s.status.state === SandboxState.Terminated) throw new SandboxError(`SandboxHandle entered ${s.status.state}: ${s.status.message ?? ""}`, this.sandboxId);
506
506
  await new Promise((r) => setTimeout(r, delay));
507
507
  delay = Math.min(delay * 1.5, 1e3);
508
508
  }
509
- throw new SandboxError(`Sandbox did not reach Running within ${timeoutMs}ms`, this.sandboxId);
509
+ throw new SandboxError(`SandboxHandle did not reach Running within ${timeoutMs}ms`, this.sandboxId);
510
510
  }
511
511
  async waitForSnapshot(snapshotId, timeoutMs = 12e4) {
512
512
  const deadline = Date.now() + timeoutMs;
@@ -893,8 +893,8 @@ async function resume(sb) {
893
893
  * Capture a snapshot of the sandbox's current filesystem state.
894
894
  *
895
895
  * Writes a `checkpoint_created` event to the ledger with the snapshot ID and
896
- * returns the snapshot ID. Use `Alineo.resume(sandboxId)` to restore from
897
- * the latest checkpoint, or pass the returned ID to `Alineo.restoreSnapshot()`.
896
+ * returns the snapshot ID. Use `Sandbox.resume(sandboxId)` to restore from
897
+ * the latest checkpoint, or pass the returned ID to `Sandbox.restoreSnapshot()`.
898
898
  */
899
899
  async function checkpoint(sb, name) {
900
900
  const snap = await sb.deps.control.createSnapshot(sb.sandboxId);
@@ -907,15 +907,15 @@ async function checkpoint(sb, name) {
907
907
  return snap.id;
908
908
  }
909
909
  /**
910
- * Snapshot the current sandbox and return a new independent `Sandbox` from that state.
910
+ * Snapshot the current sandbox and return a new independent `SandboxHandle` from that state.
911
911
  *
912
912
  * The original sandbox keeps running. Both operate on separate containers restored
913
- * from the same snapshot. Equivalent to `checkpoint()` followed by `Alineo.restoreSnapshot()`
913
+ * from the same snapshot. Equivalent to `checkpoint()` followed by `Sandbox.restoreSnapshot()`
914
914
  * into a new sandbox, but without closing the original.
915
915
  *
916
916
  * @param runId Override the forked sandbox's run correlation ID instead of inheriting
917
917
  * whatever this sandbox's own creation closed over. Needed when forking across a process
918
- * boundary (e.g. `alineo fork`, which re-`Agent.attach()`es in a brand-new CLI process with
918
+ * boundary (e.g. `alineo fork`, which re-`Alineo.attach()`es in a brand-new CLI process with
919
919
  * no access to the original in-memory closure) — the caller reads the correct value from
920
920
  * `process.env.ALINEO_RUN_ID` and passes it explicitly rather than relying on this sandbox's
921
921
  * own (possibly unknown) default.
@@ -994,7 +994,7 @@ async function proxy(sb, port) {
994
994
  //#endregion
995
995
  //#region src/sandbox/sandbox.ts
996
996
  /**
997
- * A live sandbox container. Returned by `Alineo.sandbox()` and `Alineo.resume()`.
997
+ * A live sandbox container. Returned by `Sandbox.sandbox()` and `Sandbox.resume()`.
998
998
  *
999
999
  * Call `exec()` to run commands, `checkpoint()` to snapshot state, and `close()`
1000
1000
  * when done. Multiple sandboxes can be held simultaneously — just assign to
@@ -1009,7 +1009,7 @@ async function proxy(sb, port) {
1009
1009
  * await sb.close();
1010
1010
  * ```
1011
1011
  */
1012
- var Sandbox = class extends SandboxCore {
1012
+ var SandboxHandle = class extends SandboxCore {
1013
1013
  /** Write a file into the sandbox. */
1014
1014
  async writeFile(path, content) {
1015
1015
  return writeFile(this, path, content);
@@ -1146,10 +1146,10 @@ var Sandbox = class extends SandboxCore {
1146
1146
  return listCheckpoints(this);
1147
1147
  }
1148
1148
  /**
1149
- * Snapshot the current sandbox and return a new independent `Sandbox` from that state.
1149
+ * Snapshot the current sandbox and return a new independent `SandboxHandle` from that state.
1150
1150
  *
1151
1151
  * The original sandbox keeps running. Both operate on separate containers restored
1152
- * from the same snapshot. Equivalent to `checkpoint()` followed by `Alineo.restoreSnapshot()`
1152
+ * from the same snapshot. Equivalent to `checkpoint()` followed by `Sandbox.restoreSnapshot()`
1153
1153
  * into a new sandbox, but without closing the original.
1154
1154
  *
1155
1155
  * @example
@@ -1171,8 +1171,8 @@ var Sandbox = class extends SandboxCore {
1171
1171
  * Capture a snapshot of the sandbox's current filesystem state.
1172
1172
  *
1173
1173
  * Writes a `checkpoint_created` event to the ledger with the snapshot ID and
1174
- * returns the snapshot ID. Use `Alineo.resume(sandboxId)` to restore from
1175
- * the latest checkpoint, or pass the returned ID to `Alineo.restoreSnapshot()`.
1174
+ * returns the snapshot ID. Use `Sandbox.resume(sandboxId)` to restore from
1175
+ * the latest checkpoint, or pass the returned ID to `Sandbox.restoreSnapshot()`.
1176
1176
  */
1177
1177
  async checkpoint(name) {
1178
1178
  return checkpoint(this, name);
@@ -1249,4 +1249,4 @@ function composeHooks(hooks, opts = {}) {
1249
1249
  };
1250
1250
  }
1251
1251
  //#endregion
1252
- export { BashSession, CommandError, ConsoleLogger, ExecConnectionError, ExecHandle, InteractiveExecHandle, LedgerEvent, LogLevel, Sandbox, SandboxError, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, resolveExecClient };
1252
+ export { BashSession, CommandError, ConsoleLogger, ExecConnectionError, ExecHandle, InteractiveExecHandle, LedgerEvent, LogLevel, SandboxError, SandboxHandle, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, resolveExecClient };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/core",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",