feat: add FX WebAssembly ACP agent

Author: NathanFlurry

.github/workflows/ci.yml

@@ -28,6 +28,9 @@ jobs:
           node-version: 24
           cache: pnpm
           cache-dependency-path: pnpm-lock.yaml
+      - uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2
+        with:
+          version: 0.16.0
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: rustfmt

.github/workflows/publish.yaml

@@ -257,6 +257,9 @@ jobs:
           cache: pnpm
           cache-dependency-path: pnpm-lock.yaml
           registry-url: https://registry.npmjs.org
+      - uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2
+        with:
+          version: 0.16.0
       - run: pnpm install --frozen-lockfile --filter='!@rivet-dev/agentos-website'
       - uses: actions/download-artifact@v4
         with:

crates/execution/assets/runners/wasm-runner.mjs

@@ -6954,6 +6954,7 @@ const hostProcessImport = {
                   argv0,
                   cwd,
                   env,
+                  envProvided: true,
                   internalBootstrapEnv: {
                     ...(activeSpawnCallContext?.internalBootstrapEnv ?? {}),
                     ...inheritedNofileBootstrapEnv(),

crates/native-sidecar/src/execution/child_process.rs

@@ -3252,8 +3252,11 @@ where
                     vm.host_cwd.clone()
                 }
             });
-        let mut env = parent_env.clone();
-        env.extend(request.options.env.clone());
+        let mut env = if request.options.env_provided {
+            request.options.env.clone()
+        } else {
+            parent_env.clone()
+        };
         // Child JavaScript executions must resolve their own entrypoint/eval state.
         // Reusing the parent's values makes the sidecar load the wrong source file.
         env.remove("AGENTOS_GUEST_ENTRYPOINT");

crates/native-sidecar/src/service.rs

@@ -4095,6 +4095,7 @@ mod legacy_child_spawn_options_tests {
                 "executableFd":11,
                 "cwd":"/work",
                 "env":{"VISIBLE":"yes"},
+                "envProvided":true,
                 "internalBootstrapEnv":{
                     "AGENTOS_WASM_INITIAL_SIGNAL_MASK":"[10]",
                     "AGENTOS_NOT_ALLOWED":"drop-me-too"
@@ -4137,6 +4138,7 @@ mod legacy_child_spawn_options_tests {
         assert_eq!(options.executable_fd, Some(11));
         assert_eq!(options.cwd.as_deref(), Some("/work"));
         assert_eq!(options.env.get("VISIBLE").map(String::as_str), Some("yes"));
+        assert!(options.env_provided);
         assert_eq!(
             options
                 .internal_bootstrap_env

crates/native-sidecar/tests/service.rs

@@ -11964,6 +11964,62 @@ console.log(JSON.stringify({ status: "ok", summary }));
                 "missing command error should mention the command: {error}"
             );
 
+            let mut parent_env = vm.guest_env.clone();
+            parent_env.insert(
+                String::from("AI_GATEWAY_API_KEY"),
+                String::from("must-not-leak"),
+            );
+            let replacement_env = BTreeMap::from([
+                (
+                    String::from("PATH"),
+                    vm.guest_env
+                        .get("PATH")
+                        .expect("configured PATH should exist")
+                        .clone(),
+                ),
+                (String::from("WORKSPACE_ONLY"), String::from("yes")),
+            ]);
+            let replaced = sidecar
+                .resolve_javascript_child_process_execution(
+                    vm,
+                    &parent_env,
+                    &vm.guest_cwd,
+                    &vm.host_cwd,
+                    &crate::protocol::JavascriptChildProcessSpawnRequest {
+                        command: String::from("echo"),
+                        args: vec![String::from("hello")],
+                        options: crate::protocol::JavascriptChildProcessSpawnOptions {
+                            env: replacement_env,
+                            env_provided: true,
+                            ..Default::default()
+                        },
+                    },
+                )
+                .expect("resolve child with explicit replacement environment");
+            assert_eq!(
+                replaced.env.get("WORKSPACE_ONLY").map(String::as_str),
+                Some("yes")
+            );
+            assert!(!replaced.env.contains_key("AI_GATEWAY_API_KEY"));
+
+            let inherited = sidecar
+                .resolve_javascript_child_process_execution(
+                    vm,
+                    &parent_env,
+                    &vm.guest_cwd,
+                    &vm.host_cwd,
+                    &crate::protocol::JavascriptChildProcessSpawnRequest {
+                        command: String::from("echo"),
+                        args: vec![String::from("hello")],
+                        options: crate::protocol::JavascriptChildProcessSpawnOptions::default(),
+                    },
+                )
+                .expect("resolve child with inherited environment");
+            assert_eq!(
+                inherited.env.get("AI_GATEWAY_API_KEY").map(String::as_str),
+                Some("must-not-leak")
+            );
+
             // execve resolves a literal relative/absolute pathname and must
             // not reuse spawnp's basename fallback. `/workspace/echo` does not
             // exist even though an `echo` command is installed on PATH.
@@ -25625,6 +25681,11 @@ try {
             run_isolated_service_test("javascript-fs-promises-hot-metadata");
         }
 
+        #[test]
+        fn javascript_child_process_explicit_env_replaces_parent_regression() {
+            javascript_child_process_searches_path_for_mounted_wasm_commands();
+        }
+
         #[test]
         fn wasm_shell_external_stdout_redirect_writes_file_regression() {
             run_isolated_service_test("wasm-shell-external-stdout-redirect");

crates/sidecar-protocol/src/protocol.rs

@@ -3275,6 +3275,11 @@ pub struct JavascriptChildProcessSpawnOptions {
     pub cwd: Option<String>,
     #[serde(default)]
     pub env: BTreeMap<String, String>,
+    /// Whether the caller supplied `options.env`. Node inherits the parent
+    /// environment only when this option is omitted; an explicitly supplied
+    /// map, including an empty one, replaces it.
+    #[serde(rename = "envProvided", default)]
+    pub env_provided: bool,
     #[serde(rename = "internalBootstrapEnv", default)]
     pub internal_bootstrap_env: BTreeMap<String, String>,
     /// POSIX spawn attributes already validated by the WASM host-import

crates/v8-runtime/src/isolate.rs

@@ -133,6 +133,10 @@ pub fn init_v8_platform() {
             .spawn(move || {
                 v8::icu::set_common_data_74(&ICU_COMMON_DATA.0)
                     .expect("failed to initialize V8 ICU common data");
+                // FX's browser/WebAssembly SDK suspends guest WASM across
+                // asynchronous host fetch and workspace calls through JSPI.
+                // Flags are process-global and must be set before V8 starts.
+                v8::V8::set_flags_from_string("--experimental-wasm-jspi");
                 let platform =
                     v8::new_default_platform(V8_PLATFORM_WORKER_THREADS, false).make_shared();
                 v8::V8::initialize_platform(platform);

crates/v8-runtime/tests/event_loop.rs

@@ -9,6 +9,7 @@ use std::thread::JoinHandle;
 use std::time::{Duration, Instant};
 
 const WASM_FORTY_TWO_BYTES: &str = "0,97,115,109,1,0,0,0,1,5,1,96,0,1,127,3,2,1,0,7,12,1,8,102,111,114,116,121,84,119,111,0,0,10,6,1,4,0,65,42,11";
+const WASM_JSPI_IMPORT_BYTES: &str = "0,97,115,109,1,0,0,0,1,5,1,96,0,1,127,2,19,1,3,101,110,118,11,97,115,121,110,99,95,118,97,108,117,101,0,0,3,2,1,0,7,7,1,3,114,117,110,0,1,10,6,1,4,0,16,0,11";
 const EVENT_LOOP_WATCHDOG_TIMEOUT: Duration = Duration::from_secs(6);
 
 // Timing-sensitive assertions flake under the CPU contention of a parallel test
@@ -250,6 +251,75 @@ fn event_loop_completes_native_async_wasm_instantiate_promises() {
     );
 }
 
+fn event_loop_resumes_jspi_guest_wasm_imports() {
+    isolate::init_v8_platform();
+
+    let mut isolate = isolate::create_isolate(None);
+    let context = isolate::create_context(&mut isolate);
+    let pending = PendingPromises::new();
+    let (_tx, rx) = crossbeam_channel::unbounded::<SessionCommand>();
+    let mut bridge_cache = None;
+
+    let scope = &mut v8::HandleScope::new(&mut isolate);
+    let ctx = v8::Local::new(scope, &context);
+    let scope = &mut v8::ContextScope::new(scope, ctx);
+
+    let source = format!(
+        "globalThis.__jspiResult = null; \
+         (async () => {{ \
+           const module = new WebAssembly.Module(new Uint8Array([{bytes}])); \
+           const asyncValue = new WebAssembly.Suspending(async () => {{ \
+             await WebAssembly.compile(new Uint8Array([0,97,115,109,1,0,0,0])); \
+             return 42; \
+           }}); \
+           const instance = new WebAssembly.Instance(module, {{ env: {{ async_value: asyncValue }} }}); \
+           globalThis.__jspiResult = await WebAssembly.promising(instance.exports.run)(); \
+         }})();",
+        bytes = WASM_JSPI_IMPORT_BYTES
+    );
+
+    let (code, error) = execution::execute_script(scope, "", &source, &mut bridge_cache);
+    assert_eq!(code, 0, "unexpected execute_script exit code");
+    assert!(
+        error.is_none(),
+        "unexpected execute_script error: {error:?}"
+    );
+    assert!(
+        execution::has_pending_script_evaluation(),
+        "expected pending script evaluation for a JSPI-suspended WASM import"
+    );
+
+    let status = run_event_loop_with_watchdog(scope, &rx, &pending);
+    assert_event_loop_watchdog_did_not_fire(&status);
+    assert!(
+        matches!(status, EventLoopStatus::Completed),
+        "unexpected event loop status: {:?}",
+        status
+    );
+
+    if let Some((next_code, next_error)) = execution::finalize_pending_script_evaluation(scope) {
+        assert_eq!(next_code, 0, "unexpected finalize exit code");
+        assert!(
+            next_error.is_none(),
+            "unexpected finalize error: {next_error:?}"
+        );
+    }
+
+    let source = v8::String::new(
+        scope,
+        "typeof WebAssembly.Suspending === 'function' && \
+         typeof WebAssembly.promising === 'function' && \
+         globalThis.__jspiResult === 42",
+    )
+    .unwrap();
+    let script = v8::Script::compile(scope, source, None).unwrap();
+    let result = script.run(scope).unwrap();
+    assert!(
+        result.boolean_value(scope),
+        "expected JSPI to resume WASM after the asynchronous host import"
+    );
+}
+
 fn event_loop_surfaces_native_async_wasm_compile_errors_without_hanging() {
     isolate::init_v8_platform();
 
@@ -406,6 +476,7 @@ fn event_loop_handles_native_async_wasm_paths_without_hanging() {
     fresh_isolate_supports_rgi_emoji_unicode_sets();
     event_loop_pumps_v8_platform_tasks_for_native_wasm_promises();
     event_loop_completes_native_async_wasm_instantiate_promises();
+    event_loop_resumes_jspi_guest_wasm_imports();
     event_loop_surfaces_native_async_wasm_compile_errors_without_hanging();
     event_loop_waits_for_refed_guest_timers_between_interval_ticks();
 }

docs/content/docs/architecture.mdx

@@ -176,6 +176,7 @@ The executor is the untrusted half of the VM. It runs the guest code and reaches
 
 - **JavaScript Acceleration.** Guest JavaScript runs on a native V8 runtime (the same engine in Chrome and Node.js, with the full JIT compiler) inside an isolate. This is what we call **JavaScript Acceleration**: the guest's JavaScript executes at native speed, not through an interpreter or a translation shim. It is genuinely fast, and it presents normal Node.js semantics. See [JavaScript](/agentos/docs/javascript).
 - **WASM alongside it.** The shell (`sh`) and the coreutils behind process execution ship as WebAssembly modules, and you can run your own WASM too. See [POSIX Syscalls](/agentos/docs/architecture/posix-syscalls) and the [Compiler Toolchain](/agentos/docs/architecture/compiler-toolchain).
+- **Web WASM inside V8.** Browser-targeted modules can run inside a JavaScript process and await JavaScript host functions through JSPI. See [Async WebAssembly & JSPI](/agentos/docs/architecture/async-webassembly).
 - **Native binaries.** Tools mounted into the VM run inside the same boundary as everything else.
 - **No host fallthrough.** The executor holds no capability of its own. For every file read, process spawn, or socket open, it issues a syscall and blocks for the kernel's reply.
 
@@ -359,6 +360,7 @@ This page is the map. Each subsystem has its own detailed page in the Advanced a
 - **[Filesystem](/agentos/docs/architecture/filesystem)**: the per-VM virtual filesystem, overlays, and host-backed mounts.
 - **[Networking](/agentos/docs/architecture/networking)**: the virtual socket table, DNS, the allowlist, and guest `fetch()`.
 - **[JavaScript Executor & Socket Reactor](/agentos/docs/architecture/javascript-executor)**: how the shared Tokio runtime, V8 executor threads, coalesced readiness, bounded channels, and Node stream backpressure fit together.
+- **[Async WebAssembly & JSPI](/agentos/docs/architecture/async-webassembly)**: how web-targeted WASM suspends across JavaScript promises without requiring the POSIX sysroot.
 - **[POSIX Syscalls](/agentos/docs/architecture/posix-syscalls)**: how WebAssembly guests behave like normal POSIX programs on top of the kernel.
 - **[Compiler Toolchain](/agentos/docs/architecture/compiler-toolchain)**: how the shell and coreutils are compiled to WebAssembly and mounted into the VM.
 - **[System Prompt](/agentos/docs/system-prompt)**: the context agentOS injects into every agent session.