C API — use Kineti from code

Each release includes libkineti and include/kineti.h on GitHub. Works from C, Python (ctypes/cffi), and other hosts. Run all calls with your project folder as the current folder.

01HEADER CONTRACT

#include "kineti.h"   /* grab kineti.h from the Release assets */

typedef struct KinetiResult {
    bool ok;            /* false => payload holds the error text  */
    char *payload;      /* JSON on success, error text on failure */
} KinetiResult;

const char *kineti_version(void);                 /* static storage — do NOT free */
void        kineti_free_string(char *ptr);        /* NULL is a no-op */
KinetiResult kineti_run    (const char *args_json);
KinetiResult kineti_verify (const char *args_json);
KinetiResult kineti_receipt(const char *args_json);

02MEMORY CONTRACT

Input text: Ends with a zero byte, UTF-8. You own it. Kineti does not free it.
Output text: You own it once returned. Free it once with kineti_free_string(). NULL means out of memory.
Errors: Failures come back as ok=false with an error string. No crash crosses the border.
One run at a time: Do not run two kineti_run() calls at the same time in one process.

03EXAMPLE

KinetiResult r = kineti_run("{\"goal\":\"create hello.txt\",",
                             "\"provider\":\"gemini\"}");
/* r.ok ? JSON payload : error text */
KinetiResult v = kineti_verify("{\"all\":true}");
KinetiResult q = kineti_receipt(NULL);
kineti_free_string(r.payload); kineti_free_string(v.payload);
kineti_free_string(q.payload);

04ARGS AND RESULTS

kineti_run args: {goal*, provider?, model?, cap?, mode? ("single"|"swarm"), auto_approve_spec?} — auto_approve_spec=true lets the calling program approve the spec. This is logged as "ffi auto-approval". On ok, you get: {"exit","stage_reached","spec_approved","shipped_at"}.

kineti_verify: {"all": bool}. all=false → {"ok","records","head"}; all=true → also "branches":[{branch,records,head}], "orphans":[…], "errors":[…]. If the log was changed, you get ok=false with error text.

kineti_receipt: result has spend (main/workers/total), gates steps, dag state, egress tags, and clean_files_violations.

05PYTHON QUICKSTART

from ctypes import CDLL, c_char_p, c_bool, Structure, POINTER
class R(Structure): _fields_ = [("ok", c_bool), ("payload", c_char_p)]
k = CDLL("./libkineti.so"); k.kineti_run.restype = R
r = k.kineti_run(b'{"goal":"create hello.txt"}')
print(r.payload.decode())