@alineo-labs/sandbox 0.5.0 → 0.6.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
@@ -1,6 +1,7 @@
1
1
  import { BashSession, CheckpointInfo, CommandError, CredentialBinding, CredentialBroker, CredentialBroker as CredentialBroker$1, CredentialResolver, DiagnosticEvent, DiagnosticLog, EnvironmentRecord, EnvironmentRecord as EnvironmentRecord$1, EnvironmentRecord as EnvironmentRecord$2, ExecCodeOptions, ExecConnectionError, ExecHandle, ExecOptions, ExecResult, FileInfo, IStorageAdapter, IStorageAdapter as IStorageAdapter$1, InteractiveExecHandle, LedgerEntry, LedgerEvent, ListSandboxOptions, ListSandboxOptions as ListSandboxOptions$1, Metrics, PendingInteractiveExec, SandboxDetails, SandboxDetails as SandboxDetails$1, SandboxError, SandboxHandle, SandboxHandle as SandboxHandle$1, SandboxHooks, SandboxStatus, StepTimeoutError } from "@alineo-labs/core";
2
- import { CodeLanguage, CredentialProxyConfig, NetworkPolicy, NetworkPolicy as NetworkPolicy$1, NetworkRule } from "@alineo-labs/opensandbox";
3
2
  import { OpenSandboxCredentialBroker } from "@alineo-labs/vault";
3
+ import { AlineoError, AlineoError as AlineoError$1, AlineoErrorOptions, ErrorCode, ErrorCode as ErrorCode$1, errorCodeOf, isAlineoError, isRetryable } from "@alineo-labs/errors";
4
+ import { CodeLanguage, CredentialProxyConfig, NetworkPolicy, NetworkPolicy as NetworkPolicy$1, NetworkRule, SandboxProvider } from "@alineo-labs/provider";
4
5
  import { LedgerEnvelope } from "@alineo-labs/schema/types";
5
6
  //#region src/types.d.ts
6
7
  /**
@@ -11,16 +12,24 @@ import { LedgerEnvelope } from "@alineo-labs/schema/types";
11
12
  * `OpenSandboxError` from `@alineo-labs/opensandbox`, which is never rethrown as a
12
13
  * `SandboxClientError`.
13
14
  */
14
- export declare class SandboxClientError extends Error {
15
+ export declare class SandboxClientError extends AlineoError$1 {
15
16
  readonly status: number;
16
- constructor(message: string, status: number);
17
+ constructor(message: string, status: number, code?: ErrorCode$1, options?: AlineoErrorOptions);
17
18
  }
18
19
  /** Options for constructing a {@link Sandbox} client. */
19
20
  interface SandboxClientOptions {
20
- /** Base URL of your OpenSandbox server (e.g. `http://localhost:8080`). */
21
- baseUrl: string;
21
+ /**
22
+ * Base URL of your OpenSandbox server (e.g. `http://localhost:8080`). Required unless
23
+ * `provider` is given.
24
+ */
25
+ baseUrl?: string;
22
26
  /** OpenSandbox API key. Pass an empty string for local dev with no auth. */
23
27
  apiKey?: string;
28
+ /**
29
+ * The sandbox provider to run on. Leave it out to use OpenSandbox at `baseUrl`, which is what
30
+ * `apiKey` and `useServerProxy` configure. They do not apply to a provider you pass.
31
+ */
32
+ provider?: SandboxProvider;
24
33
  /**
25
34
  * Storage adapter for persisting sandbox events.
26
35
  *
@@ -56,7 +65,7 @@ interface SandboxClientOptions {
56
65
  * Broker for `sb.credentials.*` — registers credentials with, and resolves endpoints
57
66
  * against, whatever backend actually injects them. Defaults to
58
67
  * `OpenSandboxCredentialBroker` (from `@alineo-labs/vault`), wired to this client's own
59
- * `ControlClient`/`useServerProxy`, if omitted. Only relevant for sandboxes created with
68
+ * provider and `useServerProxy`, if omitted. Only relevant for sandboxes created with
60
69
  * `credentialProxy: true`.
61
70
  */
62
71
  credentialBroker?: CredentialBroker$1;
@@ -291,12 +300,11 @@ export declare class Environment {
291
300
  * ```
292
301
  */
293
302
  export declare class Sandbox {
294
- private readonly _control;
303
+ private readonly _provider;
295
304
  private readonly _adapter;
296
305
  private readonly _sink;
297
306
  private readonly _credentialBroker;
298
307
  private readonly _maxConcurrency;
299
- private readonly _useServerProxy;
300
308
  private _activeCount;
301
309
  private readonly _waiters;
302
310
  private _connectPromise;
@@ -312,6 +320,11 @@ export declare class Sandbox {
312
320
  */
313
321
  private _append;
314
322
  constructor(options: SandboxClientOptions);
323
+ /**
324
+ * The sandbox provider this client runs on. For a caller that needs something the client
325
+ * does not wrap, such as listing sandboxes the ledger never recorded.
326
+ */
327
+ get provider(): SandboxProvider;
315
328
  /** Lazily initialises the adapter on first use. Concurrent callers share the same promise. */
316
329
  private _ensureConnected;
317
330
  /**
@@ -531,4 +544,32 @@ export declare class Sandbox {
531
544
  private _releaseSlot;
532
545
  }
533
546
  //#endregion
534
- export { BashSession, type CheckpointInfo, CodeLanguage, CommandError, type CredentialBinding, type CredentialBroker, type CredentialProxyConfig, type DiagnosticEvent, type DiagnosticLog, type EnvironmentOptions, type EnvironmentRecord, type EnvironmentSandboxOptions, type ExecCodeOptions, ExecConnectionError, type ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type IStorageAdapter, type InteractiveExecHandle, type LedgerEntry, LedgerEvent, type ListSandboxOptions, type Metrics, type NetworkPolicy, type NetworkRule, OpenSandboxCredentialBroker, type PendingInteractiveExec, type ResumeOptions, type SandboxClientOptions, type SandboxDetails, SandboxError, SandboxHandle, type SandboxOptions, SandboxStatus, StepTimeoutError };
547
+ //#region src/provider-config.d.ts
548
+ /**
549
+ * The part of `alineo.config.json` that picks a provider and says where it is. Structural, so
550
+ * the SDK needs no dependency on the package that loads the file.
551
+ */
552
+ interface ProviderConfig {
553
+ /** Which provider. Absent means `"opensandbox"`. */
554
+ provider?: string;
555
+ /** OpenSandbox server URL. */
556
+ serverUrl: string;
557
+ apiKey?: string;
558
+ useServerProxy?: boolean;
559
+ }
560
+ /** The provider ids `providerFromConfig` can build. */
561
+ export declare const KNOWN_PROVIDERS: readonly ["opensandbox"];
562
+ /**
563
+ * Build the provider a config names.
564
+ *
565
+ * An id this build does not know is refused here, naming the ids it does know. Guessing
566
+ * OpenSandbox instead would run someone's agents on the wrong substrate without a word.
567
+ */
568
+ export declare function providerFromConfig(config: ProviderConfig): SandboxProvider;
569
+ /**
570
+ * A {@link Sandbox} client for the provider a config names. Every CLI command and the agent
571
+ * runtime build their client through this, so the provider is chosen in one place.
572
+ */
573
+ export declare function clientFromConfig(config: ProviderConfig, options: Omit<SandboxClientOptions, "provider" | "baseUrl" | "apiKey" | "useServerProxy">): Sandbox;
574
+ //#endregion
575
+ export { AlineoError, BashSession, type CheckpointInfo, CodeLanguage, CommandError, type CredentialBinding, type CredentialBroker, type CredentialProxyConfig, type DiagnosticEvent, type DiagnosticLog, type EnvironmentOptions, type EnvironmentRecord, type EnvironmentSandboxOptions, type ErrorCode, type ExecCodeOptions, ExecConnectionError, type ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type IStorageAdapter, type InteractiveExecHandle, type LedgerEntry, LedgerEvent, type ListSandboxOptions, type Metrics, type NetworkPolicy, type NetworkRule, OpenSandboxCredentialBroker, type PendingInteractiveExec, type ProviderConfig, type ResumeOptions, type SandboxClientOptions, type SandboxDetails, SandboxError, SandboxHandle, type SandboxOptions, SandboxStatus, StepTimeoutError, errorCodeOf, isAlineoError, isRetryable };
package/dist/index.mjs CHANGED
@@ -1,6 +1,8 @@
1
- import { BashSession, CommandError, ExecConnectionError, LedgerEvent, LedgerEvent as LedgerEvent$1, SandboxError, SandboxHandle, SandboxHandle as SandboxHandle$1, SandboxStatus, StepTimeoutError, reconstructBoundCredentials, reconstructEgressRules, resolveBoundCredential } from "@alineo-labs/core";
2
- import { CodeLanguage, ControlClient, SandboxState, SnapshotState, isValidEgressTarget } from "@alineo-labs/opensandbox";
1
+ import { BashSession, CommandError, DEFAULT_PROVIDER_ID, ExecConnectionError, LedgerEvent, LedgerEvent as LedgerEvent$1, SandboxError, SandboxHandle, SandboxHandle as SandboxHandle$1, SandboxStatus, StepTimeoutError, reconstructBoundCredentials, reconstructEgressRules, requireCapability, resolveBoundCredential } from "@alineo-labs/core";
2
+ import { OpenSandboxProvider, isValidEgressTarget } from "@alineo-labs/opensandbox";
3
3
  import { OpenSandboxCredentialBroker, OpenSandboxCredentialBroker as OpenSandboxCredentialBroker$1 } from "@alineo-labs/vault";
4
+ import { AlineoError, AlineoError as AlineoError$1, errorCodeOf, isAlineoError, isRetryable } from "@alineo-labs/errors";
5
+ import { CodeLanguage } from "@alineo-labs/provider";
4
6
  //#region src/types.ts
5
7
  /**
6
8
  * Client-side SDK error carrying an HTTP-style status code, thrown for
@@ -10,14 +12,30 @@ import { OpenSandboxCredentialBroker, OpenSandboxCredentialBroker as OpenSandbox
10
12
  * `OpenSandboxError` from `@alineo-labs/opensandbox`, which is never rethrown as a
11
13
  * `SandboxClientError`.
12
14
  */
13
- var SandboxClientError = class extends Error {
15
+ var SandboxClientError = class extends AlineoError$1 {
14
16
  status;
15
- constructor(message, status) {
16
- super(message);
17
+ constructor(message, status, code = codeForStatus(status), options) {
18
+ super(code, message, {
19
+ ...options,
20
+ details: {
21
+ status,
22
+ ...options?.details
23
+ }
24
+ });
17
25
  this.status = status;
18
26
  this.name = "SandboxClientError";
19
27
  }
20
28
  };
29
+ /**
30
+ * The code for a status when the throw site did not choose one. Call sites that know better
31
+ * (a missing session, a sandbox that is not Running) pass their own.
32
+ */
33
+ function codeForStatus(status) {
34
+ if (status === 408) return "SANDBOX_START_TIMEOUT";
35
+ if (status === 404) return "SESSION_NOT_FOUND";
36
+ if (status === 400) return "INVALID_ARGUMENT";
37
+ return "INTERNAL";
38
+ }
21
39
  //#endregion
22
40
  //#region src/environment.ts
23
41
  /**
@@ -111,12 +129,11 @@ function assertValidNetworkPolicy(policy) {
111
129
  * ```
112
130
  */
113
131
  var Sandbox = class {
114
- _control;
132
+ _provider;
115
133
  _adapter;
116
134
  _sink;
117
135
  _credentialBroker;
118
136
  _maxConcurrency;
119
- _useServerProxy;
120
137
  _activeCount = 0;
121
138
  _waiters = [];
122
139
  _connectPromise = null;
@@ -131,6 +148,16 @@ var Sandbox = class {
131
148
  * must not delay, or fail, the write it is exporting.
132
149
  */
133
150
  async _append(entry) {
151
+ if (entry.event === LedgerEvent$1.SandboxCreated) {
152
+ const payload = entry.payload ?? {};
153
+ if (payload.provider === void 0) entry = {
154
+ ...entry,
155
+ payload: {
156
+ ...payload,
157
+ provider: this._provider.id
158
+ }
159
+ };
160
+ }
134
161
  if (this._sink) try {
135
162
  this._sink({
136
163
  v: 1,
@@ -148,15 +175,19 @@ var Sandbox = class {
148
175
  await this._adapter.append(entry);
149
176
  }
150
177
  constructor(options) {
151
- this._control = new ControlClient({
152
- baseUrl: options.baseUrl,
153
- apiKey: options.apiKey ?? ""
154
- });
178
+ if (options.provider) this._provider = options.provider;
179
+ else {
180
+ if (!options.baseUrl) throw new SandboxClientError("Sandbox needs a `provider`, or a `baseUrl` for the OpenSandbox server", 400, "INVALID_ARGUMENT");
181
+ this._provider = new OpenSandboxProvider({
182
+ baseUrl: options.baseUrl,
183
+ apiKey: options.apiKey ?? "",
184
+ useServerProxy: options.useServerProxy ?? false
185
+ });
186
+ }
155
187
  this._adapter = options.adapter;
156
188
  this._sink = options.sink;
157
189
  this._maxConcurrency = options.maxConcurrency;
158
- this._useServerProxy = options.useServerProxy ?? false;
159
- this._credentialBroker = options.credentialBroker ?? new OpenSandboxCredentialBroker$1(this._control, this._useServerProxy);
190
+ this._credentialBroker = options.credentialBroker ?? new OpenSandboxCredentialBroker$1(this._provider, options.useServerProxy ?? false);
160
191
  process.setMaxListeners(process.getMaxListeners() + 1);
161
192
  process.on("beforeExit", () => {
162
193
  if (!this._adapterClosed) {
@@ -165,6 +196,13 @@ var Sandbox = class {
165
196
  }
166
197
  });
167
198
  }
199
+ /**
200
+ * The sandbox provider this client runs on. For a caller that needs something the client
201
+ * does not wrap, such as listing sandboxes the ledger never recorded.
202
+ */
203
+ get provider() {
204
+ return this._provider;
205
+ }
168
206
  /** Lazily initialises the adapter on first use. Concurrent callers share the same promise. */
169
207
  _ensureConnected() {
170
208
  this._connectPromise ??= this._adapter.connect?.() ?? Promise.resolve();
@@ -189,6 +227,8 @@ var Sandbox = class {
189
227
  */
190
228
  async sandbox(opts) {
191
229
  assertValidNetworkPolicy(opts.networkPolicy);
230
+ if (opts.networkPolicy?.egress?.length) requireCapability(this._provider, "egress");
231
+ if (opts.credentialProxy) requireCapability(this._provider, "credentials");
192
232
  await this._ensureConnected();
193
233
  await this._acquireSlot();
194
234
  const image = typeof opts.image === "string" ? { uri: opts.image } : opts.image;
@@ -197,7 +237,7 @@ var Sandbox = class {
197
237
  const teamId = opts.teamId;
198
238
  let sandboxId;
199
239
  try {
200
- sandboxId = (await this._control.createSandbox({
240
+ sandboxId = (await this._provider.createSandbox({
201
241
  image,
202
242
  env: opts.env,
203
243
  metadata: {
@@ -233,7 +273,7 @@ var Sandbox = class {
233
273
  }
234
274
  });
235
275
  const sb = new SandboxHandle$1(sandboxId, name, {
236
- control: this._control,
276
+ provider: this._provider,
237
277
  adapter: this._adapter,
238
278
  sink: this._sink,
239
279
  credentialBroker: this._credentialBroker,
@@ -242,8 +282,7 @@ var Sandbox = class {
242
282
  this._releaseSlot();
243
283
  },
244
284
  shell: opts.shell,
245
- fork: (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, name, opts.resources, opts.shell, overrideRunId ?? runId, sandboxId, resourceId, teamId, forkOpts),
246
- useServerProxy: this._useServerProxy
285
+ fork: (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, name, opts.resources, opts.shell, overrideRunId ?? runId, sandboxId, resourceId, teamId, forkOpts)
247
286
  });
248
287
  opts.hooks?.onSandboxCreated?.(sandboxId, name);
249
288
  return sb;
@@ -283,13 +322,19 @@ var Sandbox = class {
283
322
  }
284
323
  async _resumeSession(name, sandboxId, tag, resolveCredential) {
285
324
  const entries = await this._adapter.readAll(name, sandboxId);
325
+ const owner = (entries.find((e) => e.event === LedgerEvent$1.SandboxCreated)?.payload)?.provider ?? DEFAULT_PROVIDER_ID;
326
+ if (owner !== this._provider.id) throw new SandboxClientError(`Session ${sandboxId} was created on the "${owner}" provider, but this client is configured for "${this._provider.id}".`, 409, "PROVIDER_MISMATCH", { details: {
327
+ sandboxId,
328
+ provider: owner,
329
+ configured: this._provider.id
330
+ } });
286
331
  let checkpointIdx;
287
332
  if (tag) {
288
333
  checkpointIdx = entries.findIndex((e) => e.event === LedgerEvent$1.CheckpointCreated && e.payload?.name === tag);
289
- if (checkpointIdx === -1) throw new SandboxClientError(`No checkpoint with tag '${tag}' found for session ${sandboxId}`, 404);
334
+ if (checkpointIdx === -1) throw new SandboxClientError(`No checkpoint with tag '${tag}' found for session ${sandboxId}`, 404, "CHECKPOINT_NOT_FOUND");
290
335
  } else {
291
336
  checkpointIdx = entries.map((e) => e.event).lastIndexOf(LedgerEvent$1.CheckpointCreated);
292
- if (checkpointIdx === -1) throw new SandboxClientError(`No checkpoint found for session ${sandboxId}`, 404);
337
+ if (checkpointIdx === -1) throw new SandboxClientError(`No checkpoint found for session ${sandboxId}`, 404, "CHECKPOINT_NOT_FOUND");
293
338
  }
294
339
  const { snapshotId } = entries[checkpointIdx].payload;
295
340
  const createdPayload = entries.find((e) => e.event === LedgerEvent$1.SandboxCreated)?.payload;
@@ -351,7 +396,7 @@ var Sandbox = class {
351
396
  }
352
397
  await this._acquireSlot();
353
398
  try {
354
- const newSessionId = (await this._control.createSandbox({
399
+ const newSessionId = (await this._provider.createSandbox({
355
400
  snapshotId,
356
401
  resourceLimits: resources,
357
402
  metadata: { runId },
@@ -377,15 +422,14 @@ var Sandbox = class {
377
422
  }
378
423
  });
379
424
  const sb = new SandboxHandle$1(newSessionId, name, {
380
- control: this._control,
425
+ provider: this._provider,
381
426
  adapter: this._adapter,
382
427
  sink: this._sink,
383
428
  credentialBroker: this._credentialBroker,
384
429
  onClose: () => {
385
430
  this._releaseSlot();
386
431
  },
387
- fork: resources?.cpu && resources.memory ? (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, name, resources, void 0, overrideRunId ?? runId, newSessionId, resourceId, teamId, forkOpts) : void 0,
388
- useServerProxy: this._useServerProxy
432
+ fork: resources?.cpu && resources.memory ? (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, name, resources, void 0, overrideRunId ?? runId, newSessionId, resourceId, teamId, forkOpts) : void 0
389
433
  }, replayCache, pendingInteractive);
390
434
  for (const [credName, { binding, source }] of boundCredentials) {
391
435
  const value = await resolveBoundCredential(credName, source, resolveCredential, newSessionId);
@@ -427,21 +471,24 @@ var Sandbox = class {
427
471
  */
428
472
  async connect(sandboxId, name, opts) {
429
473
  await this._ensureConnected();
430
- const state = (await this._control.getSandbox(sandboxId)).status.state;
431
- const paused = state === SandboxState.Paused;
432
- if (state !== SandboxState.Running && !(paused && opts?.allowPaused)) throw new SandboxClientError(`SandboxHandle ${sandboxId} is ${state} — can only connect to Running sandboxes` + (paused ? " (pass allowPaused to connect to a Paused one)" : ""), 409);
474
+ const info = await this._provider.getSandbox(sandboxId);
475
+ const state = info.nativeState ?? info.state;
476
+ const paused = info.state === "paused";
477
+ if (info.state !== "running" && !(paused && opts?.allowPaused)) throw new SandboxClientError(`SandboxHandle ${sandboxId} is ${state} — can only connect to Running sandboxes` + (paused ? " (pass allowPaused to connect to a Paused one)" : ""), 409, paused ? "SANDBOX_PAUSED" : "SANDBOX_NOT_RUNNING", { details: {
478
+ sandboxId,
479
+ state
480
+ } });
433
481
  await this._acquireSlot();
434
482
  const resources = opts?.resources;
435
483
  const handle = new SandboxHandle$1(sandboxId, name, {
436
- control: this._control,
484
+ provider: this._provider,
437
485
  adapter: this._adapter,
438
486
  sink: this._sink,
439
487
  credentialBroker: this._credentialBroker,
440
488
  onClose: () => {
441
489
  this._releaseSlot();
442
490
  },
443
- fork: resources ? (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, name, resources, void 0, overrideRunId ?? opts?.runId, sandboxId, opts?.resourceId, opts?.teamId, forkOpts) : void 0,
444
- useServerProxy: this._useServerProxy
491
+ fork: resources ? (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, name, resources, void 0, overrideRunId ?? opts?.runId, sandboxId, opts?.resourceId, opts?.teamId, forkOpts) : void 0
445
492
  });
446
493
  if (paused) handle.setPaused(true);
447
494
  return handle;
@@ -476,7 +523,7 @@ var Sandbox = class {
476
523
  await this._acquireSlot();
477
524
  try {
478
525
  const finalRunId = runId ?? crypto.randomUUID();
479
- const newId = (await this._control.createSandbox({
526
+ const newId = (await this._provider.createSandbox({
480
527
  snapshotId,
481
528
  env: opts?.env,
482
529
  resourceLimits: resources,
@@ -502,15 +549,14 @@ var Sandbox = class {
502
549
  }
503
550
  });
504
551
  return new SandboxHandle$1(newId, name, {
505
- control: this._control,
552
+ provider: this._provider,
506
553
  adapter: this._adapter,
507
554
  sink: this._sink,
508
555
  credentialBroker: this._credentialBroker,
509
556
  onClose: () => {
510
557
  this._releaseSlot();
511
558
  },
512
- fork: (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, name, resources, void 0, overrideRunId ?? finalRunId, newId, opts?.resourceId, opts?.teamId, forkOpts),
513
- useServerProxy: this._useServerProxy
559
+ fork: (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, name, resources, void 0, overrideRunId ?? finalRunId, newId, opts?.resourceId, opts?.teamId, forkOpts)
514
560
  });
515
561
  } catch (err) {
516
562
  this._releaseSlot();
@@ -611,7 +657,9 @@ var Sandbox = class {
611
657
  await this._ensureConnected();
612
658
  const record = await this._adapter.getEnvironment(name);
613
659
  if (record) {
614
- if ((await this._control.getSnapshot(record.snapshotId).catch(() => null))?.state === SnapshotState.Ready) return this._createFromSnapshot(record.snapshotId, opts.resources, name, opts.shell, extra);
660
+ if ((await this._provider.getSnapshot(record.snapshotId).catch(() => null))?.state === "ready") try {
661
+ return await this._createFromSnapshot(record.snapshotId, opts.resources, name, opts.shell, extra);
662
+ } catch {}
615
663
  }
616
664
  const snapshotId = await this._getOrBuildEnvironment(name, opts);
617
665
  return this._createFromSnapshot(snapshotId, opts.resources, name, opts.shell, extra);
@@ -653,7 +701,7 @@ var Sandbox = class {
653
701
  await this._acquireSlot();
654
702
  try {
655
703
  const runId = crypto.randomUUID();
656
- const newId = (await this._control.createSandbox({
704
+ const newId = (await this._provider.createSandbox({
657
705
  snapshotId,
658
706
  resourceLimits: resources,
659
707
  env: extra?.env,
@@ -679,7 +727,7 @@ var Sandbox = class {
679
727
  }
680
728
  });
681
729
  const sb = new SandboxHandle$1(newId, sessionName, {
682
- control: this._control,
730
+ provider: this._provider,
683
731
  adapter: this._adapter,
684
732
  sink: this._sink,
685
733
  credentialBroker: this._credentialBroker,
@@ -688,8 +736,7 @@ var Sandbox = class {
688
736
  this._releaseSlot();
689
737
  },
690
738
  shell: extra?.shell ?? envShell,
691
- fork: (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, sessionName, resources, extra?.shell ?? envShell, overrideRunId ?? runId, newId, resourceId, teamId, forkOpts),
692
- useServerProxy: this._useServerProxy
739
+ fork: (snapshotId, tag, overrideRunId, forkOpts) => this._forkFromSnapshot(snapshotId, sessionName, resources, extra?.shell ?? envShell, overrideRunId ?? runId, newId, resourceId, teamId, forkOpts)
693
740
  });
694
741
  extra?.hooks?.onSandboxCreated?.(newId, sessionName);
695
742
  return sb;
@@ -704,7 +751,7 @@ var Sandbox = class {
704
751
  const finalRunId = runId ?? crypto.randomUUID();
705
752
  const finalResourceId = forkOpts?.resourceId ?? resourceId;
706
753
  const finalTeamId = forkOpts?.teamId ?? teamId;
707
- const newId = (await this._control.createSandbox({
754
+ const newId = (await this._provider.createSandbox({
708
755
  snapshotId,
709
756
  resourceLimits: resources,
710
757
  metadata: { runId: finalRunId },
@@ -731,7 +778,7 @@ var Sandbox = class {
731
778
  }
732
779
  });
733
780
  return new SandboxHandle$1(newId, sessionName, {
734
- control: this._control,
781
+ provider: this._provider,
735
782
  adapter: this._adapter,
736
783
  sink: this._sink,
737
784
  credentialBroker: this._credentialBroker,
@@ -739,8 +786,7 @@ var Sandbox = class {
739
786
  this._releaseSlot();
740
787
  },
741
788
  shell,
742
- fork: (sid, tag, overrideRunId, nextForkOpts) => this._forkFromSnapshot(sid, sessionName, resources, shell, overrideRunId ?? finalRunId, newId, finalResourceId, finalTeamId, nextForkOpts),
743
- useServerProxy: this._useServerProxy
789
+ fork: (sid, tag, overrideRunId, nextForkOpts) => this._forkFromSnapshot(sid, sessionName, resources, shell, overrideRunId ?? finalRunId, newId, finalResourceId, finalTeamId, nextForkOpts)
744
790
  });
745
791
  } catch (err) {
746
792
  this._releaseSlot();
@@ -751,13 +797,19 @@ var Sandbox = class {
751
797
  const deadline = Date.now() + timeoutMs;
752
798
  let delay = 100;
753
799
  while (Date.now() < deadline) {
754
- const s = await this._control.getSandbox(sandboxId);
755
- if (s.status.state === SandboxState.Running) return;
756
- if (s.status.state === SandboxState.Failed || s.status.state === SandboxState.Terminated) throw new SandboxClientError(`SandboxHandle ${sandboxId} entered state ${s.status.state}: ${s.status.message ?? ""}`, 500);
800
+ const s = await this._provider.getSandbox(sandboxId);
801
+ if (s.state === "running") return;
802
+ if (s.state === "failed" || s.state === "terminated") throw new SandboxClientError(`SandboxHandle ${sandboxId} entered state ${s.nativeState ?? s.state}: ${s.message ?? ""}`, 500, "SANDBOX_START_FAILED", { details: {
803
+ sandboxId,
804
+ state: s.nativeState ?? s.state
805
+ } });
757
806
  await new Promise((r) => setTimeout(r, delay));
758
807
  delay = Math.min(delay * 1.5, 1e3);
759
808
  }
760
- throw new SandboxClientError(`SandboxHandle ${sandboxId} did not reach Running within ${timeoutMs}ms`, 408);
809
+ throw new SandboxClientError(`SandboxHandle ${sandboxId} did not reach Running within ${timeoutMs}ms`, 408, "SANDBOX_START_TIMEOUT", { details: {
810
+ sandboxId,
811
+ timeoutMs
812
+ } });
761
813
  }
762
814
  async _acquireSlot() {
763
815
  if (!this._maxConcurrency || this._activeCount < this._maxConcurrency) {
@@ -773,4 +825,36 @@ var Sandbox = class {
773
825
  }
774
826
  };
775
827
  //#endregion
776
- export { BashSession, CodeLanguage, CommandError, Environment, ExecConnectionError, LedgerEvent, OpenSandboxCredentialBroker, Sandbox, SandboxClientError, SandboxError, SandboxHandle, SandboxStatus, StepTimeoutError };
828
+ //#region src/provider-config.ts
829
+ /** The provider ids `providerFromConfig` can build. */
830
+ const KNOWN_PROVIDERS = ["opensandbox"];
831
+ /**
832
+ * Build the provider a config names.
833
+ *
834
+ * An id this build does not know is refused here, naming the ids it does know. Guessing
835
+ * OpenSandbox instead would run someone's agents on the wrong substrate without a word.
836
+ */
837
+ function providerFromConfig(config) {
838
+ const id = config.provider ?? "opensandbox";
839
+ switch (id) {
840
+ case "opensandbox": return new OpenSandboxProvider({
841
+ baseUrl: config.serverUrl,
842
+ apiKey: config.apiKey ?? "",
843
+ useServerProxy: config.useServerProxy ?? false
844
+ });
845
+ default: throw new SandboxClientError(`Unknown sandbox provider "${id}". Known providers: ${KNOWN_PROVIDERS.join(", ")}.`, 400, "INVALID_ARGUMENT");
846
+ }
847
+ }
848
+ /**
849
+ * A {@link Sandbox} client for the provider a config names. Every CLI command and the agent
850
+ * runtime build their client through this, so the provider is chosen in one place.
851
+ */
852
+ function clientFromConfig(config, options) {
853
+ return new Sandbox({
854
+ ...options,
855
+ provider: providerFromConfig(config),
856
+ useServerProxy: config.useServerProxy ?? false
857
+ });
858
+ }
859
+ //#endregion
860
+ export { AlineoError, BashSession, CodeLanguage, CommandError, Environment, ExecConnectionError, KNOWN_PROVIDERS, LedgerEvent, OpenSandboxCredentialBroker, Sandbox, SandboxClientError, SandboxError, SandboxHandle, SandboxStatus, StepTimeoutError, clientFromConfig, errorCodeOf, isAlineoError, isRetryable, providerFromConfig };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/sandbox",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -29,10 +29,12 @@
29
29
  "test:watch": "vitest"
30
30
  },
31
31
  "dependencies": {
32
- "@alineo-labs/core": "0.5.0",
33
- "@alineo-labs/opensandbox": "0.3.2",
34
- "@alineo-labs/schema": "0.2.0",
35
- "@alineo-labs/vault": "0.3.3"
32
+ "@alineo-labs/core": "0.6.0",
33
+ "@alineo-labs/errors": "0.1.0",
34
+ "@alineo-labs/opensandbox": "0.4.0",
35
+ "@alineo-labs/provider": "0.1.0",
36
+ "@alineo-labs/schema": "0.3.0",
37
+ "@alineo-labs/vault": "0.4.0"
36
38
  },
37
39
  "devDependencies": {
38
40
  "bun-types": "1.4.2",