Third-party core plugins have no token bootstrap path — cannot call other modules via IPC

[xAlisher]

Summary

A third-party core plugin calling logosAPI->getClient("storage_module")->invokeRemoteMethod(...) silently times out (~40s) even when storage_module is running and healthy. No error is surfaced — LogosAPIClient just returns an invalid QVariant.

cc @dlipicar

Root cause

LogosAPIClient::invokeRemoteMethod auto-provisions module access by calling capability_module.requestModule(origin, target). But that call needs a pre-existing capability_module token in the process-wide TokenManager. Third-party core plugins never receive this bootstrap token at load time — main_ui gets it, arbitrary core plugins do not.

From logos_api_client.cpp:

if (token.isEmpty() && objectName != "capability_module") {
    QString capabilityToken = getToken("capability_module");  // empty for third-party plugins
    QVariant result = pmc->invokeRemoteMethod(
        capabilityToken,   // empty string
        "capability_module", "requestModule",
        QVariantList() << m_origin_module << objectName,
        timeout);
    token = result.toString();
}

callRemoteMethod in module_proxy.cpp rejects the empty capabilityToken at line 229:

if (authToken.isEmpty()) {
    return QVariant();  // silent fail — caller gets invalid QVariant after full timeout
}

Secondary finding: token validation check is inverted

module_proxy.cpp:235:

if (!tokenManager->getToken(authToken).isEmpty()) {
    // labelled "INVALID" in debug output
    return QVariant();
}

authToken is a UUID token value, but getToken() uses it as a module-name key. UUID strings are never module names, so getToken() always returns empty, and the "INVALID" branch is never taken. Effectively any non-empty string passes the token check. This will cause subtle breakage if fixed without also fixing the bootstrap gap.

Steps to reproduce

1. Create a third-party core plugin (type: core, .so loaded by logos_host)
2. In initLogos(LogosAPI* api): call api->getClient("storage_module")->invokeRemoteMethod("storage_module", "someMethod", {})
3. Launch LogosBasecamp with both plugins installed
4. Observe: 40s block, then invalid QVariant returned. No error logged by the framework.

Question

Is there an intended mechanism for core plugins to obtain cross-module IPC access?

Options we considered:

• Manifest "dependencies" field — load-order only, no token provisioning
• Manifest "capabilities" field — declarative metadata only
• logos_core_get_token("capability_module") (C API) — reads the host's TokenManager, but async IPC plumbing still required
• informModuleToken — not token-gated (Q_UNUSED(authToken)) so the loader could inject a bootstrap token when loading any core plugin

If core-to-core IPC is not a supported pattern today, that's useful to know too — we'll route through QML instead.

Environment

• LogosBasecamp AppImage: 9b52529-160
• SDK: logos-cpp-sdk-headers-0.1.0 (nix store)
• Ubuntu 24.04

---

[Claude Code] — filed on behalf of a notes module developer

[xAlisher]

Testing report: pre-release-8d09a32-173 with user-installed third-party plugins

Filed by Fergie (Claude Code agent) on behalf of @xAlisher

---

We tested this release against two user-installed plugins: notes (core + ui_qml) and stash (core + ui_qml), where stash's checkAll() calls invokeRemoteMethod("NotesBackend", "getFileForStash") on the notes logos_host to trigger a backup.

What this release fixed for us

• Dependency auto-loading (Dependency auto-loading broken for user-installed third-party modules (ui_qml) #141) working — notes_ui with "dependencies": ["keycard", "notes"] now spawns both cores before QML loads. No more 20s timeout.
• Cross-registry discovery improved: stash logos_host now connects to local:logos_notes directly. Wasn't working pre-160.

What's still missing — and why

After exploring the SDK source we understand the failure chain:

Layer 1 — stash logos_host has no bootstrap token for capability_module. getToken("capability_module") returns "" immediately for third-party plugins — only main_ui receives the bootstrap token at load time.

Layer 2 — the empty token hits a hard reject in LogosAPIConsumer before requestModule is even called. The 20s timeout we observe is the consumer waiting for a capability_module replica that it can never authenticate to.

So the question answers itself: cross-module invokeRemoteMethod between two user-installed core plugins is not a supported path in the current SDK. The spec only documents main_ui → Logos Module as an authenticated IPC pattern. Core → core is not described anywhere.

Possible workaround we're exploring

LogosQmlBridge in the Basecamp process (main_ui) holds tokens for all loaded modules. So logos.callModule("notes", "getFileForStash", []) called from stash_ui's QML layer — rather than from the stash C++ logos_host — may bypass the token bootstrap problem entirely, routing through the main process which already has both tokens.

Is this the intended pattern for cross-module coordination between user-installed plugins? Or is there a planned SDK path for core → core IPC that we should wait for?

[dlipicar]

hmm I don't believe the root cause analysis is correct here. Maybe the modules trying to talk to each other were built incompatible module-builder versions? could you retry with logos-module-builder@tutorial-v2?

[fryorcraken]

Hit this on basecamp 0.1.2 with logos-module-builder@tutorial-v2
(dlipicar's suggested combination above). The behaviour is worse than
the original silent timeout — the consumer plugin crashes hard at
init instead of failing silently.

Reproduction

• App: logos-witness
• A core-type plugin (logos_witness_core) that calls
  m_logos->storage_module.init(...) and
  m_logos->delivery_module.subscribe(...) from its initLogos() —
  the documented typed-accessor pattern from the journey docs.
• A ui_qml plugin (logos_witness_ui_qml) that declares
  dependencies: ["logos_witness_core"] so basecamp loads the core
  before the UI.
• Pinned versions:
  • basecamp 2576ef8f (tag 0.1.2 / tutorial-v2)
  • logos-module-builder pinned to tutorial-v2 (b15a3724) at the
    top of both flakes
  • storage_module / delivery_module inputs with
    inputs.logos-module-builder.follows = "logos-module-builder" to
    avoid the mixed-version trap dlipicar flagged

Symptoms

basecamp log lines on launch:

[warning] Failed to register token with capability module for: delivery_module
[info]    Module loaded: delivery_module
[warning] Failed to register token with capability module for: storage_module
[info]    Module loaded: storage_module
[warning] Failed to register token with capability module for: logos_witness_core
[info]    Module loaded: logos_witness_core
[critical] Module process crashed: logos_witness_core

Process stderr (caught via the launcher, not basecamp's log):

corrupted size vs. prev_size in fastbins

Crash happens ~90ms after logos_witness_core loads. Every
non-main_ui plugin gets the "Failed to register token" warning on
0.1.2 — that's the new visible signature of the bootstrap-token gap
described in this issue's OP. In our case the warning becomes
fatal because our core plugin actually exercises cross-module IPC
(unlike e.g. the demo apps which only consume the QML→main_ui lane).

What we tried

1. Original setup: logos-module-builder@5e196e2 + basecamp
   pre-release-b44a5cf-260 → silent failure (timeouts, missing
   data, but no crash). Submit worked sometimes, sometimes not.
2. logos-module-builder@tutorial-v2 + basecamp 0.1.2 (per
   dlipicar's suggestion) → hard crash, fastbins corruption.
3. Same as (2) + follows on storage/delivery transitive
   module-builder inputs → still crashes. flake.lock confirms the
   top-level + main consumers all resolve to b15a3724; only
   logos-capability-module's own transitive module-builder
   remains at b0e41abf. Doesn't seem to make a difference.

In all three configurations, the call shape is the documented one
(m_logos->X.method(...) typed accessor) — not the untyped
invokeRemoteMethod lane the OP started with.

What this suggests

The OP's diagnosis ("core → core IPC is not a supported path")
matches our observation. Switching to a synced module-builder
version doesn't fix it; the bootstrap-token gap is real. On 0.1.2
the failure mode changed from "silent timeout" to "fatal at load"
because the new token-check path crashes inside the dep's init when
the auth handshake fails.

The OP's proposed workaround (route through QML → main_ui process
which already has tokens) is the only path we can see. We can do
that by moving storage_module.init / delivery_module.subscribe
out of logos_witness_core and into our UI plugin's backend (where
the calls would still cross processes but at least originate in a
context that has the bootstrap token). Confirming that's the
intended pattern would be useful.

Question

Two options upstream-side, in priority order:

1. Inject a capability_module bootstrap token into every loaded
   core plugin at load time (the OP's option suggesting
   informModuleToken could carry this). One-line fix in the
   plugin loader; unblocks the entire third-party-core-IPC lane.
2. Document that core → core IPC isn't supported and that
   cross-module coordination must go through the host's QML bridge.
   Cheaper to ship, but pushes architectural friction onto every
   app that needs more than one user-installed module.

Either resolves the original issue; (1) is the more powerful
answer. Happy to test patches.

[fryorcraken]

@dlipicar @iurimatias flag as critical label, justification:

1. We request in all RFPs that the deliverable are split in a core module + ui module, so that we can build more refine UI on their protocol module. This is an architecture we want to see working.
2. Similarly, for sample app such as forum, multisig, we want to have core module with most of the logic, and different UIs to use them.

[dlipicar]

@fryorcraken notes on partial progress on this issue:

• We found an issue in logos-tutorial/tutorial-v2 where the libcalc library isn't getting bundled correctly with the module, causing it to segfault on every call. Most likely not related to the issue you're facing in logos-witness, but still worth mentioning just in case.

• I built, as an example, logos-accounts-module and logos-accounts-ui pinning logos-module-builder to tutorial-v2 and it works just fine in Basecamp 0.1.2 . There's nothing special about these packages compared to any other "third party" package.

We're gonna fix the example modules and then I'll check your repo a bit better. I saw some weird stuff with QThread and QThreadPool that are big red flags, but still need to make sense of it.

[fryorcraken]

@dlipicar can I see your examples?

[dlipicar]

@fryorcraken

logos-tutorial/tutorial-v2 updated to have working logos-calc-module. tags on all other referred repos haven't moved
https://github.com/logos-co/logos-tutorial/tree/tutorial-v2

as for examples, check any of the ones you can download through Basecamp's package manager UI such as https://github.com/logos-co/logos-accounts-ui, https://github.com/logos-co/logos-chat-ui, https://github.com/logos-co/logos-package-manager-ui. They aren't treated differently in any way compared to the ones you can compile and install yourself (referring to an earlier comment about third-party plugins not being able to get a token).
I can't 100% vouch for the coding style, but you've got several different use cases covered there (wrt UI QML <-> UI Backend <-> Core Module communication). Please tell me if you have some special requirements in this regard and I'll look into it.

Still need to look deeper into the logos-witness repo. Couple notes in the meantime.

About the Core module:

Some things I see are due to unfortunate decisions in how the dependency modules are done.
For example, storage_module seems to have mostly methods that return immediately and inform progress via events (then you have to do a bunch of stuff here with timers and eventloops https://github.com/fryorcraken/logos-witness/blob/main/logos-witness-core/lib/storage_client.cpp#L139).
We favour making events blocking, since Async versions of methods are autogenerated (see how package manager UI calls installPluginAsync https://github.com/logos-co/logos-package-manager-ui/blob/master/src/PackageManagerBackend.cpp#L647, while package manager module only declares a blocking installPlugin method https://github.com/logos-co/logos-package-manager-module/blob/b0401c0058f3b7492185aaf55aba425cc5257b36/src/package_manager_impl.h#L23)

About the UI:

I have no idea wtf is going on with all these QThread/QThreadPool things, I'd start by getting rid of them and figuring out why your AI put them there to begin with.
There is one limitation in the shipped cpp-sdk (which has been fixed in master), where depending on what you do in the callback you might need to defer it to the EventLoop (see what's done here, for example: https://github.com/logos-co/logos-chat-ui/blob/master/src/ChatBackend.cpp#L240). This won't be needed anymore on the next module-builder release.
Other than that, you should be able to safely call either the "normal" or "Async" version of methods without doing any threading wizardy.

[fryorcraken]

Update from a fresh attempt on a new minimal repro app, fryorcraken/ui-core-core @ 7cebe86 — app-ui (ui_qml + C++ backend, Part 3 template) → app-core (core) → storage_module + delivery_module. All pinned to logos-module-builder@tutorial-v2, with storage_module.inputs.logos-module-builder.follows = "logos-module-builder" per @dlipicar's earlier suggestion.

Short version

• Cross-module IPC works between third-party plugins when the inherited PluginInterface::logosAPI field is assigned in initLogos (more on that below). app_core reaches storage_module and delivery_module via the typed SDK, and app_ui reaches app_core via the same — both ways. Storage status flows end-to-end and the UI paints Storage: started=yes connected=yes. This is encouraging — it lines up with @dlipicar's report that logos-accounts-module + logos-accounts-ui work on 0.1.2.
• The remaining failure is narrower than this issue's OP and looks like two bugs in logos-delivery-module@v0.1.x, not in basecamp's token bootstrap. Filing details below; happy to move them to a new issue or to logos-co/logos-delivery-module if that's preferred.

What the docs say vs what we observe

Compared the local code against the authoritative tutorial-v2 docs and logos-docs PRs #166 / #226 / #284 before filing. The code matches the docs everywhere I checked. Two real divergences between the docs and the shipped binaries:

1. PluginInterface::logosAPI is not a global — it's a public field on the base class

tutorial-wrapping-c-library.md (Part 1) Troubleshooting says:

If inter-module calls or API features silently fail, check that initLogos assigns to the global logosAPI variable (defined in the Logos SDK / liblogos), not to a class member like m_logosAPI.

There is no extern LogosAPI* logosAPI anywhere in logos_api.h or other liblogos headers. The "global" the doc means is actually a public field on PluginInterface itself:

// liblogos-headers/include/interface.h
class PluginInterface {
public:
    LogosAPI* logosAPI = nullptr;   // ← inherited by every plugin
};

Without logosAPI = api; in initLogos, our app_ui subscription to app_core.on("statusChanged", …) never fires — even though app_core is emitting eventResponse("statusChanged", …). Setting the inherited field fixed the cross-module event flow. Worth a tutorial PR if @dlipicar agrees the diagnosis matches the SDK's internal expectation.

2. delivery_module.start() returns success=false on a fully operational node

In app_core::initLogos we call m_logos->delivery_module.startAsync(cb, Timeout(60000)). The callback fires at exactly 60s with success=false and an empty error string. But the host stdout shows the node is fully up: relay traffic with 4+ peers within seconds, kademlia discovery working, filter protocol mounting, libp2p ping protocol active. We see lines like:

[delivery_module] DBG sent relay message ... to_peer_id=16U*T3UNSE ...
[delivery_module] DBG received relay message ... from_peer_id=16U*P1S397 ...

while the startAsync callback is still waiting to fire.

Sync delivery_module.start() (the path PR #226 §3.6 documents — "All lifecycle calls (createNode, start, stop, subscribe, unsubscribe, send) are synchronous and return LogosResult") behaves identically: returns success=false after exactly 20s (the SDK default), again with the node fully operational. So the timeout is inside delivery_module.start() itself, not in the SDK's IPC layer.

We can't use sync because app_core::initLogos then blocks longer than the standalone-app's 10s ui-host ready handshake — which produces the "Failed to load UI plugin" symptom — but that's a separate concern.

3. connectionStateChanged event documented in PR #226 is never emitted

PR #226 §3.1 documents this as the authoritative liveness signal:

m_logos->delivery_module.on("connectionStateChanged", [](const QVariantList& data) {
    // data[0]: QString — connection status
    // data[1]: QString — ISO-8601 timestamp
});

Wire your handlers before start() so you don't miss the first connectionStateChanged event

We subscribe before createNodeAsync (handler is registered ~1s before createNode is called). Waited 90+ seconds while the node was actively relaying messages with 4+ peers. Zero events ever delivered to the handler. No other event from delivery_module arrives either, but I didn't subscribe to messageReceived / messageSent to verify (could add that as another probe if useful).

Either the event is implemented under a different name in v0.1.x, or it was never wired up — but PR #226 and the shipped binary disagree. This is the visible cause of Delivery: started=no connected=no in our UI even though the node is healthy.

What changed in this round

fryorcraken/ui-core-core@7cebe86 — assign inherited logosAPI field, document upstream bugs. Pins:

• logos-module-builder@tutorial-v2 (b15a3724)
• storage_module and delivery_module unpinned (their tutorial-v2-compatible refs), with inputs.logos-module-builder.follows
• basecamp not used directly for this run — nix run . from app-ui/ launches the standalone-app, which is enough to exercise the same code paths as basecamp 0.1.2 for the IPC question

Asks

1. Token bootstrap on basecamp 0.1.2: in this minimal repro running outside basecamp, storage's IPC works without any special token setup. Does basecamp's plugin loader inject something the standalone-app doesn't? If yes, that might be why logos-witness still fails to call across modules on 0.1.2 even though accounts-module works. Happy to test a nix run against basecamp directly if you'd like a side-by-side.
2. delivery_module.start() / connectionStateChanged: if these reproduce on your side too with accounts-module or another delivery_module consumer, they're worth filing against logos-co/logos-delivery-module. If they're specific to my setup, I'd appreciate a pointer to what's different.
3. PluginInterface::logosAPI field documentation: small but high-leverage doc fix — Part 1's "global variable" framing is misleading, and Part 3's Step 5 example doesn't show the assignment at all. I think this is one line of code added to both tutorials.

Happy to dig further on any of these.