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.

tests/test_diff.c

@@ -77,10 +77,26 @@ static char *gnu_diff(const char *a, const char *b) {
 }
 
 static int have_gnu_diff(void) {
+#ifdef _WIN32
+  return 0; /* gnu_diff() has no implementation there */
+#else
+  /* Android's toybox diff (and busybox's) print the same "@@ -1 +1 @@" for a
+   * one-line change but group hunks and context their own way, so the layout
+   * comparisons only make sense against real diffutils. */
+  FILE *pp = popen("LC_ALL=C diff --version 2>/dev/null", "r");
+  char line[128] = "";
+  if (pp) {
+    if (!fgets(line, sizeof(line), pp))
+      line[0] = 0;
+    pclose(pp);
+  }
+  if (!strstr(line, "GNU diffutils"))
+    return 0;
   char *o = gnu_diff("x\n", "y\n");
   int ok = o && strstr(o, "@@ -1 +1 @@");
   free(o);
   return ok;
+#endif
 }
 
 static char *mine(const char *a, const char *b) {

tests/test_embed.c

@@ -0,0 +1,189 @@
+/* The Qt app embeds the engine in-process: it creates an agent from a
+ * config, registers its own platform tools with owner "app:*" and dispatches
+ * them exactly like the model would. No HTTP server, no port, no token and
+ * no second process -- this is the embedding path app/ (Qt) relies on, kept
+ * runnable without Qt so it guards the C side on every `make check`. */
+
+#define _POSIX_C_SOURCE 200809L
+
+#include "cJSON.h"
+#include "cst_agent.h"
+#include "cst_test_util.h"
+#include "cst_tools.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int nfail;
+
+#define EXPECT(cond, msg)                                                      \
+  do {                                                                         \
+    if (!(cond)) {                                                             \
+      fprintf(stderr, "FAIL %s:%d: %s\n", __FILE__, __LINE__, msg);            \
+      nfail++;                                                                 \
+    }                                                                          \
+  } while (0)
+
+/* What a platform tool implemented by the front end looks like on the C
+ * side: a callback plus whatever the front end needs to keep. */
+struct app_ctx {
+  int calls;
+  char last[128];
+};
+
+static int app_notify_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                          cst_tool_result_t *r, void *ud) {
+  (void)ctx;
+  struct app_ctx *a = ud;
+  const char *msg = NULL;
+  for (int i = 0; i < c->nargs; i++)
+    if (strcmp(c->args[i].key, "message") == 0)
+      msg = c->args[i].value;
+  a->calls++;
+  snprintf(a->last, sizeof(a->last), "%s", msg ? msg : "");
+  char buf[256];
+  snprintf(buf, sizeof(buf), "notified: %s", msg ? msg : "");
+  r->out = strdup(buf);
+  r->out_len = r->out ? strlen(r->out) : 0;
+  r->exit_code = 0;
+  return 0;
+}
+
+static void dispatch_notify(const cst_tool_ctx_t *ctx,
+                            const ctl_tool_call_t *call, cst_tool_result_t *r,
+                            struct app_ctx *actx) {
+  EXPECT(cst_tool_run(ctx, call, r) == 0, "the app tool runs");
+  EXPECT(r->out && strstr(r->out, "notified: hi") != NULL,
+         "its output is the tool result");
+  EXPECT(actx->calls == 1 && strcmp(actx->last, "hi") == 0,
+         "the C callback saw the argument");
+  cst_tool_result_free(r);
+}
+
+int main(void) {
+  char root[1024];
+  if (test_tmpdir(root, sizeof(root), "cst-embed") != 0) {
+    fprintf(stderr, "cannot create a scratch dir\n");
+    return 1;
+  }
+
+  cst_agent_config_t cfg;
+  memset(&cfg, 0, sizeof(cfg));
+  snprintf(cfg.workspace_root, sizeof(cfg.workspace_root), "%s", root);
+  snprintf(cfg.session_path, sizeof(cfg.session_path), "%s/s.jsonl", root);
+  snprintf(cfg.provider, sizeof(cfg.provider), "deepseek");
+  snprintf(cfg.model, sizeof(cfg.model), "deepseek-flash");
+  snprintf(cfg.api_base, sizeof(cfg.api_base), "https://api.deepseek.com/v1");
+  snprintf(cfg.api_key, sizeof(cfg.api_key), "test-key");
+  snprintf(cfg.mode, sizeof(cfg.mode), "general");
+  cfg.max_steps = 1;
+  cfg.headless = 1;
+
+  cst_agent_t *a = cst_agent_create(&cfg);
+  EXPECT(a != NULL, "the app can create an engine in-process");
+  if (!a) {
+    test_rmrf(root);
+    return 1;
+  }
+  EXPECT(cst_agent_session_path(a) != NULL, "the agent owns its session");
+
+  /* the front end registers its own tool: android-only, policy "notify" */
+  static const char *const ANDROID_ONLY[] = {"android", NULL};
+  struct app_ctx actx;
+  memset(&actx, 0, sizeof(actx));
+  cst_tool_def_t def;
+  memset(&def, 0, sizeof(def));
+  def.name = "app_notify";
+  def.desc = "Send a system notification (provided by the app).";
+  def.perm = CST_TP_ASK;
+  def.perm_name = "notify";
+  def.platforms = ANDROID_ONLY;
+  def.run_ex = app_notify_run;
+  def.ud = &actx;
+  def.owner = "app:test";
+  EXPECT(cst_tool_register(&def) == 0, "the app registers a tool in-process");
+
+  const cst_tool_def_t *t = cst_tool_find("app_notify");
+  EXPECT(t != NULL, "the registry knows it");
+  if (!t) {
+    cst_agent_destroy(a);
+    test_rmrf(root);
+    return 1;
+  }
+  EXPECT(strcmp(cst_tool_perm_name(t), "notify") == 0,
+         "its policy name survives registration");
+  EXPECT(t->run_ex == app_notify_run && t->ud == &actx,
+         "so does the callback and its userdata");
+
+  /* on a desktop host it must not be offered (the probe is the only gate) */
+  setenv("CST_PLATFORM", "linux", 1);
+  cst_tool_meta_reload();
+  char why[160];
+  EXPECT(cst_tool_available(t, why, sizeof(why)) != 0,
+         "an android-only tool is not available on this host");
+  EXPECT(!cst_tool_active(cst_agent_config(a), t),
+         "the agent's config does not offer it");
+
+  /* ... and once the host is the phone it is, through the same config */
+  setenv("CST_PLATFORM", "android", 1);
+  cst_tool_meta_reload();
+  EXPECT(cst_tool_available(t, why, sizeof(why)) == 0, "available on android");
+  EXPECT(cst_tool_active(cst_agent_config(a), t), "and offered there");
+  char *names = cst_tools_names(cst_agent_config(a));
+  EXPECT(names && strstr(names, "app_notify") != NULL,
+         "it is part of the active tool set");
+  free(names);
+  char *prompt = cst_tools_prompt(cst_agent_config(a));
+  EXPECT(prompt && strstr(prompt, "app_notify") != NULL,
+         "and the prompt describes it like any built-in");
+  free(prompt);
+  void *schema = cst_tools_schema_cfg(cst_agent_config(a));
+  char *sj = schema ? cJSON_PrintUnformatted(schema) : NULL;
+  EXPECT(sj && strstr(sj, "app_notify") != NULL, "tools[] carries it too");
+  free(sj);
+  if (schema)
+    cJSON_Delete(schema);
+
+  /* dispatch: the front end's callback is what runs */
+  ctl_tool_call_t call;
+  memset(&call, 0, sizeof(call));
+  snprintf(call.name, sizeof(call.name), "app_notify");
+  snprintf(call.args[0].key, sizeof(call.args[0].key), "message");
+  call.args[0].value = strdup("hi");
+  call.args[0].value_len = strlen("hi");
+  call.nargs = 1;
+  cst_tool_result_t r;
+  cst_tool_ctx_t ctx;
+  memset(&ctx, 0, sizeof(ctx));
+  ctx.workspace_root = root;
+  ctx.agent = a;
+  dispatch_notify(&ctx, &call, &r, &actx);
+  free(call.args[0].value);
+
+  /* a name that is already taken by a tool that *can* run here is refused */
+  cst_tool_def_t dup;
+  memset(&dup, 0, sizeof(dup));
+  dup.name = "read_file";
+  dup.desc = "not allowed to shadow a working built-in";
+  dup.perm = CST_TP_READ;
+  dup.run_ex = app_notify_run;
+  dup.owner = "app:test";
+  EXPECT(cst_tool_find("read_file")->owner == NULL, "read_file is a built-in");
+  EXPECT(cst_tool_register(&dup) != 0,
+         "a working built-in cannot be shadowed");
+
+  /* dropping the app's tools leaves the built-in registry untouched */
+  EXPECT(cst_tool_unregister_owner("app:test") == 1, "the app unregisters");
+  EXPECT(cst_tool_find("app_notify") == NULL, "its tool is gone");
+  EXPECT(cst_tool_find("read_file") != NULL, "the built-ins are still there");
+
+  cst_agent_destroy(a);
+  test_rmrf(root);
+  if (nfail) {
+    fprintf(stderr, "test_embed: %d failed\n", nfail);
+    return 1;
+  }
+  printf("test_embed: OK\n");
+  return 0;
+}

tests/test_llm_body.c

@@ -108,8 +108,13 @@ static void test_tool_calls_and_null_content(void) {
   EXPECT(cJSON_IsString(tid) && strcmp(tid->valuestring, "c1") == 0,
          "tool_call_id");
   const cJSON *tools = cJSON_GetObjectItemCaseSensitive(j, "tools");
-  EXPECT(cJSON_IsArray(tools) && cJSON_GetArraySize(tools) >= 4,
+  /* The exact set depends on the host: a tool whose platform probe fails is
+   * offered nowhere, so look for a core tool instead of counting. */
+  char *tj = tools ? cJSON_PrintUnformatted(tools) : NULL;
+  EXPECT(cJSON_IsArray(tools) && cJSON_GetArraySize(tools) >= 4 && tj &&
+             strstr(tj, "read_file") != NULL,
          "tools[] schema present");
+  free(tj);
   const cJSON *choice = cJSON_GetObjectItemCaseSensitive(j, "tool_choice");
   EXPECT(cJSON_IsString(choice) && strcmp(choice->valuestring, "auto") == 0,
          "tool_choice auto");

tests/test_registry.c

@@ -138,7 +138,13 @@ int main(void) {
   }
 
   cJSON *all = cst_tools_schema_cfg(&cfg);
-  EXPECT(cJSON_GetArraySize(all) == cst_tool_count(), "default: every tool");
+  /* Every tool the host can actually run is offered in the default profile;
+   * one whose platform probe fails (the clipboard without a helper) is not. */
+  int usable = 0;
+  for (int i = 0; i < cst_tool_count(); i++)
+    if (cst_tool_available(cst_tool_at(i), NULL, 0) == 0)
+      usable++;
+  EXPECT(cJSON_GetArraySize(all) == usable, "default: every usable tool");
   EXPECT(schema_has(all, "edit_file") && schema_has(all, "grep") &&
              schema_has(all, "web_fetch"),
          "default schema has new tools");

tests/test_tool_meta.c

@@ -0,0 +1,196 @@
+/* Tool capability metadata: platform declarations, availability probes and
+ * the shadowing rule (an app-provided tool may take over a name whose
+ * built-in cannot run on this host). */
+
+#define _POSIX_C_SOURCE 200809L
+
+#include "cst_tools.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int nfail;
+
+#define EXPECT(cond, msg)                                                      \
+  do {                                                                         \
+    if (!(cond)) {                                                             \
+      fprintf(stderr, "FAIL %s:%d: %s\n", __FILE__, __LINE__, msg);            \
+      nfail++;                                                                 \
+    }                                                                          \
+  } while (0)
+
+static int echo_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
+                    cst_tool_result_t *r) {
+  (void)ctx;
+  (void)c;
+  r->out = strdup("ran");
+  r->out_len = r->out ? strlen(r->out) : 0;
+  r->exit_code = 0;
+  return 0;
+}
+
+static int probe_fail(char *why, size_t why_sz) {
+  snprintf(why, why_sz, "no notification daemon on this host");
+  return -1;
+}
+
+static const char *const ANDROID_ONLY[] = {"android", NULL};
+
+static void test_platform_gating(void) {
+  cst_tool_def_t d;
+  memset(&d, 0, sizeof(d));
+  d.name = "meta_android_only";
+  d.desc = "Android-only test tool.";
+  d.perm = CST_TP_ASK;
+  d.perm_name = "notify";
+  d.platforms = ANDROID_ONLY;
+  d.run = echo_run;
+  d.owner = "test:meta";
+  EXPECT(cst_tool_register(&d) == 0, "register an android-only tool");
+  const cst_tool_def_t *t = cst_tool_find("meta_android_only");
+  EXPECT(t != NULL, "it is in the registry");
+  if (!t)
+    return;
+  EXPECT(strcmp(cst_tool_perm_name(t), "notify") == 0, "perm_name is kept");
+
+  setenv("CST_PLATFORM", "linux", 1);
+  cst_tool_meta_reload();
+  char why[160];
+  EXPECT(cst_tool_available(t, why, sizeof(why)) != 0,
+         "an android-only tool is unavailable on linux");
+  EXPECT(strstr(why, "android") != NULL, "and says what it is for");
+  EXPECT(!cst_tool_active(NULL, t), "so it is not offered at all");
+
+  /* the model must not be able to force it either: the call is answered with
+   * an error result (run() reports 0 for a tool-level failure, the exit code
+   * and the text carry it) */
+  ctl_tool_call_t call;
+  memset(&call, 0, sizeof(call));
+  snprintf(call.name, sizeof(call.name), "meta_android_only");
+  cst_tool_result_t r;
+  cst_tool_ctx_t ctx;
+  memset(&ctx, 0, sizeof(ctx));
+  ctx.workspace_root = ".";
+  EXPECT(cst_tool_run(&ctx, &call, &r) == 0 && r.out && r.exit_code != 0 &&
+             strstr(r.out, "cannot run here") != NULL,
+         "calling it anyway is refused with a reason");
+  EXPECT(strstr(r.out, "android") != NULL, "the reason names the platform");
+  cst_tool_result_free(&r);
+
+  setenv("CST_PLATFORM", "android", 1);
+  cst_tool_meta_reload();
+  EXPECT(cst_tool_available(t, why, sizeof(why)) == 0,
+         "available once the host is an android device");
+  EXPECT(cst_tool_active(NULL, t), "and offered to the model");
+  char *names = cst_tools_names(NULL);
+  EXPECT(names && strstr(names, "meta_android_only") != NULL,
+         "it shows up in the active tool names");
+  free(names);
+
+  /* a Termux host counts as android; "termux" is not matched by "android" */
+  setenv("CST_PLATFORM", "termux", 1);
+  cst_tool_meta_reload();
+  EXPECT(cst_tool_available(t, why, sizeof(why)) == 0,
+         "a Termux host is an android device");
+
+  /* the desktop pseudo-platform covers linux / win / macos */
+  cst_tool_def_t desk;
+  memset(&desk, 0, sizeof(desk));
+  desk.name = "meta_desktop";
+  desk.desc = "Desktop-only test tool.";
+  desk.perm = CST_TP_READ;
+  desk.platforms = CST_PLAT_DESKTOP;
+  desk.run = echo_run;
+  desk.owner = "test:meta";
+  EXPECT(cst_tool_register(&desk) == 0, "register a desktop-only tool");
+  const cst_tool_def_t *dt = cst_tool_find("meta_desktop");
+  setenv("CST_PLATFORM", "linux", 1);
+  cst_tool_meta_reload();
+  EXPECT(dt && cst_tool_available(dt, why, sizeof(why)) == 0, "desktop on linux");
+  setenv("CST_PLATFORM", "android", 1);
+  cst_tool_meta_reload();
+  EXPECT(dt && cst_tool_available(dt, why, sizeof(why)) != 0,
+         "not on android");
+}
+
+static void test_probe(void) {
+  cst_tool_def_t d;
+  memset(&d, 0, sizeof(d));
+  d.name = "meta_no_daemon";
+  d.desc = "A tool whose service is missing.";
+  d.perm = CST_TP_ASK;
+  d.available = probe_fail;
+  d.run = echo_run;
+  d.owner = "test:meta";
+  EXPECT(cst_tool_register(&d) == 0, "register a tool with a failing probe");
+  const cst_tool_def_t *t = cst_tool_find("meta_no_daemon");
+  char why[160];
+  setenv("CST_PLATFORM", "linux", 1);
+  cst_tool_meta_reload();
+  EXPECT(t && cst_tool_available(t, why, sizeof(why)) != 0, "probe says no");
+  EXPECT(strstr(why, "notification daemon") != NULL,
+         "the probe's own reason is passed on");
+  EXPECT(t && !cst_tool_active(NULL, t), "and it is not offered");
+  /* the cache answers the same way, and a reload re-probes */
+  EXPECT(t && cst_tool_available(t, NULL, 0) != 0, "cached answer");
+  cst_tool_meta_reload();
+  EXPECT(t && cst_tool_available(t, why, sizeof(why)) != 0, "re-probed answer");
+}
+
+static void test_shadowing(void) {
+  /* A tool the app provides may take a built-in name when that built-in
+   * cannot run here; the app's entry then shadows it. */
+  cst_tool_def_t d;
+  memset(&d, 0, sizeof(d));
+  d.name = "clipboard_read";
+  d.desc = "Read the clipboard (provided by the app).";
+  d.perm = CST_TP_READ;
+  d.perm_name = "read";
+  d.run = echo_run;
+  d.owner = "app:test";
+  int registered = cst_tool_register(&d) == 0;
+  const cst_tool_def_t *t = cst_tool_find("clipboard_read");
+  EXPECT(t != NULL, "clipboard_read stays findable either way");
+  if (registered) {
+    EXPECT(t && t->owner && strcmp(t->owner, "app:test") == 0,
+           "the app's tool shadows the unavailable built-in");
+    EXPECT(t && cst_tool_active(NULL, t), "and it is offered");
+    EXPECT(cst_tool_unregister_owner("app:test") == 1, "dropping it again");
+    t = cst_tool_find("clipboard_read");
+    EXPECT(t && (t->owner == NULL || strcmp(t->owner, "app:test") != 0),
+           "the built-in is back");
+  } else {
+    EXPECT(t && cst_tool_available(t, NULL, 0) == 0,
+           "a name is only taken by a tool that can run here");
+  }
+}
+
+static void test_perm_names(void) {
+  const cst_tool_def_t *t = cst_tool_find("delete_file");
+  EXPECT(t && strcmp(cst_tool_perm_name(t), "delete") == 0,
+         "delete_file is a delete, not just a write");
+  t = cst_tool_find("read_file");
+  EXPECT(t && strcmp(cst_tool_perm_name(t), "read") == 0, "read_file is read");
+  t = cst_tool_find("run_shell");
+  EXPECT(t && strcmp(cst_tool_perm_name(t), "shell") == 0, "carried by class");
+  t = cst_tool_find("clipboard_write");
+  EXPECT(t && strcmp(cst_tool_perm_name(t), "write") == 0, "clipboard_write");
+  EXPECT(cst_platform_name() != NULL && cst_platform_name()[0],
+         "host platform has a name");
+}
+
+int main(void) {
+  test_platform_gating();
+  test_probe();
+  test_shadowing();
+  test_perm_names();
+  cst_tool_unregister_owner("test:meta");
+  cst_tool_unregister_owner("app:test");
+  if (nfail) {
+    fprintf(stderr, "test_tool_meta: %d failed\n", nfail);
+    return 1;
+  }
+  printf("test_tool_meta: OK\n");
+  return 0;
+}