@sistemo/sdk 0.1.0 → 0.1.2

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
@@ -10,7 +10,18 @@ Requires Node 18+ (uses the global `fetch`). Zero runtime dependencies.
10
10
 
11
11
  ## Quickstart (< 10 lines)
12
12
 
13
- ```ts
13
+ First, get an API key from the dashboard (**Dashboard → API Keys**) and export it:
14
+
15
+ ```bash
16
+ export SISTEMO_API_KEY=sk_live_xxxxxxxx
17
+ ```
18
+
19
+ Then save this as `hello.mjs` — it is a source file, not something to paste at a shell
20
+ prompt. The `.mjs` extension matters: the snippet uses `import` and top-level
21
+ `await`, so a plain `.js` file needs `"type": "module"` in your `package.json`.
22
+
23
+ ```js
24
+ // hello.mjs
14
25
  import { Sandbox } from "@sistemo/sdk";
15
26
 
16
27
  const sb = await Sandbox.create(); // reads SISTEMO_API_KEY
@@ -19,10 +30,10 @@ console.log(res.stdout, res.exitCode); // "4\n" 0
19
30
  await sb.close();
20
31
  ```
21
32
 
22
- Get an API key from the dashboard (**Dashboard → API Keys**), then:
33
+ Then run it:
23
34
 
24
35
  ```bash
25
- export SISTEMO_API_KEY=sk_live_xxxxxxxx
36
+ node hello.mjs
26
37
  ```
27
38
 
28
39
  ## Configuration
@@ -38,7 +49,7 @@ Or pass them explicitly: `Sandbox.create({ apiKey: "sk_live_…", baseUrl: "http
38
49
 
39
50
  ```ts
40
51
  const sb = await Sandbox.create({ vcpus: 1, memoryMb: 1024, stack: "base" });
41
- 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 } (default 120s, max 24h)
42
53
  await sb.close(); // destroy
43
54
  ```
44
55
 
@@ -67,3 +78,68 @@ dimension bound and how much is in use, and `GET /v1/quotas` reports every limit
67
78
  alongside current usage.
68
79
 
69
80
  Apache-2.0.
81
+
82
+ ## Long-running commands
83
+
84
+ `sb.run()` starts a guest job and waits for it on your machine (default **120
85
+ seconds**, maximum 24 hours). Each poll is a short request, so a proxy never
86
+ holds a connection for the whole command. Pass a longer timeout for installs
87
+ and builds:
88
+
89
+ ```ts
90
+ const sb = await Sandbox.create();
91
+ try {
92
+ const r = await sb.run("npm ci && npm run build", 3600);
93
+ console.log(r.exitCode);
94
+ } finally {
95
+ await sb.close();
96
+ }
97
+ ```
98
+
99
+ `sb.start()` returns the handle without waiting, when you want to stream,
100
+ cancel, or reconnect:
101
+
102
+ ```ts
103
+ const sb = await Sandbox.create();
104
+ try {
105
+ const job = await sb.start("npm ci && npm run build", 3600);
106
+
107
+ for await (const chunk of job.stream()) process.stdout.write(chunk);
108
+
109
+ await job.wait();
110
+ console.log(job.state, job.exitCode);
111
+ } finally {
112
+ await sb.close();
113
+ }
114
+ ```
115
+
116
+ The handle outlives the process that created it, so a crashed client can
117
+ reconnect with `sb.job(execId)` or list what is running with `sb.jobs()`.
118
+
119
+ ### Three things worth knowing
120
+
121
+ **`exitCode` is `null` until it is known** — and `null` forever if the job is
122
+ `lost`. It is never `0` as a placeholder, because a zero would read as success.
123
+ Branch on `state`, or use `job.ok`.
124
+
125
+ **`lost` is not `failed`.** `failed` means the command ran and returned non-zero.
126
+ `lost` means the machine could not account for it — neither that it ran nor that
127
+ it did not. Do not retry blindly and do not assume completion.
128
+
129
+ **A failed `start()` may still have started something.** On
130
+ `ExecStartUnconfirmed` the command may be running; the error carries the handle:
131
+
132
+ ```ts
133
+ let job;
134
+ try {
135
+ job = await sb.start("./deploy.sh");
136
+ } catch (e) {
137
+ if (!(e instanceof ExecStartUnconfirmed)) throw e;
138
+ job = await sb.job(e.execId); // find out what actually happened
139
+ }
140
+ await job.wait();
141
+ ```
142
+
143
+ You mint `execId` (a UUID is generated if you omit it). Re-sending the same id
144
+ is a 409 and returns the existing job, not a second run. If start throws
145
+ `ExecStartUnconfirmed`, poll that id — do not start again.
package/dist/index.d.ts CHANGED
@@ -16,7 +16,15 @@ 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
+ constructor(status: number, detail: string, code?: string, body?: Record<string, unknown>);
20
28
  }
21
29
  /** 401/403 — key missing, invalid, revoked, or a read-only key on a mutation. */
22
30
  export declare class AuthError extends APIError {
@@ -44,6 +52,41 @@ export declare class NotFoundError extends APIError {
44
52
  /** 429 — rate limited. */
45
53
  export declare class RateLimitError extends APIError {
46
54
  }
55
+ /**
56
+ * 410 — it existed and is no longer retained.
57
+ *
58
+ * Deliberately NOT a `NotFoundError`. Telling a caller their job never existed,
59
+ * when in fact its record or output aged out, invites them to re-run work that
60
+ * already ran.
61
+ */
62
+ export declare class GoneError extends APIError {
63
+ }
64
+ /**
65
+ * 501 — this machine's image predates async exec.
66
+ *
67
+ * **Do not retry.** The in-guest agent is baked into the image, so the answer
68
+ * cannot change until the image is rebuilt (or the agent is updated in place).
69
+ * Deliberately distinct from a 502/503, which mean "ask again".
70
+ */
71
+ export declare class AsyncExecUnsupportedError extends APIError {
72
+ }
73
+ /**
74
+ * 503 — we could not confirm the command started, and it **may be running**.
75
+ *
76
+ * This is not a failure. The most dangerous thing a caller can do here is treat
77
+ * it as one and start the command again. `execId` is the handle:
78
+ *
79
+ * ```ts
80
+ * try {
81
+ * job = await sb.start("./deploy.sh");
82
+ * } catch (e) {
83
+ * if (e instanceof ExecStartUnconfirmed) job = await sb.job(e.execId);
84
+ * }
85
+ * ```
86
+ */
87
+ export declare class ExecStartUnconfirmed extends APIError {
88
+ get execId(): string;
89
+ }
47
90
  export interface ClientOptions {
48
91
  apiKey?: string;
49
92
  baseUrl?: string;
@@ -110,6 +153,7 @@ export interface ExecResult {
110
153
  exitCode: number;
111
154
  stdout: string;
112
155
  stderr: string;
156
+ truncated?: boolean;
113
157
  }
114
158
  export interface SandboxOptions extends ClientOptions {
115
159
  client?: Client;
@@ -133,8 +177,146 @@ export declare class Sandbox {
133
177
  private constructor();
134
178
  /** Provision a new microVM (resolves once it has booted). */
135
179
  static create(opts?: SandboxOptions): Promise<Sandbox>;
136
- /** Run a shell command/script inside the sandbox. */
180
+ /**
181
+ * Run a shell command/script inside the sandbox and return its output.
182
+ *
183
+ * This is start + wait on a guest job (`POST /execs`). Default timeout 120s,
184
+ * ceiling 24 hours. A proxy never holds the connection for the whole command.
185
+ */
137
186
  run(script: string, timeoutSec?: number): Promise<ExecResult>;
187
+ /**
188
+ * Start a command and return a handle without waiting.
189
+ *
190
+ * {@link run} is start + wait — use this to stream, cancel, or reconnect.
191
+ * Same guest job, same timeout ceiling (24 hours).
192
+ *
193
+ * ⚠ You mint `execId` (a UUID is generated if you omit it). If the start
194
+ * response is lost, poll that id rather than starting again. Re-sending the
195
+ * same id is a 409, not a second run.
196
+ *
197
+ * ⚠ On {@link ExecStartUnconfirmed} the command **may be running**. The error
198
+ * carries `execId`; poll it with {@link job} rather than starting over.
199
+ */
200
+ start(script: string, timeoutSec?: number, opts?: {
201
+ execId?: string;
202
+ }): Promise<Job>;
203
+ /** Re-attach to a job by id — after a crash, or after an unconfirmed start. */
204
+ job(execId: string): Promise<Job>;
205
+ /** List this sandbox's async jobs, newest first. */
206
+ jobs(limit?: number): Promise<Job[]>;
138
207
  /** Destroy the sandbox (and its disk unless `preserveStorage`). */
139
208
  close(preserveStorage?: boolean): Promise<void>;
140
209
  }
210
+ interface JobRecord {
211
+ exec_id?: string;
212
+ machine_id?: string;
213
+ state?: string;
214
+ exit_code?: number | null;
215
+ stdout_bytes?: number;
216
+ stderr_bytes?: number;
217
+ truncated?: boolean;
218
+ started_at?: string | null;
219
+ finished_at?: string | null;
220
+ }
221
+ /**
222
+ * `wait()`/`stream()` gave up waiting.
223
+ *
224
+ * ⚠ The job is **still running** — this is your client's patience running out,
225
+ * not the command's. The handle stays valid; poll it again later.
226
+ */
227
+ export declare class JobTimeout extends SistemoError {
228
+ }
229
+ /**
230
+ * A handle on a command running inside a sandbox.
231
+ *
232
+ * The handle outlives the process that created it, so a crashed client can
233
+ * reconnect with `sb.job(execId)` or list what is running with `sb.jobs()`.
234
+ */
235
+ export declare class Job {
236
+ private readonly client;
237
+ private readonly sandboxId;
238
+ id: string;
239
+ machineId: string;
240
+ state: string;
241
+ /**
242
+ * ⚠ `null` until known, and null FOREVER when `state` is `"lost"`. Never
243
+ * coerce this to 0 — a zero here reads as "the command succeeded".
244
+ */
245
+ exitCode: number | null;
246
+ stdoutBytes: number;
247
+ stderrBytes: number;
248
+ truncated: boolean;
249
+ startedAt: string | null;
250
+ finishedAt: string | null;
251
+ constructor(client: Client, sandboxId: string, rec: JobRecord);
252
+ private apply;
253
+ /** Whether the job reached a terminal state. */
254
+ get done(): boolean;
255
+ /**
256
+ * `true` only for a command that finished and exited 0.
257
+ *
258
+ * ⚠ A `lost` job is never ok, because we cannot say that it worked — and a
259
+ * property that guessed would be worse than no property.
260
+ */
261
+ get ok(): boolean;
262
+ /**
263
+ * The machine could not account for this job.
264
+ *
265
+ * ⚠ Not the same as failed. `failed` means it ran and returned non-zero;
266
+ * `lost` means we can say neither that it ran nor that it did not.
267
+ */
268
+ get lost(): boolean;
269
+ /** Re-read the job's state from the API. */
270
+ refresh(): Promise<this>;
271
+ /**
272
+ * Resolve once the job reaches a terminal state.
273
+ *
274
+ * The waiting happens **client-side**: each poll is a fast request, so no
275
+ * proxy between you and the API is ever holding a long connection.
276
+ *
277
+ * Rejects with {@link JobTimeout} if `timeoutMs` elapses first — ⚠ which does
278
+ * not stop the job. Call {@link cancel} if that is what you meant.
279
+ */
280
+ wait(opts?: {
281
+ timeoutMs?: number;
282
+ pollIntervalMs?: number;
283
+ }): Promise<this>;
284
+ /**
285
+ * Stop the job: SIGTERM, a short grace period, then SIGKILL.
286
+ *
287
+ * Cancelling a job that already finished is a no-op, so a retried cancel is
288
+ * safe.
289
+ */
290
+ cancel(): Promise<this>;
291
+ /**
292
+ * Yield raw output bytes as they are produced, until the job ends.
293
+ *
294
+ * ⚠ Chunks split on BYTE boundaries and one can end mid-character. Use
295
+ * {@link stream} unless you actually want bytes.
296
+ */
297
+ streamBytes(opts?: {
298
+ stream?: "stdout" | "stderr";
299
+ pollIntervalMs?: number;
300
+ timeoutMs?: number;
301
+ limit?: number;
302
+ }): AsyncGenerator<Uint8Array>;
303
+ /**
304
+ * Yield output as text as it is produced.
305
+ *
306
+ * ⚠ Decoding is INCREMENTAL (`TextDecoder` with `stream: true`). A page can
307
+ * end in the middle of a multi-byte character, and decoding each page on its
308
+ * own would corrupt every character that straddles a boundary — which, at a
309
+ * 64 KiB page size, is rare enough to survive testing and common enough to
310
+ * corrupt real logs.
311
+ */
312
+ stream(opts?: {
313
+ stream?: "stdout" | "stderr";
314
+ pollIntervalMs?: number;
315
+ timeoutMs?: number;
316
+ }): AsyncGenerator<string>;
317
+ /** Read everything written to a stream so far, without waiting. */
318
+ output(which?: "stdout" | "stderr"): Promise<Uint8Array>;
319
+ /** {@link output} decoded as text. */
320
+ logs(which?: "stdout" | "stderr"): Promise<string>;
321
+ }
322
+ 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.0";
18
+ const USER_AGENT = "@sistemo/sdk/0.1.2";
19
19
  const RETRY_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
20
20
  export class SistemoError extends Error {
21
21
  }
@@ -23,12 +23,21 @@ 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
+ constructor(status, detail, code, body) {
27
35
  super(`[${status}] ${detail}${code ? ` (${code})` : ""}`);
28
36
  this.name = "APIError";
29
37
  this.status = status;
30
38
  this.detail = detail;
31
39
  this.code = code;
40
+ this.body = body ?? {};
32
41
  }
33
42
  }
34
43
  /** 401/403 — key missing, invalid, revoked, or a read-only key on a mutation. */
@@ -57,17 +66,63 @@ export class NotFoundError extends APIError {
57
66
  /** 429 — rate limited. */
58
67
  export class RateLimitError extends APIError {
59
68
  }
60
- function apiError(status, detail, code) {
69
+ /**
70
+ * 410 — it existed and is no longer retained.
71
+ *
72
+ * Deliberately NOT a `NotFoundError`. Telling a caller their job never existed,
73
+ * when in fact its record or output aged out, invites them to re-run work that
74
+ * already ran.
75
+ */
76
+ export class GoneError extends APIError {
77
+ }
78
+ /**
79
+ * 501 — this machine's image predates async exec.
80
+ *
81
+ * **Do not retry.** The in-guest agent is baked into the image, so the answer
82
+ * cannot change until the image is rebuilt (or the agent is updated in place).
83
+ * Deliberately distinct from a 502/503, which mean "ask again".
84
+ */
85
+ export class AsyncExecUnsupportedError extends APIError {
86
+ }
87
+ /**
88
+ * 503 — we could not confirm the command started, and it **may be running**.
89
+ *
90
+ * This is not a failure. The most dangerous thing a caller can do here is treat
91
+ * it as one and start the command again. `execId` is the handle:
92
+ *
93
+ * ```ts
94
+ * try {
95
+ * job = await sb.start("./deploy.sh");
96
+ * } catch (e) {
97
+ * if (e instanceof ExecStartUnconfirmed) job = await sb.job(e.execId);
98
+ * }
99
+ * ```
100
+ */
101
+ export class ExecStartUnconfirmed extends APIError {
102
+ get execId() {
103
+ return String(this.body.exec_id ?? "");
104
+ }
105
+ }
106
+ function apiError(status, detail, code, body) {
61
107
  // 403 is two different things, told apart by `code` — never by the status.
62
108
  if (status === 403 && code === "quota_exceeded")
63
- return new QuotaExceededError(status, detail, code);
109
+ return new QuotaExceededError(status, detail, code, body);
64
110
  if (status === 401 || status === 403)
65
- return new AuthError(status, detail, code);
111
+ return new AuthError(status, detail, code, body);
66
112
  if (status === 404)
67
- return new NotFoundError(status, detail, code);
113
+ return new NotFoundError(status, detail, code, body);
114
+ if (status === 410)
115
+ return new GoneError(status, detail, code, body);
68
116
  if (status === 429)
69
- return new RateLimitError(status, detail, code);
70
- return new APIError(status, detail, code);
117
+ return new RateLimitError(status, detail, code, body);
118
+ if (status === 501)
119
+ return new AsyncExecUnsupportedError(status, detail, code, body);
120
+ // ⚠ Only a 503 that NAMES an exec is the unconfirmed-start case. A plain 503
121
+ // (no host available, say) is an ordinary retryable error and must not be
122
+ // dressed up as a command that might be running.
123
+ if (status === 503 && body && body.exec_id)
124
+ return new ExecStartUnconfirmed(status, detail, code, body);
125
+ return new APIError(status, detail, code, body);
71
126
  }
72
127
  function newIdempotencyKey() {
73
128
  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
@@ -153,15 +208,21 @@ export class Client {
153
208
  if (!res.ok) {
154
209
  let detail = "request failed";
155
210
  let code;
211
+ let body;
156
212
  try {
157
213
  const parsed = JSON.parse(text);
158
- detail = parsed.detail ?? detail;
214
+ // Some errors use `error` rather than `detail` (an unconfirmed exec
215
+ // start is the live example), so fall back rather than reporting
216
+ // "request failed" over a message that was right there.
217
+ detail = parsed.detail ?? parsed.error ?? detail;
159
218
  code = parsed.code;
219
+ if (parsed && typeof parsed === "object")
220
+ body = parsed;
160
221
  }
161
222
  catch {
162
223
  /* non-JSON error body */
163
224
  }
164
- throw apiError(res.status, detail, code);
225
+ throw apiError(res.status, detail, code, body);
165
226
  }
166
227
  return (text ? JSON.parse(text) : {});
167
228
  }
@@ -236,21 +297,311 @@ export class Sandbox {
236
297
  }
237
298
  return new Sandbox(client, machine.id, machine.state ?? "");
238
299
  }
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 });
300
+ /**
301
+ * Run a shell command/script inside the sandbox and return its output.
302
+ *
303
+ * This is start + wait on a guest job (`POST /execs`). Default timeout 120s,
304
+ * ceiling 24 hours. A proxy never holds the connection for the whole command.
305
+ */
306
+ async run(script, timeoutSec = 120) {
307
+ const execId = newIdempotencyKey();
308
+ let job;
309
+ try {
310
+ job = await this.start(script, timeoutSec, { execId });
311
+ }
312
+ catch (e) {
313
+ if (e instanceof ExecStartUnconfirmed) {
314
+ job = await this.job(execId);
315
+ }
316
+ else {
317
+ throw e;
318
+ }
319
+ }
320
+ await job.wait();
321
+ const dec = new TextDecoder("utf-8");
245
322
  return {
246
- exitCode: out.exit_code ?? -1,
247
- stdout: out.stdout ?? "",
248
- stderr: out.stderr ?? "",
323
+ exitCode: job.exitCode ?? -1,
324
+ stdout: dec.decode(await job.output("stdout")),
325
+ stderr: dec.decode(await job.output("stderr")),
326
+ truncated: job.truncated,
249
327
  };
250
328
  }
329
+ /**
330
+ * Start a command and return a handle without waiting.
331
+ *
332
+ * {@link run} is start + wait — use this to stream, cancel, or reconnect.
333
+ * Same guest job, same timeout ceiling (24 hours).
334
+ *
335
+ * ⚠ You mint `execId` (a UUID is generated if you omit it). If the start
336
+ * response is lost, poll that id rather than starting again. Re-sending the
337
+ * same id is a 409, not a second run.
338
+ *
339
+ * ⚠ On {@link ExecStartUnconfirmed} the command **may be running**. The error
340
+ * carries `execId`; poll it with {@link job} rather than starting over.
341
+ */
342
+ async start(script, timeoutSec = 120, opts = {}) {
343
+ const execId = opts.execId ?? newIdempotencyKey();
344
+ try {
345
+ const rec = await this.client.request("POST", `/v1/machines/${this.id}/execs`, { exec_id: execId, script, timeout_sec: timeoutSec });
346
+ return new Job(this.client, this.id, rec);
347
+ }
348
+ catch (e) {
349
+ if (e instanceof APIError && e.status === 409) {
350
+ try {
351
+ const rec = await this.client.request("GET", `/v1/machines/${this.id}/execs/${execId}`);
352
+ return new Job(this.client, this.id, rec);
353
+ }
354
+ catch (inner) {
355
+ if (inner instanceof NotFoundError)
356
+ throw e;
357
+ throw inner;
358
+ }
359
+ }
360
+ throw e;
361
+ }
362
+ }
363
+ /** Re-attach to a job by id — after a crash, or after an unconfirmed start. */
364
+ async job(execId) {
365
+ const rec = await this.client.request("GET", `/v1/machines/${this.id}/execs/${execId}`);
366
+ return new Job(this.client, this.id, rec);
367
+ }
368
+ /** List this sandbox's async jobs, newest first. */
369
+ async jobs(limit = 50) {
370
+ const out = await this.client.request("GET", `/v1/machines/${this.id}/execs?limit=${limit}`);
371
+ return (out.execs ?? []).map((r) => new Job(this.client, this.id, r));
372
+ }
251
373
  /** Destroy the sandbox (and its disk unless `preserveStorage`). */
252
374
  async close(preserveStorage = false) {
253
375
  const q = preserveStorage ? "?preserve_storage=true" : "";
254
376
  await this.client.request("DELETE", `/v1/machines/${this.id}${q}`);
255
377
  }
256
378
  }
379
+ // ── Async exec ────────────────────────────────────────────────────────
380
+ /** States that mean nothing further will happen. */
381
+ const TERMINAL = new Set(["succeeded", "failed", "cancelled", "expired", "lost"]);
382
+ /**
383
+ * `wait()`/`stream()` gave up waiting.
384
+ *
385
+ * ⚠ The job is **still running** — this is your client's patience running out,
386
+ * not the command's. The handle stays valid; poll it again later.
387
+ */
388
+ export class JobTimeout extends SistemoError {
389
+ }
390
+ /**
391
+ * A handle on a command running inside a sandbox.
392
+ *
393
+ * The handle outlives the process that created it, so a crashed client can
394
+ * reconnect with `sb.job(execId)` or list what is running with `sb.jobs()`.
395
+ */
396
+ export class Job {
397
+ client;
398
+ sandboxId;
399
+ id = "";
400
+ machineId = "";
401
+ state = "";
402
+ /**
403
+ * ⚠ `null` until known, and null FOREVER when `state` is `"lost"`. Never
404
+ * coerce this to 0 — a zero here reads as "the command succeeded".
405
+ */
406
+ exitCode = null;
407
+ stdoutBytes = 0;
408
+ stderrBytes = 0;
409
+ truncated = false;
410
+ startedAt = null;
411
+ finishedAt = null;
412
+ constructor(client, sandboxId, rec) {
413
+ this.client = client;
414
+ this.sandboxId = sandboxId;
415
+ this.apply(rec);
416
+ }
417
+ apply(rec) {
418
+ this.id = rec.exec_id ?? "";
419
+ this.machineId = rec.machine_id ?? "";
420
+ this.state = rec.state ?? "";
421
+ this.exitCode = rec.exit_code ?? null;
422
+ this.stdoutBytes = rec.stdout_bytes ?? 0;
423
+ this.stderrBytes = rec.stderr_bytes ?? 0;
424
+ this.truncated = rec.truncated ?? false;
425
+ this.startedAt = rec.started_at ?? null;
426
+ this.finishedAt = rec.finished_at ?? null;
427
+ return this;
428
+ }
429
+ /** Whether the job reached a terminal state. */
430
+ get done() {
431
+ return TERMINAL.has(this.state);
432
+ }
433
+ /**
434
+ * `true` only for a command that finished and exited 0.
435
+ *
436
+ * ⚠ A `lost` job is never ok, because we cannot say that it worked — and a
437
+ * property that guessed would be worse than no property.
438
+ */
439
+ get ok() {
440
+ return this.state === "succeeded" && this.exitCode === 0;
441
+ }
442
+ /**
443
+ * The machine could not account for this job.
444
+ *
445
+ * ⚠ Not the same as failed. `failed` means it ran and returned non-zero;
446
+ * `lost` means we can say neither that it ran nor that it did not.
447
+ */
448
+ get lost() {
449
+ return this.state === "lost";
450
+ }
451
+ /** Re-read the job's state from the API. */
452
+ async refresh() {
453
+ return this.apply(await this.client.request("GET", `/v1/machines/${this.sandboxId}/execs/${this.id}`));
454
+ }
455
+ /**
456
+ * Resolve once the job reaches a terminal state.
457
+ *
458
+ * The waiting happens **client-side**: each poll is a fast request, so no
459
+ * proxy between you and the API is ever holding a long connection.
460
+ *
461
+ * Rejects with {@link JobTimeout} if `timeoutMs` elapses first — ⚠ which does
462
+ * not stop the job. Call {@link cancel} if that is what you meant.
463
+ */
464
+ async wait(opts = {}) {
465
+ const poll = opts.pollIntervalMs ?? 1000;
466
+ const deadline = opts.timeoutMs === undefined ? undefined : Date.now() + opts.timeoutMs;
467
+ for (;;) {
468
+ if (this.done)
469
+ return this;
470
+ if (deadline !== undefined && Date.now() >= deadline) {
471
+ throw new JobTimeout(`job ${this.id} is still ${this.state} after ${opts.timeoutMs}ms ` +
472
+ `(it is still running; poll it again or cancel it)`);
473
+ }
474
+ // Refresh BEFORE sleeping. POST /execs returns running immediately, so a
475
+ // hello-world `sb.run("echo hi")` would otherwise wait a full poll
476
+ // interval for a command that finished in milliseconds.
477
+ await this.refresh();
478
+ if (this.done)
479
+ return this;
480
+ if (deadline === undefined) {
481
+ await sleep(poll);
482
+ }
483
+ else {
484
+ const remaining = deadline - Date.now();
485
+ if (remaining <= 0) {
486
+ throw new JobTimeout(`job ${this.id} is still ${this.state} after ${opts.timeoutMs}ms ` +
487
+ `(it is still running; poll it again or cancel it)`);
488
+ }
489
+ await sleep(Math.min(poll, remaining));
490
+ }
491
+ }
492
+ }
493
+ /**
494
+ * Stop the job: SIGTERM, a short grace period, then SIGKILL.
495
+ *
496
+ * Cancelling a job that already finished is a no-op, so a retried cancel is
497
+ * safe.
498
+ */
499
+ async cancel() {
500
+ return this.apply(await this.client.request("DELETE", `/v1/machines/${this.sandboxId}/execs/${this.id}`));
501
+ }
502
+ /**
503
+ * Yield raw output bytes as they are produced, until the job ends.
504
+ *
505
+ * ⚠ Chunks split on BYTE boundaries and one can end mid-character. Use
506
+ * {@link stream} unless you actually want bytes.
507
+ */
508
+ async *streamBytes(opts = {}) {
509
+ const which = opts.stream ?? "stdout";
510
+ const poll = opts.pollIntervalMs ?? 500;
511
+ const limit = opts.limit ?? 65536;
512
+ const deadline = opts.timeoutMs === undefined ? undefined : Date.now() + opts.timeoutMs;
513
+ let offset = 0;
514
+ for (;;) {
515
+ const page = await this.client.request("GET", `/v1/machines/${this.sandboxId}/execs/${this.id}/output` +
516
+ `?stream=${which}&offset=${offset}&limit=${limit}`);
517
+ offset = page.next_offset ?? offset;
518
+ const data = page.data ? base64ToBytes(page.data) : new Uint8Array(0);
519
+ if (data.length > 0) {
520
+ yield data;
521
+ // ⚠ Loop straight back without sleeping. A producer faster than the
522
+ // poll interval would otherwise be read at one page per interval,
523
+ // turning a 30-second build log into minutes of trickle for no reason.
524
+ continue;
525
+ }
526
+ // ⚠ Stop on eof, NEVER on an empty page. An empty page from a running job
527
+ // means "nothing new yet"; treating it as the end truncates the output of
528
+ // every job that pauses to think.
529
+ if (page.eof)
530
+ return;
531
+ if (deadline !== undefined && Date.now() >= deadline) {
532
+ throw new JobTimeout(`job ${this.id} produced no further output within ${opts.timeoutMs}ms`);
533
+ }
534
+ await sleep(poll);
535
+ }
536
+ }
537
+ /**
538
+ * Yield output as text as it is produced.
539
+ *
540
+ * ⚠ Decoding is INCREMENTAL (`TextDecoder` with `stream: true`). A page can
541
+ * end in the middle of a multi-byte character, and decoding each page on its
542
+ * own would corrupt every character that straddles a boundary — which, at a
543
+ * 64 KiB page size, is rare enough to survive testing and common enough to
544
+ * corrupt real logs.
545
+ */
546
+ async *stream(opts = {}) {
547
+ const decoder = new TextDecoder("utf-8");
548
+ for await (const chunk of this.streamBytes(opts)) {
549
+ const text = decoder.decode(chunk, { stream: true });
550
+ if (text)
551
+ yield text;
552
+ }
553
+ // Flush whatever partial sequence is left, so a truncated final character
554
+ // surfaces as U+FFFD rather than silently disappearing.
555
+ const tail = decoder.decode();
556
+ if (tail)
557
+ yield tail;
558
+ }
559
+ /** Read everything written to a stream so far, without waiting. */
560
+ async output(which = "stdout") {
561
+ const parts = [];
562
+ let offset = 0;
563
+ for (;;) {
564
+ const page = await this.client.request("GET", `/v1/machines/${this.sandboxId}/execs/${this.id}/output` +
565
+ `?stream=${which}&offset=${offset}&limit=65536`);
566
+ const data = page.data ? base64ToBytes(page.data) : new Uint8Array(0);
567
+ if (data.length > 0)
568
+ parts.push(data);
569
+ const next = page.next_offset ?? offset;
570
+ if (data.length === 0 || next <= offset)
571
+ break;
572
+ offset = next;
573
+ }
574
+ const total = parts.reduce((n, p) => n + p.length, 0);
575
+ const out = new Uint8Array(total);
576
+ let at = 0;
577
+ for (const p of parts) {
578
+ out.set(p, at);
579
+ at += p.length;
580
+ }
581
+ return out;
582
+ }
583
+ /** {@link output} decoded as text. */
584
+ async logs(which = "stdout") {
585
+ return new TextDecoder("utf-8").decode(await this.output(which));
586
+ }
587
+ }
588
+ /**
589
+ * Decode base64 without assuming a runtime.
590
+ *
591
+ * ⚠ `atob` produces a string of char codes, not bytes — mapping through
592
+ * charCodeAt is what keeps binary output intact. Buffer is preferred where it
593
+ * exists because it skips that round trip entirely.
594
+ */
595
+ function base64ToBytes(b64) {
596
+ const g = globalThis;
597
+ if (typeof g.Buffer !== "undefined")
598
+ return new Uint8Array(g.Buffer.from(b64, "base64"));
599
+ if (typeof g.atob === "function") {
600
+ const bin = g.atob(b64);
601
+ const out = new Uint8Array(bin.length);
602
+ for (let i = 0; i < bin.length; i++)
603
+ out[i] = bin.charCodeAt(i);
604
+ return out;
605
+ }
606
+ throw new SistemoError("no base64 decoder available in this runtime");
607
+ }
package/package.json CHANGED
@@ -1,9 +1,11 @@
1
1
  {
2
2
  "name": "@sistemo/sdk",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
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
  },