@sistemo/sdk 0.1.1 → 0.1.3

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/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @sistemo/sdk (JavaScript / TypeScript)
2
2
 
3
- Run AI agents and untrusted code in **real isolated Firecracker microVMs** — self-host for free or use the cloud.
3
+ Run AI agents and untrusted code in **real isolated Firecracker microVMs**
4
4
 
5
5
  ```bash
6
6
  npm install @sistemo/sdk
@@ -49,7 +49,8 @@ Or pass them explicitly: `Sandbox.create({ apiKey: "sk_live_…", baseUrl: "http
49
49
 
50
50
  ```ts
51
51
  const sb = await Sandbox.create({ vcpus: 1, memoryMb: 1024, stack: "base" });
52
- const res = await sb.run("echo hi && uname -a", 30); // -> { exitCode, stdout, stderr }
52
+ const res = await sb.run("echo hi && uname -a"); // -> { exitCode, stdout, stderr, truncated, requestId } (default 120s, max 24h)
53
+ await sb.run("node app.js", 120, { env: { FOO: "bar" }, cwd: "/tmp" });
53
54
  await sb.close(); // destroy
54
55
  ```
55
56
 
@@ -69,7 +70,7 @@ try {
69
70
  // quota refusal does once you free the resource it names.
70
71
  if (e instanceof QuotaExceededError) { console.log(e.detail); }
71
72
  else if (e instanceof AuthError) { /* 401/403 — key invalid or read-only */ }
72
- else if (e instanceof APIError) { console.log(e.status, e.detail, e.code); }
73
+ else if (e instanceof APIError) { console.log(e.status, e.detail, e.code, e.requestId); }
73
74
  }
74
75
  ```
75
76
 
@@ -77,4 +78,72 @@ try {
77
78
  dimension bound and how much is in use, and `GET /v1/quotas` reports every limit
78
79
  alongside current usage.
79
80
 
81
+ Every request sends `X-Request-Id`. Quote `e.requestId` when you contact support.
82
+ On `429`, the client honours `Retry-After` (capped at 60 s) from version 0.1.3.
83
+
80
84
  Apache-2.0.
85
+
86
+ ## Long-running commands
87
+
88
+ `sb.run()` starts a guest job and waits for it on your machine (default **120
89
+ seconds**, maximum 24 hours). Each poll is a short request, so a proxy never
90
+ holds a connection for the whole command. Pass a longer timeout for installs
91
+ and builds:
92
+
93
+ ```ts
94
+ const sb = await Sandbox.create();
95
+ try {
96
+ const r = await sb.run("npm ci && npm run build", 3600);
97
+ console.log(r.exitCode);
98
+ } finally {
99
+ await sb.close();
100
+ }
101
+ ```
102
+
103
+ `sb.start()` returns the handle without waiting, when you want to stream,
104
+ cancel, or reconnect:
105
+
106
+ ```ts
107
+ const sb = await Sandbox.create();
108
+ try {
109
+ const job = await sb.start("npm ci && npm run build", 3600);
110
+
111
+ for await (const chunk of job.stream()) process.stdout.write(chunk);
112
+
113
+ await job.wait();
114
+ console.log(job.state, job.exitCode);
115
+ } finally {
116
+ await sb.close();
117
+ }
118
+ ```
119
+
120
+ The handle outlives the process that created it, so a crashed client can
121
+ reconnect with `sb.job(execId)` or list what is running with `sb.jobs()`.
122
+
123
+ ### Three things worth knowing
124
+
125
+ **`exitCode` is `null` until it is known** — and `null` forever if the job is
126
+ `lost`. It is never `0` as a placeholder, because a zero would read as success.
127
+ Branch on `state`, or use `job.ok`.
128
+
129
+ **`lost` is not `failed`.** `failed` means the command ran and returned non-zero.
130
+ `lost` means the machine could not account for it — neither that it ran nor that
131
+ it did not. Do not retry blindly and do not assume completion.
132
+
133
+ **A failed `start()` may still have started something.** On
134
+ `ExecStartUnconfirmed` the command may be running; the error carries the handle:
135
+
136
+ ```ts
137
+ let job;
138
+ try {
139
+ job = await sb.start("./deploy.sh");
140
+ } catch (e) {
141
+ if (!(e instanceof ExecStartUnconfirmed)) throw e;
142
+ job = await sb.job(e.execId); // find out what actually happened
143
+ }
144
+ await job.wait();
145
+ ```
146
+
147
+ You mint `execId` (a UUID is generated if you omit it). Re-sending the same id
148
+ is a 409 and returns the existing job, not a second run. If start throws
149
+ `ExecStartUnconfirmed`, poll that id — do not start again.
package/dist/index.d.ts CHANGED
@@ -16,13 +16,28 @@ export declare class APIError extends SistemoError {
16
16
  readonly status: number;
17
17
  readonly detail: string;
18
18
  readonly code?: string;
19
- constructor(status: number, detail: string, code?: string);
19
+ /**
20
+ * The parsed response body, when there was one.
21
+ *
22
+ * Some errors carry a field the caller genuinely needs — a failed `start()`
23
+ * returns the `exec_id` of a command that may well be running, and throwing
24
+ * that away would leave it unaddressable.
25
+ */
26
+ readonly body: Record<string, unknown>;
27
+ /** Seconds from `Retry-After`, capped at 60. */
28
+ readonly retryAfter?: number;
29
+ private readonly explicitRequestId?;
30
+ constructor(status: number, detail: string, code?: string, body?: Record<string, unknown>, extra?: {
31
+ retryAfter?: number;
32
+ requestId?: string;
33
+ });
34
+ get requestId(): string | undefined;
20
35
  }
21
36
  /** 401/403 — key missing, invalid, revoked, or a read-only key on a mutation. */
22
37
  export declare class AuthError extends APIError {
23
38
  }
24
39
  /**
25
- * 403 `quota_exceeded` — an account limit was reached.
40
+ * 403 `quota_exceeded` — this request would exceed an account limit.
26
41
  *
27
42
  * Deliberately NOT an `AuthError`, even though both arrive as 403. They need
28
43
  * opposite handling, and conflating them sends callers to the wrong place:
@@ -44,6 +59,48 @@ export declare class NotFoundError extends APIError {
44
59
  /** 429 — rate limited. */
45
60
  export declare class RateLimitError extends APIError {
46
61
  }
62
+ /**
63
+ * 410 — it existed and is no longer retained.
64
+ *
65
+ * Deliberately NOT a `NotFoundError`. Telling a caller their job never existed,
66
+ * when in fact its record or output aged out, invites them to re-run work that
67
+ * already ran.
68
+ */
69
+ export declare class GoneError extends APIError {
70
+ }
71
+ /**
72
+ * 501 — this machine's image predates async exec.
73
+ *
74
+ * **Do not retry.** The in-guest agent is baked into the image, so the answer
75
+ * cannot change until the image is rebuilt (or the agent is updated in place).
76
+ * Deliberately distinct from a 502/503, which mean "ask again".
77
+ */
78
+ export declare class AsyncExecUnsupportedError extends APIError {
79
+ }
80
+ /**
81
+ * 503 — we could not confirm the command started, and it **may be running**.
82
+ *
83
+ * This is not a failure. The most dangerous thing a caller can do here is treat
84
+ * it as one and start the command again. `execId` is the handle:
85
+ *
86
+ * ```ts
87
+ * try {
88
+ * job = await sb.start("./deploy.sh");
89
+ * } catch (e) {
90
+ * if (e instanceof ExecStartUnconfirmed) job = await sb.job(e.execId);
91
+ * }
92
+ * ```
93
+ */
94
+ export declare class ExecStartUnconfirmed extends APIError {
95
+ get execId(): string;
96
+ }
97
+ /** Seconds from a Retry-After header (delta-seconds or HTTP-date), capped at 60. */
98
+ export declare function parseRetryAfter(value: string | null | undefined): number | undefined;
99
+ /** Milliseconds to wait before the next attempt. Tests pass `rand` so they do not sleep. */
100
+ export declare function retryDelayMs(attempt: number, backoffMs: number, maxBackoffMs: number, err?: {
101
+ status: number;
102
+ retryAfter?: number;
103
+ }, rand?: () => number): number;
47
104
  export interface ClientOptions {
48
105
  apiKey?: string;
49
106
  baseUrl?: string;
@@ -66,6 +123,7 @@ export interface RequestOptions {
66
123
  /** Low-level API client. Most users want {@link Sandbox} instead. */
67
124
  export declare class Client {
68
125
  readonly baseUrl: string;
126
+ lastRequestId?: string;
69
127
  private readonly apiKey;
70
128
  private readonly timeoutMs;
71
129
  private readonly maxRetries;
@@ -110,6 +168,8 @@ export interface ExecResult {
110
168
  exitCode: number;
111
169
  stdout: string;
112
170
  stderr: string;
171
+ truncated?: boolean;
172
+ requestId?: string;
113
173
  }
114
174
  export interface SandboxOptions extends ClientOptions {
115
175
  client?: Client;
@@ -133,8 +193,152 @@ export declare class Sandbox {
133
193
  private constructor();
134
194
  /** Provision a new microVM (resolves once it has booted). */
135
195
  static create(opts?: SandboxOptions): Promise<Sandbox>;
136
- /** Run a shell command/script inside the sandbox. */
137
- run(script: string, timeoutSec?: number): Promise<ExecResult>;
196
+ /**
197
+ * Run a shell command/script inside the sandbox and return its output.
198
+ *
199
+ * This is start + wait on a guest job (`POST /execs`). Default timeout 120s,
200
+ * ceiling 24 hours. A proxy never holds the connection for the whole command.
201
+ */
202
+ run(script: string, timeoutSec?: number, opts?: {
203
+ env?: Record<string, string>;
204
+ cwd?: string;
205
+ }): Promise<ExecResult>;
206
+ /**
207
+ * Start a command and return a handle without waiting.
208
+ *
209
+ * {@link run} is start + wait — use this to stream, cancel, or reconnect.
210
+ * Same guest job, same timeout ceiling (24 hours).
211
+ *
212
+ * ⚠ You mint `execId` (a UUID is generated if you omit it). If the start
213
+ * response is lost, poll that id rather than starting again. Re-sending the
214
+ * same id is a 409, not a second run.
215
+ *
216
+ * ⚠ On {@link ExecStartUnconfirmed} the command **may be running**. The error
217
+ * carries `execId`; poll it with {@link job} rather than starting over.
218
+ */
219
+ start(script: string, timeoutSec?: number, opts?: {
220
+ execId?: string;
221
+ env?: Record<string, string>;
222
+ cwd?: string;
223
+ }): Promise<Job>;
224
+ /** Re-attach to a job by id — after a crash, or after an unconfirmed start. */
225
+ job(execId: string): Promise<Job>;
226
+ /** List this sandbox's async jobs, newest first. */
227
+ jobs(limit?: number): Promise<Job[]>;
138
228
  /** Destroy the sandbox (and its disk unless `preserveStorage`). */
139
229
  close(preserveStorage?: boolean): Promise<void>;
140
230
  }
231
+ interface JobRecord {
232
+ exec_id?: string;
233
+ machine_id?: string;
234
+ state?: string;
235
+ exit_code?: number | null;
236
+ stdout_bytes?: number;
237
+ stderr_bytes?: number;
238
+ truncated?: boolean;
239
+ started_at?: string | null;
240
+ finished_at?: string | null;
241
+ }
242
+ /**
243
+ * `wait()`/`stream()` gave up waiting.
244
+ *
245
+ * ⚠ The job is **still running** — this is your client's patience running out,
246
+ * not the command's. The handle stays valid; poll it again later.
247
+ */
248
+ export declare class JobTimeout extends SistemoError {
249
+ }
250
+ /**
251
+ * A handle on a command running inside a sandbox.
252
+ *
253
+ * The handle outlives the process that created it, so a crashed client can
254
+ * reconnect with `sb.job(execId)` or list what is running with `sb.jobs()`.
255
+ */
256
+ export declare class Job {
257
+ private readonly client;
258
+ private readonly sandboxId;
259
+ id: string;
260
+ machineId: string;
261
+ state: string;
262
+ requestId?: string;
263
+ /**
264
+ * ⚠ `null` until known, and null FOREVER when `state` is `"lost"`. Never
265
+ * coerce this to 0 — a zero here reads as "the command succeeded".
266
+ */
267
+ exitCode: number | null;
268
+ stdoutBytes: number;
269
+ stderrBytes: number;
270
+ truncated: boolean;
271
+ startedAt: string | null;
272
+ finishedAt: string | null;
273
+ constructor(client: Client, sandboxId: string, rec: JobRecord);
274
+ private apply;
275
+ /** Whether the job reached a terminal state. */
276
+ get done(): boolean;
277
+ /**
278
+ * `true` only for a command that finished and exited 0.
279
+ *
280
+ * ⚠ A `lost` job is never ok, because we cannot say that it worked — and a
281
+ * property that guessed would be worse than no property.
282
+ */
283
+ get ok(): boolean;
284
+ /**
285
+ * The machine could not account for this job.
286
+ *
287
+ * ⚠ Not the same as failed. `failed` means it ran and returned non-zero;
288
+ * `lost` means we can say neither that it ran nor that it did not.
289
+ */
290
+ get lost(): boolean;
291
+ /** Re-read the job's state from the API. */
292
+ refresh(): Promise<this>;
293
+ /**
294
+ * Resolve once the job reaches a terminal state.
295
+ *
296
+ * The waiting happens **client-side**: each poll is a fast request, so no
297
+ * proxy between you and the API is ever holding a long connection.
298
+ *
299
+ * Rejects with {@link JobTimeout} if `timeoutMs` elapses first — ⚠ which does
300
+ * not stop the job. Call {@link cancel} if that is what you meant.
301
+ */
302
+ wait(opts?: {
303
+ timeoutMs?: number;
304
+ pollIntervalMs?: number;
305
+ }): Promise<this>;
306
+ /**
307
+ * Stop the job: SIGTERM, a short grace period, then SIGKILL.
308
+ *
309
+ * Cancelling a job that already finished is a no-op, so a retried cancel is
310
+ * safe.
311
+ */
312
+ cancel(): Promise<this>;
313
+ /**
314
+ * Yield raw output bytes as they are produced, until the job ends.
315
+ *
316
+ * ⚠ Chunks split on BYTE boundaries and one can end mid-character. Use
317
+ * {@link stream} unless you actually want bytes.
318
+ */
319
+ streamBytes(opts?: {
320
+ stream?: "stdout" | "stderr";
321
+ pollIntervalMs?: number;
322
+ timeoutMs?: number;
323
+ limit?: number;
324
+ }): AsyncGenerator<Uint8Array>;
325
+ /**
326
+ * Yield output as text as it is produced.
327
+ *
328
+ * ⚠ Decoding is INCREMENTAL (`TextDecoder` with `stream: true`). A page can
329
+ * end in the middle of a multi-byte character, and decoding each page on its
330
+ * own would corrupt every character that straddles a boundary — which, at a
331
+ * 64 KiB page size, is rare enough to survive testing and common enough to
332
+ * corrupt real logs.
333
+ */
334
+ stream(opts?: {
335
+ stream?: "stdout" | "stderr";
336
+ pollIntervalMs?: number;
337
+ timeoutMs?: number;
338
+ }): AsyncGenerator<string>;
339
+ /** Read everything written to a stream so far, without waiting. */
340
+ output(which?: "stdout" | "stderr"): Promise<Uint8Array>;
341
+ /** {@link output} decoded as text. */
342
+ logs(which?: "stdout" | "stderr"): Promise<string>;
343
+ }
344
+ export {};
package/dist/index.js CHANGED
@@ -15,7 +15,7 @@ const DEFAULT_BASE_URL = "https://api.sistemo.io";
15
15
  // User-Agent is required: the production WAF (Cloudflare) blocks generic
16
16
  // library UAs with a 403. Browsers ignore attempts to set User-Agent and send
17
17
  // their own (which the WAF allows), so this is a no-op there.
18
- const USER_AGENT = "@sistemo/sdk/0.1.1";
18
+ const USER_AGENT = "@sistemo/sdk/0.1.3";
19
19
  const RETRY_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
20
20
  export class SistemoError extends Error {
21
21
  }
@@ -23,19 +23,39 @@ export class APIError extends SistemoError {
23
23
  status;
24
24
  detail;
25
25
  code;
26
- constructor(status, detail, code) {
26
+ /**
27
+ * The parsed response body, when there was one.
28
+ *
29
+ * Some errors carry a field the caller genuinely needs — a failed `start()`
30
+ * returns the `exec_id` of a command that may well be running, and throwing
31
+ * that away would leave it unaddressable.
32
+ */
33
+ body;
34
+ /** Seconds from `Retry-After`, capped at 60. */
35
+ retryAfter;
36
+ explicitRequestId;
37
+ constructor(status, detail, code, body, extra) {
27
38
  super(`[${status}] ${detail}${code ? ` (${code})` : ""}`);
28
39
  this.name = "APIError";
29
40
  this.status = status;
30
41
  this.detail = detail;
31
42
  this.code = code;
43
+ this.body = body ?? {};
44
+ this.retryAfter = extra?.retryAfter;
45
+ this.explicitRequestId = extra?.requestId;
46
+ }
47
+ get requestId() {
48
+ if (this.explicitRequestId)
49
+ return this.explicitRequestId;
50
+ const v = this.body.request_id;
51
+ return typeof v === "string" ? v : undefined;
32
52
  }
33
53
  }
34
54
  /** 401/403 — key missing, invalid, revoked, or a read-only key on a mutation. */
35
55
  export class AuthError extends APIError {
36
56
  }
37
57
  /**
38
- * 403 `quota_exceeded` — an account limit was reached.
58
+ * 403 `quota_exceeded` — this request would exceed an account limit.
39
59
  *
40
60
  * Deliberately NOT an `AuthError`, even though both arrive as 403. They need
41
61
  * opposite handling, and conflating them sends callers to the wrong place:
@@ -57,17 +77,63 @@ export class NotFoundError extends APIError {
57
77
  /** 429 — rate limited. */
58
78
  export class RateLimitError extends APIError {
59
79
  }
60
- function apiError(status, detail, code) {
80
+ /**
81
+ * 410 — it existed and is no longer retained.
82
+ *
83
+ * Deliberately NOT a `NotFoundError`. Telling a caller their job never existed,
84
+ * when in fact its record or output aged out, invites them to re-run work that
85
+ * already ran.
86
+ */
87
+ export class GoneError extends APIError {
88
+ }
89
+ /**
90
+ * 501 — this machine's image predates async exec.
91
+ *
92
+ * **Do not retry.** The in-guest agent is baked into the image, so the answer
93
+ * cannot change until the image is rebuilt (or the agent is updated in place).
94
+ * Deliberately distinct from a 502/503, which mean "ask again".
95
+ */
96
+ export class AsyncExecUnsupportedError extends APIError {
97
+ }
98
+ /**
99
+ * 503 — we could not confirm the command started, and it **may be running**.
100
+ *
101
+ * This is not a failure. The most dangerous thing a caller can do here is treat
102
+ * it as one and start the command again. `execId` is the handle:
103
+ *
104
+ * ```ts
105
+ * try {
106
+ * job = await sb.start("./deploy.sh");
107
+ * } catch (e) {
108
+ * if (e instanceof ExecStartUnconfirmed) job = await sb.job(e.execId);
109
+ * }
110
+ * ```
111
+ */
112
+ export class ExecStartUnconfirmed extends APIError {
113
+ get execId() {
114
+ return String(this.body.exec_id ?? "");
115
+ }
116
+ }
117
+ function apiError(status, detail, code, body, extra) {
61
118
  // 403 is two different things, told apart by `code` — never by the status.
62
119
  if (status === 403 && code === "quota_exceeded")
63
- return new QuotaExceededError(status, detail, code);
120
+ return new QuotaExceededError(status, detail, code, body, extra);
64
121
  if (status === 401 || status === 403)
65
- return new AuthError(status, detail, code);
122
+ return new AuthError(status, detail, code, body, extra);
66
123
  if (status === 404)
67
- return new NotFoundError(status, detail, code);
124
+ return new NotFoundError(status, detail, code, body, extra);
125
+ if (status === 410)
126
+ return new GoneError(status, detail, code, body, extra);
68
127
  if (status === 429)
69
- return new RateLimitError(status, detail, code);
70
- return new APIError(status, detail, code);
128
+ return new RateLimitError(status, detail, code, body, extra);
129
+ if (status === 501)
130
+ return new AsyncExecUnsupportedError(status, detail, code, body, extra);
131
+ // ⚠ Only a 503 that NAMES an exec is the unconfirmed-start case. A plain 503
132
+ // (no host available, say) is an ordinary retryable error and must not be
133
+ // dressed up as a command that might be running.
134
+ if (status === 503 && body && body.exec_id)
135
+ return new ExecStartUnconfirmed(status, detail, code, body, extra);
136
+ return new APIError(status, detail, code, body, extra);
71
137
  }
72
138
  function newIdempotencyKey() {
73
139
  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
@@ -78,9 +144,44 @@ function newIdempotencyKey() {
78
144
  function sleep(ms) {
79
145
  return new Promise((r) => setTimeout(r, ms));
80
146
  }
147
+ const RETRY_AFTER_CAP_SEC = 60;
148
+ /** Seconds from a Retry-After header (delta-seconds or HTTP-date), capped at 60. */
149
+ export function parseRetryAfter(value) {
150
+ if (value == null || value === "")
151
+ return undefined;
152
+ const text = String(value).trim();
153
+ if (/^-?\d+$/.test(text)) {
154
+ const secs = Number(text);
155
+ if (!Number.isFinite(secs) || secs < 0)
156
+ return undefined;
157
+ return Math.min(secs, RETRY_AFTER_CAP_SEC);
158
+ }
159
+ const ms = Date.parse(text);
160
+ if (Number.isNaN(ms))
161
+ return undefined;
162
+ const delay = (ms - Date.now()) / 1000;
163
+ if (delay < 0)
164
+ return 0;
165
+ return Math.min(delay, RETRY_AFTER_CAP_SEC);
166
+ }
167
+ /** Milliseconds to wait before the next attempt. Tests pass `rand` so they do not sleep. */
168
+ export function retryDelayMs(attempt, backoffMs, maxBackoffMs, err, rand = Math.random) {
169
+ const base = Math.min(maxBackoffMs, backoffMs * 2 ** attempt);
170
+ let delay = base * (0.5 + rand());
171
+ if (err?.status === 429) {
172
+ if (err.retryAfter == null) {
173
+ delay = Math.max(delay, base);
174
+ }
175
+ else {
176
+ delay = Math.min(Math.max(delay, err.retryAfter * 1000), RETRY_AFTER_CAP_SEC * 1000);
177
+ }
178
+ }
179
+ return delay;
180
+ }
81
181
  /** Low-level API client. Most users want {@link Sandbox} instead. */
82
182
  export class Client {
83
183
  baseUrl;
184
+ lastRequestId;
84
185
  apiKey;
85
186
  timeoutMs;
86
187
  maxRetries;
@@ -104,9 +205,23 @@ export class Client {
104
205
  const retries = opts.maxRetries ?? this.maxRetries;
105
206
  const methodU = method.toUpperCase();
106
207
  let lastErr;
208
+ const headers = { ...(opts.headers ?? {}) };
209
+ let reqId;
210
+ for (const [k, v] of Object.entries(headers)) {
211
+ if (k.toLowerCase() === "x-request-id" && v) {
212
+ reqId = v;
213
+ break;
214
+ }
215
+ }
216
+ if (!reqId) {
217
+ reqId = newIdempotencyKey();
218
+ headers["X-Request-Id"] = reqId;
219
+ }
220
+ this.lastRequestId = reqId;
221
+ const next = { ...opts, headers };
107
222
  for (let attempt = 0; attempt <= retries; attempt++) {
108
223
  try {
109
- return await this.once(methodU, path, body, opts);
224
+ return await this.once(methodU, path, body, next);
110
225
  }
111
226
  catch (e) {
112
227
  lastErr = e;
@@ -153,15 +268,27 @@ export class Client {
153
268
  if (!res.ok) {
154
269
  let detail = "request failed";
155
270
  let code;
271
+ let body;
156
272
  try {
157
273
  const parsed = JSON.parse(text);
158
- detail = parsed.detail ?? detail;
274
+ // Some errors use `error` rather than `detail` (an unconfirmed exec
275
+ // start is the live example), so fall back rather than reporting
276
+ // "request failed" over a message that was right there.
277
+ detail = parsed.detail ?? parsed.error ?? detail;
159
278
  code = parsed.code;
279
+ if (parsed && typeof parsed === "object")
280
+ body = parsed;
160
281
  }
161
282
  catch {
162
283
  /* non-JSON error body */
163
284
  }
164
- throw apiError(res.status, detail, code);
285
+ const retryAfter = parseRetryAfter(res.headers.get("Retry-After"));
286
+ let requestId;
287
+ if (body && typeof body.request_id === "string")
288
+ requestId = body.request_id;
289
+ if (!requestId)
290
+ requestId = res.headers.get("X-Request-Id") ?? this.lastRequestId;
291
+ throw apiError(res.status, detail, code, body, { retryAfter, requestId: requestId ?? undefined });
165
292
  }
166
293
  return (text ? JSON.parse(text) : {});
167
294
  }
@@ -174,11 +301,7 @@ export class Client {
174
301
  return Boolean(idempotencyKey);
175
302
  }
176
303
  async backoff(attempt, err) {
177
- const base = Math.min(this.retryMaxBackoffMs, this.retryBackoffMs * 2 ** attempt);
178
- let delay = base * (0.5 + Math.random());
179
- if (err?.status === 429)
180
- delay = Math.max(delay, base);
181
- await sleep(delay);
304
+ await sleep(retryDelayMs(attempt, this.retryBackoffMs, this.retryMaxBackoffMs, err));
182
305
  }
183
306
  // --- volumes (incl. detachable root volumes) ---------------------------
184
307
  /** List the account's volumes (root and data). */
@@ -236,21 +359,326 @@ export class Sandbox {
236
359
  }
237
360
  return new Sandbox(client, machine.id, machine.state ?? "");
238
361
  }
239
- /** Run a shell command/script inside the sandbox. */
240
- async run(script, timeoutSec = 30) {
241
- // No Idempotency-Key: HTTP errors are not retried (would re-run the script).
242
- // Connection failures still use the client's connection-retry path only when
243
- // they throw SistemoError before a response — see Client.request.
244
- const out = await this.client.request("POST", `/v1/machines/${this.id}/exec`, { script, timeout_sec: timeoutSec });
362
+ /**
363
+ * Run a shell command/script inside the sandbox and return its output.
364
+ *
365
+ * This is start + wait on a guest job (`POST /execs`). Default timeout 120s,
366
+ * ceiling 24 hours. A proxy never holds the connection for the whole command.
367
+ */
368
+ async run(script, timeoutSec = 120, opts = {}) {
369
+ const execId = newIdempotencyKey();
370
+ let job;
371
+ try {
372
+ job = await this.start(script, timeoutSec, { execId, ...opts });
373
+ }
374
+ catch (e) {
375
+ if (e instanceof ExecStartUnconfirmed) {
376
+ job = await this.job(execId);
377
+ }
378
+ else {
379
+ throw e;
380
+ }
381
+ }
382
+ await job.wait();
383
+ const dec = new TextDecoder("utf-8");
245
384
  return {
246
- exitCode: out.exit_code ?? -1,
247
- stdout: out.stdout ?? "",
248
- stderr: out.stderr ?? "",
385
+ exitCode: job.exitCode ?? -1,
386
+ stdout: dec.decode(await job.output("stdout")),
387
+ stderr: dec.decode(await job.output("stderr")),
388
+ truncated: job.truncated,
389
+ requestId: job.requestId,
249
390
  };
250
391
  }
392
+ /**
393
+ * Start a command and return a handle without waiting.
394
+ *
395
+ * {@link run} is start + wait — use this to stream, cancel, or reconnect.
396
+ * Same guest job, same timeout ceiling (24 hours).
397
+ *
398
+ * ⚠ You mint `execId` (a UUID is generated if you omit it). If the start
399
+ * response is lost, poll that id rather than starting again. Re-sending the
400
+ * same id is a 409, not a second run.
401
+ *
402
+ * ⚠ On {@link ExecStartUnconfirmed} the command **may be running**. The error
403
+ * carries `execId`; poll it with {@link job} rather than starting over.
404
+ */
405
+ async start(script, timeoutSec = 120, opts = {}) {
406
+ const execId = opts.execId ?? newIdempotencyKey();
407
+ const body = { exec_id: execId, script, timeout_sec: timeoutSec };
408
+ if (opts.env && Object.keys(opts.env).length)
409
+ body.env = opts.env;
410
+ if (opts.cwd)
411
+ body.cwd = opts.cwd;
412
+ try {
413
+ const rec = await this.client.request("POST", `/v1/machines/${this.id}/execs`, body);
414
+ return new Job(this.client, this.id, rec);
415
+ }
416
+ catch (e) {
417
+ if (e instanceof APIError && e.status === 409) {
418
+ if (e.code === "too_many_execs" ||
419
+ e.code === "machine_process_limit" ||
420
+ e.code === "machine_disk_full" ||
421
+ e.code === "machine_out_of_memory" ||
422
+ e.code === "machine_not_running") {
423
+ throw e;
424
+ }
425
+ try {
426
+ const rec = await this.client.request("GET", `/v1/machines/${this.id}/execs/${execId}`);
427
+ return new Job(this.client, this.id, rec);
428
+ }
429
+ catch (inner) {
430
+ if (inner instanceof NotFoundError)
431
+ throw e;
432
+ throw inner;
433
+ }
434
+ }
435
+ throw e;
436
+ }
437
+ }
438
+ /** Re-attach to a job by id — after a crash, or after an unconfirmed start. */
439
+ async job(execId) {
440
+ const rec = await this.client.request("GET", `/v1/machines/${this.id}/execs/${execId}`);
441
+ return new Job(this.client, this.id, rec);
442
+ }
443
+ /** List this sandbox's async jobs, newest first. */
444
+ async jobs(limit = 50) {
445
+ const out = await this.client.request("GET", `/v1/machines/${this.id}/execs?limit=${limit}`);
446
+ return (out.execs ?? []).map((r) => new Job(this.client, this.id, r));
447
+ }
251
448
  /** Destroy the sandbox (and its disk unless `preserveStorage`). */
252
449
  async close(preserveStorage = false) {
253
450
  const q = preserveStorage ? "?preserve_storage=true" : "";
254
451
  await this.client.request("DELETE", `/v1/machines/${this.id}${q}`);
255
452
  }
256
453
  }
454
+ // ── Async exec ────────────────────────────────────────────────────────
455
+ /** States that mean nothing further will happen. */
456
+ const TERMINAL = new Set(["succeeded", "failed", "cancelled", "expired", "lost"]);
457
+ /**
458
+ * `wait()`/`stream()` gave up waiting.
459
+ *
460
+ * ⚠ The job is **still running** — this is your client's patience running out,
461
+ * not the command's. The handle stays valid; poll it again later.
462
+ */
463
+ export class JobTimeout extends SistemoError {
464
+ }
465
+ /**
466
+ * A handle on a command running inside a sandbox.
467
+ *
468
+ * The handle outlives the process that created it, so a crashed client can
469
+ * reconnect with `sb.job(execId)` or list what is running with `sb.jobs()`.
470
+ */
471
+ export class Job {
472
+ client;
473
+ sandboxId;
474
+ id = "";
475
+ machineId = "";
476
+ state = "";
477
+ requestId;
478
+ /**
479
+ * ⚠ `null` until known, and null FOREVER when `state` is `"lost"`. Never
480
+ * coerce this to 0 — a zero here reads as "the command succeeded".
481
+ */
482
+ exitCode = null;
483
+ stdoutBytes = 0;
484
+ stderrBytes = 0;
485
+ truncated = false;
486
+ startedAt = null;
487
+ finishedAt = null;
488
+ constructor(client, sandboxId, rec) {
489
+ this.client = client;
490
+ this.sandboxId = sandboxId;
491
+ this.requestId = client.lastRequestId;
492
+ this.apply(rec);
493
+ }
494
+ apply(rec) {
495
+ this.id = rec.exec_id ?? "";
496
+ this.machineId = rec.machine_id ?? "";
497
+ this.state = rec.state ?? "";
498
+ this.exitCode = rec.exit_code ?? null;
499
+ this.stdoutBytes = rec.stdout_bytes ?? 0;
500
+ this.stderrBytes = rec.stderr_bytes ?? 0;
501
+ this.truncated = rec.truncated ?? false;
502
+ this.startedAt = rec.started_at ?? null;
503
+ this.finishedAt = rec.finished_at ?? null;
504
+ return this;
505
+ }
506
+ /** Whether the job reached a terminal state. */
507
+ get done() {
508
+ return TERMINAL.has(this.state);
509
+ }
510
+ /**
511
+ * `true` only for a command that finished and exited 0.
512
+ *
513
+ * ⚠ A `lost` job is never ok, because we cannot say that it worked — and a
514
+ * property that guessed would be worse than no property.
515
+ */
516
+ get ok() {
517
+ return this.state === "succeeded" && this.exitCode === 0;
518
+ }
519
+ /**
520
+ * The machine could not account for this job.
521
+ *
522
+ * ⚠ Not the same as failed. `failed` means it ran and returned non-zero;
523
+ * `lost` means we can say neither that it ran nor that it did not.
524
+ */
525
+ get lost() {
526
+ return this.state === "lost";
527
+ }
528
+ /** Re-read the job's state from the API. */
529
+ async refresh() {
530
+ return this.apply(await this.client.request("GET", `/v1/machines/${this.sandboxId}/execs/${this.id}`));
531
+ }
532
+ /**
533
+ * Resolve once the job reaches a terminal state.
534
+ *
535
+ * The waiting happens **client-side**: each poll is a fast request, so no
536
+ * proxy between you and the API is ever holding a long connection.
537
+ *
538
+ * Rejects with {@link JobTimeout} if `timeoutMs` elapses first — ⚠ which does
539
+ * not stop the job. Call {@link cancel} if that is what you meant.
540
+ */
541
+ async wait(opts = {}) {
542
+ const poll = opts.pollIntervalMs ?? 1000;
543
+ const deadline = opts.timeoutMs === undefined ? undefined : Date.now() + opts.timeoutMs;
544
+ for (;;) {
545
+ if (this.done)
546
+ return this;
547
+ if (deadline !== undefined && Date.now() >= deadline) {
548
+ throw new JobTimeout(`job ${this.id} is still ${this.state} after ${opts.timeoutMs}ms ` +
549
+ `(it is still running; poll it again or cancel it)`);
550
+ }
551
+ // Refresh BEFORE sleeping. POST /execs returns running immediately, so a
552
+ // hello-world `sb.run("echo hi")` would otherwise wait a full poll
553
+ // interval for a command that finished in milliseconds.
554
+ await this.refresh();
555
+ if (this.done)
556
+ return this;
557
+ if (deadline === undefined) {
558
+ await sleep(poll);
559
+ }
560
+ else {
561
+ const remaining = deadline - Date.now();
562
+ if (remaining <= 0) {
563
+ throw new JobTimeout(`job ${this.id} is still ${this.state} after ${opts.timeoutMs}ms ` +
564
+ `(it is still running; poll it again or cancel it)`);
565
+ }
566
+ await sleep(Math.min(poll, remaining));
567
+ }
568
+ }
569
+ }
570
+ /**
571
+ * Stop the job: SIGTERM, a short grace period, then SIGKILL.
572
+ *
573
+ * Cancelling a job that already finished is a no-op, so a retried cancel is
574
+ * safe.
575
+ */
576
+ async cancel() {
577
+ return this.apply(await this.client.request("DELETE", `/v1/machines/${this.sandboxId}/execs/${this.id}`));
578
+ }
579
+ /**
580
+ * Yield raw output bytes as they are produced, until the job ends.
581
+ *
582
+ * ⚠ Chunks split on BYTE boundaries and one can end mid-character. Use
583
+ * {@link stream} unless you actually want bytes.
584
+ */
585
+ async *streamBytes(opts = {}) {
586
+ const which = opts.stream ?? "stdout";
587
+ const poll = opts.pollIntervalMs ?? 500;
588
+ const limit = opts.limit ?? 65536;
589
+ const deadline = opts.timeoutMs === undefined ? undefined : Date.now() + opts.timeoutMs;
590
+ let offset = 0;
591
+ for (;;) {
592
+ const page = await this.client.request("GET", `/v1/machines/${this.sandboxId}/execs/${this.id}/output` +
593
+ `?stream=${which}&offset=${offset}&limit=${limit}`);
594
+ offset = page.next_offset ?? offset;
595
+ const data = page.data ? base64ToBytes(page.data) : new Uint8Array(0);
596
+ if (data.length > 0) {
597
+ yield data;
598
+ // ⚠ Loop straight back without sleeping. A producer faster than the
599
+ // poll interval would otherwise be read at one page per interval,
600
+ // turning a 30-second build log into minutes of trickle for no reason.
601
+ continue;
602
+ }
603
+ // ⚠ Stop on eof, NEVER on an empty page. An empty page from a running job
604
+ // means "nothing new yet"; treating it as the end truncates the output of
605
+ // every job that pauses to think.
606
+ if (page.eof)
607
+ return;
608
+ if (deadline !== undefined && Date.now() >= deadline) {
609
+ throw new JobTimeout(`job ${this.id} produced no further output within ${opts.timeoutMs}ms`);
610
+ }
611
+ await sleep(poll);
612
+ }
613
+ }
614
+ /**
615
+ * Yield output as text as it is produced.
616
+ *
617
+ * ⚠ Decoding is INCREMENTAL (`TextDecoder` with `stream: true`). A page can
618
+ * end in the middle of a multi-byte character, and decoding each page on its
619
+ * own would corrupt every character that straddles a boundary — which, at a
620
+ * 64 KiB page size, is rare enough to survive testing and common enough to
621
+ * corrupt real logs.
622
+ */
623
+ async *stream(opts = {}) {
624
+ const decoder = new TextDecoder("utf-8");
625
+ for await (const chunk of this.streamBytes(opts)) {
626
+ const text = decoder.decode(chunk, { stream: true });
627
+ if (text)
628
+ yield text;
629
+ }
630
+ // Flush whatever partial sequence is left, so a truncated final character
631
+ // surfaces as U+FFFD rather than silently disappearing.
632
+ const tail = decoder.decode();
633
+ if (tail)
634
+ yield tail;
635
+ }
636
+ /** Read everything written to a stream so far, without waiting. */
637
+ async output(which = "stdout") {
638
+ const parts = [];
639
+ let offset = 0;
640
+ for (;;) {
641
+ const page = await this.client.request("GET", `/v1/machines/${this.sandboxId}/execs/${this.id}/output` +
642
+ `?stream=${which}&offset=${offset}&limit=65536`);
643
+ const data = page.data ? base64ToBytes(page.data) : new Uint8Array(0);
644
+ if (data.length > 0)
645
+ parts.push(data);
646
+ const next = page.next_offset ?? offset;
647
+ if (data.length === 0 || next <= offset)
648
+ break;
649
+ offset = next;
650
+ }
651
+ const total = parts.reduce((n, p) => n + p.length, 0);
652
+ const out = new Uint8Array(total);
653
+ let at = 0;
654
+ for (const p of parts) {
655
+ out.set(p, at);
656
+ at += p.length;
657
+ }
658
+ return out;
659
+ }
660
+ /** {@link output} decoded as text. */
661
+ async logs(which = "stdout") {
662
+ return new TextDecoder("utf-8").decode(await this.output(which));
663
+ }
664
+ }
665
+ /**
666
+ * Decode base64 without assuming a runtime.
667
+ *
668
+ * ⚠ `atob` produces a string of char codes, not bytes — mapping through
669
+ * charCodeAt is what keeps binary output intact. Buffer is preferred where it
670
+ * exists because it skips that round trip entirely.
671
+ */
672
+ function base64ToBytes(b64) {
673
+ const g = globalThis;
674
+ if (typeof g.Buffer !== "undefined")
675
+ return new Uint8Array(g.Buffer.from(b64, "base64"));
676
+ if (typeof g.atob === "function") {
677
+ const bin = g.atob(b64);
678
+ const out = new Uint8Array(bin.length);
679
+ for (let i = 0; i < bin.length; i++)
680
+ out[i] = bin.charCodeAt(i);
681
+ return out;
682
+ }
683
+ throw new SistemoError("no base64 decoder available in this runtime");
684
+ }
package/package.json CHANGED
@@ -1,9 +1,11 @@
1
1
  {
2
2
  "name": "@sistemo/sdk",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "Run AI agents and untrusted code in real isolated microVMs.",
5
5
  "license": "Apache-2.0",
6
+ "author": "Sistemo",
6
7
  "type": "module",
8
+ "sideEffects": false,
7
9
  "main": "dist/index.js",
8
10
  "module": "dist/index.js",
9
11
  "types": "dist/index.d.ts",
@@ -24,7 +26,7 @@
24
26
  "scripts": {
25
27
  "build": "npm run clean && tsc -p tsconfig.json",
26
28
  "typecheck": "tsc -p tsconfig.json --noEmit",
27
- "test": "npm run build && node --test test/sdk.test.mjs",
29
+ "test": "npm run build && node --test test/sdk.test.mjs test/async-exec.test.mjs",
28
30
  "prepublishOnly": "npm run build && npm test",
29
31
  "clean": "rm -rf dist"
30
32
  },