#ifndef CST_TOOLS_H #define CST_TOOLS_H #include "cst_agent.h" #ifdef __cplusplus extern "C" { #endif #define CST_TOOL_MAX_PARAMS 6 #define CST_TOOL_MAX_TARGETS 16 /* Up to max workspace-relative regular files (ignores .git, node_modules, * root .gitignore ...). Caller frees each entry and the array. */ int cst_workspace_files(const char *ws, char ***out, int max); /* What a call can touch; drives confirmation, undo and duplicate-read logic. */ typedef enum { CST_TP_READ = 0, /* reads the workspace */ CST_TP_WRITE, /* changes files (snapshotted for /undo) */ CST_TP_SHELL, /* arbitrary commands */ CST_TP_NET, /* network access */ CST_TP_ASK, /* talks to the user */ CST_TP_META /* agent bookkeeping (todo list) */ } cst_tool_perm_t; typedef struct { const char *name; const char *type; /* "string" | "integer" | "boolean" */ int required; const char *desc; } cst_tool_param_t; typedef struct cst_tool_ctx { const char *workspace_root; /* ask_user: fills ans; returns 0, or -1 when nobody can answer. */ int (*ask)(const char *question, const char *options, char *ans, size_t ans_sz, void *ud); void *ask_ud; /* todo_write: the list was replaced (text form, one item per line). */ void (*set_todo)(const char *text, void *ud); void *todo_ud; int sandbox; /* run_shell: confine to the workspace (cst_sandbox.h) */ /* Information-dense output (read_file headers and line numbers, cleaned * run_shell output). Off for `--tools minimal` so paper runs see the * original bytes. */ int compact; /* The calling agent and its turn hooks (task runs sub-agents). */ cst_agent_t *agent; const cst_agent_hooks_t *hooks; } cst_tool_ctx_t; typedef int (*cst_tool_run_fn)(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *call, cst_tool_result_t *r); /* Write tools: compute the diff a call would produce without touching disk. * Returns 0 and a malloc'd text, or -1 with an error text in *out. */ typedef int (*cst_tool_preview_fn)(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *call, char **out); typedef int (*cst_tool_run_ex_fn)(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *call, cst_tool_result_t *r, void *ud); /* Platforms a tool exists on, for def.platforms (NULL-terminated). * CST_PLAT_DESKTOP covers linux / win / macos; an app-provided tool can * declare its own, e.g. a static {"android", NULL} in the Qt frontend. */ extern const char *const CST_PLAT_DESKTOP[]; /* Host platform: "linux" | "win" | "macos" | "android" | "termux" | "other". * CST_PLATFORM overrides it (tests, cross checks). */ const char *cst_platform_name(void); typedef struct { const char *name; const char *desc; /* `--tools minimal` schema text (the original wording; required params * only), so paper runs keep sending byte-identical requests. */ const char *min_desc; cst_tool_param_t params[CST_TOOL_MAX_PARAMS]; cst_tool_perm_t perm; int minimal; /* member of `--tools minimal` (the original four) */ cst_tool_run_fn run; cst_tool_preview_fn preview; /* Dynamic tools (skills, plugins, MCP, sub-agents). */ const char *schema_json; /* JSON Schema object for the arguments; when set params[] is unused */ cst_tool_run_ex_fn run_ex; void *ud; const char *owner; /* "plugin:", "mcp:", ... */ /* Non-READ tools that may still join a parallel batch for this call. */ int (*parallel)(const ctl_tool_call_t *call, void *ud); /* --- capability metadata (discovery + availability) ------------------- */ /* Fine-grained policy name for permissions.json and consent UIs * ("read","write","delete","shell","net","notify","device","ui","meta"). * NULL falls back to the class name of perm. */ const char *perm_name; /* Platforms the tool exists on (NULL = everywhere). A tool that is not * for this host never reaches the prompt or tools[]. */ const char *const *platforms; /* Probe: 0 when the tool can run here, -1 with a reason in why (NULL = * always). Keep it cheap (no forks); the answer is cached until * cst_tool_meta_reload(). */ int (*available)(char *why, size_t why_sz); } cst_tool_def_t; /* 0 when t exists on this platform. */ int cst_tool_platform_ok(const cst_tool_def_t *t); /* 0 when the tool can run here, -1 with a reason in why. Cached. */ int cst_tool_available(const cst_tool_def_t *t, char *why, size_t why_sz); /* Drop cached probes (a platform service appeared or went away). */ void cst_tool_meta_reload(void); /* Policy name of t: perm_name, or the class default of perm. */ const char *cst_tool_perm_name(const cst_tool_def_t *t); /* Add a tool at runtime (strings are copied, ud is not). Safe while turns * run; returns 0, or -1 when the name is taken or the table is full. An * app-provided tool may take a name whose built-in cannot run on this host * (the Android clipboard replacing the xclip one) and then shadows it for * lookups: one capability, one name. */ int cst_tool_register(const cst_tool_def_t *def); /* Drop every dynamic tool of owner (call only while no turn runs). */ int cst_tool_unregister_owner(const char *owner); /* Arguments of call as a JSON object text, typed by the tool's schema * (numbers/booleans/objects stay JSON). malloc'd. */ char *cst_tool_args_json(const cst_tool_def_t *t, const ctl_tool_call_t *call); /* Turn a name into a valid tool name ([A-Za-z0-9_-], at most 63 bytes). */ void cst_tool_sanitize_name(const char *in, char *out, size_t out_sz); /* Per-config switches by name (/tools on|off). */ int cst_tool_disabled(const cst_agent_config_t *cfg, const char *name); void cst_tool_set_disabled(cst_agent_config_t *cfg, const char *name, int off); typedef enum { CST_TOOLS_DEFAULT = 0, CST_TOOLS_MINIMAL } cst_tool_profile_t; int cst_tool_profile_parse(const char *s, int *out); const char *cst_tool_profile_name(int p); int cst_tool_count(void); const cst_tool_def_t *cst_tool_at(int i); const cst_tool_def_t *cst_tool_find(const char *name); int cst_tool_index(const char *name); /* Enabled for this config (profile + /tools switches). cfg may be NULL. */ int cst_tool_active(const cst_agent_config_t *cfg, const cst_tool_def_t *t); /* OpenAI tools[] for the active set (cJSON*, caller frees). */ void *cst_tools_schema_cfg(const cst_agent_config_t *cfg); /* "Tools:\n- name(a, b?): ...\n" for the active set (malloc'd). */ char *cst_tools_prompt(const cst_agent_config_t *cfg); /* Comma-separated active tool names (malloc'd). */ char *cst_tools_names(const cst_agent_config_t *cfg); /* Missing required args / bad integers. 0 = ok. */ int cst_tool_validate(const cst_tool_def_t *t, const ctl_tool_call_t *call, char *err, size_t err_sz); int cst_tool_run(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *call, cst_tool_result_t *r); int cst_tool_preview(const cst_tool_ctx_t *ctx, const ctl_tool_call_t *call, char **out); /* Workspace-relative files a write call may change (for /undo snapshots). * Returns the count written into paths. */ int cst_tool_targets(const ctl_tool_call_t *call, char paths[][1024], int max); /* Shell output cleaned for a model: ANSI escapes removed, `\r` progress * redraws folded to their final state, runs of identical lines collapsed, * very long output cut to head + tail. Returns malloc'd text. */ char *cst_shell_compact(const char *s, size_t n, size_t *out_len); /* Unified diff (3 lines of context, GNU `diff -u` layout) with * `--- a/