What is the 'Neural Link'?

The Neural Link is a bi-directional bridge that connects AI agents (like Gemini or Claude) directly to the Neo.mjs runtime. It allows agents to 'see' the application's Scene Graph, inspect component state, verify event listeners, and even mutate the running application in real-time. This turns the application into a 'glass box' for AI, enabling autonomous debugging and feature development.

Why is Neo.mjs called an 'Application Engine' instead of a framework?

Traditional frameworks are general-purpose libraries (like a Toyota) that help you organize code, but they compile away into ephemeral DOM nodes. Neo.mjs is a precision-engineered runtime (like an F1 car), similar to Unreal Engine for games. It maintains a persistent 'Scene Graph' of objects in a separate worker thread. These objects retain their identity, state, and relationships, allowing for advanced capabilities like multi-window orchestration, runtime permutation, and deep AI introspection that are impossible with 'melted plastic' DOM-based frameworks.

What is 'Context Engineering'?

Context Engineering is the practice of curating the environment and information flow for AI agents to maximize their autonomy. In Neo.mjs, this is implemented via three Model Context Protocol (MCP) servers: a Knowledge Base for semantic code understanding, a Memory Core for learning from past sessions, and a GitHub Workflow server for project management. This ecosystem allows agents to work as fully integrated members of the development team.

What is 'Object Permanence' in the context of Neo.mjs?

In Neo.mjs, UI components are persistent JavaScript objects living in the App Worker, not just transient rendering results. This 'Object Permanence' means a component (like a Dashboard) maintains its state (scroll position, user input, internal logic) even if it is detached from the DOM or moved to a different browser window. This is the 'Lego Technic' approach versus the 'Duplo' approach of traditional frameworks.

What is an 'Agent Operating System'?

Neo.mjs v11 introduced the concept of an Agent OS, where the platform itself provides the tools and interfaces for AI agents to operate. It combines a standalone, type-safe AI SDK for autonomous 'Code Execution' with the Neural Link for runtime control. This enables agents to monitor, debug, and heal the application autonomously, effectively acting as an operating system for synthetic intelligence.

How does Neo.mjs handle multi-window applications?

Neo.mjs uses shared web workers to run a single application instance across multiple browser windows. All windows share the same application state and data in real-time. Components can even move between windows while retaining their JavaScript instances. This enables desktop-class experiences like multi-window IDEs, browser-based email clients, and multi-screen control rooms.

What makes Neo.mjs different from React, Angular, or Vue?

Neo.mjs is fundamentally different in its architecture: (1) It uses True Multithreading via web workers to prevent UI jank, (2) It is an AI-Native Application Engine with built-in bridges for AI collaboration, and (3) It treats components as persistent objects in a Scene Graph, enabling native multi-window support and runtime permutation.

Frontmatter

id	6619
title	EINVAL / EPERM error when running build script on Windows due to D:\System Volume Information
state	Closed
labels	bugstale
assignees	[]
createdAt	Apr 5, 2025, 7:27 AM
updatedAt	Oct 23, 2025, 12:54 AM
githubUrl	https://github.com/neomjs/neo/issues/6619
author	ahmad-su
commentsCount	5
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jul 19, 2025, 5:02 AM

EINVAL / EPERM error when running build script on Windows due to D:\System Volume Information

Name: Neo.mjs Application Engine
Author: Neo.mjs

Closed v10.0.0 bugstale

ahmad-su commented on Apr 5, 2025, 7:27 AM

Description

When trying to build the appworker thread using the build script (build-all or build-threads), I get either:

EINVAL: invalid argument, stat 'D:\System Volume Information', or
EPERM: operation not permitted, stat 'D:\System Volume Information' (when not running as administrator)

This occurs on Windows when building the Neo.mjs project.

Cause

The script (likely through ContextModule.resolveDependencies) tries to access restricted system folders like D:\System Volume Information, which is not permitted.

Environment

OS: Windows 11
Node.js: v23.10
Neo.mjs: latest
Terminal: PowerShell

Additional Info

It appears that Webpack is attempting to resolve .mjs files across the entire project directory, including protected system folders. This causes permission errors on Windows.

Log

neoapp buildThreads starting dist/production
assets by status 69.9 KiB [cached] 3 assets
orphan modules 202 KiB [orphan] 27 modules
runtime modules 3.37 KiB 8 modules
built modules 275 KiB [built]
  modules by path ./node_modules/neo.mjs/src/core/*.mjs 21.3 KiB
    ./node_modules/neo.mjs/src/core/Base.mjs 19.9 KiB [built] [code generated]
    ./node_modules/neo.mjs/src/core/IdGenerator.mjs 1.39 KiB [built] [code generated]
  modules by path ./node_modules/neo.mjs/src/util/*.mjs 10.1 KiB
    ./node_modules/neo.mjs/src/util/Function.mjs 5.31 KiB [built] [code generated]
    ./node_modules/neo.mjs/src/util/Array.mjs 4.76 KiB [built] [code generated]
  ./node_modules/neo.mjs/src/worker/App.mjs + 24 modules 212 KiB [built] [code generated]
  ../../../ lazy ^\.\/.*\.mjs$ include: (?:\/%7C\\)app.mjs$ exclude: (?:\/%7C\\)no...(truncated) 160 bytes [built] [code generated]
  ./node_modules/neo.mjs/src/remotes/Api.mjs 1.81 KiB [built] [code generated]
  ./node_modules/neo.mjs/src/vdom/Helper.mjs + 3 modules 30.1 KiB [built] [code generated]

ERROR in ../../../ lazy ^\.\/.*\.mjs$ include: (?:\/%7C\\)app.mjs$ exclude: (?:\/%7C\\)node_modules strict namespace object
EINVAL: invalid argument, stat 'D:\System Volume Information'
caused by plugins in ContextModule.resolveDependencies
Error: EINVAL: invalid argument, stat 'D:\System Volume Information'
 @ ./node_modules/neo.mjs/src/worker/App.mjs 301:19-306:13

What I’ve Tried

Reinstall dependencies & rebuild as administrator npm i && npm run build-threads : leads to EINVAL err
Filter out the system folder in neo.mjs/src/worker/App.mjs, but looks like it's not the case:

if (!path.includes('D:\\System')) {
    return import(
        /* webpackInclude: /(?:\/|\\)app.mjs$/ */
        /* webpackExclude: /(?:\/|\\)node_modules/ */
        /* webpackMode: "lazy" */
        `../../${path}.mjs`
    )
}

Let me know if you need help reproducing it. Thanks

tobiu Apr 5, 2025, 4:55 PM

@ahmad-su Without having Windows installed, I can sadly not help too much on this one (flying blind).

I am sure though, that the problem is the following regex comment: /* webpackInclude: /(?:\/|\\)app.mjs$/ */. For / based file systems it does work fine, for \ it looks like it does not.

Let me explain what it is supposed to do:

For a webpack based build, the app worker => worker/App.mjs file is supposed to find all app.mjs files.

Inside the framework repo, it needs to go 2 folder levels up (repo root), and it can then find the target files inside the apps, examples & docs folder.

Inside a workspace, it needs to go 4 folder levels up, since neo is inside node_modules/neo.mjs/.

If it would try to go further up, there might be security related restrictions (permission denied).

The main idea is, that by fetching all app.mjs files, we do get split chunks & tree-shaking across multiple apps out of the box. E.g. if you would lazy-load a 2nd neo app into your website, there should be little overhead.

@ahmad-su - 2025-04-05T16:11:36Z

Thanks for the insight @tobiu , the solution is just by nesting the project folder 1 level deeper. so ../.. will not accidentally go to D:
But I'm still curious to modify the App.mjs to make it work wherever I place the project.

@github-actions - 2025-07-05T02:53:16Z

This issue is stale because it has been open for 90 days with no activity.

2025-07-05T02:53:17Z @github-actions added the stale label

@github-actions - 2025-07-19T03:02:59Z

This issue was closed because it has been inactive for 14 days since being marked as stale.

2025-07-19T03:02:59Z @github-actions closed this issue