[LXC] (5/5) Enable Node SDK select a containment backend in-process

[Soham Das (SohamDas2021)]

Adds a containment option to spawnSandbox/spawnSandboxAsync so callers can name a backend (e.g. 'lxc') instead of always getting the host default — Bubblewrap on Linux.

Moves mxc_spawn_request onto koffi .async so a slow native spawn can't block Node's event loop.

---

This can merge independently. It targets main, not PR 4, and shares no source with PRs 1–4. The only file it has in common with PR 4 is sdk/node/tests/integration/native-streaming.test.ts, which 3-way merges cleanly in either direction (PR 4 already awaits its new call site).

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Copilot review overview

🟡 Changes recommended

The narrowed config-spawn overload breaks an existing typed caller and the TypeScript test build.

Review effort: Balanced
Findings: 1

Open (1)

• Narrowed overload rejects valid SandboxSpawnOptions callers · New

What changed in this PR

Adds explicit containment selection to Node SDK convenience APIs and moves native streaming spawn work off the event loop.

Changes:

• Adds containment spawn options and validation.
• Makes native streaming spawn asynchronous.
• Expands documentation and tests for backend routing and ownership.

File	Description
sdk/​node/​src/​sandbox.ts	Adds containment selection and config-option validation.
sdk/​node/​src/​index.ts	Exports the new options type.
sdk/​node/​src/​state-aware.ts	Rejects containment options for state-aware APIs.
sdk/​node/​src/​bindings/​streaming.ts	Moves native spawn to Koffi async invocation.
sdk/​node/​README.md	Documents backend selection and errors.
sdk/​node/​tests/​unit/​streaming-binding.test.ts	Tests asynchronous spawn and ownership.
sdk/​node/​tests/​unit/​state-aware.test.ts	Tests unsupported containment options.
sdk/​node/​tests/​unit/​sandbox.test.ts	Tests convenience-path routing.
sdk/​node/​tests/​unit/​inprocess-run.test.ts	Tests in-process containment selection.
sdk/​node/​tests/​unit/​binding-request.test.ts	Tests supported native containments.
sdk/​node/​tests/​integration/​native-streaming.test.ts	Awaits asynchronous native streaming spawn.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The new config-spawn overload breaks integration typechecking, and the concurrent-handle test does not validate handle identity.

Review effort: Balanced
Findings: 1

Open (1)

• Narrowed overload rejects valid SandboxSpawnOptions callers

Previously missed (1)

In code that hasn't changed since last review

Use handle-specific IDs to validate completion handle ownership

sdk/​node/​tests/​unit/​streaming-binding.test.ts:486

This test does not verify that each completion adopts its own handle: FakeNative.id() always returns 23 and free() only increments a counter, so both promises could accidentally adopt the first handle and every assertion would still pass. Make the fake return a handle-specific ID so this test actually catches shared/out-of-order out-parameter bugs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The public option documentation incorrectly promises identical backend support across both convenience APIs.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Narrowed overload rejects valid SandboxSpawnOptions callers

Previously missed (1)

In code that hasn't changed since last review

Document microvm exception in spawnSandboxAsync containment contract

sdk/​node/​src/​sandbox.ts:655

This IntelliSense contract overstates parity: spawnSandboxAsync still rejects microvm, while spawnSandbox can launch the generated MicroVM config through the executor (the README now documents this exception at lines 307–313). Please include that exception here so callers do not infer that every typed containment value behaves identically on both APIs.