{"id":2048,"date":"2026-07-18T06:47:55","date_gmt":"2026-07-18T13:47:55","guid":{"rendered":"http:\/\/macdaddy4sure.ai\/?p=2048"},"modified":"2026-07-18T06:47:55","modified_gmt":"2026-07-18T13:47:55","slug":"plugin-sdk","status":"publish","type":"post","link":"http:\/\/macdaddy4sure.ai\/index.php\/2026\/07\/18\/plugin-sdk\/","title":{"rendered":"Plugin SDK"},"content":{"rendered":"\n

How to write a plugin for _AugmentedIntelligence using the _IPlugin interface and the PLUGIN_REGISTER self-registration macro. This is the modern extension path \u2014 a plugin declares a manifest<\/strong>, an optional command schema<\/strong>, and the scopes it needs, and the host loads it with no hand-edits<\/strong> to SpeechCommands.cpp or RSIAgent.cpp.<\/p>\n\n\n\n

**Status.** The pure SDK core (`PluginCore.hpp`) is unit-tested (`tests\/suite_plugin.cpp`). Host glue is **wired**: `PluginManager::Init` at boot, `TryHandle` early in `SpeechCommands`, Lua registration from `AgentRuntime`, builtin plugins in `BuiltinPlugins.cpp`. See also [PluginBridges.md](PluginBridges.md) for the unified bridge manager.<\/em><\/p>\n\n\n\n

Related: Developer-Extensibility.md (Developer-Extensibility.md) covers the legacy<\/em> module contract; this document covers the plugin SDK that supersedes it.<\/p>\n\n\n\n

1. Anatomy of a plugin<\/h2>\n\n\n\n

A plugin is a class implementing _IPlugin (from PluginManager.hpp):<\/p>\n\n\n\n

[cpp]
<\/em>class _IPlugin
{
public:
    virtual ~_IPlugin() {}
    virtual plugincore::Manifest Manifest() const = 0;                  \/\/ required: identity + capabilities
    virtual vector<plugincore::Command> Commands() const { return {}; } \/\/ optional: declarative arg schema
    virtual void Handle(const vector<string>& command, size_t start_index) = 0; \/\/ required: do the work
    virtual void RegisterLua(lua_State*) {}                             \/\/ optional: expose Lua globals
    virtual void OnLoad() {}                                            \/\/ optional lifecycle hook
    virtual void OnUnload() {}
};<\/p>\n\n\n\n

You provide at minimum Manifest() and Handle().<\/p>\n\n\n\n

2. Quick start \u2014 a minimal plugin<\/h2>\n\n\n\n

[cpp]
<\/em>\/\/ GreetPlugin.cpp
#include “PluginManager.hpp”

using namespace std;

class _GreetPlugin : public _IPlugin
{
public:
    plugincore::Manifest Manifest() const override
    {
        \/\/ The key=value manifest format (parsed + validated by PluginCore).
        return plugincore::parseManifest(
            “name=greet\\n”
            “version=1.0.0\\n”
            “min_host=11.0.0\\n”
            “commands=greet\\n”
            “scopes=\\n”);            \/\/ no host capabilities needed
    }

    vector<plugincore::Command> Commands() const override
    {
        plugincore::Command c;
        c.verb = “greet”;
        c.help = “greet someone by name”;
        c.args = { { “name”, “string”, true, “who to greet” } };
        return { c };
    }

    void Handle(const vector<string>& command, size_t) override
    {
        \/\/ command[0] == “greet”; args follow.
        const string who = command.size() > 1 ? command[1] : “world”;
        cout << “Hello, ” << who << “!” << endl;
    }
};

\/\/ Self-register at startup. Second arg = the capability scopes to grant.
PLUGIN_REGISTER(_GreetPlugin, {});<\/p>\n\n\n\n

Add the file to the project (<ClCompile> in the vcxproj + filters), rebuild, and \u2014 once the SDK is wired into the host \u2014 typing greet Ada runs it. No dispatch or Lua-registration edits required.<\/p>\n\n\n\n

3. The manifest<\/h2>\n\n\n\n

Declares identity and requirements. Parsed from a simple key=value block (plugincore::parseManifest) \u2014 one key per line, # comments allowed:<\/p>\n\n\n\n

Key<\/strong><\/td>Meaning<\/strong><\/td>Example<\/strong><\/td><\/tr>
name<\/td>Unique plugin id (required)<\/td>media<\/td><\/tr>
version<\/td>Plugin semver (required)<\/td>1.2.0<\/td><\/tr>
min_host<\/td>Minimum host version it needs<\/td>11.0.0<\/td><\/tr>
commands<\/td>CSV of typed-command verbs it provides (required)<\/td>media,mv<\/td><\/tr>
scopes<\/td>CSV of capability scopes it requires<\/td>db.read,llm.invoke<\/td><\/tr>
deps<\/td>CSV of other plugin names it depends on<\/td>core<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Validation (plugincore::validateManifest) rejects a manifest with no name, no\/invalid version, or no commands, and refuses to load if min_host exceeds the running host version. You may also construct the Manifest struct directly instead of parsing text.<\/p>\n\n\n\n

4. Command schema (optional but recommended)<\/h2>\n\n\n\n

Publishing a Command schema gets you argument validation, usage\/help text, and tab-completion for free<\/strong>, and feeds the NLU natural-language\u2192command mapping.<\/p>\n\n\n\n

[cpp]
<\/em>struct Arg     { string name; string type; bool required; string help; };
struct Command { string verb; string help; vector<Arg> args; };<\/p>\n\n\n\n

    \n
  • type \u2208 string | int | float | bool \u2014 values are type-checked before your Handle runs.<\/li>\n\n\n\n
  • Required args must come before the host will dispatch; too many\/too few args produce a usage message instead of calling you.<\/li>\n<\/ul>\n\n\n\n

    [cpp]
    <\/em>plugincore::Command c;
    c.verb = “play”;
    c.help = “play a title”;
    c.args = { {“title”,”string”,true,”movie\/track title”},
               {“count”,”int”,false,”repeat N times”} };
    \/\/ usageString(c) => “play <title:string> [count:int]  – play a title”<\/p>\n\n\n\n

    If you skip Commands(), your Handle still runs \u2014 you just parse command yourself and get no auto-validation.<\/p>\n\n\n\n

    5. Capability scopes (security)<\/h2>\n\n\n\n

    Every plugin is granted only the scopes passed to PLUGIN_REGISTER (or, for DLL plugins, its manifest scopes intersected with host policy). The host checks scopes before letting a plugin reach a protected service.<\/p>\n\n\n\n

    Scope matching (plugincore::authorize):<\/p>\n\n\n\n

    Granted<\/strong><\/td>Matches<\/strong><\/td><\/tr>
    llm.invoke<\/td>exactly llm.invoke<\/td><\/tr>
    net.*<\/td>any net.<something> (wildcard)<\/td><\/tr>
    *<\/td>everything (super-scope \u2014 grant sparingly)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    [cpp]
    <\/em>PLUGIN_REGISTER(_MediaPlugin, { “db.read”, “llm.invoke” });   \/\/ scoped
    PLUGIN_REGISTER(_TrustedTool,  { “*” });                       \/\/ full access<\/p>\n\n\n\n

    Declare the same scopes in your manifest’s scopes= line so they’re visible in plugins info and enforced when calling the Host API.<\/p>\n\n\n\n

    6. The Host API facade<\/h2>\n\n\n\n

    Plugins reach host services through a stable facade (_PluginManager::Host()), rather than touching globals \u2014 this keeps plugins decoupled and testable:<\/p>\n\n\n\n

    [cpp]
    <\/em>struct HostApi
    {
        function<string(const string& prompt, const string& model)> Llm;
        function<void(const string& key, const string& value)>      MemoryPut;
        function<string(const string& key)>                          MemoryGet;
        function<void(const string& name, double v)>                 Metric;
        function<bool(const string& action_scope)>                   EthicsAllows;
        string host_version;
    };

    \/\/ inside Handle():
    auto& host = _PluginManager::Host();
    if (host.EthicsAllows(“actuate.write”)) {
        string answer = host.Llm(“summarize: ” + input, “gemma3:12b”);
        host.MemoryPut(“last_summary”, answer);
    }<\/p>\n\n\n\n

    7. Lifecycle & runtime enforcement<\/h2>\n\n\n\n
      \n
    • OnLoad() \/ OnUnload() \u2014 set up \/ tear down state. Called on load, unload, and plugins reload.<\/li>\n\n\n\n
    • On every dispatch, _PluginManager::TryHandle wraps your Handle with:<\/li>\n\n\n\n
    • kill-switch<\/strong> check (safe-mode blocks all plugin actuation),<\/li>\n\n\n\n
    • rate limiting<\/strong> per plugin,<\/li>\n\n\n\n
    • schema validation<\/strong> (if you published one),<\/li>\n\n\n\n
    • timing + audit<\/strong> \u2014 invocation count, error count, latency, and a tamper-evident audit entry (reusing _KillSwitch \/ _RateLimiter \/ _Metrics \/ _AuditLog from NetFeatures).<\/li>\n<\/ul>\n\n\n\n

      Exceptions thrown from Handle are caught and recorded as errors, not crashes.<\/p>\n\n\n\n

      8. The plugins command<\/h2>\n\n\n\n

      Runtime management (available once the SDK is wired in):<\/p>\n\n\n\n

      plugins list                 # all plugins, on\/off, version, verbs, call\/error counts
      plugins info <name>          # scopes, deps, avg latency, error rate
      plugins enable <name>        # turn a plugin on
      plugins disable <name>       # turn it off (its verbs stop routing)
      plugins reload <name>        # OnUnload + OnLoad (state reset; DLL reload for dynamic)
      plugins doctor               # dependency load order + cycle \/ missing-dep report
      plugins help <verb>          # usage string from the command schema<\/p>\n\n\n\n

      9. Dynamic (out-of-tree) plugins<\/h2>\n\n\n\n

      Ship a plugin as a DLL without the host source tree. Export a C entry point:<\/p>\n\n\n\n

      [cpp]
      <\/em>extern “C” __declspec(dllexport) _IPlugin* ai_plugin_entry() { return new _MyPlugin(); }<\/p>\n\n\n\n

      The host loads it with _PluginManager::LoadDynamic(“plugins\\\\mymod.dll”, err), reads its manifest, grants scopes per policy, and registers it. Unload \/ Reload manage the module handle. (This path is written but depends on the full Windows\/MSVC build; treat it as the design contract until exercised.)<\/em><\/p>\n\n\n\n

      10. Testing your plugin<\/h2>\n\n\n\n

      Follow the project’s tested-core convention:<\/p>\n\n\n\n

        \n
      1. Put pure logic in a header-only MyPluginCore.hpp (std-only) so it compiles under the g++ harness.<\/li>\n\n\n\n
      2. Write tests\/suite_myplugin.cpp exercising that logic (see tests\/suite_plugin.cpp for the pattern).<\/li>\n\n\n\n
      3. Add copies + a build\/run line to tests\/run_math_tests.ps1, and confirm it stays green.<\/li>\n<\/ol>\n\n\n\n

        The SDK’s own core is validated this way \u2014 PluginCore (registry, manifests, semver, scopes, schema, dependency ordering, metrics) has 42 passing checks in the plugin core suite.<\/p>\n\n\n\n

        Enabling the SDK in the host<\/h2>\n\n\n\n

        The SDK isn’t live until these three edits are made (kept out of this doc’s scope so you can decide the integration point):<\/p>\n\n\n\n

          \n
        • Build:<\/strong> add PluginCore.hpp, PluginManager.hpp, PluginManager.cpp to _AugmentedIntelligence.vcxproj (+ .filters).<\/li>\n\n\n\n
        • Startup + dispatch:<\/strong> call _PluginManager::Init(“11.0.0”) during boot, and at the top of myCallback in SpeechCommands.cpp call if (_PluginManager::TryHandle(command)) return vector<string>(); so plugin verbs are routed first.<\/li>\n\n\n\n
        • Lua:<\/strong> add _PluginManager::RegisterLuaGlobals(L) to registerExtendedLuaGlobals in RSIAgent.cpp.<\/li>\n<\/ul>\n\n\n\n

          API reference (essentials)<\/h2>\n\n\n\n

          `plugincore` (PluginCore.hpp) \u2014 pure, tested<\/strong><\/p>\n\n\n\n

          Symbol<\/strong><\/td>Purpose<\/strong><\/td><\/tr>
          Version, parseVersion, compareVersion, hostSatisfies<\/td>semver<\/td><\/tr>
          authorize, scopeMatches, firstMissingScope<\/td>capability scopes<\/td><\/tr>
          Arg, Command, validateInvocation, usageString, completions<\/td>command schema<\/td><\/tr>
          Manifest, parseManifest, validateManifest<\/td>plugin manifest<\/td><\/tr>
          Registry<\/td>add\/enable\/route\/metrics\/loadOrder (dependency topo-sort)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

          `_IPlugin` \/ `_PluginManager` (PluginManager.hpp) \u2014 host glue<\/strong><\/p>\n\n\n\n

          Symbol<\/strong><\/td>Purpose<\/strong><\/td><\/tr>
          PLUGIN_REGISTER(Type, {scopes})<\/td>self-registration at startup<\/td><\/tr>
          _PluginManager::Init\/Shutdown\/GetStatus<\/td>lifecycle<\/td><\/tr>
          _PluginManager::TryHandle(command)<\/td>scoped, audited dispatch<\/td><\/tr>
          _PluginManager::LoadDynamic\/Unload\/Reload<\/td>dynamic DLL plugins<\/td><\/tr>
          _PluginManager::Complete(prefix)<\/td>REPL autocomplete<\/td><\/tr>
          _PluginManager::Host()<\/td>host-service facade<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

          Related documents<\/h2>\n\n\n\n
            \n
          • Developer-Extensibility.md (Developer-Extensibility.md) \u2014 legacy module contract + mesh systems<\/li>\n\n\n\n
          • PluginCore.hpp \/ PluginManager.hpp \u2014 the SDK headers (source of truth)<\/li>\n\n\n\n
          • tests\/suite_plugin.cpp \u2014 worked examples of the core API<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"

            How to write a plugin for _AugmentedIntelligence using the _IPlugin interface and the PLUGIN_REGISTER self-registration macro. This is the modern extension path \u2014 a plugin declares a manifest, an optional command schema, and the scopes it needs, and the host loads it with no hand-edits to SpeechCommands.cpp or RSIAgent.cpp. **Status.** The pure SDK core (`PluginCore.hpp`) […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-2048","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/posts\/2048","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/comments?post=2048"}],"version-history":[{"count":1,"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/posts\/2048\/revisions"}],"predecessor-version":[{"id":2049,"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/posts\/2048\/revisions\/2049"}],"wp:attachment":[{"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/media?parent=2048"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/categories?post=2048"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/macdaddy4sure.ai\/index.php\/wp-json\/wp\/v2\/tags?post=2048"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}