NULLAIN Tool Fabric

NULLAIN Tool Fabric is a secure, local execution module written in C++20. It serves as a secure, observable interface between high-level orchestration layers (e.g., TS, Node, Rails) and the local machine's operating system.

Philosophy

• Determinism before autonomy: The runtime does not decide what to do; it executes registered tasks exactly as specified.
• Observability by default: Every execution creates a machine-readable trace JSON line in .traces/nullain-tool-fabric.jsonl. (Note: Trace write failures are currently non-fatal. The runtime will not crash if the trace file cannot be written. This preserves tool execution stability but means trace loss is possible. A future version may add configurable trace failure policies such as silent, stderr, or strict).
• Zero magic, low-level first: Small modules, clear structures, and zero dynamic LLM interactions or vector databases.

---

What it is vs. What it is NOT

What it IS	What it is NOT
A local C++20 tool executor	A cognitive agent framework
Confinement layer for paths & processes	An LLM orchestrator
Append-only JSONL execution tracker	A vector database or search tool
Low-overhead cross-platform executable	A networking daemon or server (yet)

---

Integration Model

NULLAIN-AGENT / Node.js / Rails
        │
        ▼ (stdin/arg payload)
nullain-tool-fabric (C++ binary)
        │
        ├──────────────────────┐
        ▼                      ▼
  Local OS (FS / Proc)     JSONL Trace Logs

---

Features

1. filesystem.list_directory: Safe recursive directory listing with depth limits.
2. filesystem.read_file: Size-capped reading with binary rejection and full UTF-8 character screening.
3. filesystem.write_file: Overwrite guard, isolation from .git and .traces, and protection against Windows device names (CON, PRN, AUX, etc.).
4. process.run: Spawns processes bypassing cmd.exe shell injection risks. Maps to a strict allowlist of binaries, intercepts shell built-ins (like echo) in C++, and uses non-blocking polling to drain buffers and enforce timeouts.

---

Build Guide

Ensure you have CMake (>= 3.20) and a C++20 compliant compiler (MSVC 2019/2022 on Windows, GCC 10+, Clang 10+).

Generic / Unix-like Environments:

# Generate Build files
cmake -B build

# Build target binaries and tests
cmake --build build --config Release

# Run automated tests
ctest --test-dir build -C Release

Windows (PowerShell with Visual Studio Build Tools):

If cmake is not directly in your environment PATH, you can execute it by referencing the Visual Studio Build Tools installation:

# Define Build Tools executable paths
$CMake = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe"
$CTest = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\ctest.exe"

# Generate build files with compile commands exported
& $CMake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

# Build target binaries and tests
& $CMake --build build --config Debug

# Run automated tests
& $CTest --test-dir build -C Debug

---

Usage Examples

Run a command via payload files:

# Execute list directory example
nullain-tool-fabric run --request examples/requests/list_directory.json

# Execute read file example
nullain-tool-fabric run --request examples/requests/read_file.json

# Run safe echo command
nullain-tool-fabric run --request examples/requests/run_command.json

Or run tools directly via inline JSON strings:

# Inline list directory
nullain-tool-fabric run --inline "{\"tool\":\"filesystem.list_directory\",\"input\":{\"path\":\"./\",\"recursive\":false}}"