@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 +23 -23
- package/dist/index.mjs +20 -20
- package/package.json +1 -1
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()`/`
|
|
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
|
-
/**
|
|
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
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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
|
|
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<
|
|
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
|
-
* `
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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
|
|
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:
|
|
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 `
|
|
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 `
|
|
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<
|
|
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 `
|
|
719
|
-
* the latest checkpoint, or pass the returned ID to `
|
|
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 `
|
|
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,
|
|
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 `
|
|
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 `
|
|
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 `
|
|
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
|
-
* `
|
|
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 `
|
|
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 `
|
|
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(`
|
|
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(`
|
|
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 `
|
|
897
|
-
* the latest checkpoint, or pass the returned ID to `
|
|
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 `
|
|
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 `
|
|
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-`
|
|
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 `
|
|
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
|
|
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 `
|
|
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 `
|
|
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 `
|
|
1175
|
-
* the latest checkpoint, or pass the returned ID to `
|
|
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,
|
|
1252
|
+
export { BashSession, CommandError, ConsoleLogger, ExecConnectionError, ExecHandle, InteractiveExecHandle, LedgerEvent, LogLevel, SandboxError, SandboxHandle, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, resolveExecClient };
|