Developer Extensibility & Mesh Systems

How to extend _AugmentedIntelligence with new capabilities, and how the multi-node mesh stack works. This is the developer counterpart to the user-facing install/usage docs.

Two extension surfaces:

• Native C++ modules — compiled into the host, each exposing a typed command and (optionally) Lua globals.
• Lua scripts — orchestrators that drive the runtime through the registered Lua API, without recompiling.

The mesh systems (NetMesh, NetFeatures, NetLLM) are themselves ordinary modules that follow the same contract, so understanding the module contract explains the whole system.

Part 1 — The module contract

Every extensible subsystem is a class named _Something with static entry points. The minimal contract:

#pragma once
// Apache 2.0 header ...
#include "AugmentedIntelligence.hpp"      // the platform umbrella header
using namespace std;

class _MyModule
{
public:
    // Optional lifecycle
    static void Init();
    static void Shutdown();
    static string GetStatus();

    // Typed-command entry point. `command` is the whitespace-tokenized input;
    // `start_index` is where this module's arguments begin.
    static void HandleSpeechCommand(const vector<string>& command, size_t start_index = 0);

    // Expose scripting helpers to the embedded Lua VM.
    static void RegisterLuaGlobals(lua_State* L);
};

The tested-core pattern (recommended)

Most numeric/logic subsystems split into:

The pure core is unit-tested offline via tests/run_math_tests.ps1 (a MinGW g++ harness with a shim AugmentedIntelligence.hpp), while the glue is validated by static review + the real MSVC build. Keeping the testable logic in a header-only *Core.hpp is the single most useful convention in this codebase.

Part 2 — Adding a typed command

Typed commands are the primary control plane. Dispatch is an additive block in SpeechCommands.cpp (myCallback), where each umbrella claims a top-level verb and returns early:

// SpeechCommands.cpp — v11 build-cycle command umbrellas
if (!command.empty() && command[0] == "net")   { _NetworkingFeatures::HandleSpeechCommand(command, 0); return vector<string>(); }
if (!command.empty() && command[0] == "rl")    { _RLFeatures::HandleSpeechCommand(command, 0);        return vector<string>(); }
if (!command.empty() && command[0] == "nn")    { _MathNNFeatures::HandleSpeechCommand(command, 0);    return vector<string>(); }
// ... calc, algebra, de, mlapp, ...

Steps

1. Create MyModule.hpp / MyModule.cpp implementing HandleSpeechCommand.
2. Include the header in SpeechCommands.cpp and add one dispatch line to the umbrella block: cpp if (!command.empty() && command[0] == "mymod") { _MyModule::HandleSpeechCommand(command, 0); return vector<string>(); }
3. Register the source in _AugmentedIntelligence.vcxproj (<ClInclude> + <ClCompile>) and .vcxproj.filters.
4. (Optional) Add a suite_mymodule.cpp + core header and wire it into tests/run_math_tests.ps1.

Sub-command umbrella pattern

For a family of related commands, dispatch on the next token — exactly how net fans out:

void _NetworkingFeatures::HandleSpeechCommand(const vector<string>& command, size_t start_index)
{
    const string selector = command.size() > 1 ? command[1] : "";
    if (selector == "features") { _NetFeatures::HandleSpeechCommand(command, start_index + 2); return; }
    if (selector == "mesh")     { _NetMesh::HandleSpeechCommand(command, start_index + 2);     return; }
    if (selector == "llm")      { _NetLLM::HandleSpeechCommand(command, start_index + 2);      return; }
    // else: print usage
}

command is the tokenized line (command[0] = verb); parse your arguments starting at start_index.

Part 3 — Exposing a Lua API

Scripts run in the embedded Lua VM. To make a module scriptable:

1. Implement RegisterLuaGlobals(lua_State* L) using lua_register and the C-API push/check helpers: cpp static int l_mymod_do(lua_State* L) { const char* arg = luaL_checkstring(L, 1); lua_pushnumber(L, /* result */); return 1; // number of return values } void _MyModule::RegisterLuaGlobals(lua_State* L) { lua_register(L, "mymod_do", l_mymod_do); }
2. Hook it in to the host's Lua init — the registration list in RSIAgent.cpp: cpp // RSIAgent.cpp — registerExtendedLuaGlobals(lua_State* L) _HardwareAcceleration::RegisterLuaGlobals(L); _PerceptionBus::RegisterLuaGlobals(L); // ... add: _MyModule::RegisterLuaGlobals(L);

Existing Lua surfaces you can build on

Lua orchestrators live in lua_scripts/ (e.g. the RL orchestrators). They're loaded at runtime — no recompile needed to iterate on behavior.

Part 4 — Mesh systems

The mesh turns a single always-on node into a self-organizing fleet. Entry point: the net command → _NetworkingFeatures → three modules.

net features <...>   -> _NetFeatures   (security / resilience / observability)
net mesh <...>       -> _NetMesh        (discovery / gossip / relay / federation)
net llm <...>        -> _NetLLM         (distributed LLM routing)

4a. NetMesh — fleet fabric

Built on the existing RemotePeer registry ( _Networking remote-commands channel).

4b. NetFeatures — security, resilience, observability

Dependency-light (std + OpenSSL, already linked). Hardens the remote-commands channel.

4c. NetLLM — distributed inference

Ports summary

Security model

Capability tokens (scoped + expiring) replace a single shared secret, every relayed command is authorized for a scope, the kill-switch/quarantine severs compromised peers, and the audit log is tamper-evident. Heavier transports are declared but stubbed until their library is wired — each returns a clear not-implemented status:

Part 5 — Wiring status & how to finish it

• Typed commands (net …) are wired into the host dispatcher (SpeechCommands.cpp), and _NetworkingFeatures::InitAll() starts the three modules.
• Lua globals: _NetworkingFeatures::RegisterLuaGlobals(L) is implemented but confirm it's called from your Lua init (RSIAgent.cpp registerExtendedLuaGlobals) — add it alongside the other module registrations if you want the net_* helpers in scripts.
• Stubs (_SecureChannel, _KerberosAuth, _WebRtcEgress, _MqttBridge, _LlmStreamingRelay) compile and return a not-implemented status until their third-party library is linked.

See NETWORKING_FEATURES.md (repo root) for the full brainstorm-to-code status matrix of every mesh feature.

Checklist: ship a new module

• [ ] MyModuleCore.hpp (pure, testable) + MyModule.{hpp,cpp} (glue), Apache header, #include "AugmentedIntelligence.hpp".
• [ ] HandleSpeechCommand implemented; dispatch line added to SpeechCommands.cpp.
• [ ] RegisterLuaGlobals implemented (if scriptable); call added to RSIAgent.cpp.
• [ ] <ClInclude>/<ClCompile> added to .vcxproj and .vcxproj.filters.
• [ ] suite_mymodule.cpp + core wired into tests/run_math_tests.ps1; run_math_tests.ps1 green.
• [ ] Builds in a real MSVC configuration (Release-GPU-AVX2 or a CPU variant).

Related documents

• NETWORKING_FEATURES.md — mesh feature status matrix (source of truth)
• AGENT_ORCHESTRATION.md — multi-agent / Lua orchestration
• MathNN.md — native neural-net framework (ai_nn_* Lua API)
• ReinforcementLearning.md — RL hub (curriculum, MathNN, domains)
• AugmentedIntelligenceSystems.md — whole-app system map
• FileSystemUpdate.md — background FS inventory + MySQL
• LifeRL.md — advisory life-domain RL
• Windows-Install.md / Ubuntu-Install.md — build & run