engine/include/tools.h

// Strumenti di programmazione: Neuronal legge, scrive ed esegue codice dentro la cartella di lavoro.
// Il modello li chiama nel formato che conosce: <tool_call>{"name": ..., "arguments": {...}}</tool_call>.
#pragma once
#include <stdbool.h>
#include <stddef.h>

typedef struct {
    char  name[48];
    char *args;        // oggetto JSON degli argomenti (malloc)
    bool  bad;         // JSON illeggibile: si risponde con l'errore
} ToolCall;

// dir: cartella di lavoro (creata se manca). Tutti i percorsi degli strumenti sono relativi a questa.
void        tools_init(const char *dir);
void        tools_log_path(const char *path);   // dove registrare le chiamate (nella cartella dello stato)
const char *tools_workspace(void);          // percorso assoluto
// Istruzioni e firme degli strumenti da aggiungere al prompt di sistema.
const char *tools_prompt(void);

// Chiamate presenti nel testo (fino a max). Ritorna quante; ogni args va liberato con tools_free.
int  tools_parse(const char *text, ToolCall *out, int max);
void tools_free(ToolCall *c, int n);
// Esegue una chiamata. Ritorna il risultato per il modello (malloc); ok = riuscita.
char *tools_run(const ToolCall *c, bool *ok);
// Istruzioni per strumenti di programmazione (code) più altri definiti dal chiamante. Da liberare.
char *tools_prompt_build(bool code, const char *intro, const char *funcs);
// File binario della cartella di lavoro, per intero (malloc). NULL con err se manca o supera max byte.
unsigned char *tools_read_binary(const char *rel, size_t max, size_t *len, const char **err, char *clean, size_t clean_cap);
// Scrive un file (anche binario) nella cartella di lavoro. false con err se il percorso non vale o la scrittura fallisce.
bool tools_write_binary(const char *rel, const void *data, size_t n, const char **err);
// Internet: tools_web_init va chiamata all'avvio (cerca mind/web_tool.py e Python a partire dalla cartella corrente).
void  tools_web_init(void);
bool  tools_web_available(void);
// op "cerca" (arg = domanda, extra = numero di risultati) o "leggi" (arg = indirizzo, extra = caratteri). Da liberare.
char *tools_web(const char *op, const char *arg, int extra, bool *ok);