welsonjs

WelsonJS Agent Architecture Guide

This guide describes the architecture and contributor conventions visible in this repository. Treat the source code and project files as authoritative when behavior changes.

1. Runtime overview

WelsonJS is a Windows application framework built around the Windows Script Host (WSH) JScript engine, with an application loader in app.js, startup scripts at the repository root, JavaScript modules in lib/, and optional .NET components in native/WelsonJS.Augmented/.

The runtime is not a general-purpose sandbox. Scripts can reach Windows facilities through COM, JavaScript modules, and installed managed components. Document required privileges and side effects for any such functionality.

JavaScript runtime and modules

2. Managed projects

The solution native/WelsonJS.Augmented/WelsonJS.Augmented.sln contains these projects:

Project Role
Catswords.Phantomizer Assembly loading support. Consult its implementation and README for supported sources, caching, and verification behavior.
WelsonJS.ManagedObject Shared managed types and Windows/COM integration helpers used by other projects.
WelsonJS.Launcher Managed application launcher and related startup/UI components.
WelsonJS.Service Windows service host and lifecycle support.
WelsonJS.Esent ESENT database integration.
WelsonJS.Cryptography Managed Korean block ciphers (ARIA, SEED, HIGHT) as SymmetricAlgorithm classes, with the modes ECB, CBC, CFB, OFB, CTS, CTR, GCM, CCM and CMAC; see its README.md.
WelsonJS.Cryptography.Test Checks WelsonJS.Cryptography against published test vectors and .NET’s AES; exits with 1 on a failure (dotnet run --project native\WelsonJS.Augmented\WelsonJS.Cryptography.Test).

Do not assume every capability is implemented by a managed project: many APIs live in lib/ and interact directly with WSH, COM, external programs, or optional components. Preserve graceful handling of unavailable optional dependencies where the surrounding API already provides it.

3. Contributor principles

4. Test profiles and runner

Test profiles are JSON files under data/, including:

Profiles use schema version 0.2 and describe tests using metadata and a tests array. A profile entry documents a test; it does not by itself implement or execute the test.

testloader.js contains a test_implements map keyed by test ID. It expects a single test ID and a profile path, looks up that ID in both places, and calls the corresponding implementation. For example:

cscript.exe app.js testloader es5_polyfills data\test-oss-korea-2023.json

The runner logs the result and waits before closing. It is an interactive/manual harness, not a profile-wide automated pass/fail runner. Test implementations can have side effects or require Windows features, installed applications, network access, or user interaction; inspect the selected implementation before running it. Keep IDs consistent between the profile and test_implements, and describe requirements and effects in the profile entry.

The cryptography validation project is separate from the JavaScript profile runner. Use the relevant project documentation and build configuration for that suite.

5. Repository map

Path Contents
app.js WSH runtime, module loading, and command dispatch.
lib/ JavaScript libraries and integrations.
data/ Configuration, data files, and JSON test profiles.
native/WelsonJS.Augmented/ WelsonJS managed solution and projects.
native/ManagedEsent/ Vendored ManagedEsent source, samples, and tests.
native/chakracore/ ChakraCore build (pinned commit, resource patch, build script), built on a developer PC for x64, arm64 and x86 and published to the WelsonJS blob storage, from which CI restores it (native/restore-prebuilt.ps1); see its README.md.
native/crispembed/ CrispEmbed build for the launcher’s embedding and decision servers (pinned commit, build script), built on a developer PC for x64, arm64 and x86 and published to the WelsonJS blob storage, from which CI restores it (native/restore-prebuilt.ps1); see its README.md.
native/llamacpp/ Patched llama.cpp build from bitnet.cpp’s llama.cpp fork with BitNet I2_S support (pinned commit, patches, build script), built on a developer PC for x64, arm64 and x86 and published to the WelsonJS blob storage, from which CI restores it (native/restore-prebuilt.ps1); see its README.md.
examples/ Application and integration examples.

When updating this guide, verify project names, entry-point behavior, and profile paths against the checked-in repository rather than carrying forward outdated architecture descriptions.