Hermit/app/README.md

app/ — the Qt front end

CST-agent's GUI: Qt 6 + QML + the C engine, in one process. No HTTP server, no port, no token, no second process — the app creates a cst_agent_t directly and drives it through cst_agent.h.

app/                         the GUI
  src/main.cpp               entry point, --workspace / --selftest
  src/core/AgentCore.*       QObject around cst_agent_t: turns, hooks, consent
  src/core/ToolProvider.h    how the front end hands tools to the engine
  src/platform/<os>/         platform tools the app implements itself
  qml/Main.qml               the window (chat, tool runs, consent dialog)
  tools/selftest.c           C smoke test of the embedding path (no Qt)

Build

# engine + GUI + C smoke test
cmake -S app -B build-app -DCMAKE_BUILD_TYPE=Debug
cmake --build build-app -j
QT_QPA_PLATFORM=offscreen ctest --test-dir build-app   # cst-app-selftest

# the app alone
./build-app/cst-agent-app --workspace ~/notes
./build-app/cst-agent-app --size 480x900    # the narrow (drawer) layout
./build-app/cst-agent-app --uitest          # drive the window, exit code = failures
./build-app/cst-agent-app --selftest        # same checks as the C test

The standalone build is the supported one: app/CMakeLists.txt uses the cstcore target when the parent project defines one, and otherwise builds the engine itself from ../src (TUI, main.c and the HTTP front end excluded). Wiring it into the repository's CMakeLists.txt as -DCST_APP=ON is on the list below.

Needs Qt 6.4+ with Quick / Qml / QuickControls2 (qt6.qtdeclarative, qt6.qtquickcontrols2 on Nix; the online installer's "Qt 6.x Desktop" on Windows/macOS). Without them the configure step warns and builds only the C smoke test — that is deliberate: the embedding path stays verifiable everywhere. Kirigami is not required yet; qml/Main.qml uses Qt Quick Controls and keeps the layout in Kirigami's shape (single column, cards, navigation drawer) so swapping in org.kde.kirigami later is a QML-only change. Point the app at a Kirigami outside the Qt prefix with -DCST_APP_QML_IMPORT=/path/to/qml.

Why in one process

The engine is a library, not a daemon: libcstcore.a (Makefile) / the cstcore target (CMake). The app owns one cst_agent_t per window, so there is no protocol to version, no socket to authenticate and no second process to babysit — and the CLI, TUI and WebUI keep working off the same source.

• AgentCore::send() runs cst_agent_run_turn_ex() on a worker thread; the cst_agent_hooks_t callbacks turn into Qt signals (assistant deltas, tool events, tool results, todo, turn end).
• Consent is a blocking hook: the worker waits on a QWaitCondition, the GUI answers, the turn goes on. CST_PERM_DENY / ONCE / ALWAYS_TOOL / ALWAYS_PREFIX map 1:1 onto the buttons, and ALWAYS_* still lands in .agent/permissions.json, so a desktop decision is visible to the TUI.
• cancel() is cst_agent_request_cancel(); the turn unwinds as a normal result, not an exception.

Layout and input

One shell, three sizes (everything is styled from qml/Theme.qml):

• Desktop: the sidebar is docked and its divider can be dragged (double click restores the auto width). Hover states, tooltips, selectable text and a wheel-scrolled transcript.
• Narrow window (below Theme.compactBreakpoint, 880 px): the sidebar folds away, the header grows a ☰ button, and the settings slide in over the transcript with a scrim; the sidebar itself scrolls, because a phone window cannot show it all.
• Touch: controls keep a Theme.touchTarget (34 px) hit area, buttons do not depend on hover, the composer asks the platform keyboard not to autocorrect (ImhNoPredictiveText), and Enter/Shift+Enter still behave.

--uitest checks this without a human: it loads the window, clicks with synthesized mouse events, taps with a synthesized touch device, types into the composer, then narrows the window to 460 px to assert the dock → drawer switch and opens/closes the drawer. One line per check, non-zero exit on failure:

QT_QPA_PLATFORM=offscreen ./build-app/cst-agent-app --uitest
# ok   wide window: sidebar docked
# ok   mouse click on "general" reaches the engine
# ok   touch tap on "coding" reaches the engine
# ...

Tools the app provides

A tool implemented in the front end is registered with cst_tool_register() and the owner app:<name>, exactly like a plugin or MCP server would:

cst_tool_def_t def = {0};
def.name = "notification_send";
def.desc = "Send a system notification.";
def.perm = CST_TP_ASK;          /* class: drives the consent dialog */
def.perm_name = "notify";       /* policy: what the user is really granting */
def.platforms = ANDROID_ONLY;   /* NULL = everywhere */
def.available = probe;          /* 0 / -1 with a reason; cached */
def.run_ex = my_run;
def.ud = my_state;
def.owner = "app:android";
cst_tool_register(&def);

• platforms + available decide whether the tool exists here: an Android-only tool never reaches the prompt or tools[] on Linux, and cst_tool_run() refuses it with the reason if a model asks anyway.
• A front-end tool may take over the name of a built-in that cannot run on this host (the Android clipboard replacing the desktop xclip one); it may not shadow one that works.
• cst_tool_unregister_owner("app:android") drops them again — do it when a platform service goes away, then cst_tool_meta_reload().
• setenv("CST_PLATFORM", ...) overrides the detected host name (tests, a launcher that knows better).

Note run_ex runs on the worker thread while the turn is going: touch the GUI only through queued signals.

Platform notes

Platform	How the engine gets built	Platform tools
Linux	cmake -S app -B build-app (libcurl via pkg-config)	clipboard (shell helpers), notification (notify-send / D-Bus)
Windows	Qt's MinGW kit, cmake -G Ninja -DCMAKE_PREFIX_PATH=<Qt>/lib/cmake; the engine needs libcurl for Windows (see docs/README-windows.md)	notification via the WinRT/tray API, clipboard through the core's Win32 path
Android	engine compiled with the NDK inside the APK (-DCST_TUI=0, CST_NO_WEBUI=1); the app talks to Android APIs through Qt (JNI)	notification (Android), share sheet, clipboard, file picker
macOS	Qt from the installer, libcurl from the system	notification (osascript), clipboard (pbpaste/pbcopy)

Android's long-term shape: the core lives in the APK (no Termux needed), the platform tools are Kotlin/JNI behind the same cst_tool_register() contract. The build flag that keeps Unix helpers out of the picture is CST_PLATFORM=android (or the __ANDROID__ detection inside the engine).

Status

• engine as a library (libcstcore.a / cstcore), in-process embed API
• tool metadata: perm_name, platforms, available, shadowing rule
• AgentCore (turns, cancel, consent, todo) and the C smoke test
• QML shell: transcript cards, tool cards with diff coloring, thinking blocks, consent/ask dialogs, sidebar, responsive dock/drawer layout, --uitest for mouse, touch and small-screen checks
• a real turn driven through the window (needs a provider key)
• session list / switch, attachments, settings page
• Kirigami (Breeze look), tray, global shortcuts
• Android APK (engine in-process, JNI platform tools)