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
2026-10-11 11:42:04 +08:00
parent e0b0eddf3a
commit 5ba215b36c
28 changed files with 2452 additions and 34 deletions
+45
View File
@@ -18,6 +18,51 @@ static void set_err(char *err, size_t err_sz, const char *msg) {
snprintf(err, err_sz, "%s", msg);
}
#ifndef _WIN32
/* PATH lookup without shelling out: cheap enough for a capability probe. */
static int on_path(const char *name) {
const char *path = getenv("PATH");
if (!path)
return 0;
for (const char *p = path;;) {
const char *colon = strchr(p, ':');
size_t len = colon ? (size_t)(colon - p) : strlen(p);
char cand[4096];
if (len + strlen(name) + 2 < sizeof(cand)) {
if (len == 0)
snprintf(cand, sizeof(cand), "./%s", name);
else
snprintf(cand, sizeof(cand), "%.*s/%s", (int)len, p, name);
if (access(cand, X_OK) == 0)
return 1;
}
if (!colon)
break;
p = colon + 1;
}
return 0;
}
#endif
int cst_clipboard_available(char *why, size_t why_sz) {
if (why && why_sz)
why[0] = 0;
#ifdef _WIN32
return 0; /* the Win32 clipboard API is always there */
#elif defined(__APPLE__)
return 0; /* pbpaste / pbcopy ship with the OS */
#else
static const char *const helpers[] = {"wl-paste", "wl-copy", "xclip", NULL};
for (int i = 0; helpers[i]; i++)
if (on_path(helpers[i]))
return 0;
if (why && why_sz)
snprintf(why, why_sz,
"no clipboard helper on PATH (install wl-clipboard or xclip)");
return -1;
#endif
}
static void put_le32(unsigned char *p, unsigned long v) {
p[0] = (unsigned char)(v & 0xff);
p[1] = (unsigned char)((v >> 8) & 0xff);
+7 -1
View File
@@ -24,7 +24,13 @@
#include <sddl.h>
#endif
#if defined(__linux__) && (defined(__x86_64__) || defined(__aarch64__))
/* Android keeps the plain exec path, like its Landlock branch above: the NDK
* build compiles the seccomp supervisor, the probe then reports "seccomp",
* but on the device the writes outside the workspace are not denied
* (tests/test_sandbox.c:308). Claiming a sandbox that does not hold is worse
* than reporting none -- see docs/android.md. */
#if defined(__linux__) && !defined(__ANDROID__) && \
(defined(__x86_64__) || defined(__aarch64__))
#include <fcntl.h>
#include <linux/audit.h>
#include <linux/filter.h>
+157 -17
View File
@@ -9,6 +9,7 @@
#include <pthread.h>
#include "cJSON.h"
#include "cst_clipboard.h"
#include "cst_tools.h"
#include "cst_util.h"
#include "tools_internal.h"
@@ -44,6 +45,7 @@ static int run_shell(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *c,
#define I "integer"
#define B "boolean"
#define NO_DYN NULL, NULL, NULL, NULL, NULL
#define NO_META NULL, NULL, NULL
static const cst_tool_def_t TOOLS[] = {
{"read_file",
@@ -55,7 +57,7 @@ static const cst_tool_def_t TOOLS[] = {
{"offset", I, 0, "first line to return (1-based)"},
{"limit", I, 0, "maximum number of lines"},
{"line_numbers", B, 0, "`N|` line prefixes (default true)"}},
CST_TP_READ, 1, run_read_file, NULL, NO_DYN},
CST_TP_READ, 1, run_read_file, NULL, NO_DYN, NO_META},
{"view_image",
"Show a local image to yourself: PNG, JPEG, GIF, WebP or BMP, checked by "
"content. The file is copied into the session store and comes back as an "
@@ -64,7 +66,7 @@ static const cst_tool_def_t TOOLS[] = {
NULL,
{{"path", S, 1, "image file path relative to the workspace"},
{"detail", S, 0, "low or high (provider hint; default auto)"}},
CST_TP_READ, 0, cst_tool_view_image, NULL, NO_DYN},
CST_TP_READ, 0, cst_tool_view_image, NULL, NO_DYN, NO_META},
{"run_shell",
"Run a non-interactive shell command in the workspace root: builds, "
"tests, git, scripts, computations, data processing, other CLIs "
@@ -74,14 +76,14 @@ static const cst_tool_def_t TOOLS[] = {
"Run a shell command in the workspace root (non-interactive, stdin is "
"empty, killed after a timeout). Returns combined stdout+stderr.",
{{"cmd", S, 1, "shell command"}},
CST_TP_SHELL, 1, run_shell, NULL, NO_DYN},
CST_TP_SHELL, 1, run_shell, NULL, NO_DYN, NO_META},
{"write_file",
"Create a file or replace a whole file (parent directories are "
"created). For changes to existing files prefer edit_file.",
"Create or overwrite a whole file under the workspace (parent "
"directories are created).",
{{"path", S, 1, "file path"}, {"content", S, 1, "complete new content"}},
CST_TP_WRITE, 1, run_write_file, cst_preview_write_file, NO_DYN},
CST_TP_WRITE, 1, run_write_file, cst_preview_write_file, NO_DYN, NO_META},
{"apply_patch",
"Apply a unified diff (---/+++ headers, @@ -a,b +c,d @@ hunks, 3 "
"context lines) across one or more files; all hunks apply or nothing "
@@ -90,7 +92,7 @@ static const cst_tool_def_t TOOLS[] = {
"context lines) to one or more files. All hunks must apply or nothing "
"changes.",
{{"patch", S, 1, "unified diff text"}},
CST_TP_WRITE, 1, run_apply_patch, cst_preview_apply_patch, NO_DYN},
CST_TP_WRITE, 1, run_apply_patch, cst_preview_apply_patch, NO_DYN, NO_META},
{"edit_file",
"Replace an exact snippet in a file — the default for small edits. "
"old_string must match byte-for-byte (indentation included, without "
@@ -100,7 +102,7 @@ static const cst_tool_def_t TOOLS[] = {
{"old_string", S, 1, "exact text to replace"},
{"new_string", S, 1, "replacement text"},
{"replace_all", B, 0, "replace every occurrence"}},
CST_TP_WRITE, 0, cst_tool_edit_file, cst_preview_edit_file, NO_DYN},
CST_TP_WRITE, 0, cst_tool_edit_file, cst_preview_edit_file, NO_DYN, NO_META},
{"list_dir",
"Show a directory tree (dirs end with /, files show sizes, dirs at the "
"depth limit show entry counts). Skips .git, node_modules and "
@@ -108,7 +110,7 @@ static const cst_tool_def_t TOOLS[] = {
NULL,
{{"path", S, 0, "directory (default: workspace root)"},
{"depth", I, 0, "levels to descend (default 2, max 6)"}},
CST_TP_READ, 0, cst_tool_list_dir, NULL, NO_DYN},
CST_TP_READ, 0, cst_tool_list_dir, NULL, NO_DYN, NO_META},
{"glob",
"Find files by name, newest first (max 200). `*`/`?` stay within one "
"path segment, `**` spans directories (`src/**/*.c`); a pattern without "
@@ -116,7 +118,7 @@ static const cst_tool_def_t TOOLS[] = {
NULL,
{{"pattern", S, 1, "glob relative to path"},
{"path", S, 0, "directory to search (default: workspace root)"}},
CST_TP_READ, 0, cst_tool_glob, NULL, NO_DYN},
CST_TP_READ, 0, cst_tool_glob, NULL, NO_DYN, NO_META},
{"grep",
"Search file contents with an extended regex (\\d \\w \\s work). "
"Results are grouped by file as `line:text` under each path, with a "
@@ -127,51 +129,53 @@ static const cst_tool_def_t TOOLS[] = {
{"glob", S, 0, "only files whose name matches, e.g. *.c"},
{"ignore_case", B, 0, "case-insensitive"},
{"context", I, 0, "lines of context around each match (max 5)"}},
CST_TP_READ, 0, cst_tool_grep, NULL, NO_DYN},
CST_TP_READ, 0, cst_tool_grep, NULL, NO_DYN, NO_META},
{"delete_file",
"Delete one file (not directories). Undoable with /undo.",
NULL,
{{"path", S, 1, "file path"}},
CST_TP_WRITE, 0, cst_tool_delete_file, cst_preview_delete_file, NO_DYN},
CST_TP_WRITE, 0, cst_tool_delete_file, cst_preview_delete_file, NO_DYN,
"delete", NULL, NULL},
{"move_file",
"Move or rename a file; fails if the destination exists.",
NULL,
{{"from", S, 1, "existing file"}, {"to", S, 1, "new path"}},
CST_TP_WRITE, 0, cst_tool_move_file, cst_preview_move_file, NO_DYN},
CST_TP_WRITE, 0, cst_tool_move_file, cst_preview_move_file, NO_DYN, NO_META},
{"todo_write",
"Replace your task list for work with 3+ steps; keep exactly one item "
"in progress. One item per line: `[ ] todo`, `[~] in progress`, `[x] "
"done`.",
NULL,
{{"todos", S, 1, "the whole list, one item per line"}},
CST_TP_META, 0, cst_tool_todo_write, NULL, NO_DYN},
CST_TP_META, 0, cst_tool_todo_write, NULL, NO_DYN, NO_META},
{"web_fetch",
"Fetch an http(s) URL (docs, issues, APIs) and return its text; HTML "
"is reduced to readable text.",
NULL,
{{"url", S, 1, "http:// or https:// URL"},
{"max_bytes", I, 0, "maximum bytes to return (default 65536)"}},
CST_TP_NET, 0, cst_tool_web_fetch, NULL, NO_DYN},
CST_TP_NET, 0, cst_tool_web_fetch, NULL, NO_DYN, NO_META},
{"ask_user",
"Ask the user and wait for the answer. Only for decisions that are "
"truly theirs (preferences, credentials, destructive choices).",
NULL,
{{"question", S, 1, "the question"},
{"options", S, 0, "suggested answers, one per line"}},
CST_TP_ASK, 0, cst_tool_ask_user, NULL, NO_DYN},
CST_TP_ASK, 0, cst_tool_ask_user, NULL, NO_DYN, NO_META},
{"clipboard_read",
"Read the text on the system clipboard — what the user copied outside "
"the workspace. Returns UTF-8 text.",
NULL,
{{"max_bytes", I, 0, "cap on the returned text (default 65536)"}},
CST_TP_READ, 0, cst_tool_clipboard_read, NULL, NO_DYN},
CST_TP_READ, 0, cst_tool_clipboard_read, NULL, NO_DYN, "read",
CST_PLAT_DESKTOP, cst_clipboard_available},
{"clipboard_write",
"Replace the system clipboard with text, so the user can paste it into "
"another app. Overwrites what they had copied.",
NULL,
{{"text", S, 1, "text to put on the clipboard"}},
CST_TP_WRITE, 0, cst_tool_clipboard_write, cst_preview_clipboard_write,
NO_DYN},
NO_DYN, "write", CST_PLAT_DESKTOP, cst_clipboard_available},
};
#define NTOOLS ((int)(sizeof(TOOLS) / sizeof(TOOLS[0])))
@@ -179,6 +183,7 @@ static const cst_tool_def_t TOOLS[] = {
#undef I
#undef B
#undef NO_DYN
#undef NO_META
int cst_tool_profile_parse(const char *s, int *out) {
if (!s || !out)
@@ -231,11 +236,129 @@ int cst_tool_index(const char *name) {
}
const cst_tool_def_t *cst_tool_find(const char *name) {
if (!name)
return NULL;
/* An app-provided tool of the same name shadows the built-in: it could
* only be registered while that built-in cannot run on this host. */
int n = atomic_load(&g_ndyn);
for (int i = 0; i < n; i++)
if (g_dyn[i] && strcmp(g_dyn[i]->name, name) == 0)
return g_dyn[i];
return cst_tool_at(cst_tool_index(name));
}
int cst_tool_known(const char *name) { return cst_tool_find(name) != NULL; }
/* --- capability metadata ------------------------------------------------- */
const char *const CST_PLAT_DESKTOP[] = {"desktop", NULL};
const char *cst_platform_name(void) {
const char *over = getenv("CST_PLATFORM");
if (over && over[0])
return over; /* tests, cross checks, a launcher that knows better */
#if defined(_WIN32)
return "win";
#elif defined(__APPLE__)
return "macos";
#elif defined(__ANDROID__)
return getenv("TERMUX_VERSION") ? "termux" : "android";
#elif defined(__linux__)
return "linux";
#else
return "other";
#endif
}
int cst_tool_platform_ok(const cst_tool_def_t *t) {
if (!t || !t->platforms)
return 1;
const char *cur = cst_platform_name();
for (int i = 0; t->platforms[i]; i++) {
const char *p = t->platforms[i];
if (strcmp(p, cur) == 0)
return 1;
if (strcmp(p, "desktop") == 0 && (strcmp(cur, "linux") == 0 ||
strcmp(cur, "win") == 0 ||
strcmp(cur, "macos") == 0))
return 1;
/* A Termux host is an Android device, so "android" covers it; the other
* way round is not true: Termux helpers are absent in an app sandbox. */
if (strcmp(cur, "termux") == 0 && strcmp(p, "android") == 0)
return 1;
}
return 0;
}
/* Probes are cached by def pointer: built-ins are static, dynamic entries
* keep their address while registered. */
#define META_CACHE_MAX 256
static struct {
const cst_tool_def_t *t;
int ok;
char why[128];
} g_meta[META_CACHE_MAX];
static int g_nmeta;
static pthread_mutex_t g_meta_mu = PTHREAD_MUTEX_INITIALIZER;
void cst_tool_meta_reload(void) {
pthread_mutex_lock(&g_meta_mu);
g_nmeta = 0;
pthread_mutex_unlock(&g_meta_mu);
}
int cst_tool_available(const cst_tool_def_t *t, char *why, size_t why_sz) {
if (why && why_sz)
why[0] = 0;
if (!t)
return -1;
pthread_mutex_lock(&g_meta_mu);
for (int i = 0; i < g_nmeta; i++) {
if (g_meta[i].t != t)
continue;
int ok = g_meta[i].ok;
if (why && why_sz)
snprintf(why, why_sz, "%s", g_meta[i].why);
pthread_mutex_unlock(&g_meta_mu);
return ok;
}
pthread_mutex_unlock(&g_meta_mu);
char tmp[128] = "";
int ok = 0;
if (!cst_tool_platform_ok(t)) {
snprintf(tmp, sizeof(tmp), "it exists on %s only and this host is %s",
t->platforms && t->platforms[0] ? t->platforms[0]
: "another platform",
cst_platform_name());
ok = -1;
} else if (t->available && t->available(tmp, sizeof(tmp)) != 0) {
if (!tmp[0])
snprintf(tmp, sizeof(tmp), "a service it needs is missing here");
ok = -1;
}
pthread_mutex_lock(&g_meta_mu);
if (g_nmeta < META_CACHE_MAX) {
g_meta[g_nmeta].t = t;
g_meta[g_nmeta].ok = ok;
snprintf(g_meta[g_nmeta].why, sizeof(g_meta[g_nmeta].why), "%s", tmp);
g_nmeta++;
}
pthread_mutex_unlock(&g_meta_mu);
if (why && why_sz)
snprintf(why, why_sz, "%s", tmp);
return ok;
}
const char *cst_tool_perm_name(const cst_tool_def_t *t) {
static const char *const class_names[] = {"read", "write", "shell",
"net", "ask", "meta"};
if (t && t->perm_name && t->perm_name[0])
return t->perm_name;
int p = t ? (int)t->perm : (int)CST_TP_READ;
return p >= 0 && p < 6 ? class_names[p] : "?";
}
void cst_tool_sanitize_name(const char *in, char *out, size_t out_sz) {
size_t o = 0;
for (size_t i = 0; in && in[i] && o + 1 < out_sz && o < 63; i++) {
@@ -255,6 +378,7 @@ static void dyn_free(cst_tool_def_t *t) {
return;
free((char *)t->name);
free((char *)t->desc);
free((char *)t->perm_name);
free((char *)t->schema_json);
free((char *)t->owner);
free(t);
@@ -266,7 +390,10 @@ int cst_tool_register(const cst_tool_def_t *def) {
DYN_LOCK();
int rc = -1;
int n = atomic_load(&g_ndyn);
if (n < DYN_MAX && cst_tool_index(def->name) < 0) {
/* The name is free, or held by a tool that cannot run on this host (the
* app's Android clipboard taking over the name of the desktop one). */
const cst_tool_def_t *taken = cst_tool_find(def->name);
if (n < DYN_MAX && (!taken || cst_tool_available(taken, NULL, 0) != 0)) {
cst_tool_def_t *t = calloc(1, sizeof(*t));
if (t) {
*t = *def;
@@ -274,6 +401,7 @@ int cst_tool_register(const cst_tool_def_t *def) {
t->minimal = 0;
t->name = dup_or_null(def->name);
t->desc = dup_or_null(def->desc ? def->desc : "");
t->perm_name = dup_or_null(def->perm_name);
t->schema_json = dup_or_null(def->schema_json);
t->owner = dup_or_null(def->owner);
if (t->name && t->desc) {
@@ -286,6 +414,8 @@ int cst_tool_register(const cst_tool_def_t *def) {
}
}
DYN_UNLOCK();
if (rc == 0)
cst_tool_meta_reload(); /* a new entry may shadow an old probe */
return rc;
}
@@ -306,6 +436,8 @@ int cst_tool_unregister_owner(const char *owner) {
g_dyn[i] = NULL;
atomic_store(&g_ndyn, k);
DYN_UNLOCK();
if (removed)
cst_tool_meta_reload(); /* drop probes of defs that are now gone */
return removed;
}
@@ -352,6 +484,10 @@ int cst_tool_is_write(const char *name) {
int cst_tool_active(const cst_agent_config_t *cfg, const cst_tool_def_t *t) {
if (!t)
return 0;
/* A tool this host cannot run is never offered: the prompt, tools[] and the
* /tools panel all go through here. */
if (cst_tool_available(t, NULL, 0) != 0)
return 0;
if (!cfg)
return 1;
if (cfg->tool_profile == CST_TOOLS_MINIMAL && !t->minimal)
@@ -628,6 +764,10 @@ int cst_tool_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *call,
const cst_tool_def_t *t = cst_tool_find(call->name);
if (!t)
return tool_set_resultf(r, 1, "error: unknown tool: %.64s", call->name);
char why[160];
if (cst_tool_available(t, why, sizeof(why)) != 0)
return tool_set_resultf(r, 1, "error: %.64s cannot run here: %.120s",
call->name, why[0] ? why : "not supported");
char err[256];
if (cst_tool_validate(t, call, err, sizeof(err)) != 0)
return tool_set_result(r, err, 1);
+23
View File
@@ -1699,9 +1699,32 @@ static int h_settings_get(cst_http_conn_t *c, void *ud) {
cJSON_AddStringToObject(t, "name", d->name);
cJSON_AddStringToObject(t, "perm", (int)d->perm < 6 ? wui_perm_names[d->perm]
: "?");
cJSON_AddStringToObject(t, "perm_name", cst_tool_perm_name(d));
cJSON_AddBoolToObject(t, "on", cst_tool_active(cfg, d));
cJSON_AddBoolToObject(t, "off", cst_tool_disabled(cfg, d->name));
cJSON_AddStringToObject(t, "desc", first);
if (d->platforms) {
cJSON *pl = cJSON_AddArrayToObject(t, "platforms");
for (int k = 0; pl && d->platforms[k]; k++)
cJSON_AddItemToArray(pl, cJSON_CreateString(d->platforms[k]));
}
char why[160] = "";
if (cst_tool_available(d, why, sizeof(why)) != 0) {
cJSON_AddBoolToObject(t, "available", 0);
cJSON_AddStringToObject(t, "why", why);
} else {
cJSON_AddBoolToObject(t, "available", 1);
}
if (d->params[0].name) {
cJSON *pa = cJSON_AddArrayToObject(t, "params");
for (int k = 0; pa && k < CST_TOOL_MAX_PARAMS && d->params[k].name; k++) {
cJSON *p = cJSON_CreateObject();
cJSON_AddStringToObject(p, "name", d->params[k].name);
cJSON_AddStringToObject(p, "type", d->params[k].type);
cJSON_AddBoolToObject(p, "required", d->params[k].required);
cJSON_AddItemToArray(pa, p);
}
}
if (d->owner)
cJSON_AddStringToObject(t, "owner", d->owner);
cJSON_AddItemToArray(tools, t);