agent-kernel 0.1.0

/**
 * agent_kernel.h — C bindings for agent-kernel v0.1.0
 *
 * Minimal FFI surface exposing three functions:
 *   agent_kernel_version()      — query the library version
 *   agent_kernel_free()         — release memory allocated by this library
 *   agent_kernel_discuss_sync() — synchronous multi-agent discussion
 *
 * Build:
 *   Link against libagent_kernel_ffi.dylib (macOS) or libagent_kernel_ffi.so (Linux).
 *   Add the directory containing this header to your include path.
 *
 * Minimal usage example:
 *
 *   #include "agent_kernel.h"
 *   #include <stdio.h>
 *
 *   int main(void) {
 *       printf("agent-kernel %s\n", agent_kernel_version());
 *
 *       char *result = agent_kernel_discuss_sync("What is Rust?", 2);
 *       if (result) {
 *           printf("summary: %s\n", result);
 *           agent_kernel_free(result);
 *       }
 *       return 0;
 *   }
 */

#ifndef AGENT_KERNEL_H
#define AGENT_KERNEL_H

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Returns the agent-kernel version string (e.g. "0.1.0").
 *
 * The returned pointer is a static C string owned by the library.
 * It is valid for the entire lifetime of the process.
 * DO NOT pass this pointer to `agent_kernel_free`.
 */
const char *agent_kernel_version(void);

/**
 * Frees a C string that was returned by `agent_kernel_discuss_sync`.
 *
 * Passing NULL is a safe no-op.
 *
 * SAFETY: `ptr` must have been returned by `agent_kernel_discuss_sync`.
 * Passing any other pointer (including the value from `agent_kernel_version`)
 * is undefined behaviour.
 */
void agent_kernel_free(char *ptr);

/**
 * Runs a synchronous multi-agent discussion and returns the summary.
 *
 * Internally creates a Tokio runtime, constructs a single demo agent
 * with a no-op LLM backend, and calls the kernel's `discuss()` primitive
 * for `rounds` rounds.  This demonstrates the full FFI surface without
 * requiring a real LLM provider; the agent returns empty strings.
 *
 * @param topic   UTF-8 encoded, null-terminated topic string.  Must not be NULL.
 * @param rounds  Number of discussion rounds (capped internally at 20).
 *
 * @return  A heap-allocated, null-terminated C string containing the discussion
 *          summary (the primary agent's last response).
 *          The caller MUST free it with `agent_kernel_free`.
 *          Returns NULL on error or if `topic` is NULL.
 */
char *agent_kernel_discuss_sync(const char *topic, size_t rounds);

#ifdef __cplusplus
}
#endif

#endif /* AGENT_KERNEL_H */