@namzu/sandbox 6.1.0 → 7.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/README.md +29 -1
  3. package/dist/backends/aci-standby-pool/index.d.ts.map +1 -1
  4. package/dist/backends/aci-standby-pool/index.js +163 -111
  5. package/dist/backends/aci-standby-pool/index.js.map +1 -1
  6. package/dist/backends/docker/index.d.ts.map +1 -1
  7. package/dist/backends/docker/index.js +212 -149
  8. package/dist/backends/docker/index.js.map +1 -1
  9. package/dist/backends/firecracker/index.d.ts.map +1 -1
  10. package/dist/backends/firecracker/index.js +154 -71
  11. package/dist/backends/firecracker/index.js.map +1 -1
  12. package/dist/backends/firecracker/protocol.d.ts +19 -27
  13. package/dist/backends/firecracker/protocol.d.ts.map +1 -1
  14. package/dist/backends/firecracker/protocol.js +57 -32
  15. package/dist/backends/firecracker/protocol.js.map +1 -1
  16. package/dist/backends/firecracker/transport.d.ts +26 -7
  17. package/dist/backends/firecracker/transport.d.ts.map +1 -1
  18. package/dist/backends/firecracker/transport.js +235 -72
  19. package/dist/backends/firecracker/transport.js.map +1 -1
  20. package/dist/backends/http-worker-client.d.ts +17 -0
  21. package/dist/backends/http-worker-client.d.ts.map +1 -0
  22. package/dist/backends/http-worker-client.js +173 -0
  23. package/dist/backends/http-worker-client.js.map +1 -0
  24. package/dist/backends/readiness.d.ts +43 -0
  25. package/dist/backends/readiness.d.ts.map +1 -0
  26. package/dist/backends/readiness.js +150 -0
  27. package/dist/backends/readiness.js.map +1 -0
  28. package/dist/backends/remote-execution-controller.d.ts +76 -0
  29. package/dist/backends/remote-execution-controller.d.ts.map +1 -0
  30. package/dist/backends/remote-execution-controller.js +294 -0
  31. package/dist/backends/remote-execution-controller.js.map +1 -0
  32. package/dist/egress/proxy.d.ts.map +1 -1
  33. package/dist/egress/proxy.js +20 -3
  34. package/dist/egress/proxy.js.map +1 -1
  35. package/dist/index.d.ts +18 -0
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +9 -0
  38. package/dist/index.js.map +1 -1
  39. package/package.json +2 -2
  40. package/src/backends/aci-standby-pool/index.ts +199 -117
  41. package/src/backends/docker/index.ts +235 -175
  42. package/src/backends/firecracker/index.ts +163 -63
  43. package/src/backends/firecracker/protocol.ts +67 -33
  44. package/src/backends/firecracker/transport.ts +301 -77
  45. package/src/backends/http-worker-client.ts +230 -0
  46. package/src/backends/readiness.ts +173 -0
  47. package/src/backends/remote-execution-controller.ts +462 -0
  48. package/src/egress/proxy.ts +18 -3
  49. package/src/index.ts +27 -0
@@ -1,5 +1,5 @@
1
1
  /**
2
- * The ONE wire contract, shared across both transports.
2
+ * The execution-data codec shared by both transports.
3
3
  *
4
4
  * The docker (`backends/docker/`) and ACI (`backends/aci-standby-pool/`)
5
5
  * backends speak this contract over **HTTP**: a streaming NDJSON
@@ -9,21 +9,12 @@
9
9
  * shapes** — only the transport changes from HTTP-over-TCP to
10
10
  * framed-over-vsock (see `transport.ts`).
11
11
  *
12
- * This module is the single source of truth for the message shapes
13
- * and the streaming exec-line parser, so the two transports cannot
14
- * drift. It deliberately carries NO transport concern (no `fetch`, no
15
- * socket) — it is pure codec. The HTTP backends keep their own inline
16
- * copies (they predate this module and stay UNTOUCHED per the P0
17
- * scope); this module mirrors those shapes verbatim and is the
18
- * canonical definition the vsock path consumes.
19
- *
20
- * Why mirror rather than refactor docker/aci onto it: the P0 scope is
21
- * "do NOT touch docker or aci". Centralising the shapes here, with the
22
- * inline docker copy pinned by `backends/docker/__tests__` and this
23
- * module pinned by `backends/firecracker/__tests__`, keeps both honest
24
- * without editing the frozen HTTP path. A later cleanup pass can fold
25
- * docker/aci onto this module once it is no longer release-frozen.
12
+ * This module remains the pure codec consumed by the framed guest transport.
13
+ * The two HTTP backends share one strict HTTP client, and both transports put
14
+ * the same reserve-before-admission + idempotent-cancel state machine around
15
+ * these data events. HTTP uses endpoints; the framed guest uses dedicated ops.
26
16
  */
17
+ import { RemoteCommandError, RemoteProtocolError } from '../remote-execution-controller.js';
27
18
  // ---------------------------------------------------------------------------
28
19
  // Streaming exec-line accumulator — the parser docker/aci inline today,
29
20
  // lifted out so the vsock transport reuses it byte-for-byte.
@@ -35,9 +26,8 @@
35
26
  * terminal `result`, and **throw** on an `error` event.
36
27
  *
37
28
  * Transport-agnostic: feed it whole parsed {@link ExecEvent}s (the
38
- * transport owns newline-framing → JSON.parse → here). Malformed lines
39
- * are dropped by the transport's `JSON.parse` guard before they reach
40
- * this accumulator, matching the docker loop's `SyntaxError` swallow.
29
+ * transport owns framing → strict JSON validation → here). Malformed or
30
+ * trailing events are protocol failures rather than silently discarded data.
41
31
  */
42
32
  export class ExecResultAccumulator {
43
33
  stdout = '';
@@ -45,10 +35,15 @@ export class ExecResultAccumulator {
45
35
  exitCode = -1;
46
36
  timedOut = false;
47
37
  signal;
38
+ durationMs;
39
+ stdoutTruncated;
40
+ stderrTruncated;
48
41
  settled = false;
49
42
  start;
50
- constructor(start = Date.now()) {
43
+ onOutput;
44
+ constructor(start = Date.now(), onOutput) {
51
45
  this.start = start;
46
+ this.onOutput = onOutput;
52
47
  }
53
48
  /**
54
49
  * Apply one event. Returns `true` once a terminal `result` has been
@@ -57,56 +52,86 @@ export class ExecResultAccumulator {
57
52
  * docker loop uses (`throw new Error(event.error)`).
58
53
  */
59
54
  push(event) {
55
+ if (this.settled) {
56
+ throw new RemoteProtocolError('exec stream emitted data after its terminal event');
57
+ }
60
58
  if (event.type === 'stdout_delta') {
61
59
  this.stdout += event.data;
60
+ this.onOutput?.({ stream: 'stdout', data: event.data });
62
61
  return false;
63
62
  }
64
63
  if (event.type === 'stderr_delta') {
65
64
  this.stderr += event.data;
65
+ this.onOutput?.({ stream: 'stderr', data: event.data });
66
66
  return false;
67
67
  }
68
68
  if (event.type === 'result') {
69
69
  this.exitCode = event.exitCode;
70
70
  this.timedOut = event.timedOut;
71
+ this.durationMs = event.durationMs;
72
+ this.signal = event.signal;
73
+ this.stdoutTruncated = event.stdoutTruncated;
74
+ this.stderrTruncated = event.stderrTruncated;
71
75
  this.settled = true;
72
76
  return true;
73
77
  }
74
78
  // event.type === 'error'
75
- throw new Error(event.error);
79
+ throw new RemoteCommandError(event.error);
76
80
  }
77
81
  get done() {
78
82
  return this.settled;
79
83
  }
80
- /** Build the SDK-shaped result. `durationMs` measured host-side. */
84
+ /** Build the SDK-shaped result from the guest's terminal metadata. */
81
85
  finish() {
86
+ if (!this.settled || this.durationMs === undefined) {
87
+ throw new RemoteProtocolError('exec stream ended without exactly one result event');
88
+ }
82
89
  return {
83
90
  exitCode: this.exitCode,
84
91
  stdout: this.stdout,
85
92
  stderr: this.stderr,
86
93
  ...(this.signal ? { signal: this.signal } : {}),
87
94
  timedOut: this.timedOut,
88
- durationMs: Date.now() - this.start,
95
+ durationMs: this.durationMs ?? Date.now() - this.start,
96
+ ...(this.stdoutTruncated !== undefined ? { stdoutTruncated: this.stdoutTruncated } : {}),
97
+ ...(this.stderrTruncated !== undefined ? { stderrTruncated: this.stderrTruncated } : {}),
89
98
  };
90
99
  }
91
100
  }
92
101
  /**
93
- * Parse a single NDJSON line into an {@link ExecEvent}, or `undefined`
94
- * if the line is blank or not valid JSON (the docker loop's
95
- * `SyntaxError` swallow). Non-`SyntaxError` problems are impossible
96
- * here because we only `JSON.parse`; structural validation is by the
97
- * `type` discriminator at the call site.
102
+ * Parse and structurally validate a single NDJSON event. Blank padding is
103
+ * ignored; malformed JSON and unknown/partial event shapes are refused.
98
104
  */
99
105
  export function parseExecLine(line) {
100
106
  const trimmed = line.trim();
101
107
  if (!trimmed)
102
108
  return undefined;
109
+ let parsed;
103
110
  try {
104
- return JSON.parse(trimmed);
111
+ parsed = JSON.parse(trimmed);
112
+ }
113
+ catch (error) {
114
+ throw new RemoteProtocolError(`agent emitted malformed NDJSON: ${error instanceof Error ? error.message : String(error)}`);
115
+ }
116
+ if (!parsed || typeof parsed !== 'object') {
117
+ throw new RemoteProtocolError('agent emitted an event without an object body');
118
+ }
119
+ const event = parsed;
120
+ if ((event.type === 'stdout_delta' || event.type === 'stderr_delta') &&
121
+ typeof event.data === 'string') {
122
+ return event;
105
123
  }
106
- catch (err) {
107
- if (err instanceof SyntaxError)
108
- return undefined;
109
- throw err;
124
+ if (event.type === 'error' && typeof event.error === 'string')
125
+ return event;
126
+ if (event.type === 'result' &&
127
+ Number.isFinite(event.exitCode) &&
128
+ typeof event.timedOut === 'boolean' &&
129
+ Number.isFinite(event.durationMs) &&
130
+ (event.signal === undefined || typeof event.signal === 'string') &&
131
+ (event.stdoutTruncated === undefined || typeof event.stdoutTruncated === 'boolean') &&
132
+ (event.stderrTruncated === undefined || typeof event.stderrTruncated === 'boolean')) {
133
+ return event;
110
134
  }
135
+ throw new RemoteProtocolError(`agent emitted an invalid ${String(event.type)} event`);
111
136
  }
112
137
  //# sourceMappingURL=protocol.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/backends/firecracker/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA8EH,8EAA8E;AAC9E,wEAAwE;AACxE,6DAA6D;AAC7D,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,OAAO,qBAAqB;IACzB,MAAM,GAAG,EAAE,CAAA;IACX,MAAM,GAAG,EAAE,CAAA;IACX,QAAQ,GAAG,CAAC,CAAC,CAAA;IACb,QAAQ,GAAG,KAAK,CAAA;IAChB,MAAM,CAAoB;IAC1B,OAAO,GAAG,KAAK,CAAA;IACN,KAAK,CAAQ;IAE9B,YAAY,QAAgB,IAAI,CAAC,GAAG,EAAE;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACnB,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAgB;QACpB,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAA;YACzB,OAAO,KAAK,CAAA;QACb,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAA;YACzB,OAAO,KAAK,CAAA;QACb,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;YAC9B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;YAC9B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;YACnB,OAAO,IAAI,CAAA;QACZ,CAAC;QACD,yBAAyB;QACzB,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;IAED,IAAI,IAAI;QACP,OAAO,IAAI,CAAC,OAAO,CAAA;IACpB,CAAC;IAED,oEAAoE;IACpE,MAAM;QACL,OAAO;YACN,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;SACnC,CAAA;IACF,CAAC;CACD;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAA;IAC9B,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAc,CAAA;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,GAAG,YAAY,WAAW;YAAE,OAAO,SAAS,CAAA;QAChD,MAAM,GAAG,CAAA;IACV,CAAC;AACF,CAAC"}
1
+ {"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/backends/firecracker/protocol.ts"],"names":[],"mappings":"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"}
@@ -52,7 +52,7 @@
52
52
  * socket to be silently severed by a resume), which makes the
53
53
  * transport resume-survivable by construction.
54
54
  */
55
- import type { SandboxExecResult } from '@namzu/sdk';
55
+ import type { SandboxExecOptions, SandboxExecResult } from '@namzu/sdk';
56
56
  import { type ExecRequest, type ReadFileRequest, type WriteFileRequest } from './protocol.js';
57
57
  /**
58
58
  * An addressable agent endpoint. The orchestrator hands one of these
@@ -140,6 +140,13 @@ export type WireSandboxAgentHandle = {
140
140
  export type AgentRequest = {
141
141
  readonly op: 'execute';
142
142
  readonly body: ExecRequest;
143
+ } | {
144
+ readonly op: 'reserve-execution';
145
+ } | {
146
+ readonly op: 'cancel-execution';
147
+ readonly body: {
148
+ readonly executionId: string;
149
+ };
143
150
  } | {
144
151
  readonly op: 'read-file';
145
152
  readonly body: ReadFileRequest;
@@ -174,12 +181,13 @@ declare function frame(payload: string): Buffer;
174
181
  declare class FrameReader {
175
182
  private buf;
176
183
  push(chunk: Buffer): string[];
184
+ get bufferedBytes(): number;
177
185
  }
178
186
  /**
179
187
  * The transport. One instance per sandbox handle; every request opens
180
188
  * a fresh connection (resume-survivable — no socket lingers across a
181
- * resume to be silently severed). All four ops + the heartbeat go
182
- * through {@link request} / {@link execute}.
189
+ * resume to be silently severed). Execution reservation, data, cancellation,
190
+ * file I/O and heartbeat all use independent calls through this dialer.
183
191
  */
184
192
  export declare class VsockAgentTransport {
185
193
  private readonly handle;
@@ -187,6 +195,7 @@ export declare class VsockAgentTransport {
187
195
  private readonly connectRetryBudgetMs;
188
196
  private readonly connectRetryIntervalMs;
189
197
  private readonly readIdleTimeoutMs;
198
+ private readonly executionController;
190
199
  constructor(handle: SandboxAgentHandle, options?: VsockTransportOptions);
191
200
  /**
192
201
  * Dial the agent with the resume-survival retry budget. Resolves a
@@ -224,22 +233,32 @@ export declare class VsockAgentTransport {
224
233
  * healthz). Applies the read-idle timeout so a post-resume hung read
225
234
  * is torn down rather than wedging the caller.
226
235
  */
227
- request<T>(req: AgentRequest): Promise<T>;
236
+ request<T>(req: AgentRequest, signal?: AbortSignal): Promise<T>;
228
237
  /**
229
238
  * Send an `/execute` and accumulate the streamed NDJSON frames into a
230
239
  * {@link SandboxExecResult} via the shared {@link ExecResultAccumulator}.
231
240
  * The agent terminates the stream with a zero-length frame.
232
241
  */
233
- execute(body: ExecRequest): Promise<SandboxExecResult>;
242
+ private executeRaw;
243
+ /**
244
+ * Compatibility request-shaped entry point. It now enters the same
245
+ * reserve-before-admission controller as {@link exec}; the raw data-plane
246
+ * primitive is deliberately private so aborting this public method cannot
247
+ * abandon a live guest command.
248
+ */
249
+ execute(body: ExecRequest, opts?: SandboxExecOptions, signal?: AbortSignal): Promise<SandboxExecResult>;
250
+ exec(command: string, argv?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>;
251
+ private reserveExecution;
252
+ private cancelExecution;
234
253
  /** Liveness probe. Returns true on an `{ ok: true }` healthz reply. */
235
- healthz(): Promise<boolean>;
254
+ healthz(signal?: AbortSignal): Promise<boolean>;
236
255
  /**
237
256
  * Poll the agent until a healthz succeeds or the timeout elapses.
238
257
  * Mirrors the HTTP `waitForWorkerReady`, but over the vsock dialer
239
258
  * (which already carries connect retry) — used by the backend's
240
259
  * post-create readiness fence.
241
260
  */
242
- waitForReady(timeoutMs: number, pollIntervalMs: number): Promise<void>;
261
+ waitForReady(timeoutMs: number, pollIntervalMs: number, signal?: AbortSignal): Promise<void>;
243
262
  writeFile(path: string, content: Buffer): Promise<void>;
244
263
  readFile(path: string): Promise<Buffer>;
245
264
  }
@@ -1 +1 @@
1
- {"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/backends/firecracker/transport.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/backends/firecracker/transport.ts"],"names":[],"mappings":"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"}