@sistemo/sdk 0.1.1 → 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 +67 -2
- package/dist/index.d.ts +184 -2
- package/dist/index.js +370 -19
- package/package.json +4 -2
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**
|
|
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,7 @@ 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"
|
|
52
|
+
const res = await sb.run("echo hi && uname -a"); // -> { exitCode, stdout, stderr, truncated } (default 120s, max 24h)
|
|
53
53
|
await sb.close(); // destroy
|
|
54
54
|
```
|
|
55
55
|
|
|
@@ -78,3 +78,68 @@ dimension bound and how much is in use, and `GET /v1/quotas` reports every limit
|
|
|
78
78
|
alongside current usage.
|
|
79
79
|
|
|
80
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
|
-
|
|
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
|
-
/**
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
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:
|
|
247
|
-
stdout:
|
|
248
|
-
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.
|
|
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
|
},
|