v0.8.7: tool capability metadata, in-process engine, Qt app, Android engine
The engine can be embedded now instead of only driven from a terminal: the same objects link into a Qt front end (app/) that owns a cst_agent_t inside its own process -- no port, no token, no second process -- and that front end now runs on the desktop and, engine-side, on the phone. Capability metadata (include/cst_tools.h, src/tools/registry.c): - cst_tool_def_t gains perm_name, platforms and available (a probe that returns a reason), so a permission is addressable by name and a tool can say why it cannot run here. - cst_platform_name(), cst_tool_platform_ok(), cst_tool_available(), cst_tool_meta_reload(), cst_tool_perm_name() and CST_PLAT_DESKTOP[]. - cst_tool_register() may take over a built-in name that is not runnable on this platform, so a front end replaces it with its own implementation. - the registry entries carry their class (delete_file -> "delete"), the desktop clipboard tools carry a clipboard probe; find/active/run gate on it. - /api/settings.tools[] exposes perm_name, platforms, available, why and the declared parameters. Engine as a library (Makefile, CMakeLists.txt): - libcstcore.a from the CORE_OBJ set, and a CMake cstcore target shared by the CLI and by app/ (-DCST_BUILD_APP=ON): the engine is compiled once. - Android branch for the vendored sashidown: a per-ABI archive built with the NDK's aarch64-linux-android24-clang wrapper, because CMake's compiler is plain clang and keeps --target/--sysroot in its own variables. Qt front end (app/, new): - AgentCore wraps one cst_agent_t: turns run on a worker thread, every cst_agent_hooks_t callback becomes a Qt signal, and the two hooks that need an answer (on_permission, on_ask_user) block the worker until the GUI replies; mode, approval and plan mode go through the engine's config. - ToolProvider hands the front end's tools to the engine (owner "app:*"); the Linux one is notification_send with a probe for notify-send/D-Bus. - Main.qml: transcript, tool blocks, consent dialog (Deny/Once/Always -> CST_PERM_*), ask_user, mode switch, Esc to cancel; --selftest stays headless and runs the embedding checks without QML. Android (scripts/, docs/android.md, new): - scripts/build_third_party_android.sh builds static mbedTLS + libcurl for an ABI (CA path /system/etc/security/cacerts); build_android.sh builds cst-agent, libcstcore.a and the test binaries for the phone, can push them and run the whole suite there. - sandbox_exec.c keeps the plain exec path on Android: the seccomp supervisor compiled in and the probe reported "seccomp", but writes outside the workspace were not denied on the device -- claiming a sandbox that does not hold is worse than reporting none. - tests/test_diff.c compares layouts only against real GNU diffutils: toybox's diff prints the same hunk header with its own hunk/context rules. Tests: test_tool_meta (metadata, platform gate, probe reasons, takeover of a built-in name) and test_embed (in-process embedding contract) are new; the existing registry/llm_body assertions now follow availability. 38 test binaries pass on the host, 36/36 on arm64-v8a Android 16, cst-app-selftest passes in both the standalone app/ build and the repo build. Version 0.8.7.
This commit is contained in:
WHC
+119
@@ -0,0 +1,119 @@
|
||||
# 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
|
||||
|
||||
```sh
|
||||
# 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 --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.
|
||||
|
||||
## 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:
|
||||
|
||||
```c
|
||||
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
|
||||
|
||||
- [x] engine as a library (`libcstcore.a` / `cstcore`), in-process embed API
|
||||
- [x] tool metadata: `perm_name`, `platforms`, `available`, shadowing rule
|
||||
- [x] `AgentCore` (turns, cancel, consent, todo) and the C smoke test
|
||||
- [ ] QML window against a real provider (needs Qt Quick)
|
||||
- [ ] session list / switch, attachments, diff viewer, settings page
|
||||
- [ ] Kirigami (Breeze look), tray, global shortcuts
|
||||
- [ ] Android APK (engine in-process, JNI platform tools)
|
||||
Reference in New Issue
Block a user