tools.c

/* tools.c - what the model can do: the tool table with its JSON
 * schemas, the implementations, and the shell policy (allow/deny prefix
 * lists) the loop consults before running one. */
#include <ctype.h>
#include <dirent.h>
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <poll.h>
#include <signal.h>
#include <stdlib.h>
#include <string.h>
#include <sys/wait.h>
#include <time.h>
#include <unistd.h>

#include "hai.h"
#include "stb_ds.h"

long tools_maxout = 16384;
int planmode; /* mirrors Agent.plan for the policy */
int tools_cmdtimeout = 120;
const char **tools_skilldirs;
static const char **allow, **deny; /* stb_ds */
static const char **always;        /* tools the user said "always" to */
const char *tools_mailroot;        /* set for a child agent: the Maildir root */
const char *tools_ownbox;          /* its Maildir: the mail it may change */
const char **tools_souls; /* the soul files: the person's, never the model's */

void tools_allow(const char *prefix) { arrput(allow, prefix); }
void tools_deny(const char *prefix) { arrput(deny, prefix); }

/* --- helpers --- */

static char *fmt(const char *f, const char *a, const char *b) {
    size_t n = strlen(f) + (a ? strlen(a) : 0) + (b ? strlen(b) : 0) + 1;
    char *s = malloc(n);
    snprintf(s, n, f, a ? a : "", b ? b : "");
    return s;
}

/* "~/x" and relative paths under $HOME */
static void expand(char *dst, size_t n, const char *p) {
    if (p[0] == '~' && (p[1] == '/' || !p[1]))
        homepath(dst, n, p + 1 + (p[1] == '/'));
    else
        snprintf(dst, n, "%s", p);
}

/* --- a child agent's mail: its own boxes may change, the rest is
 * read-only (main has no such limit; haid sets tools_mailroot only
 * for children) --- */

/* p is dir or below it */
static int under(const char *p, const char *dir) {
    size_t n = strlen(dir);
    return n && !strncmp(p, dir, n) && (!p[n] || p[n] == '/');
}

/* an absolute path with its . and .. segments folded, in place */
static void normpath(char *p) {
    char *out = p, *seg;

    for (seg = p; *seg;) {
        char *e = strchr(seg + 1, '/'), c;
        if (!e)
            e = seg + strlen(seg);
        c = *e, *e = '\0';
        if (!strcmp(seg, "/..")) {
            while (out > p && *--out != '/')
                ;
        } else if (strcmp(seg, "/.") && strcmp(seg, "/")) {
            memmove(out, seg, (size_t)(e - seg));
            out += e - seg;
        }
        *e = c;
        seg = e;
    }
    if (out == p)
        *out++ = '/';
    *out = '\0';
}

/* path made absolute: ~, $HOME, a relative path and .. resolved */
static void fullpath(char *full, size_t n, const char *path) {
    char cwd[4096];

    if (!strncmp(path, "$HOME/", 6))
        homepath(full, n, path + 6);
    else if (path[0] != '/' && path[0] != '~') {
        if (!getcwd(cwd, sizeof(cwd)))
            cwd[0] = '\0';
        snprintf(full, n, "%.2000s/%.2000s", cwd, path);
    } else
        expand(full, n, path);
    normpath(full);
}

/* 1 = path is mail of another agent's */
static int foreignmail(const char *path) {
    char full[4096];

    if (!tools_mailroot)
        return 0;
    fullpath(full, sizeof(full), path);
    return under(full, tools_mailroot) && !under(full, tools_ownbox);
}

/* 1 = path is one of the soul files, by name or through a link: a
 * soul.md that links to a SOUL.md beside it guards both */
static int soulfile(const char *path) {
    char full[4096], real[PATH_MAX], soul[PATH_MAX];
    ptrdiff_t i;
    int isreal;

    if (!arrlen(tools_souls))
        return 0;
    fullpath(full, sizeof(full), path);
    isreal = realpath(full, real) != NULL;
    for (i = 0; i < arrlen(tools_souls); i++)
        if (!strcmp(full, tools_souls[i]) ||
            (isreal && realpath(tools_souls[i], soul) && !strcmp(real, soul)))
            return 1;
    return 0;
}

/* the paths named in a command line (words starting with /, ~, ./,
 * ../ or $HOME): 1 = one of them satisfies is() */
static int cmd_names(const char *cmd, int (*is)(const char *)) {
    char tok[4096];
    const char *p;
    size_t n;

    for (p = cmd; *p; p++) {
        if (p > cmd && !strchr(" \t\n'\"=;|&(<>", p[-1]))
            continue;
        if (*p != '/' && *p != '~' && strncmp(p, "$HOME/", 6) &&
            strncmp(p, "./", 2) && strncmp(p, "../", 3))
            continue;
        n = strcspn(p, " \t\n'\";|&)<>");
        if (n >= sizeof(tok))
            n = sizeof(tok) - 1;
        memcpy(tok, p, n);
        tok[n] = '\0';
        if (is(tok))
            return 1;
        p += n - 1;
    }
    return 0;
}

/* keep the head and tail of a long output, note what was dropped; the
 * cuts land on character boundaries, a split UTF-8 sequence being what
 * a strict endpoint refuses the whole request over */
static char *capout(char *s, long cap) {
    long n = (long)strlen(s), head = cap / 2, tail = n - cap / 2;
    char note[64], *r;

    if (n <= cap)
        return s;
    while (head > 0 && (s[head] & 0xc0) == 0x80)
        head--;
    while (tail < n && (s[tail] & 0xc0) == 0x80)
        tail++;
    snprintf(note, sizeof(note), "\n...[%ld bytes omitted]...\n", tail - head);
    r = malloc((size_t)(head + n - tail) + strlen(note) + 1);
    memcpy(r, s, (size_t)head);
    strcpy(r + head, note);
    strcat(r, s + tail);
    free(s);
    return r;
}

/* --- the shell policy --- */

/* the command's segments: split on ; && || | & and newlines, trimmed */
static char **segments(const char *cmd) {
    char **segs = NULL, *dup = xstrdup(cmd), *p = dup, *start = dup;
    int quote = 0;

    for (;; p++) {
        char c = *p;
        int cut = 0;
        if (quote) {
            if (c == quote)
                quote = 0;
            else if (c == '\\' && quote == '"' && p[1])
                p++;
        } else if (c == '\'' || c == '"')
            quote = c;
        else if (c == ';' || c == '|' || c == '&' || c == '\n' || !c)
            cut = 1;
        if (cut) {
            *p = '\0';
            while (*start == ' ' || *start == '\t')
                start++;
            if (*start) {
                char *e = start + strlen(start);
                while (e > start && (e[-1] == ' ' || e[-1] == '\t'))
                    *--e = '\0';
                arrput(segs, xstrdup(start));
            }
            start = p + 1;
        }
        if (!c)
            break;
    }
    free(dup);
    return segs;
}

static void freesegs(char **segs) {
    ptrdiff_t i;
    for (i = 0; i < arrlen(segs); i++)
        free(segs[i]);
    arrfree(segs);
}

static int segmatch(const char *seg, const char *pfx) {
    size_t n = strlen(pfx);
    return !strncmp(seg, pfx, n) &&
           (!seg[n] || seg[n] == ' ' || seg[n] == '\t');
}

/* `PROG -h` or `PROG --help`, nothing else: a program's own help is how
 * the model learns to drive it, so it never asks, whatever the program */
static int helpcmd(const char *seg) {
    const char *sp = strchr(seg, ' ');
    if (!sp || sp == seg)
        return 0;
    while (*sp == ' ')
        sp++;
    if (!strncmp(sp, "-h", 2))
        sp += 2;
    else if (!strncmp(sp, "--help", 6))
        sp += 6;
    else
        return 0;
    return !*sp;
}

int cmd_allowed(const char *cmd, const char *const *pfx, int n) {
    char **segs = segments(cmd);
    ptrdiff_t i;
    int j, ok = arrlen(segs) > 0;

    for (i = 0; ok && i < arrlen(segs); i++) {
        if (strstr(segs[i], "$(") || strchr(segs[i], '`') ||
            strstr(segs[i], "${")) {
            ok = 0;
            break;
        }
        for (j = 0; j < n && !segmatch(segs[i], pfx[j]); j++)
            ;
        ok = j < n || helpcmd(segs[i]);
    }
    freesegs(segs);
    return ok;
}

int cmd_denied(const char *cmd, const char *const *pfx, int n) {
    char **segs = segments(cmd);
    ptrdiff_t i;
    int j, hit = 0;

    for (i = 0; !hit && i < arrlen(segs); i++)
        for (j = 0; j < n; j++)
            if (segmatch(segs[i], pfx[j]) ||
                strstr(segs[i], pfx[j])) { /* anywhere in the segment too */
                hit = 1;
                break;
            }
    freesegs(segs);
    return hit;
}

int tools_isalways(const char *name) {
    ptrdiff_t i;
    for (i = 0; i < arrlen(always); i++)
        if (!strcmp(always[i], name))
            return 1;
    return 0;
}

/* the program and, when it has one, the subcommand of each segment:
 * "git commit -m x && make install" -> "git commit", "make install" */
void tools_always(const char *name, const cJSON *args) {
    const char *cmd;
    char **segs;
    ptrdiff_t i;

    if (strcmp(name, "shell") || !(cmd = jstr(args, "command"))) {
        if (!tools_isalways(name))
            arrput(always, xstrdup(name));
        return;
    }
    segs = segments(cmd);
    for (i = 0; i < arrlen(segs); i++) {
        char *sp = strchr(segs[i], ' '), *pfx;
        if (sp && sp[1] && sp[1] != '-' && sp[1] != '/' && sp[1] != '.' &&
            sp[1] != '~' && sp[1] != '$') {
            char *e = strchr(sp + 1, ' ');
            if (e)
                *e = '\0';
        } else if (sp)
            *sp = '\0';
        pfx = xstrdup(segs[i]);
        if (!cmd_allowed(pfx, allow, (int)arrlen(allow)))
            arrput(allow, pfx);
        else
            free(pfx);
    }
    freesegs(segs);
}

static const char soulwhy[] =
    "the soul file: the person who runs you writes it, you never touch "
    "it; what it says is already in your context";

int tools_policy(const char *name, const cJSON *args, char *why, size_t n) {
    const char *cmd, *path;

    if ((!strcmp(name, "write_file") || !strcmp(name, "edit_file")) &&
        (path = jstr(args, "path"))) {
        if (soulfile(path)) {
            snprintf(why, n, "%s", soulwhy);
            return -1;
        }
        if (foreignmail(path)) {
            snprintf(why, n,
                     "another agent's mail: only your own Maildir may "
                     "change, the rest is read-only");
            return -1;
        }
    }
    if (tools_isalways(name) && strcmp(name, "shell"))
        return 1;

    if (!strcmp(name, "shell")) {
        if (!(cmd = jstr(args, "command")))
            return 1; /* the tool will complain about the argument */
        if (cmd_denied(cmd, deny, (int)arrlen(deny))) {
            snprintf(why, n, "command is on the deny list");
            return -1;
        }
        if (cmd_names(cmd, soulfile)) { /* before the allow list: an
                                           allowed sed -i is still no */
            snprintf(why, n, "%s", soulwhy);
            return -1;
        }
        if (cmd_allowed(cmd, allow, (int)arrlen(allow)))
            return 1; /* reads, wherever they look */
        if (tools_mailroot && cmd_names(cmd, foreignmail)) {
            snprintf(why, n,
                     "another agent's mail: only your own Maildir may "
                     "change, the rest is read-only (reads like cat and "
                     "ls run freely)");
            return -1;
        }
        return 0;
    }
    if (!strcmp(name, "write_file") || !strcmp(name, "edit_file"))
        return 0;
    if (planmode && (!strcmp(name, "send_mail") || !strcmp(name, "delegate")))
        return 0; /* they set others in motion; the loop refuses a 0 */
    if (!strcmp(name, "send_mail")) { /* local stays on this machine */
        const char *to = jstr(args, "to");
        return to && mail_islocal(to);
    }
    if (!strcmp(name, "delegate") && child_depth >= child_maxdepth) {
        snprintf(why, n, "this agent is too deep in the tree to delegate");
        return -1;
    }
    return 1;
}

/* --- the tools --- */

/* run argv (stdin = input, or nothing) and collect stdout+stderr,
 * serving tick() meanwhile; killed on timeout or cancel. For an
 * external tool the arguments also go into its environment as
 * HAI_ARG_<name> (strings, numbers, booleans) and HAI_ARGS (the JSON),
 * HAI_APPROVED=1 when the user said yes. The exit status lands in
 * *status (-1 = killed), the output is returned, uncapped. */
static char *run(Agent *a, char *const argv[], const char *input,
                 const cJSON *env, int approved, int tmo, int *status) {
    char buf[4096], *out = NULL;
    struct timespec t0, now;
    int fd[2], in[2] = {-1, -1}, killed = 0;
    pid_t pid;

    *status = 127;
    if (pipe(fd) < 0 || (input && pipe(in) < 0))
        return fmt("error: pipe: %s", strerror(errno), NULL);
    if ((pid = fork()) < 0)
        return fmt("error: fork: %s", strerror(errno), NULL);
    if (pid == 0) {
        const cJSON *v;
        char name[128];
        setpgid(0, 0);
        if (input)
            dup2(in[0], 0), close(in[0]), close(in[1]);
        else
            dup2(open("/dev/null", O_RDONLY), 0);
        dup2(fd[1], 1);
        dup2(fd[1], 2);
        close(fd[0]);
        close(fd[1]);
        if (env) {
            char *j = cJSON_PrintUnformatted(env);
            setenv("HAI_ARGS", j, 1);
            cJSON_ArrayForEach(v, env) {
                snprintf(name, sizeof(name), "HAI_ARG_%s", v->string);
                if (cJSON_IsString(v))
                    setenv(name, v->valuestring, 1);
                else if (cJSON_IsNumber(v)) {
                    snprintf(buf, sizeof(buf), "%g", v->valuedouble);
                    setenv(name, buf, 1);
                } else if (cJSON_IsBool(v))
                    setenv(name, cJSON_IsTrue(v) ? "true" : "false", 1);
            }
        }
        if (approved)
            setenv("HAI_APPROVED", "1", 1);
        execvp(argv[0], argv);
        _exit(127);
    }
    close(fd[1]);
    if (input) { /* small: fits the pipe, written before we read */
        close(in[0]);
        (void)!write(in[1], input, strlen(input) < 60000 ? strlen(input) : 0);
        close(in[1]);
    }
    clock_gettime(CLOCK_MONOTONIC, &t0);
    for (;;) {
        struct pollfd pfd = {fd[0], POLLIN, 0};
        int r = poll(&pfd, 1, 200);
        ssize_t n;
        if (r > 0) {
            if ((n = read(fd[0], buf, sizeof(buf))) <= 0)
                break;
            if (arrlen(out) < 4 * tools_maxout) {
                ssize_t i;
                for (i = 0; i < n; i++)
                    arrput(out, buf[i]);
            }
        }
        clock_gettime(CLOCK_MONOTONIC, &now);
        if (now.tv_sec - t0.tv_sec >= tmo ||
            (a->tick && a->tick(a->ud) && (a->cancelled = 1))) {
            kill(-pid, SIGKILL);
            killed = 1;
            break;
        }
    }
    close(fd[0]);
    waitpid(pid, status, 0);
    if (killed)
        *status = -1;
    else if (WIFEXITED(*status))
        *status = WEXITSTATUS(*status);
    else
        *status = 128 + (WIFSIGNALED(*status) ? WTERMSIG(*status) : 0);
    arrput(out, '\0');
    {
        char *r = xstrdup(out);
        arrfree(out);
        return r;
    }
}

/* the output the model sees: capped, the exit status noted */
static char *result(Agent *a, char *out, int status) {
    char tail[64], *s, *r;

    if (status == -1)
        snprintf(tail, sizeof(tail), "\n[killed: %s]",
                 a->cancelled ? "cancelled" : "timeout");
    else if (status > 128)
        snprintf(tail, sizeof(tail), "\n[signal %d]", status - 128);
    else if (status)
        snprintf(tail, sizeof(tail), "\n[exit %d]", status);
    else
        tail[0] = '\0';
    s = capout(out, tools_maxout);
    r = fmt("%s%s", *s ? s : "(no output)", tail);
    free(s);
    return r;
}

static int timeoutof(const cJSON *args) {
    int tmo = (int)jnum(args, "timeout", tools_cmdtimeout);
    if (tmo < 1 || tmo > 10 * tools_cmdtimeout) /* models guess units */
        tmo = tmo < 1 ? tools_cmdtimeout : 10 * tools_cmdtimeout;
    return tmo;
}

static char *t_shell(Agent *a, const cJSON *args) {
    const char *cmd = jstr(args, "command");
    char *const argv[] = {"sh", "-c", (char *)cmd, NULL};
    char *out;
    int status;

    if (!cmd)
        return xstrdup("error: missing command");
    out = run(a, argv, NULL, NULL, 0, timeoutof(args), &status);
    return result(a, out, status);
}

static char *t_read(Agent *a, const cJSON *args) {
    const char *p = jstr(args, "path");
    char path[4096], *s;
    (void)a;

    if (!p)
        return xstrdup("error: missing path");
    expand(path, sizeof(path), p);
    if (!(s = readfile(path, 0)))
        return fmt("error: %s: %s", path, strerror(errno));
    return capout(s, tools_maxout);
}

static char *t_write(Agent *a, const cJSON *args) {
    const char *p = jstr(args, "path"), *c = jstr(args, "content");
    char path[4096], n[32];
    FILE *f;
    (void)a;

    if (!p || !c)
        return xstrdup("error: need path and content");
    expand(path, sizeof(path), p);
    if (!(f = fopen(path, "w")))
        return fmt("error: %s: %s", path, strerror(errno));
    fputs(c, f);
    fclose(f);
    snprintf(n, sizeof(n), "%zu", strlen(c));
    return fmt("wrote %s bytes to %s", n, path);
}

static char *t_edit(Agent *a, const cJSON *args) {
    const char *p = jstr(args, "path"), *o = jstr(args, "old"),
               *nw = jstr(args, "new");
    char path[4096], *s, *hit, *r;
    size_t before, on, nn;
    FILE *f;
    (void)a;

    if (!p || !o || !nw || !*o)
        return xstrdup("error: need path, old (non-empty) and new");
    expand(path, sizeof(path), p);
    if (!(s = readfile(path, 0)))
        return fmt("error: %s: %s", path, strerror(errno));
    if (!(hit = strstr(s, o))) {
        free(s);
        return xstrdup("error: old text not found");
    }
    if (strstr(hit + 1, o)) {
        free(s);
        return xstrdup("error: old text occurs more than once; add context");
    }
    before = (size_t)(hit - s), on = strlen(o), nn = strlen(nw);
    r = malloc(strlen(s) - on + nn + 1);
    memcpy(r, s, before);
    memcpy(r + before, nw, nn);
    strcpy(r + before + nn, hit + on);
    free(s);
    if (!(f = fopen(path, "w"))) {
        free(r);
        return fmt("error: %s: %s", path, strerror(errno));
    }
    fputs(r, f);
    fclose(f);
    free(r);
    return fmt("edited %s", path, NULL);
}

static char *t_speak(Agent *a, const cJSON *args) {
    const char *t = jstr(args, "text");
    if (!t)
        return xstrdup("error: missing text");
    if (!a->say)
        return xstrdup("error: no voice available");
    a->say(a->ud, t);
    return xstrdup("spoken");
}

/* the question, with the choices as its last line "(a / b / c)": the
 * form the permission question has too, and what a menu shows as rows */
static char *t_ask(Agent *a, const cJSON *args) {
    const char *q = jstr(args, "question");
    const cJSON *ch = cJSON_GetObjectItemCaseSensitive(args, "choices"), *c;
    char line[1024] = "", *ans, *full;
    size_t n = 0;

    if (!q)
        return xstrdup("error: missing question");
    if (cJSON_IsArray(ch))
        cJSON_ArrayForEach(c, ch) {
            /* only what the one-line "(a / b / c)" form cannot hold is
             * dropped: a newline or tab in the choice, or the " / "
             * separator itself. Parentheses are the choice's own
             * business: the menu reads the group from its first paren,
             * so "Re: clear (06:13)" is a row like any other */
            if (!cJSON_IsString(c) || !*c->valuestring ||
                strpbrk(c->valuestring, "\t\n") ||
                strstr(c->valuestring, " / ") ||
                n + strlen(c->valuestring) + 8 > sizeof(line))
                continue;
            n += (size_t)snprintf(line + n, sizeof(line) - n, "%s%s",
                                  n ? " / " : "\n(", c->valuestring);
        }
    if (n)
        strcat(line, ")");
    full = malloc(strlen(q) + strlen(line) + 1);
    sprintf(full, "%s%s", q, line);
    ans = a->ask ? a->ask(a->ud, full) : NULL;
    free(full);
    return ans ? ans
               : xstrdup("no answer: the user is not available right now");
}

static char *t_notify(Agent *a, const cJSON *args) {
    const char *s = jstr(args, "summary"), *b = jstr(args, "body");
    (void)a;
    if (!s)
        return xstrdup("error: missing summary");
    if (fork() == 0) {
        execlp("notify-send", "notify-send", "-a", "hai", s, b ? b : "",
               (char *)NULL);
        _exit(1);
    }
    return xstrdup("notified");
}

static char *t_mail(Agent *a, const cJSON *args) {
    const char *to = jstr(args, "to"), *subj = jstr(args, "subject"),
               *b = jstr(args, "body"), *ref = jstr(args, "in_reply_to"),
               *at = jstr(args, "at"), *every = jstr(args, "every");
    char err[256];
    MailHdr h;
    Msg m;
    int rc;
    (void)a;

    if (!to || !b)
        return xstrdup("error: need to and body");
    if (at && *at && trigger_at(at, time(NULL)) < 0)
        return xstrdup("error: at is \"YYYY-MM-DD HH:MM\" or \"HH:MM\"");
    if (every && *every && trigger_every(every, time(NULL)) < 0)
        return xstrdup("error: every is \"30m\", \"2h\", \"1d\" or a "
                       "daily \"HH:MM\"");
    if ((at && *at) || (every && *every)) {
        if (!mail_islocal(to)) /* only an agent's inbox keeps time */
            return xstrdup("error: at/every only for @hai addresses");
    }
    memset(&h, 0, sizeof(h));
    h.from = mail_from;
    h.to = to;
    h.subject = subj ? subj : "(no subject)";
    h.inreplyto = ref;
    h.intent = "message";
    h.at = at && *at ? at : NULL;
    h.every = every && *every ? every : NULL;
    m = msg_new("assistant", b);
    rc = mail_send(&h, &m, err, sizeof(err));
    msg_free(&m);
    if (rc < 0)
        return fmt("error: %s", err, NULL);
    if (h.at || h.every)
        return fmt("queued for %s; it runs when due (`hai triggers` lists "
                   "timed mail, deleting the file cancels it)",
                   to, NULL);
    return fmt("sent to %s", to, NULL);
}

static char *t_delegate(Agent *a, const cJSON *args) {
    const char *name = jstr(args, "name"), *task = jstr(args, "task"),
               *dir = jstr(args, "dir"), *model = jstr(args, "model");
    if (!name || !task)
        return xstrdup("error: need name and task");
    return child_delegate(a, name, task, jbool(args, "wait", 1), dir, model);
}

static char *t_skill(Agent *a, const cJSON *args) {
    const char *n = jstr(args, "name");
    char path[4096], *s;
    ptrdiff_t i;
    (void)a;

    if (!n || strchr(n, '/') || n[0] == '.')
        return xstrdup("error: bad skill name");
    for (i = 0; i < arrlen(tools_skilldirs); i++) {
        snprintf(path, sizeof(path), "%s/%s.md", tools_skilldirs[i], n);
        if ((s = readfile(path, 0)))
            return capout(s, tools_maxout);
    }
    return fmt("error: no skill named %s", n, NULL);
}

const Tool tools[] = {
    {"shell",
     "Run a shell command on this machine (sh -c) and get its combined "
     "stdout and stderr, plus the exit status when nonzero. Commands not "
     "on the allow list are confirmed with the user first. Long output "
     "is cut in the middle. When a dedicated tool exists (git, mail, "
     "services, packages, browse, windows, show), use it instead.",
     "{\"type\":\"object\",\"properties\":{"
     "\"command\":{\"type\":\"string\",\"description\":\"the command "
     "line\"},"
     "\"timeout\":{\"type\":\"integer\",\"description\":\"seconds before "
     "it is killed (default 120, at most 1200)\"}},"
     "\"required\":[\"command\"]}",
     t_shell},
    {"read_file", "Read a text file; ~ expands to the home directory.",
     "{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},"
     "\"required\":[\"path\"]}",
     t_read},
    {"write_file",
     "Create or overwrite a file with the given content (asks the user "
     "first).",
     "{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"},"
     "\"content\":{\"type\":\"string\"}},\"required\":[\"path\","
     "\"content\"]}",
     t_write},
    {"edit_file",
     "Replace one exact, unique occurrence of `old` in a file with `new` "
     "(asks the user first).",
     "{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"},"
     "\"old\":{\"type\":\"string\"},\"new\":{\"type\":\"string\"}},"
     "\"required\":[\"path\",\"old\",\"new\"]}",
     t_edit},
    {"speak",
     "Say something aloud to the user right now (text to speech). Use "
     "for progress on long tasks; the final reply is spoken anyway in "
     "voice mode.",
     "{\"type\":\"object\",\"properties\":{\"text\":{\"type\":\"string\"}},"
     "\"required\":[\"text\"]}",
     t_speak},
    {"ask",
     "Ask the user a question and wait for the answer (spoken, typed in "
     "the terminal, or picked from a menu on the desktop, depending on "
     "how they are talking to you). Keep it short. choices: a few short "
     "options offered as the menu's rows or listed after the question; "
     "the user may still answer in their own words.",
     "{\"type\":\"object\",\"properties\":{\"question\":{\"type\":"
     "\"string\"},\"choices\":{\"type\":\"array\",\"items\":{\"type\":"
     "\"string\"}}},\"required\":[\"question\"]}",
     t_ask},
    {"notify",
     "Show a desktop notification. Use for results the user should see "
     "later without being interrupted.",
     "{\"type\":\"object\",\"properties\":{\"summary\":{\"type\":"
     "\"string\"},\"body\":{\"type\":\"string\"}},\"required\":["
     "\"summary\"]}",
     t_notify},
    {"send_mail",
     "Send an email. Addresses @hai stay on this machine and need no "
     "confirmation: user@hai reaches the user later (results of work "
     "done while nobody was around, things to read at leisure), your "
     "own address reaches you as a new inbox turn, a group address is "
     "taken by whichever agent listening there is free. Any other "
     "address is real email and is confirmed with the user first. "
     "in_reply_to threads the message under a Message-ID you were "
     "given. Timed mail (to an @hai address): at = \"YYYY-MM-DD HH:MM\" "
     "or \"HH:MM\" (the next such time) delivers it then, once; every = "
     "\"30m\", \"2h\", \"1d\" or a daily \"HH:MM\" delivers it again and "
     "again - a reminder, a check, a report to yourself or the user.",
     "{\"type\":\"object\",\"properties\":{\"to\":{\"type\":\"string\"},"
     "\"subject\":{\"type\":\"string\"},\"body\":{\"type\":\"string\"},"
     "\"in_reply_to\":{\"type\":\"string\"},\"at\":{\"type\":\"string\"},"
     "\"every\":{\"type\":\"string\"}},\"required\":[\"to\",\"body\"]}",
     t_mail},
    {"load_skill",
     "Load the full text of a skill from the skills list in your "
     "instructions. Do this before a task the skill covers.",
     "{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"}},"
     "\"required\":[\"name\"]}",
     t_skill},
    {"delegate",
     "Hand a task to a child agent: a separate hai with its own "
     "conversation and the same tools; a question it asks reaches the "
     "user through the daemon (not through you) and its run waits for "
     "the answer, so give it a complete, self-contained task and say "
     "what to report back. name is a short lowercase word "
     "of your choosing; the same name again continues that child's "
     "conversation. With wait (the default) the child's report is the "
     "result; with wait false it arrives later as an inbox turn from "
     "the child's address, and you can start several in parallel. A "
     "child can delegate in turn; its children's addresses carry its "
     "name, and the root (main) gives the leave: this is the only way "
     "an agent is started. dir sends the child to work in a directory: its "
     "shell "
     "commands and relative paths are there, and it picks up that "
     "project's instructions (AGENTS.md or CLAUDE.md) and skills "
     "(.hai/skills/*.md). model picks another model for it (a cheaper "
     "one for simple work, a stronger one for hard work); dir and "
     "model are fixed once the child is started.",
     "{\"type\":\"object\",\"properties\":{\"name\":{\"type\":"
     "\"string\"},\"task\":{\"type\":\"string\"},\"wait\":{\"type\":"
     "\"boolean\"},\"dir\":{\"type\":\"string\",\"description\":"
     "\"absolute path of the working directory\"},\"model\":{\"type\":"
     "\"string\",\"description\":\"model name at the same endpoint\"}},"
     "\"required\":[\"name\",\"task\"]}",
     t_delegate},
};
int ntools = sizeof(tools) / sizeof(tools[0]);

/* --- external tools: executables that describe themselves --- */

typedef struct {
    char *name, *desc, *params, *path;
    Mcp *srv;     /* set: a tool of an MCP server, not an executable */
    char *mname;  /* its name on the server */
    int readonly; /* the server's readOnlyHint: runs without asking */
} Ext;
static Ext *exts; /* stb_ds */

static int known(const char *name) {
    ptrdiff_t i;
    for (i = 0; i < ntools; i++)
        if (!strcmp(tools[i].name, name))
            return 1;
    for (i = 0; i < arrlen(exts); i++)
        if (!strcmp(exts[i].name, name))
            return 1;
    return 0;
}

/* every executable in dir: `NAME --schema` prints {"name",
 * "description", "parameters"}; the first of a name wins */
void tools_load(const char *dir) {
    char path[4400], *out, **names = NULL;
    struct dirent *d;
    DIR *dp;
    ptrdiff_t i, j;

    if (!(dp = opendir(dir)))
        return;
    while ((d = readdir(dp)))
        if (d->d_name[0] != '.')
            arrput(names, xstrdup(d->d_name));
    closedir(dp);
    for (i = 1; i < arrlen(names); i++) { /* stable order for the prompt */
        char *t = names[i];
        for (j = i; j > 0 && strcmp(names[j - 1], t) > 0; j--)
            names[j] = names[j - 1];
        names[j] = t;
    }
    for (i = 0; i < arrlen(names); i++) {
        cJSON *j;
        const cJSON *pa;
        const char *n, *de;
        FILE *f;
        size_t got;
        snprintf(path, sizeof(path), "%.4000s/%.300s", dir, names[i]);
        free(names[i]);
        if (access(path, X_OK) < 0)
            continue;
        out = malloc(16384);
        snprintf(out, 16384, "'%s' --schema 2>/dev/null", path);
        if (!(f = popen(out, "r"))) {
            free(out);
            continue;
        }
        got = fread(out, 1, 16383, f);
        out[got] = '\0';
        pclose(f);
        j = cJSON_Parse(out);
        free(out);
        n = jstr(j, "name");
        de = jstr(j, "description");
        pa = jget(j, "parameters");
        if (!n || !de || !cJSON_IsObject(pa))
            fprintf(stderr, "hai: %s: no usable --schema, skipped\n", path);
        else if (!known(n)) {
            Ext e = {0};
            e.name = xstrdup(n);
            e.desc = xstrdup(de);
            e.params = cJSON_PrintUnformatted(pa);
            e.path = xstrdup(path);
            arrput(exts, e);
        }
        cJSON_Delete(j);
    }
    arrfree(names);
}

/* --- MCP servers: their tools as externals --- */

static Mcp **servers; /* stb_ds */

/* is word one of the space-separated names in list */
static int inlist(const char *list, const char *word) {
    size_t n = strlen(word);
    const char *p;

    for (p = list; p && (p = strstr(p, word)); p += n)
        if ((p == list || p[-1] == ' ') && (!p[n] || p[n] == ' '))
            return 1;
    return 0;
}

int tools_mcp(const char *server, const char *url, const char *const *hdrs,
              const char *readonly, char *err, size_t n) {
    Mcp *m;
    const cJSON *t, *schema;
    const char *v, *desc;
    char name[200], *p;
    int added = 0;

    if (!(m = mcp_connect(server, url, hdrs, NULL, err, n)))
        return -1;
    arrput(servers, m);
    cJSON_ArrayForEach(t, mcp_tools(m)) {
        Ext e = {0};
        if (!(v = jstr(t, "name")))
            continue;
        snprintf(name, sizeof(name), "%s_%s", server, v);
        for (p = name; *p; p++) /* the model's names: word chars only */
            if (!isalnum((unsigned char)*p) && *p != '_' && *p != '-')
                *p = '_';
        if (known(name)) {
            fprintf(stderr, "hai: mcp %s: %s: name taken, skipped\n", server,
                    name);
            continue;
        }
        e.name = xstrdup(name);
        e.mname = xstrdup(v);
        desc = jstr(t, "description");
        e.desc = xstrdup(desc ? desc : "");
        schema = jget(t, "inputSchema");
        e.params = cJSON_IsObject(schema) ? cJSON_PrintUnformatted(schema)
                                          : xstrdup("{\"type\":\"object\"}");
        e.path = xstrdup(url);
        e.srv = m;
        e.readonly = jbool(t, "annotations.readOnlyHint", 0) ||
                     (readonly && inlist(readonly, e.mname));
        arrput(exts, e);
        added++;
    }
    return added;
}

char *tools_mcpnotes(void) {
    char *out = NULL, line[256];
    const char *p;
    ptrdiff_t i;

    for (i = 0; i < arrlen(servers); i++) {
        if (!mcp_instructions(servers[i]))
            continue;
        snprintf(line, sizeof(line),
                 "\nThe %s server (tools %s_*) says: ", mcp_name(servers[i]),
                 mcp_name(servers[i]));
        for (p = line; *p; p++)
            arrput(out, *p);
        for (p = mcp_instructions(servers[i]); *p; p++)
            arrput(out, *p);
        arrput(out, '\n');
    }
    arrput(out, '\0');
    {
        char *r = xstrdup(out);
        arrfree(out);
        return r;
    }
}

/* a call to an MCP server: read-only tools run at once, the rest are
 * confirmed like a shell command */
static char *runmcp(Agent *a, const Ext *e, const char *argsjson) {
    char q[400], *ans, *out;

    if (!(e->readonly || a->autonomous || tools_isalways(e->name))) {
        if (a->plan)
            return xstrdup("not run: plan mode is on. Describe this step "
                           "in your plan instead; the user will turn plan "
                           "mode off and tell you to proceed.");
        snprintf(q, sizeof(q), "%s: %s %.250s%s?", mcp_name(e->srv), e->mname,
                 argsjson, strlen(argsjson) > 250 ? "..." : "");
        ans = a->ask ? a->ask(a->ud, q) : NULL;
        if (!ans)
            return xstrdup("not run: nobody could approve it right now; "
                           "explain what you wanted to do instead");
        if (answer_always(ans))
            tools_always(e->name, NULL);
        if (!answer_yes(ans)) {
            out = fmt("not run: the user declined (\"%s\"). Do not try "
                      "another way to do the same thing; tell the user it "
                      "was not done.",
                      ans, NULL);
            free(ans);
            return out;
        }
        free(ans);
    }
    out = mcp_call(e->srv, a, e->mname, argsjson);
    return capout(out, tools_maxout);
}

/* every tool name, builtins then externals, one per line; malloc'd */
char *tools_names(void) {
    char *out = NULL;
    ptrdiff_t i;
    const char *p;

    for (i = 0; i < ntools + arrlen(exts); i++) {
        for (p = i < ntools ? tools[i].name : exts[i - ntools].name; *p; p++)
            arrput(out, *p);
        arrput(out, '\n');
    }
    arrput(out, '\0');
    {
        char *r = xstrdup(out);
        arrfree(out);
        return r;
    }
}

char *tools_extlist(void) {
    char *out = NULL, line[400];
    ptrdiff_t i;
    const char *p;

    for (i = 0; i < arrlen(exts); i++) {
        if (exts[i].srv) /* listed by server */
            continue;
        snprintf(line, sizeof(line), "%s%s (%s)", arrlen(out) ? ", " : "",
                 exts[i].name, exts[i].path);
        for (p = line; *p; p++)
            arrput(out, *p);
    }
    arrput(out, '\0');
    {
        char *r = xstrdup(out);
        arrfree(out);
        return r;
    }
}

/* an external tool asks for itself: exit 3 with the question on stdout
 * means "confirm this", and a yes runs it again with HAI_APPROVED=1 */
static char *runext(Agent *a, const Ext *e, const cJSON *args,
                    const char *argsjson) {
    char *const argv[] = {e->path, NULL};
    char *out, *q, *ans;
    int status, approved = a->autonomous;

    if (e->srv)
        return runmcp(a, e, argsjson);
    if (tools_isalways(e->name))
        approved = 1;
    for (;;) {
        out = run(a, argv, argsjson, args, approved, timeoutof(args), &status);
        if (status != 3 || approved)
            return result(a, out, status);
        if (a->plan) {
            free(out);
            return xstrdup("not run: plan mode is on. Describe this step "
                           "in your plan instead; the user will turn plan "
                           "mode off and tell you to proceed.");
        }
        q = out;
        while (*q && q[strlen(q) - 1] == '\n')
            q[strlen(q) - 1] = '\0';
        if (strlen(q) > 300)
            strcpy(q + 297, "...");
        ans = a->ask ? a->ask(a->ud, *q ? q : "Allow?") : NULL;
        free(out);
        if (!ans)
            return xstrdup("not run: nobody could approve it right now; "
                           "explain what you wanted to do instead");
        if (answer_always(ans))
            tools_always(e->name, NULL);
        if (!answer_yes(ans)) {
            out = fmt("not run: the user declined (\"%s\"). Do not try "
                      "another way to do the same thing; tell the user it "
                      "was not done.",
                      ans, NULL);
            free(ans);
            return out;
        }
        free(ans);
        approved = 1;
    }
}

cJSON *tools_schema(void) {
    cJSON *arr = cJSON_CreateArray(), *t, *f;
    ptrdiff_t i;

    for (i = 0; i < ntools; i++) {
        if (child_depth >= child_maxdepth && !strcmp(tools[i].name, "delegate"))
            continue;
        t = cJSON_CreateObject();
        cJSON_AddStringToObject(t, "type", "function");
        f = cJSON_AddObjectToObject(t, "function");
        cJSON_AddStringToObject(f, "name", tools[i].name);
        cJSON_AddStringToObject(f, "description", tools[i].desc);
        cJSON_AddItemToObject(f, "parameters", cJSON_Parse(tools[i].params));
        cJSON_AddItemToArray(arr, t);
    }
    for (i = 0; i < arrlen(exts); i++) {
        t = cJSON_CreateObject();
        cJSON_AddStringToObject(t, "type", "function");
        f = cJSON_AddObjectToObject(t, "function");
        cJSON_AddStringToObject(f, "name", exts[i].name);
        cJSON_AddStringToObject(f, "description", exts[i].desc);
        cJSON_AddItemToObject(f, "parameters", cJSON_Parse(exts[i].params));
        cJSON_AddItemToArray(arr, t);
    }
    return arr;
}

char *tools_call(Agent *a, const char *name, const char *argsjson) {
    cJSON *args = cJSON_Parse(argsjson);
    char *r = NULL;
    ptrdiff_t i;

    if (!args)
        return xstrdup("error: arguments are not valid JSON");
    for (i = 0; i < ntools; i++)
        if (!strcmp(tools[i].name, name)) {
            r = tools[i].fn(a, args);
            break;
        }
    for (i = 0; !r && i < arrlen(exts); i++)
        if (!strcmp(exts[i].name, name))
            r = runext(a, &exts[i], args, argsjson);
    cJSON_Delete(args);
    return r ? r : fmt("error: no tool named %s", name, NULL);
}