summaryrefslogtreecommitdiff
path: root/libpanto-lua
diff options
context:
space:
mode:
Diffstat (limited to 'libpanto-lua')
-rw-r--r--libpanto-lua/build.zig143
-rw-r--r--libpanto-lua/build.zig.zon26
-rw-r--r--libpanto-lua/libpanto-lua-0.0.0-1.rockspec63
-rw-r--r--libpanto-lua/src/module.zig2275
4 files changed, 2507 insertions, 0 deletions
diff --git a/libpanto-lua/build.zig b/libpanto-lua/build.zig
new file mode 100644
index 0000000..8bfaf88
--- /dev/null
+++ b/libpanto-lua/build.zig
@@ -0,0 +1,143 @@
+const std = @import("std");
+
+/// `libpanto-lua` — a native Lua 5.4 C-module implemented in pure Zig.
+///
+/// Emits a loadable `panto.so` (no `lib` prefix) exporting `luaopen_panto`,
+/// discovered on `package.cpath` and loaded by `require('panto')`. The
+/// module `@cImport`s the Lua 5.4 headers and calls the Zig `libpanto` API
+/// directly — no C translation units in this package, no dependency on
+/// `libpanto-c`.
+///
+/// Targets Lua 5.4 only (see `docs/libpanto-bindings.md`). A Lua C-module
+/// does not link the Lua library: the host interpreter supplies every
+/// `lua_*` symbol at load time, so we link only against the headers and
+/// resolve the symbols via dynamic lookup at runtime.
+pub fn build(b: *std.Build) void {
+ const target = b.standardTargetOptions(.{});
+ const optimize = b.standardOptimizeOption(.{});
+
+ const panto_dep = b.dependency("panto", .{
+ .target = target,
+ .optimize = optimize,
+ });
+ const lua_src = b.dependency("lua_src", .{});
+
+ const mod = b.createModule(.{
+ .root_source_file = b.path("src/module.zig"),
+ .target = target,
+ .optimize = optimize,
+ .link_libc = true,
+ });
+ mod.addImport("panto", panto_dep.module("panto"));
+ // Lua headers for `@cImport`. Headers only — see the note above.
+ mod.addIncludePath(lua_src.path("src"));
+
+ const lib = b.addLibrary(.{
+ .name = "panto",
+ .root_module = mod,
+ .linkage = .dynamic,
+ });
+ // Lua modules export a fixed-name init function; keep it in the
+ // dynamic symbol table so the host's `require` can find it.
+ lib.rdynamic = true;
+ // The `lua_*` / `luaL_*` symbols are provided by the host
+ // interpreter at `dlopen` time, not by this module. Allow them to be
+ // left undefined at link time and resolved dynamically when loaded.
+ allowUndefinedHostSymbols(lib, target);
+
+ // Register the Compile step as a named artifact so dependents (the
+ // panto CLI build) can address it via `dep.artifact("panto")` to embed
+ // the compiled `.so`. This installs `libpanto.so`/`libpanto.dylib`
+ // under the default `lib/` name; the bare-name staging below produces
+ // the `panto.so` a Lua `require` needs.
+ b.installArtifact(lib);
+
+ // A Lua C-module must be named exactly `panto.so` (no `lib` prefix,
+ // no version suffix) to be found as `require('panto')` on `cpath`.
+ // `addLibrary` produces `libpanto.so` (or `.dylib`); install it under
+ // the bare module name into `lib/`.
+ const install_so = b.addInstallFileWithDir(
+ lib.getEmittedBin(),
+ .lib,
+ "panto.so",
+ );
+ b.getInstallStep().dependOn(&install_so.step);
+
+ // Unit tests. The test binary is an ordinary executable that links a
+ // real Lua so the C symbols resolve; we compile the Lua sources into
+ // it directly (see `addLuaForTests`).
+ const test_mod = b.createModule(.{
+ .root_source_file = b.path("src/module.zig"),
+ .target = target,
+ .optimize = optimize,
+ .link_libc = true,
+ });
+ test_mod.addImport("panto", panto_dep.module("panto"));
+ test_mod.addIncludePath(lua_src.path("src"));
+ addLuaForTests(test_mod, lua_src);
+
+ const unit_tests = b.addTest(.{
+ .name = "panto-lua-tests",
+ .root_module = test_mod,
+ });
+ const run_unit_tests = b.addRunArtifact(unit_tests);
+ const test_step = b.step("test", "Run unit tests");
+ test_step.dependOn(&run_unit_tests.step);
+}
+
+/// On macOS the linker rejects undefined symbols by default; a Lua
+/// C-module relies on the host interpreter to provide every `lua_*`
+/// symbol at `dlopen` time. Pass the flag that defers resolution to load
+/// time. On ELF (Linux/BSD) shared objects already allow undefined
+/// symbols resolved by the loader, so nothing is needed.
+fn allowUndefinedHostSymbols(
+ lib: *std.Build.Step.Compile,
+ target: std.Build.ResolvedTarget,
+) void {
+ switch (target.result.os.tag) {
+ .macos => {
+ lib.linker_allow_shlib_undefined = true;
+ lib.root_module.addCMacro("LUA_USE_MACOSX", "");
+ },
+ .linux => lib.root_module.addCMacro("LUA_USE_LINUX", ""),
+ .freebsd, .netbsd, .openbsd => lib.root_module.addCMacro("LUA_USE_POSIX", ""),
+ else => {},
+ }
+}
+
+/// The Lua source files needed to compile a self-contained Lua into the
+/// test binary so the `lua_*` symbols resolve (the standalone `.so`
+/// borrows them from a host instead). This is the same `core + lib + aux`
+/// set the CLI compiles, minus `lua.c`/`luac.c` (the standalone front
+/// ends, which carry their own `main`).
+const lua_files = [_][]const u8{
+ // core
+ "lapi.c", "lcode.c", "lctype.c", "ldebug.c", "ldo.c",
+ "ldump.c", "lfunc.c", "lgc.c", "llex.c", "lmem.c",
+ "lobject.c", "lopcodes.c", "lparser.c", "lstate.c", "lstring.c",
+ "ltable.c", "ltm.c", "lundump.c", "lvm.c", "lzio.c",
+ // lib
+ "lauxlib.c", "lbaselib.c", "lcorolib.c", "ldblib.c", "liolib.c",
+ "lmathlib.c", "loadlib.c", "loslib.c", "lstrlib.c", "ltablib.c",
+ "lutf8lib.c", "linit.c",
+};
+
+fn addLuaForTests(mod: *std.Build.Module, lua_src: *std.Build.Dependency) void {
+ const cflags = [_][]const u8{
+ "-std=gnu99",
+ "-Wall",
+ "-Wextra",
+ "-Wno-unused-parameter",
+ };
+ mod.addCSourceFiles(.{
+ .root = lua_src.path("src"),
+ .files = &lua_files,
+ .flags = &cflags,
+ });
+ switch (mod.resolved_target.?.result.os.tag) {
+ .macos => mod.addCMacro("LUA_USE_MACOSX", ""),
+ .linux => mod.addCMacro("LUA_USE_LINUX", ""),
+ .freebsd, .netbsd, .openbsd => mod.addCMacro("LUA_USE_POSIX", ""),
+ else => {},
+ }
+}
diff --git a/libpanto-lua/build.zig.zon b/libpanto-lua/build.zig.zon
new file mode 100644
index 0000000..d685c13
--- /dev/null
+++ b/libpanto-lua/build.zig.zon
@@ -0,0 +1,26 @@
+.{
+ .fingerprint = 0xe0ed1e60c285f54f,
+ .name = .panto_lua,
+ .version = "0.0.0",
+ .dependencies = .{
+ .panto = .{
+ .path = "../libpanto",
+ },
+ // Lua 5.4 source — used only for its headers (`lua.h`,
+ // `lauxlib.h`, `lualib.h`) at `@cImport` time. A Lua C-module
+ // does NOT link the Lua library: the host interpreter provides
+ // every `lua_*`/`luaL_*` symbol at `dlopen` time, resolved via
+ // dynamic lookup. We pin the same tarball the CLI uses so the
+ // standalone module and the embedded VM build against identical
+ // 5.4 headers.
+ .lua_src = .{
+ .url = "https://www.lua.org/ftp/lua-5.4.7.tar.gz",
+ .hash = "N-V-__8AAIMvFABt-Qcpk24RD10ldEN743D8Q2e19Er8x3dJ",
+ },
+ },
+ .paths = .{
+ "build.zig",
+ "build.zig.zon",
+ "src",
+ },
+}
diff --git a/libpanto-lua/libpanto-lua-0.0.0-1.rockspec b/libpanto-lua/libpanto-lua-0.0.0-1.rockspec
new file mode 100644
index 0000000..c14353f
--- /dev/null
+++ b/libpanto-lua/libpanto-lua-0.0.0-1.rockspec
@@ -0,0 +1,63 @@
+-- LuaRocks rockspec for `libpanto-lua`: the native Lua 5.4 binding for
+-- libpanto, built in pure Zig.
+--
+-- Distribution model (see docs/libpanto-bindings.md): this is the *source*
+-- rock — universal, buildable on any OS/arch that has a Zig toolchain.
+-- LuaRocks prefers a matching pre-built `.PLATFORM.rock` when one is
+-- published and falls back to building this source rock otherwise (the
+-- pip "wheel-or-sdist" model). Pre-built binary rocks per platform are a
+-- later step; no rockspec change is needed to add them.
+--
+-- Build: `build.type = "command"` shells out to `zig build` (so the build
+-- dependency is Zig, declared informally below since LuaRocks can't fetch
+-- a compiler), then stages the emitted `panto.so` into `$(LIBDIR)` as the
+-- bare module name `panto` — discovered by `require('panto')` on cpath.
+
+rockspec_format = "3.0"
+package = "libpanto-lua"
+version = "0.0.0-1"
+
+source = {
+ url = "git+https://github.com/earendil-works/pantograph.git",
+ -- The module lives in the `libpanto-lua/` subdirectory of the repo.
+ dir = "pantograph/libpanto-lua",
+}
+
+description = {
+ summary = "Native Lua 5.4 bindings for libpanto (pure Zig).",
+ detailed = [[
+ A loadable Lua 5.4 C-module exposing libpanto's agent + pull-stream
+ API. require('panto') yields panto.agent{...}; an Agent runs turns
+ that stream Events, registers Lua tool handlers (driven by libuv via
+ luv), swaps provider config, manages the system prompt, and compacts.
+ Implemented entirely in Zig (no C translation units); the .so is
+ emitted by `zig build`.
+ ]],
+ homepage = "https://github.com/earendil-works/pantograph",
+ license = "MIT",
+ labels = { "ai", "llm", "agent", "libpanto" },
+}
+
+-- Lua 5.4 only (Lua has no stable ABI across minor versions; a module
+-- built for 5.4 will not load in 5.3 or 5.5). `luv` is required for tool
+-- dispatch: tool handlers run as coroutines driven by `uv.run`.
+dependencies = {
+ "lua >= 5.4, < 5.5",
+ "luv",
+}
+
+-- Zig is required at build time. LuaRocks has no notion of a Zig toolchain
+-- dependency, so this is enforced by the build_command failing loudly if
+-- `zig` is absent rather than by a declared dependency.
+
+build = {
+ type = "command",
+ -- Build the shared object. `zig build` reads ./build.zig and emits
+ -- zig-out/lib/panto.so (see build.zig: the install step renames the
+ -- artifact to the bare `panto.so` a Lua C-module requires).
+ build_command = "zig build -Doptimize=ReleaseFast",
+ -- Stage the emitted module into LuaRocks' library dir under the bare
+ -- name `panto` so `require('panto')` resolves it on cpath. $(LIBDIR)
+ -- is substituted by LuaRocks at install time.
+ install_command = "cp zig-out/lib/panto.so $(LIBDIR)/panto.so",
+}
diff --git a/libpanto-lua/src/module.zig b/libpanto-lua/src/module.zig
new file mode 100644
index 0000000..7f7f838
--- /dev/null
+++ b/libpanto-lua/src/module.zig
@@ -0,0 +1,2275 @@
+//! `libpanto-lua` — a native Lua 5.4 C-module for `libpanto`, in pure Zig.
+//!
+//! This file `@cImport`s the Lua 5.4 C headers and builds the module table
+//! plus two `luaL_newmetatable` userdata types — `Agent` and `Stream` —
+//! against the translated C types, calling the **Zig** `libpanto` API
+//! directly (no `libpanto-c` dependency, no C translation units). The
+//! `build.zig` emits a loadable `panto.so` exporting `luaopen_panto`,
+//! discovered on `package.cpath` and loaded by `require('panto')`.
+//!
+//! The unifying streaming contract (see `docs/libpanto-bindings.md`) maps
+//! onto Lua exactly like Python — Lua is a pull-iterator language too:
+//!
+//! | layer | progress / terminal | exhausted | failure |
+//! | ----- | --------------------- | ------------- | ----------------------- |
+//! | Lua | event table (yielded) | iterator ends | error(...) / pcall false |
+//!
+//! - `Event` -> push the event as a Lua table and return it.
+//! - `null` -> return `nil`, ending the `for` loop.
+//! - `error.X` -> `lua_error` with a mapped message, catchable via `pcall`.
+//!
+//! ## The surface
+//!
+//! local panto = require('panto')
+//! local agent = panto.agent {
+//! api_style = "openai_chat", -- or "anthropic_messages"
+//! api_key = "...",
+//! base_url = "https://...",
+//! model = "...",
+//! max_tokens = 64000, -- optional
+//! reasoning = "medium", -- optional (openai_chat)
+//! thinking = "enabled", -- optional (anthropic_messages)
+//! -- ...see config.zig parsing below for the complete set...
+//! }
+//!
+//! agent:register_tool { -- give the model a tool
+//! name = "...", description = "...",
+//! schema = { type = "object", ... },
+//! handler = function(input) ... return "result" end,
+//! }
+//!
+//! agent:set_config { ... } -- swap provider/model/policy
+//! agent:add_system_message("...") -- append to the system prompt
+//! agent:set_system_prompt("...") -- replace it
+//! agent:compact() -- summarize older turns
+//! print(agent:session_id())
+//!
+//! for ev in agent:run("hello"):events() do
+//! if ev.type == "content_delta" then io.write(ev.delta) end
+//! end
+//!
+//! ## Tools, coroutines, and luv
+//!
+//! Tool handlers run as Lua coroutines driven by libuv (via the `luv`
+//! rock, a hard dependency of this package). The contract mirrors the CLI
+//! runtime exactly: a handler may block **only** by yielding on a pending
+//! libuv operation whose callback resumes it, so a single
+//! `uv.run("default")` pass guarantees every handler has finished. A
+//! purely synchronous handler runs to completion on its first resume and
+//! needs no event loop.
+//!
+//! libpanto delivers every Lua-tool call for a turn in one `invoke_batch`
+//! on a single thread (the source-grouped dispatch contract); that thread
+//! is *not* the host thread, but the host thread is parked inside
+//! `Stream.next()` for the whole batch, so only one thread ever touches
+//! the `lua_State` at a time. We start one coroutine per call and drive
+//! `uv.run` to completion.
+//!
+//! ## Lua-version pinning
+//!
+//! Lua has no stable ABI; this module is built against 5.4 headers and the
+//! `luaL_checkversion` call in `luaopen_panto` makes a wrong-version load
+//! fail loud. 5.3/5.2/5.1(LuaJIT)/5.5 are out of scope for v1.
+
+const std = @import("std");
+const panto = @import("panto");
+
+pub const c = @cImport({
+ @cInclude("lua.h");
+ @cInclude("lauxlib.h");
+ @cInclude("lualib.h");
+});
+
+// translate_c surfaces Lua's `#define`d type tags as inline functions that
+// aren't usable as comptime constants in switch prongs; mirror the
+// canonical 5.4 values as clean `c_int`s.
+const T_NIL: c_int = 0;
+const T_BOOLEAN: c_int = 1;
+const T_NUMBER: c_int = 3;
+const T_STRING: c_int = 4;
+const T_TABLE: c_int = 5;
+const T_FUNCTION: c_int = 6;
+
+// LUAI_MAXSTACK defaults to 1_000_000 on 64-bit, so the registry pseudo-
+// index is -1_001_000 (matches lua.h). Parity with `src/lua_bridge.zig`.
+const LUA_REGISTRYINDEX: c_int = -1001000;
+
+const c_allocator = std.heap.c_allocator;
+
+const SOURCE_NAME = "panto-lua";
+
+// ===========================================================================
+// Process-global I/O context
+// ===========================================================================
+//
+// `libpanto` needs a process-global HTTP client (`panto.init`) and a
+// `std.Io` to drive blocking provider reads. A standalone Lua interpreter
+// has no `std.process.Init`, so we own a `std.Io.Threaded` here and
+// initialize it lazily on first `panto.agent{}`, tearing it down when the
+// last Agent is collected. Single-interpreter assumption: a standalone
+// `require('panto')` runs in one `lua_State` and the embedded CLI VM is
+// single-threaded; we do not guard the refcount with an atomic.
+
+const IoContext = struct {
+ threaded: std.Io.Threaded,
+ io: std.Io,
+ agent_refs: usize = 0,
+ initialized: bool = false,
+};
+
+var io_ctx: IoContext = .{ .threaded = undefined, .io = undefined };
+
+fn retainIo() void {
+ if (!io_ctx.initialized) {
+ io_ctx.threaded = .init(c_allocator, .{});
+ io_ctx.io = io_ctx.threaded.io();
+ panto.init(c_allocator, io_ctx.io);
+ io_ctx.initialized = true;
+ }
+ io_ctx.agent_refs += 1;
+}
+
+fn releaseIo() void {
+ if (io_ctx.agent_refs == 0) return;
+ io_ctx.agent_refs -= 1;
+ if (io_ctx.agent_refs == 0 and io_ctx.initialized) {
+ panto.deinit();
+ io_ctx.threaded.deinit();
+ io_ctx.initialized = false;
+ }
+}
+
+// ===========================================================================
+// Userdata payloads
+// ===========================================================================
+
+const AGENT_MT = "panto.Agent";
+const STREAM_MT = "panto.Stream";
+const CONV_MT = "panto.Conversation";
+
+/// Boxed `*Agent` userdata.
+///
+/// `libpanto` borrows `*const Config`, so we own the live `Config` and
+/// every string it points at, kept alive for the agent's lifetime. A
+/// `set_config` swap pins a *new* config without freeing the old one
+/// eagerly: an in-flight turn (or a concurrent tool worker) may still be
+/// reading the old snapshot, so old configs and their strings accumulate
+/// in `string_arena`/`old_configs` and are freed together at agent
+/// teardown. (Bounded by the number of `set_config` calls — a tiny,
+/// deliberate retain-until-deinit.)
+///
+/// A `NullStore` is embedded so a standalone consumer needs no session
+/// wiring; the store is borrowed by the agent and must outlive it, so it
+/// lives in the same box.
+///
+/// The Lua tool source is created lazily on the first `register_tool` and
+/// registered with the agent then.
+const AgentBox = struct {
+ agent: *panto.Agent,
+ /// The live config the agent reads. Heap-pinned so `set_config` can
+ /// swap the pointee the agent holds without moving this box.
+ config: *panto.Config,
+ /// Superseded configs, freed at teardown (see the struct doc).
+ old_configs: std.ArrayList(*panto.Config),
+ store_impl: panto.NullStore,
+ /// Arena owning every config string (api_key/base_url/model/prompt…)
+ /// across the live config and all superseded ones. Freed at teardown.
+ string_arena: std.heap.ArenaAllocator,
+ /// The lazily-created Lua tool source (null until first register_tool).
+ tools: ?*LuaToolSource,
+ closed: bool = false,
+
+ fn deinit(self: *AgentBox, L: *c.lua_State) void {
+ if (self.closed) return;
+ self.closed = true;
+ // Tear down the agent first (it borrows config + store + source).
+ self.agent.deinit();
+ if (self.tools) |ts| ts.deinit(L);
+ // Free the live config + every superseded one. Their string bytes
+ // live in `string_arena`, freed in one shot below.
+ c_allocator.destroy(self.config);
+ for (self.old_configs.items) |cfg| c_allocator.destroy(cfg);
+ self.old_configs.deinit(c_allocator);
+ self.string_arena.deinit();
+ releaseIo();
+ }
+};
+
+/// Boxed `*Stream` userdata. Holds a Lua reference to the owning Agent
+/// userdata so the Agent cannot be GC'd while a live Stream still borrows
+/// its conversation + config.
+const StreamBox = struct {
+ stream: *panto.Stream,
+ agent_ref: c_int,
+ closed: bool = false,
+
+ fn deinit(self: *StreamBox, L: *c.lua_State) void {
+ if (self.closed) return;
+ self.closed = true;
+ self.stream.deinit();
+ if (self.agent_ref != c.LUA_NOREF) {
+ c.luaL_unref(L, LUA_REGISTRYINDEX, self.agent_ref);
+ self.agent_ref = c.LUA_NOREF;
+ }
+ }
+};
+
+/// Boxed `Conversation` userdata. The same userdata type serves three
+/// ownership states, because `libpanto`'s `Conversation` is both a
+/// standalone buildable value and the agent's live transparent field:
+///
+/// - `.owned`: built by `panto.conversation()`; this box owns `inner`
+/// and frees it at `__gc`. Can be handed to `panto.agent{conversation=}`,
+/// which moves ownership to the agent and flips this box to `.adopted`.
+/// - `.adopted`: ownership moved into an `Agent`; the box is inert —
+/// `__gc` frees nothing and methods raise. (The agent now owns it.)
+/// - `.borrowed`: a live view returned by `agent:conversation()`. It
+/// points at the agent's `*Agent.conversation` field; `__gc` frees
+/// nothing. A Lua ref pins the owning agent so the view can't dangle.
+///
+/// `view` is the pointer methods operate through: for `.owned` it is
+/// `&self.inner`; for `.borrowed` it is `&agent.conversation`.
+const ConvBox = struct {
+ state: enum { owned, adopted, borrowed },
+ /// Storage for an owned conversation. Unused (undefined) when borrowed.
+ inner: panto.Conversation,
+ /// The conversation methods act on. Always valid while usable.
+ view: *panto.Conversation,
+ /// For `.borrowed`: a ref pinning the owning Agent userdata. NOREF
+ /// otherwise.
+ agent_ref: c_int = c.LUA_NOREF,
+
+ fn deinit(self: *ConvBox, L: *c.lua_State) void {
+ switch (self.state) {
+ .owned => self.inner.deinit(),
+ .adopted => {}, // the agent owns and frees it
+ .borrowed => {
+ if (self.agent_ref != c.LUA_NOREF) {
+ c.luaL_unref(L, LUA_REGISTRYINDEX, self.agent_ref);
+ self.agent_ref = c.LUA_NOREF;
+ }
+ },
+ }
+ }
+};
+
+// ===========================================================================
+// Module entry point
+// ===========================================================================
+
+/// `luaopen_panto` — the fixed-name init function the Lua loader calls.
+/// Builds and returns a **fresh** module table on every call (standard
+/// C-module behavior; never a process-shared singleton — the CLI relies on
+/// this to safely attach its `ext` field to its own copy).
+pub export fn luaopen_panto(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ // Fail loud if loaded into a wrong-version host (the wrong-ABI guard).
+ c.luaL_checkversion(L);
+
+ registerMetatables(L);
+
+ c.lua_createtable(L, 0, 3);
+ c.lua_pushcclosure(L, agentNew, 0);
+ c.lua_setfield(L, -2, "agent");
+ c.lua_pushcclosure(L, conversationNew, 0);
+ c.lua_setfield(L, -2, "conversation");
+ _ = c.lua_pushstring(L, "libpanto-lua 0.0.0 (Lua 5.4)");
+ c.lua_setfield(L, -2, "_VERSION");
+ return 1;
+}
+
+fn registerMetatables(L: *c.lua_State) void {
+ if (c.luaL_newmetatable(L, AGENT_MT) != 0) {
+ c.lua_createtable(L, 0, 6); // methods
+ setMethod(L, "run", agentRun);
+ setMethod(L, "register_tool", agentRegisterTool);
+ setMethod(L, "set_config", agentSetConfig);
+ setMethod(L, "add_system_message", agentAddSystemMessage);
+ setMethod(L, "set_system_prompt", agentSetSystemPrompt);
+ setMethod(L, "compact", agentCompact);
+ setMethod(L, "session_id", agentSessionId);
+ setMethod(L, "conversation", agentConversation);
+ // Internal/unstable: drive a tool batch directly, bypassing a live
+ // provider, so the luv-coroutine dispatch path is testable without
+ // a real turn. Not part of the public surface.
+ setMethod(L, "_dispatch_tools", agentDispatchTools);
+ c.lua_setfield(L, -2, "__index");
+ setMethod(L, "__gc", agentGc);
+ }
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+
+ if (c.luaL_newmetatable(L, STREAM_MT) != 0) {
+ c.lua_createtable(L, 0, 2); // methods
+ setMethod(L, "next", streamNext);
+ setMethod(L, "events", streamEvents);
+ c.lua_setfield(L, -2, "__index");
+ setMethod(L, "__gc", streamGc);
+ }
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+
+ if (c.luaL_newmetatable(L, CONV_MT) != 0) {
+ c.lua_createtable(L, 0, 9); // methods
+ setMethod(L, "add_system_message", convAddSystemMessage);
+ setMethod(L, "replace_system_message", convReplaceSystemMessage);
+ setMethod(L, "add_user_message", convAddUserMessage);
+ setMethod(L, "add_user_blocks", convAddUserBlocks);
+ setMethod(L, "add_assistant_message", convAddAssistantMessage);
+ setMethod(L, "add_compaction_summary", convAddCompactionSummary);
+ setMethod(L, "messages", convMessages);
+ setMethod(L, "len", convLen);
+ c.lua_setfield(L, -2, "__index");
+ setMethod(L, "__len", convLen);
+ setMethod(L, "__gc", convGc);
+ }
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+}
+
+fn setMethod(L: *c.lua_State, name: [:0]const u8, f: c.lua_CFunction) void {
+ c.lua_pushcclosure(L, f, 0);
+ c.lua_setfield(L, -2, name.ptr);
+}
+
+// ===========================================================================
+// panto.agent { ... } -> Agent userdata
+// ===========================================================================
+
+fn agentNew(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ c.luaL_checktype(L, 1, T_TABLE);
+
+ const ud = c.lua_newuserdatauv(L, @sizeOf(AgentBox), 0) orelse
+ return luaErr(L, "panto.agent: out of memory");
+ const box: *AgentBox = @ptrCast(@alignCast(ud));
+ box.* = .{
+ .agent = undefined,
+ .config = undefined,
+ .old_configs = .empty,
+ .store_impl = undefined,
+ .string_arena = std.heap.ArenaAllocator.init(c_allocator),
+ .tools = null,
+ .closed = false,
+ };
+
+ buildAgent(L, box) catch |err| {
+ box.string_arena.deinit();
+ box.old_configs.deinit(c_allocator);
+ return luaErr(L, configErrorMessage(err, "panto.agent"));
+ };
+
+ _ = c.luaL_setmetatable(L, AGENT_MT);
+ return 1;
+}
+
+fn buildAgent(L: *c.lua_State, box: *AgentBox) ConfigError!void {
+ const cfg = try c_allocator.create(panto.Config);
+ errdefer c_allocator.destroy(cfg);
+ cfg.* = try parseConfig(L, 1, box.string_arena.allocator());
+
+ // Optional `conversation = <panto.conversation()>`: adopt it for
+ // resumption. The userdata must be an `.owned` Conversation; on
+ // success its inner is moved into the agent and the box flips to
+ // `.adopted`. We resolve the ConvBox pointer here but only consume it
+ // *after* `Agent.init` succeeds, so a failed init leaves the caller's
+ // conversation owned and intact.
+ var adopt_box: ?*ConvBox = null;
+ {
+ const t = c.lua_getfield(L, 1, "conversation");
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t != T_NIL) {
+ const ud = c.luaL_testudata(L, -1, CONV_MT) orelse return error.BadField;
+ const cb: *ConvBox = @ptrCast(@alignCast(ud));
+ if (cb.state != .owned) return error.ConversationNotOwned;
+ adopt_box = cb;
+ }
+ }
+
+ retainIo();
+ errdefer releaseIo();
+
+ box.config = cfg;
+ box.store_impl = panto.NullStore.init(c_allocator);
+ box.agent = panto.Agent.init(
+ c_allocator,
+ io_ctx.io,
+ box.config,
+ box.store_impl.store().create(),
+ if (adopt_box) |cb| cb.inner else null,
+ ) catch return error.AgentInit;
+
+ // Ownership of the inner conversation moved into the agent; neuter the
+ // source box so its `__gc` won't double-free.
+ if (adopt_box) |cb| {
+ cb.state = .adopted;
+ cb.view = &box.agent.conversation;
+ }
+}
+
+/// `agent:set_config{...}` — swap the active provider/model/policy. Takes
+/// effect at the next turn boundary (libpanto re-reads the snapshot each
+/// turn). The new config is parsed with the *same* parser as construction,
+/// so the two argument shapes are identical by construction. The old
+/// config is retained (not freed) until agent teardown, since an in-flight
+/// turn may still read it.
+fn agentSetConfig(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+ c.luaL_checktype(L, 2, T_TABLE);
+
+ const new_cfg = c_allocator.create(panto.Config) catch
+ return luaErr(L, "panto: out of memory");
+ new_cfg.* = parseConfig(L, 2, box.string_arena.allocator()) catch |err| {
+ c_allocator.destroy(new_cfg);
+ return luaErr(L, configErrorMessage(err, "set_config"));
+ };
+
+ // Retain the prior config so an in-flight turn keeps a valid snapshot.
+ box.old_configs.append(c_allocator, box.config) catch {
+ c_allocator.destroy(new_cfg);
+ return luaErr(L, "panto: out of memory");
+ };
+ box.config = new_cfg;
+ box.agent.setConfig(new_cfg);
+ return 0;
+}
+
+fn agentAddSystemMessage(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+ var len: usize = 0;
+ const ptr = c.luaL_checklstring(L, 2, &len);
+ box.agent.addSystemMessage(ptr[0..len]) catch
+ return luaErr(L, "panto: failed to add system message");
+ return 0;
+}
+
+fn agentSetSystemPrompt(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+ var len: usize = 0;
+ const ptr = c.luaL_checklstring(L, 2, &len);
+ box.agent.setSystemPrompt(ptr[0..len]) catch
+ return luaErr(L, "panto: failed to set system prompt");
+ return 0;
+}
+
+/// `agent:compact([override_prompt[, extra_instructions]])` -> table.
+/// Returns `{ compacted=, kept_turns=, summarized_messages= }`. Both
+/// arguments are optional strings; nil falls back to the configured
+/// compaction prompt. Errors (e.g. no compaction prompt configured)
+/// surface as a Lua error.
+fn agentCompact(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+
+ const override = optArgString(L, 2);
+ const extra = optArgString(L, 3);
+
+ const res = box.agent.compact(override, extra) catch |err| {
+ return switch (err) {
+ error.NoCompactionPrompt => luaErr(L, "panto: no compaction prompt configured (set compaction.prompt in the config)"),
+ else => luaErr(L, "panto: compaction failed"),
+ };
+ };
+
+ c.lua_createtable(L, 0, 3);
+ c.lua_pushboolean(L, if (res.compacted) 1 else 0);
+ c.lua_setfield(L, -2, "compacted");
+ setIntField(L, "kept_turns", @intCast(res.kept_turns));
+ setIntField(L, "summarized_messages", @intCast(res.summarized_messages));
+ return 1;
+}
+
+fn agentSessionId(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+ const id = box.agent.sessionId();
+ _ = c.lua_pushlstring(L, id.ptr, id.len);
+ return 1;
+}
+
+/// `agent:conversation()` -> a **borrowed** Conversation view of the
+/// agent's live `conversation` field. Mutations and reads go straight
+/// through to the agent's conversation (the transparent-field semantics of
+/// the Zig API). The view pins the agent (a Lua ref) so it cannot dangle,
+/// and frees nothing at `__gc`.
+fn agentConversation(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+
+ const ud = c.lua_newuserdatauv(L, @sizeOf(ConvBox), 0) orelse
+ return luaErr(L, "panto: out of memory");
+ const cb: *ConvBox = @ptrCast(@alignCast(ud));
+ cb.* = .{
+ .state = .borrowed,
+ .inner = undefined,
+ .view = &box.agent.conversation,
+ .agent_ref = c.LUA_NOREF,
+ };
+ _ = c.luaL_setmetatable(L, CONV_MT);
+
+ // Pin the agent so the borrowed view can't outlive it.
+ c.lua_pushvalue(L, 1);
+ cb.agent_ref = c.luaL_ref(L, LUA_REGISTRYINDEX);
+ return 1;
+}
+
+fn agentRun(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+
+ var len: usize = 0;
+ const ptr = c.luaL_checklstring(L, 2, &len);
+
+ const stream = box.agent.run(.{ .text = ptr[0..len] }) catch
+ return luaErr(L, "panto: failed to start turn");
+
+ const ud = c.lua_newuserdatauv(L, @sizeOf(StreamBox), 0) orelse {
+ stream.deinit();
+ return luaErr(L, "panto: out of memory");
+ };
+ const sbox: *StreamBox = @ptrCast(@alignCast(ud));
+ sbox.* = .{ .stream = stream, .agent_ref = c.LUA_NOREF, .closed = false };
+ _ = c.luaL_setmetatable(L, STREAM_MT);
+
+ // Pin the agent so it outlives the stream.
+ c.lua_pushvalue(L, 1);
+ sbox.agent_ref = c.luaL_ref(L, LUA_REGISTRYINDEX);
+ return 1;
+}
+
+fn agentGc(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ box.deinit(L);
+ return 0;
+}
+
+// ===========================================================================
+// panto.conversation() -> Conversation userdata
+// ===========================================================================
+
+/// Build a fresh, standalone (`.owned`) `Conversation`. Hand it to
+/// `panto.agent { conversation = <conv> }` to resume against a
+/// pre-built history; ownership transfers to the agent at that point.
+fn conversationNew(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const ud = c.lua_newuserdatauv(L, @sizeOf(ConvBox), 0) orelse
+ return luaErr(L, "panto.conversation: out of memory");
+ const cb: *ConvBox = @ptrCast(@alignCast(ud));
+ cb.* = .{
+ .state = .owned,
+ .inner = panto.Conversation.init(c_allocator),
+ .view = undefined,
+ .agent_ref = c.LUA_NOREF,
+ };
+ cb.view = &cb.inner;
+ _ = c.luaL_setmetatable(L, CONV_MT);
+ return 1;
+}
+
+fn checkConv(L: *c.lua_State, idx: c_int) *ConvBox {
+ return @ptrCast(@alignCast(c.luaL_checkudata(L, idx, CONV_MT)));
+}
+
+/// Resolve the usable `*Conversation` for a method, or raise if the box was
+/// adopted (the agent owns it now — operate through `agent:conversation()`).
+fn convView(L: *c.lua_State, cb: *ConvBox) ?*panto.Conversation {
+ if (cb.state == .adopted) {
+ _ = luaErr(L, "panto: this conversation was adopted by an agent; use agent:conversation() to operate on it");
+ return null;
+ }
+ return cb.view;
+}
+
+fn convAddSystemMessage(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ const conv = convView(L, cb) orelse return 0;
+ var len: usize = 0;
+ const ptr = c.luaL_checklstring(L, 2, &len);
+ conv.addSystemMessage(ptr[0..len]) catch return luaErr(L, "panto: out of memory");
+ return 0;
+}
+
+fn convReplaceSystemMessage(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ const conv = convView(L, cb) orelse return 0;
+ var len: usize = 0;
+ const ptr = c.luaL_checklstring(L, 2, &len);
+ conv.replaceSystemMessage(ptr[0..len]) catch return luaErr(L, "panto: out of memory");
+ return 0;
+}
+
+/// `conv:add_user_message(text)` — the ergonomic single-text case. The
+/// general block-slice form is `conv:add_user_blocks{...}`.
+fn convAddUserMessage(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ const conv = convView(L, cb) orelse return 0;
+ var len: usize = 0;
+ const ptr = c.luaL_checklstring(L, 2, &len);
+ const tb = panto.textualBlockFromSlice(conv.allocator, ptr[0..len]) catch
+ return luaErr(L, "panto: out of memory");
+ var block: panto.ContentBlock = .{ .Text = tb };
+ conv.addUserMessage(&.{block}) catch {
+ block.deinit(conv.allocator);
+ return luaErr(L, "panto: out of memory");
+ };
+ return 0;
+}
+
+fn convAddCompactionSummary(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ const conv = convView(L, cb) orelse return 0;
+ var len: usize = 0;
+ const ptr = c.luaL_checklstring(L, 2, &len);
+ conv.addCompactionSummary(ptr[0..len]) catch return luaErr(L, "panto: out of memory");
+ return 0;
+}
+
+/// `conv:add_user_blocks{ <block>, ... }` — the general user-message
+/// builder, symmetric with `add_assistant_message`. Each block is a table
+/// `{ type = "text"|"tool_result", ... }`. Lets a Lua app reconstruct full
+/// user turns from serialized state: plain/queued text plus tool results.
+fn convAddUserBlocks(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ const conv = convView(L, cb) orelse return 0;
+ c.luaL_checktype(L, 2, T_TABLE);
+ addMessageFromBlocks(L, conv, 2, .user) catch |e| return luaErr(L, blockErrorMessage(e));
+ return 0;
+}
+
+/// `conv:add_assistant_message{ blocks = { <block>, ... }, usage = {...} }`
+/// — reconstruct an assistant turn: `text`, `thinking`, and `tool_use`
+/// blocks, plus optional provider `usage`. Together with `add_user_blocks`
+/// this makes a serialize→rebuild cycle lossless for tool-using turns.
+fn convAddAssistantMessage(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ const conv = convView(L, cb) orelse return 0;
+ c.luaL_checktype(L, 2, T_TABLE);
+
+ // Accept either `{ blocks = {...}, usage = ? }` or a bare block array.
+ const bt = c.lua_getfield(L, 2, "blocks");
+ const blocks_idx: c_int = if (bt == T_TABLE) c.lua_gettop(L) else blk: {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ break :blk 2;
+ };
+ const has_wrapper = bt == T_TABLE;
+ defer if (has_wrapper) c.lua_settop(L, c.lua_gettop(L) - 1);
+
+ const usage = parseUsage(L, 2) catch |e| return luaErr(L, blockErrorMessage(e));
+ addAssistantFromBlocks(L, conv, blocks_idx, usage) catch |e| return luaErr(L, blockErrorMessage(e));
+ return 0;
+}
+
+const BlockError = error{ BadBlock, UnknownBlockType, OutOfMemory };
+
+fn blockErrorMessage(e: BlockError) [:0]const u8 {
+ return switch (e) {
+ error.BadBlock => "panto: malformed content block (check field names/types)",
+ error.UnknownBlockType => "panto: unknown block type (want text/thinking/tool_use/tool_result)",
+ error.OutOfMemory => "panto: out of memory",
+ };
+}
+
+/// Build a `[]ContentBlock` from the Lua array at `arr_idx`, then hand it
+/// to the conversation (user or compaction-style role via addUserMessage).
+fn addMessageFromBlocks(L: *c.lua_State, conv: *panto.Conversation, arr_idx: c_int, comptime role: enum { user }) BlockError!void {
+ _ = role;
+ var blocks: std.ArrayList(panto.ContentBlock) = .empty;
+ defer blocks.deinit(c_allocator);
+ errdefer for (blocks.items) |*b| b.deinit(conv.allocator);
+
+ try collectBlocks(L, conv.allocator, arr_idx, &blocks);
+ conv.addUserMessage(blocks.items) catch return error.OutOfMemory;
+ // Ownership transferred; clear so errdefer/deinit don't double-free.
+ blocks.clearRetainingCapacity();
+}
+
+fn addAssistantFromBlocks(L: *c.lua_State, conv: *panto.Conversation, arr_idx: c_int, usage: ?panto.Usage) BlockError!void {
+ var blocks: std.ArrayList(panto.ContentBlock) = .empty;
+ defer blocks.deinit(c_allocator);
+ errdefer for (blocks.items) |*b| b.deinit(conv.allocator);
+
+ try collectBlocks(L, conv.allocator, arr_idx, &blocks);
+ conv.addAssistantMessage(blocks.items, usage) catch return error.OutOfMemory;
+ blocks.clearRetainingCapacity();
+}
+
+/// Walk the Lua array at `arr_idx`, append one `ContentBlock` per entry to
+/// `out`. Bytes are owned by `alloc` (the conversation's allocator). On
+/// error the caller frees whatever was appended.
+fn collectBlocks(L: *c.lua_State, alloc: std.mem.Allocator, arr_idx: c_int, out: *std.ArrayList(panto.ContentBlock)) BlockError!void {
+ const abs = c.lua_absindex(L, arr_idx);
+ const n: usize = @intCast(c.lua_rawlen(L, abs));
+ var i: usize = 1;
+ while (i <= n) : (i += 1) {
+ _ = c.lua_rawgeti(L, abs, @intCast(i));
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (c.lua_type(L, -1) != T_TABLE) return error.BadBlock;
+ const block = try buildContentBlock(L, alloc, c.lua_gettop(L));
+ out.append(c_allocator, block) catch {
+ var b = block;
+ b.deinit(alloc);
+ return error.OutOfMemory;
+ };
+ }
+}
+
+/// Construct a single `ContentBlock` from the table at `idx`. Every owned
+/// byte is allocated with `alloc` so the conversation can free it.
+fn buildContentBlock(L: *c.lua_State, alloc: std.mem.Allocator, idx: c_int) BlockError!panto.ContentBlock {
+ const type_str = blockField(L, idx, "type") orelse return error.BadBlock;
+
+ if (std.mem.eql(u8, type_str, "text")) {
+ const text = blockField(L, idx, "text") orelse return error.BadBlock;
+ const tb = panto.textualBlockFromSlice(alloc, text) catch return error.OutOfMemory;
+ return .{ .Text = tb };
+ } else if (std.mem.eql(u8, type_str, "thinking")) {
+ const text = blockField(L, idx, "text") orelse "";
+ var tb = panto.textualBlockFromSlice(alloc, text) catch return error.OutOfMemory;
+ errdefer tb.deinit(alloc);
+ const sig: ?[]const u8 = if (blockField(L, idx, "signature")) |s|
+ (alloc.dupe(u8, s) catch return error.OutOfMemory)
+ else
+ null;
+ return .{ .Thinking = .{ .text = tb, .signature = sig } };
+ } else if (std.mem.eql(u8, type_str, "tool_use")) {
+ const id = blockField(L, idx, "id") orelse return error.BadBlock;
+ const name = blockField(L, idx, "name") orelse return error.BadBlock;
+ const input = blockField(L, idx, "input") orelse "";
+ const id_owned = alloc.dupe(u8, id) catch return error.OutOfMemory;
+ errdefer alloc.free(id_owned);
+ const name_owned = alloc.dupe(u8, name) catch return error.OutOfMemory;
+ errdefer alloc.free(name_owned);
+ const input_tb = panto.textualBlockFromSlice(alloc, input) catch return error.OutOfMemory;
+ return .{ .ToolUse = .{ .id = id_owned, .name = name_owned, .input = input_tb } };
+ } else if (std.mem.eql(u8, type_str, "tool_result")) {
+ return buildToolResultBlock(L, alloc, idx);
+ }
+ return error.UnknownBlockType;
+}
+
+fn buildToolResultBlock(L: *c.lua_State, alloc: std.mem.Allocator, idx: c_int) BlockError!panto.ContentBlock {
+ const tuid = blockField(L, idx, "tool_use_id") orelse return error.BadBlock;
+ const tuid_owned = alloc.dupe(u8, tuid) catch return error.OutOfMemory;
+ errdefer alloc.free(tuid_owned);
+
+ const is_error: bool = blk: {
+ const t = c.lua_getfield(L, idx, "is_error");
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ break :blk (t == T_BOOLEAN and c.lua_toboolean(L, -1) != 0);
+ };
+
+ var parts: std.ArrayList(panto.ResultPartStored) = .empty;
+ errdefer {
+ for (parts.items) |*p| p.deinit(alloc);
+ parts.deinit(alloc);
+ }
+
+ const pt = c.lua_getfield(L, idx, "parts");
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (pt == T_TABLE) {
+ const pn: usize = @intCast(c.lua_rawlen(L, -1));
+ var i: usize = 1;
+ while (i <= pn) : (i += 1) {
+ _ = c.lua_rawgeti(L, -1, @intCast(i));
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (c.lua_type(L, -1) != T_TABLE) return error.BadBlock;
+ const part = try buildStoredPart(L, alloc, c.lua_gettop(L));
+ parts.append(alloc, part) catch {
+ var p = part;
+ p.deinit(alloc);
+ return error.OutOfMemory;
+ };
+ }
+ } else if (pt != T_NIL) {
+ return error.BadBlock;
+ }
+
+ return .{ .ToolResult = .{ .tool_use_id = tuid_owned, .parts = parts, .is_error = is_error } };
+}
+
+/// A stored result part: `{ text = "..." }` or `{ media_type = "...",
+/// data = "<base64>" }`. Media `data` is the already-encoded bytes (this
+/// is resumption of *stored* state, not raw tool output).
+fn buildStoredPart(L: *c.lua_State, alloc: std.mem.Allocator, idx: c_int) BlockError!panto.ResultPartStored {
+ if (blockField(L, idx, "text")) |t| {
+ const tb = panto.textualBlockFromSlice(alloc, t) catch return error.OutOfMemory;
+ return .{ .text = tb };
+ }
+ const media_type = blockField(L, idx, "media_type") orelse return error.BadBlock;
+ const data = blockField(L, idx, "data") orelse return error.BadBlock;
+ const mt_owned = alloc.dupe(u8, media_type) catch return error.OutOfMemory;
+ errdefer alloc.free(mt_owned);
+ const data_tb = panto.textualBlockFromSlice(alloc, data) catch return error.OutOfMemory;
+ return .{ .media = .{ .media_type = mt_owned, .data = data_tb } };
+}
+
+/// Read string field `name` from the table at `idx`, returning a borrowed
+/// slice valid until the field value is popped. We pop immediately (Lua
+/// keeps the string alive as long as it's referenced by the table), so the
+/// returned slice stays valid for the synchronous dupe that follows.
+fn blockField(L: *c.lua_State, idx: c_int, name: [*:0]const u8) ?[]const u8 {
+ const t = c.lua_getfield(L, idx, name);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t != T_STRING) return null;
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, -1, &len);
+ if (ptr == null) return null;
+ return ptr[0..len];
+}
+
+fn parseUsage(L: *c.lua_State, tbl_idx: c_int) BlockError!?panto.Usage {
+ const t = c.lua_getfield(L, tbl_idx, "usage");
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return null;
+ if (t != T_TABLE) return error.BadBlock;
+ const sub = c.lua_gettop(L);
+ return panto.Usage{
+ .input = usageField(L, sub, "input"),
+ .output = usageField(L, sub, "output"),
+ .cache_read = usageField(L, sub, "cache_read"),
+ .cache_write = usageField(L, sub, "cache_write"),
+ .reasoning = usageField(L, sub, "reasoning"),
+ };
+}
+
+fn usageField(L: *c.lua_State, tbl_idx: c_int, name: [*:0]const u8) u64 {
+ const t = c.lua_getfield(L, tbl_idx, name);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t != T_NUMBER) return 0;
+ const v = c.lua_tointegerx(L, -1, null);
+ return if (v < 0) 0 else @intCast(v);
+}
+
+fn convLen(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ const conv = convView(L, cb) orelse return 0;
+ c.lua_pushinteger(L, @intCast(conv.messages.items.len));
+ return 1;
+}
+
+/// `conv:messages()` -> array of `{ role=, blocks={ {type=, ...} } }`.
+/// A read-only inspection snapshot: bytes are copied into Lua, so the
+/// returned tables are independent of later conversation mutation.
+fn convMessages(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ const conv = convView(L, cb) orelse return 0;
+
+ const msgs = conv.messages.items;
+ c.lua_createtable(L, @intCast(msgs.len), 0);
+ for (msgs, 0..) |msg, mi| {
+ c.lua_createtable(L, 0, 3);
+ setStringField(L, "role", roleName(msg.role));
+ if (msg.usage) |u| pushUsage(L, u); // emits a `usage` field
+ // blocks = { ... } — faithful per-block detail for lossless
+ // round-trip: each block table is shaped to be fed straight back
+ // into add_user_blocks / add_assistant_message.
+ c.lua_createtable(L, @intCast(msg.content.items.len), 0);
+ for (msg.content.items, 0..) |block, bi| {
+ pushInspectBlock(L, block);
+ c.lua_rawseti(L, -2, @intCast(bi + 1));
+ }
+ c.lua_setfield(L, -2, "blocks");
+ c.lua_rawseti(L, -2, @intCast(mi + 1));
+ }
+ return 1;
+}
+
+/// Push a fully-detailed block table (leaves it on the stack top). The
+/// shape mirrors exactly what `add_user_blocks`/`add_assistant_message`
+/// accept, so `conv:messages()` output can be replayed verbatim. The block
+/// `type` strings here match `buildContentBlock`'s expectations.
+fn pushInspectBlock(L: *c.lua_State, block: panto.ContentBlock) void {
+ c.lua_createtable(L, 0, 4);
+ switch (block) {
+ .Text => |t| {
+ setStringField(L, "type", "text");
+ setStringField(L, "text", t.items);
+ },
+ .Thinking => |t| {
+ setStringField(L, "type", "thinking");
+ setStringField(L, "text", t.text.items);
+ if (t.signature) |s| setStringField(L, "signature", s);
+ },
+ .ToolUse => |tu| {
+ setStringField(L, "type", "tool_use");
+ setStringField(L, "id", tu.id);
+ setStringField(L, "name", tu.name);
+ setStringField(L, "input", tu.input.items);
+ },
+ .ToolResult => |tr| {
+ setStringField(L, "type", "tool_result");
+ setStringField(L, "tool_use_id", tr.tool_use_id);
+ c.lua_pushboolean(L, if (tr.is_error) 1 else 0);
+ c.lua_setfield(L, -2, "is_error");
+ c.lua_createtable(L, @intCast(tr.parts.items.len), 0);
+ for (tr.parts.items, 0..) |part, pi| {
+ c.lua_createtable(L, 0, 2);
+ switch (part) {
+ .text => |t| setStringField(L, "text", t.items),
+ .media => |m| {
+ setStringField(L, "media_type", m.media_type);
+ setStringField(L, "data", m.data.items);
+ },
+ }
+ c.lua_rawseti(L, -2, @intCast(pi + 1));
+ }
+ c.lua_setfield(L, -2, "parts");
+ },
+ .System => |s| {
+ setStringField(L, "type", "system");
+ setStringField(L, "text", s.text.items);
+ setStringField(L, "mode", switch (s.mode) {
+ .append => "append",
+ .replace => "replace",
+ });
+ },
+ .CompactionSummary => |s| {
+ setStringField(L, "type", "compaction_summary");
+ setStringField(L, "text", s.text.items);
+ },
+ }
+}
+
+fn convGc(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const cb = checkConv(L, 1);
+ cb.deinit(L);
+ return 0;
+}
+
+// ===========================================================================
+// Config parsing (shared by panto.agent{} and agent:set_config{})
+// ===========================================================================
+
+const ConfigError = error{
+ MissingField,
+ BadField,
+ UnknownApiStyle,
+ BadEnum,
+ ConversationNotOwned,
+ OutOfMemory,
+ AgentInit,
+};
+
+fn configErrorMessage(err: ConfigError, comptime ctx: [:0]const u8) [:0]const u8 {
+ return switch (err) {
+ error.MissingField => ctx ++ ": missing required field (need api_style, api_key, base_url, model)",
+ error.BadField => ctx ++ ": a field has the wrong type",
+ error.UnknownApiStyle => ctx ++ ": api_style must be 'openai_chat' or 'anthropic_messages'",
+ error.BadEnum => ctx ++ ": an enum field has an unrecognized value",
+ error.ConversationNotOwned => ctx ++ ": the `conversation` was already adopted by an agent or is a borrowed view; build a fresh one with panto.conversation()",
+ error.OutOfMemory => ctx ++ ": out of memory",
+ error.AgentInit => ctx ++ ": failed to initialize agent",
+ };
+}
+
+/// Parse a full `panto.Config` from the named-args table at `tbl_idx`.
+/// Every string is duped into `arena` (owned by the AgentBox for the
+/// config's lifetime). This is the single source of truth for both
+/// construction and `set_config`, so the two argument shapes never drift.
+///
+/// Provider fields (all required): `api_style`, `api_key`, `base_url`,
+/// `model`. Common optional: `max_tokens`.
+/// openai_chat optional: `reasoning`.
+/// anthropic_messages optional: `api_version`, `thinking`, `effort`,
+/// `thinking_budget_tokens`, `thinking_interleaved`.
+/// Optional `compaction = { keep_verbatim=, prompt= }`.
+/// Optional `retry = { max_attempts=, initial_delay_ms=, max_delay_ms=,
+/// multiplier=, jitter= }`.
+fn parseConfig(L: *c.lua_State, tbl_idx: c_int, arena: std.mem.Allocator) ConfigError!panto.Config {
+ const api_style = try requiredString(L, tbl_idx, "api_style");
+ const api_key = try dupArena(arena, try requiredString(L, tbl_idx, "api_key"));
+ const base_url = try dupArena(arena, try requiredString(L, tbl_idx, "base_url"));
+ const model = try dupArena(arena, try requiredString(L, tbl_idx, "model"));
+ const max_tokens = try optU32(L, tbl_idx, "max_tokens");
+
+ var provider: panto.ProviderConfig = undefined;
+ if (std.mem.eql(u8, api_style, "openai_chat")) {
+ var p: panto.OpenAIChatConfig = .{ .api_key = api_key, .base_url = base_url, .model = model };
+ if (max_tokens) |mt| p.max_tokens = mt;
+ if (try optString(L, tbl_idx, "reasoning")) |r|
+ p.reasoning = parseEnum(panto.ReasoningEffort, r) orelse return error.BadEnum;
+ provider = .{ .openai_chat = p };
+ } else if (std.mem.eql(u8, api_style, "anthropic_messages")) {
+ var p: panto.AnthropicMessagesConfig = .{ .api_key = api_key, .base_url = base_url, .model = model };
+ if (max_tokens) |mt| p.max_tokens = mt;
+ if (try optString(L, tbl_idx, "api_version")) |v| p.api_version = try dupArena(arena, v);
+ if (try optString(L, tbl_idx, "thinking")) |t|
+ p.thinking = parseEnum(panto.Thinking, t) orelse return error.BadEnum;
+ if (try optString(L, tbl_idx, "effort")) |e|
+ p.effort = parseEnum(panto.Effort, e) orelse return error.BadEnum;
+ if (try optU32(L, tbl_idx, "thinking_budget_tokens")) |b| p.thinking_budget_tokens = b;
+ if (try optBool(L, tbl_idx, "thinking_interleaved")) |i| p.thinking_interleaved = i;
+ provider = .{ .anthropic_messages = p };
+ } else {
+ return error.UnknownApiStyle;
+ }
+
+ var config: panto.Config = .{ .provider = provider };
+ try parseCompaction(L, tbl_idx, arena, &config.compaction);
+ try parseRetry(L, tbl_idx, &config.retry);
+ return config;
+}
+
+fn parseCompaction(
+ L: *c.lua_State,
+ tbl_idx: c_int,
+ arena: std.mem.Allocator,
+ out: *panto.CompactionConfig,
+) ConfigError!void {
+ const t = c.lua_getfield(L, tbl_idx, "compaction");
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return;
+ if (t != T_TABLE) return error.BadField;
+ const sub = c.lua_gettop(L);
+ if (try optU32(L, sub, "keep_verbatim")) |k| out.keep_verbatim = k;
+ if (try optString(L, sub, "prompt")) |p| out.compaction_prompt = try dupArena(arena, p);
+ // Note: a nested compaction `model` override is intentionally omitted
+ // for v1 — it would require recursively parsing a second provider
+ // block; the active model is used for compaction unless added later.
+}
+
+fn parseRetry(L: *c.lua_State, tbl_idx: c_int, out: *panto.RetryConfig) ConfigError!void {
+ const t = c.lua_getfield(L, tbl_idx, "retry");
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return;
+ if (t != T_TABLE) return error.BadField;
+ const sub = c.lua_gettop(L);
+ if (try optU32(L, sub, "max_attempts")) |v| out.max_attempts = v;
+ if (try optU64(L, sub, "initial_delay_ms")) |v| out.initial_delay_ms = v;
+ if (try optU64(L, sub, "max_delay_ms")) |v| out.max_delay_ms = v;
+ if (try optNumber(L, sub, "multiplier")) |v| out.multiplier = v;
+ if (try optBool(L, sub, "jitter")) |v| out.jitter = v;
+}
+
+fn parseEnum(comptime E: type, s: []const u8) ?E {
+ inline for (@typeInfo(E).@"enum".fields) |f| {
+ if (std.mem.eql(u8, s, f.name)) return @enumFromInt(f.value);
+ }
+ return null;
+}
+
+fn dupArena(arena: std.mem.Allocator, s: []const u8) ConfigError![]const u8 {
+ return arena.dupe(u8, s) catch error.OutOfMemory;
+}
+
+// ===========================================================================
+// Lua tool source: luv-driven cooperative coroutines
+// ===========================================================================
+//
+// Ported from the CLI's `src/lua_runtime.zig` scheduler, operating on the
+// host `lua_State` passed to `luaopen_panto`. Each registered tool stores
+// its handler in the Lua registry (`luaL_ref`). On `invoke_batch` we run
+// each call as a coroutine through a wrapper that `pcall`s the handler and
+// reports the result via a registered `_record_result` C closure, then
+// drive `uv.run("default")` to completion. Synchronous handlers finish on
+// their first resume; async handlers yield on a libuv op and are resumed
+// by its callback.
+
+/// One coroutine's outcome, written by `recordResult` and read after the
+/// event loop drains.
+const Slot = struct {
+ recorded: bool = false,
+ ok: bool = false,
+ value: ?panto.ResultParts = null,
+ err_msg: ?[]u8 = null,
+};
+
+const BatchState = struct {
+ allocator: std.mem.Allocator,
+ slots: []Slot,
+};
+
+const LuaToolSource = struct {
+ L: *c.lua_State,
+ /// Tool decls handed to libpanto (borrowed strings live in `arena`).
+ decls: std.ArrayList(panto.ToolDecl),
+ /// name -> handler registry ref.
+ handlers: std.StringHashMap(c_int),
+ /// Owns every decl string + handler-name key.
+ arena: std.heap.ArenaAllocator,
+ /// Wrapper closure ref: pcall(handler,input) -> _record_result(...).
+ wrapper_ref: c_int = c.LUA_NOREF,
+ /// Cached `require("luv").run`.
+ uv_run_ref: c_int = c.LUA_NOREF,
+ /// In-flight batch, valid only during one `invoke_batch`.
+ current_batch: ?*BatchState = null,
+ /// True once the source has been handed to the agent.
+ registered: bool = false,
+
+ fn create(L: *c.lua_State) !*LuaToolSource {
+ const self = try c_allocator.create(LuaToolSource);
+ self.* = .{
+ .L = L,
+ .decls = .empty,
+ .handlers = std.StringHashMap(c_int).init(c_allocator),
+ .arena = std.heap.ArenaAllocator.init(c_allocator),
+ };
+ return self;
+ }
+
+ fn deinit(self: *LuaToolSource, L: *c.lua_State) void {
+ var it = self.handlers.iterator();
+ while (it.next()) |e| c.luaL_unref(L, LUA_REGISTRYINDEX, e.value_ptr.*);
+ self.handlers.deinit();
+ if (self.wrapper_ref != c.LUA_NOREF) c.luaL_unref(L, LUA_REGISTRYINDEX, self.wrapper_ref);
+ if (self.uv_run_ref != c.LUA_NOREF) c.luaL_unref(L, LUA_REGISTRYINDEX, self.uv_run_ref);
+ self.decls.deinit(c_allocator);
+ self.arena.deinit();
+ c_allocator.destroy(self);
+ }
+
+ fn toolSource(self: *LuaToolSource) panto.ToolSource {
+ return .{
+ .name = SOURCE_NAME,
+ .tools = self.decls.items,
+ .ctx = self,
+ .vtable = &source_vtable,
+ };
+ }
+
+ /// Lazily build the wrapper closure + cache `uv.run`. Requires `luv`
+ /// to be `require`-able in the host (a hard package dependency).
+ fn ensureScheduler(self: *LuaToolSource) !void {
+ if (self.wrapper_ref != c.LUA_NOREF) return;
+ const L = self.L;
+
+ // Register `_record_result` as a C closure carrying `self`, and
+ // build the wrapper that closes over it. We keep them in a private
+ // table referenced only by the wrapper, so we never touch the
+ // module table (which is the host's, possibly augmented, copy).
+ const snippet =
+ \\local record = ...
+ \\return function(idx, handler, input)
+ \\ local ok, val = pcall(handler, input)
+ \\ record(idx, ok, val)
+ \\end
+ ;
+ if (c.luaL_loadstring(L, snippet) != 0) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.LuaInitFailed;
+ }
+ c.lua_pushlightuserdata(L, @ptrCast(self));
+ c.lua_pushcclosure(L, recordResultC, 1); // the `record` arg
+ if (c.lua_pcallk(L, 1, 1, 0, 0, null) != 0) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.LuaInitFailed;
+ }
+ self.wrapper_ref = c.luaL_ref(L, LUA_REGISTRYINDEX);
+
+ // Cache uv.run.
+ const uv_snippet =
+ \\return require("luv").run
+ ;
+ if (c.luaL_loadstring(L, uv_snippet) != 0) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.LuaInitFailed;
+ }
+ if (c.lua_pcallk(L, 0, 1, 0, 0, null) != 0) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.LuvMissing;
+ }
+ if (c.lua_type(L, -1) != T_FUNCTION) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.LuvMissing;
+ }
+ self.uv_run_ref = c.luaL_ref(L, LUA_REGISTRYINDEX);
+ }
+};
+
+const source_vtable: panto.ToolSource.VTable = .{
+ .invoke_batch = invokeBatch,
+ .deinit = deinitSrc,
+};
+
+/// The source's `ctx` is owned by the AgentBox (freed in `AgentBox.deinit`
+/// after `agent.deinit`), so libpanto's source teardown is a no-op.
+fn deinitSrc(_: *anyopaque, _: std.mem.Allocator) void {}
+
+/// `agent:register_tool { name=, description=, schema=, handler= }`.
+/// Validates the named-args table, serializes the schema to JSON, refs the
+/// handler, and appends a decl. The first call creates the source and
+/// hands it to the agent; later calls extend the source (visible at the
+/// next turn boundary, per libpanto's registry semantics).
+fn agentRegisterTool(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+ c.luaL_checktype(L, 2, T_TABLE);
+
+ if (box.tools == null) {
+ box.tools = LuaToolSource.create(L) catch
+ return luaErr(L, "panto: out of memory");
+ }
+ const ts = box.tools.?;
+
+ // Make sure luv + the wrapper are ready before we accept any tool, so
+ // a missing `luv` fails at registration (clear) not mid-turn.
+ ts.ensureScheduler() catch |err| {
+ return switch (err) {
+ error.LuvMissing => luaErr(L, "panto: require('luv') failed — libpanto-lua needs the 'luv' rock for tool dispatch"),
+ else => luaErr(L, "panto: failed to initialize the tool scheduler"),
+ };
+ };
+
+ addTool(L, ts, 2) catch |err| {
+ return luaErr(L, configErrorMessage2(err));
+ };
+
+ // Register the source with the agent on first tool.
+ if (!ts.registered) {
+ box.agent.registerToolSource(ts.toolSource()) catch
+ return luaErr(L, "panto: failed to register tool source");
+ ts.registered = true;
+ }
+ return 0;
+}
+
+const ToolError = error{ MissingField, BadField, OutOfMemory };
+
+fn configErrorMessage2(err: ToolError) [:0]const u8 {
+ return switch (err) {
+ error.MissingField => "register_tool: need name (string), description (string), schema (table), handler (function)",
+ error.BadField => "register_tool: a field has the wrong type",
+ error.OutOfMemory => "register_tool: out of memory",
+ };
+}
+
+fn addTool(L: *c.lua_State, ts: *LuaToolSource, tbl_idx: c_int) ToolError!void {
+ const arena = ts.arena.allocator();
+
+ const name = try arenaString(L, tbl_idx, "name", arena);
+ const description = try arenaString(L, tbl_idx, "description", arena);
+
+ // schema (table) -> JSON.
+ const sty = c.lua_getfield(L, tbl_idx, "schema");
+ if (sty != T_TABLE) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.BadField;
+ }
+ const schema_json = serializeSchema(L, c.lua_gettop(L), arena) catch {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.OutOfMemory;
+ };
+ c.lua_settop(L, c.lua_gettop(L) - 1); // pop schema
+
+ // handler (function) -> registry ref. luaL_ref pops it.
+ const hty = c.lua_getfield(L, tbl_idx, "handler");
+ if (hty != T_FUNCTION) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.BadField;
+ }
+ const handler_ref = c.luaL_ref(L, LUA_REGISTRYINDEX);
+
+ ts.handlers.put(name, handler_ref) catch {
+ c.luaL_unref(L, LUA_REGISTRYINDEX, handler_ref);
+ return error.OutOfMemory;
+ };
+ ts.decls.append(c_allocator, .{
+ .name = name,
+ .description = description,
+ .schema_json = schema_json,
+ }) catch {
+ _ = ts.handlers.remove(name);
+ c.luaL_unref(L, LUA_REGISTRYINDEX, handler_ref);
+ return error.OutOfMemory;
+ };
+}
+
+fn arenaString(L: *c.lua_State, tbl_idx: c_int, name: [:0]const u8, arena: std.mem.Allocator) ToolError![]const u8 {
+ const t = c.lua_getfield(L, tbl_idx, name.ptr);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return error.MissingField;
+ if (t != T_STRING) return error.BadField;
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, -1, &len);
+ if (ptr == null) return error.BadField;
+ return arena.dupe(u8, ptr[0..len]) catch error.OutOfMemory;
+}
+
+/// Internal test hook: `agent:_dispatch_tools({ {name=,input=}, ... })`
+/// runs the calls through the real `invoke_batch` (coroutines + luv) and
+/// returns an array of `{ ok=bool, text=string }`. Lets us validate the
+/// dispatch path without a live provider emitting tool calls.
+fn agentDispatchTools(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const box = checkAgent(L, 1);
+ if (box.closed) return luaErr(L, "panto: agent is closed");
+ c.luaL_checktype(L, 2, T_TABLE);
+ const ts = box.tools orelse return luaErr(L, "panto: no tools registered");
+
+ const n: usize = @intCast(c.lua_rawlen(L, 2));
+ var arena_state = std.heap.ArenaAllocator.init(c_allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+
+ const calls = arena.alloc(panto.ToolCall, n) catch return luaErr(L, "panto: oom");
+ var i: usize = 0;
+ while (i < n) : (i += 1) {
+ _ = c.lua_rawgeti(L, 2, @intCast(i + 1));
+ const name = (optTableString(L, -1, "name") catch null) orelse
+ return luaErr(L, "_dispatch_tools: each call needs name + input strings");
+ const name_owned = arena.dupe(u8, name) catch return luaErr(L, "panto: oom");
+ c.lua_settop(L, c.lua_gettop(L) - 1); // pop name value
+ const input = (optTableString(L, -1, "input") catch null) orelse "{}";
+ const input_owned = arena.dupe(u8, input) catch return luaErr(L, "panto: oom");
+ c.lua_settop(L, c.lua_gettop(L) - 1); // pop input value
+ c.lua_settop(L, c.lua_gettop(L) - 1); // pop call table
+ calls[i] = .{ .tool_name = name_owned, .input = input_owned };
+ }
+
+ const results = arena.alloc(panto.ToolCallResult, n) catch return luaErr(L, "panto: oom");
+ invokeBatch(ts, calls, results, arena) catch return luaErr(L, "panto: dispatch failed");
+
+ c.lua_createtable(L, @intCast(n), 0);
+ for (results, 0..) |r, idx| {
+ c.lua_createtable(L, 0, 2);
+ switch (r) {
+ .ok => |parts| {
+ c.lua_pushboolean(L, 1);
+ c.lua_setfield(L, -2, "ok");
+ const text: []const u8 = if (parts.items.len > 0 and parts.items[0] == .text)
+ parts.items[0].text
+ else
+ "";
+ setStringField(L, "text", text);
+ parts.deinit(arena);
+ },
+ .err => {
+ c.lua_pushboolean(L, 0);
+ c.lua_setfield(L, -2, "ok");
+ },
+ }
+ c.lua_rawseti(L, -2, @intCast(idx + 1));
+ }
+ return 1;
+}
+
+fn invokeBatch(
+ ctx: *anyopaque,
+ calls: []const panto.ToolCall,
+ results: []panto.ToolCallResult,
+ allocator: std.mem.Allocator,
+) anyerror!void {
+ const self: *LuaToolSource = @ptrCast(@alignCast(ctx));
+ const L = self.L;
+
+ var slots = try allocator.alloc(Slot, calls.len);
+ defer allocator.free(slots);
+ for (slots) |*s| s.* = .{};
+
+ var batch: BatchState = .{ .allocator = allocator, .slots = slots };
+ self.current_batch = &batch;
+ defer self.current_batch = null;
+
+ var thread_refs = try allocator.alloc(c_int, calls.len);
+ defer allocator.free(thread_refs);
+ @memset(thread_refs, 0);
+ defer for (thread_refs) |r| {
+ if (r != 0) c.luaL_unref(L, LUA_REGISTRYINDEX, r);
+ };
+
+ // Step 1: start every call's coroutine. Sync handlers complete here.
+ var any_pending = false;
+ for (calls, 0..) |call, i| {
+ const handler_ref = self.handlers.get(call.tool_name) orelse {
+ slots[i] = .{ .recorded = true, .ok = false, .err_msg = try allocator.dupe(u8, "unknown tool name") };
+ continue;
+ };
+ const started = startCoroutine(self, i, handler_ref, call.input, allocator) catch {
+ slots[i] = .{ .recorded = true, .ok = false, .err_msg = try allocator.dupe(u8, "failed to start handler coroutine") };
+ continue;
+ };
+ thread_refs[i] = started.thread_ref;
+ if (started.still_pending) any_pending = true;
+ }
+
+ // Step 2: drive libuv to completion (wakes any yielded coroutine).
+ if (any_pending) try driveUvToCompletion(self);
+
+ // Step 3: reap. A still-suspended coroutine violated the contract.
+ for (thread_refs, 0..) |tref, i| {
+ if (tref == 0) continue;
+ _ = c.lua_rawgeti(L, LUA_REGISTRYINDEX, tref);
+ const co: *c.lua_State = @ptrCast(c.lua_tothread(L, -1).?);
+ const status = c.lua_status(co);
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (status == c.LUA_YIELD and !slots[i].recorded) {
+ slots[i] = .{ .recorded = true, .ok = false, .err_msg = try allocator.dupe(
+ u8,
+ "handler still suspended after the event loop drained (yielded without a pending libuv op)",
+ ) };
+ }
+ c.luaL_unref(L, LUA_REGISTRYINDEX, tref);
+ thread_refs[i] = 0;
+ }
+
+ // Step 4: translate slots into libpanto results. A Lua-level failure
+ // is surfaced to the model as a textual `.ok` result rather than a
+ // `.err` (which libpanto treats as turn-aborting) — same policy as the
+ // CLI runtime.
+ for (slots, 0..) |slot, i| {
+ if (slot.ok and slot.value != null) {
+ results[i] = .{ .ok = slot.value.? };
+ if (slot.err_msg) |m| allocator.free(m);
+ } else {
+ if (slot.value) |v| v.deinit(allocator);
+ results[i] = .{ .ok = try formatToolError(
+ allocator,
+ calls[i].tool_name,
+ slot.err_msg orelse "(no message)",
+ ) };
+ if (slot.err_msg) |m| allocator.free(m);
+ }
+ }
+}
+
+fn formatToolError(allocator: std.mem.Allocator, tool_name: []const u8, message: []const u8) !panto.ResultParts {
+ const text = try std.fmt.allocPrint(allocator, "panto-lua: tool '{s}' failed: {s}", .{ tool_name, message });
+ return panto.ResultParts.fromTextOwned(allocator, text);
+}
+
+fn startCoroutine(
+ self: *LuaToolSource,
+ idx: usize,
+ handler_ref: c_int,
+ input: []const u8,
+ allocator: std.mem.Allocator,
+) !struct { thread_ref: c_int, still_pending: bool } {
+ const L = self.L;
+ const co = c.lua_newthread(L) orelse return error.LuaInitFailed;
+ const thread_ref = c.luaL_ref(L, LUA_REGISTRYINDEX);
+
+ _ = c.lua_rawgeti(co, LUA_REGISTRYINDEX, @intCast(self.wrapper_ref));
+ c.lua_pushinteger(co, @intCast(idx));
+ _ = c.lua_rawgeti(co, LUA_REGISTRYINDEX, @intCast(handler_ref));
+ var arena_state = std.heap.ArenaAllocator.init(allocator);
+ defer arena_state.deinit();
+ try pushJsonAsLua(co, arena_state.allocator(), input);
+
+ var nres: c_int = 0;
+ const status = c.lua_resume(co, L, 3, &nres);
+ return .{ .thread_ref = thread_ref, .still_pending = status == c.LUA_YIELD };
+}
+
+fn driveUvToCompletion(self: *LuaToolSource) !void {
+ const L = self.L;
+ _ = c.lua_rawgeti(L, LUA_REGISTRYINDEX, @intCast(self.uv_run_ref));
+ _ = c.lua_pushlstring(L, "default", 7);
+ if (c.lua_pcallk(L, 1, 1, 0, 0, null) != 0) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.UvRunFailed;
+ }
+ c.lua_settop(L, c.lua_gettop(L) - 1); // discard the bool return
+}
+
+/// `_record_result(idx, ok, value)` — carries `*LuaToolSource` as upvalue
+/// 1, writes into the in-flight batch's slot.
+fn recordResultC(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const self_ptr = c.lua_touserdata(L, c.lua_upvalueindex(1)) orelse return 0;
+ const self: *LuaToolSource = @ptrCast(@alignCast(self_ptr));
+ const batch = self.current_batch orelse return 0;
+
+ const idx: usize = @intCast(c.lua_tointegerx(L, 1, null));
+ const ok = c.lua_toboolean(L, 2) != 0;
+ if (idx >= batch.slots.len) return 0;
+
+ if (ok) {
+ const value = readHandlerResult(L, 3, batch.allocator) catch |e| {
+ const msg = std.fmt.allocPrint(batch.allocator, "failed to serialize handler result: {s}", .{@errorName(e)}) catch null;
+ batch.slots[idx] = .{ .recorded = true, .ok = false, .err_msg = msg };
+ return 0;
+ };
+ batch.slots[idx] = .{ .recorded = true, .ok = true, .value = value };
+ } else {
+ var len: usize = 0;
+ const ptr = c.luaL_tolstring(L, 3, &len);
+ const owned = if (ptr != null) batch.allocator.dupe(u8, ptr[0..len]) catch null else null;
+ c.lua_settop(L, c.lua_gettop(L) - 1); // pop tolstring's string
+ batch.slots[idx] = .{ .recorded = true, .ok = false, .err_msg = owned };
+ }
+ return 0;
+}
+
+// ===========================================================================
+// Stream methods
+// ===========================================================================
+
+fn streamNext(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const sbox = checkStream(L, 1);
+ if (sbox.closed) return luaErr(L, "panto: stream is closed");
+
+ const maybe_event = sbox.stream.next() catch
+ return luaErr(L, "panto: stream failed");
+ if (maybe_event) |ev| {
+ pushEvent(L, ev) catch return luaErr(L, "panto: out of memory building event");
+ return 1;
+ }
+ c.lua_pushnil(L);
+ return 1;
+}
+
+/// `stream:events()` -> (iterator, stream, nil): the generic-`for` triple,
+/// so `for ev in stream:events() do ... end` drives `next()`.
+fn streamEvents(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ _ = checkStream(L, 1);
+ c.lua_pushcclosure(L, streamIterStep, 0);
+ c.lua_pushvalue(L, 1);
+ c.lua_pushnil(L);
+ return 3;
+}
+
+fn streamIterStep(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const sbox = checkStream(L, 1);
+ if (sbox.closed) {
+ c.lua_pushnil(L);
+ return 1;
+ }
+ const maybe_event = sbox.stream.next() catch
+ return luaErr(L, "panto: stream failed");
+ if (maybe_event) |ev| {
+ pushEvent(L, ev) catch return luaErr(L, "panto: out of memory building event");
+ return 1;
+ }
+ c.lua_pushnil(L);
+ return 1;
+}
+
+fn streamGc(L_opt: ?*c.lua_State) callconv(.c) c_int {
+ const L = L_opt.?;
+ const sbox = checkStream(L, 1);
+ sbox.deinit(L);
+ return 0;
+}
+
+// ===========================================================================
+// Event -> Lua table marshalling
+// ===========================================================================
+
+fn pushEvent(L: *c.lua_State, ev: panto.Event) !void {
+ c.lua_createtable(L, 0, 4);
+ switch (ev) {
+ .message_start => |role| {
+ setStringField(L, "type", "message_start");
+ setStringField(L, "role", roleName(role));
+ },
+ .block_start => |bs| {
+ setStringField(L, "type", "block_start");
+ setStringField(L, "block_type", blockTypeName(bs.block_type));
+ setIntField(L, "index", @intCast(bs.index));
+ },
+ .tool_details => |td| {
+ setStringField(L, "type", "tool_details");
+ setIntField(L, "index", @intCast(td.index));
+ setStringField(L, "id", td.id);
+ setStringField(L, "name", td.name);
+ },
+ .content_delta => |cd| {
+ setStringField(L, "type", "content_delta");
+ setIntField(L, "index", @intCast(cd.index));
+ setStringField(L, "delta", cd.delta);
+ },
+ .block_complete => |bc| {
+ setStringField(L, "type", "block_complete");
+ setIntField(L, "index", @intCast(bc.index));
+ setStringField(L, "block_type", contentBlockTypeName(bc.block));
+ pushBlockText(L, bc.block);
+ },
+ .message_complete => |mc| {
+ setStringField(L, "type", "message_complete");
+ setStringField(L, "role", roleName(mc.message.role));
+ if (mc.usage) |u| pushUsage(L, u);
+ },
+ .provider_retry => |pr| {
+ setStringField(L, "type", "provider_retry");
+ setIntField(L, "attempt", @intCast(pr.attempt));
+ setIntField(L, "max_attempts", @intCast(pr.max_attempts));
+ setIntField(L, "delay_ms", @intCast(pr.delay_ms));
+ },
+ .tool_dispatch_start => |tds| {
+ setStringField(L, "type", "tool_dispatch_start");
+ setIntField(L, "count", @intCast(tds.count));
+ },
+ .tool_dispatch_complete => setStringField(L, "type", "tool_dispatch_complete"),
+ .turn_complete => setStringField(L, "type", "turn_complete"),
+ }
+}
+
+fn pushBlockText(L: *c.lua_State, block: panto.ContentBlock) void {
+ switch (block) {
+ .Text => |t| setStringField(L, "text", t.items),
+ .Thinking => |t| setStringField(L, "text", t.text.items),
+ .ToolUse => |tu| {
+ setStringField(L, "text", tu.input.items);
+ setStringField(L, "id", tu.id);
+ setStringField(L, "name", tu.name);
+ },
+ .ToolResult => {},
+ .System => |s| setStringField(L, "text", s.text.items),
+ .CompactionSummary => |s| setStringField(L, "text", s.text.items),
+ }
+}
+
+fn pushUsage(L: *c.lua_State, u: panto.Usage) void {
+ c.lua_createtable(L, 0, 5);
+ setIntField(L, "input", @intCast(u.input));
+ setIntField(L, "output", @intCast(u.output));
+ setIntField(L, "cache_read", @intCast(u.cache_read));
+ setIntField(L, "cache_write", @intCast(u.cache_write));
+ setIntField(L, "reasoning", @intCast(u.reasoning));
+ c.lua_setfield(L, -2, "usage");
+}
+
+fn roleName(role: panto.MessageRole) []const u8 {
+ return switch (role) {
+ .system => "system",
+ .user => "user",
+ .assistant => "assistant",
+ };
+}
+
+fn blockTypeName(t: panto.ContentBlockType) []const u8 {
+ return switch (t) {
+ .Text => "text",
+ .Thinking => "thinking",
+ .ToolUse => "tool_use",
+ .ToolResult => "tool_result",
+ };
+}
+
+fn contentBlockTypeName(block: panto.ContentBlock) []const u8 {
+ return switch (block) {
+ .Text => "text",
+ .Thinking => "thinking",
+ .ToolUse => "tool_use",
+ .ToolResult => "tool_result",
+ .System => "system",
+ .CompactionSummary => "compaction_summary",
+ };
+}
+
+// ===========================================================================
+// JSON <-> Lua (ported from src/lua_bridge.zig; standalone copy so this
+// package has no cross-package dependency on the CLI)
+// ===========================================================================
+
+const JsonError = error{ OutOfMemory, BadHandlerReturn, InputNotJsonObject };
+
+/// Parse JSON bytes (must be a top-level object — tool input convention)
+/// and push the value onto `L`.
+fn pushJsonAsLua(L: *c.lua_State, arena: std.mem.Allocator, input: []const u8) !void {
+ var parsed = std.json.parseFromSlice(std.json.Value, arena, input, .{}) catch
+ return JsonError.InputNotJsonObject;
+ defer parsed.deinit();
+ if (parsed.value != .object) return JsonError.InputNotJsonObject;
+ try pushJsonValue(L, parsed.value);
+}
+
+fn pushJsonValue(L: *c.lua_State, v: std.json.Value) !void {
+ switch (v) {
+ .null => c.lua_pushnil(L),
+ .bool => |b| c.lua_pushboolean(L, if (b) 1 else 0),
+ .integer => |i| c.lua_pushinteger(L, @intCast(i)),
+ .float => |f| c.lua_pushnumber(L, f),
+ .number_string => |s| {
+ if (std.fmt.parseInt(c.lua_Integer, s, 10)) |i| {
+ c.lua_pushinteger(L, i);
+ } else |_| {
+ const f = try std.fmt.parseFloat(c.lua_Number, s);
+ c.lua_pushnumber(L, f);
+ }
+ },
+ .string => |s| _ = c.lua_pushlstring(L, s.ptr, s.len),
+ .array => |arr| {
+ c.lua_createtable(L, @intCast(arr.items.len), 0);
+ for (arr.items, 0..) |item, i| {
+ try pushJsonValue(L, item);
+ c.lua_rawseti(L, -2, @intCast(i + 1));
+ }
+ },
+ .object => |obj| {
+ c.lua_createtable(L, 0, @intCast(obj.count()));
+ var it = obj.iterator();
+ while (it.next()) |kv| {
+ const key = kv.key_ptr.*;
+ _ = c.lua_pushlstring(L, key.ptr, key.len);
+ try pushJsonValue(L, kv.value_ptr.*);
+ c.lua_rawset(L, -3);
+ }
+ },
+ }
+}
+
+/// Read a handler's return at `idx` into owned `ResultParts`. A plain
+/// string -> one text part; a table `{ text=, attachments={{media_type=,
+/// data=}} }` -> optional text + one media part per attachment.
+fn readHandlerResult(L: *c.lua_State, idx: c_int, allocator: std.mem.Allocator) !panto.ResultParts {
+ const ty = c.lua_type(L, idx);
+ if (ty == T_STRING) {
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, idx, &len);
+ if (ptr == null) return JsonError.BadHandlerReturn;
+ return panto.ResultParts.fromText(allocator, ptr[0..len]);
+ }
+ if (ty != T_TABLE) {
+ // Coerce other scalars (numbers/bools) via tostring for ergonomics.
+ var len: usize = 0;
+ const ptr = c.luaL_tolstring(L, idx, &len);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (ptr == null) return JsonError.BadHandlerReturn;
+ return panto.ResultParts.fromText(allocator, ptr[0..len]);
+ }
+ return readHandlerResultTable(L, idx, allocator);
+}
+
+fn readHandlerResultTable(L: *c.lua_State, idx: c_int, allocator: std.mem.Allocator) !panto.ResultParts {
+ var parts: std.ArrayList(panto.ResultPart) = .empty;
+ errdefer {
+ for (parts.items) |p| p.deinit(allocator);
+ parts.deinit(allocator);
+ }
+ const abs = c.lua_absindex(L, idx);
+
+ // Optional `text`.
+ if (try optTableString(L, abs, "text")) |s| {
+ const owned = try allocator.dupe(u8, s);
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ errdefer allocator.free(owned);
+ try parts.append(allocator, .{ .text = owned });
+ }
+
+ // Optional `attachments`.
+ const at = c.lua_getfield(L, abs, "attachments");
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (at == T_TABLE) {
+ const n: usize = @intCast(c.lua_rawlen(L, -1));
+ var i: usize = 1;
+ while (i <= n) : (i += 1) {
+ _ = c.lua_rawgeti(L, -1, @intCast(i));
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (c.lua_type(L, -1) != T_TABLE) return JsonError.BadHandlerReturn;
+
+ const media_type: ?[]const u8 = if (try optTableString(L, -1, "media_type")) |mt| blk: {
+ const owned = try allocator.dupe(u8, mt);
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ break :blk owned;
+ } else null;
+ errdefer if (media_type) |mt| allocator.free(mt);
+
+ const data_slice = (try optTableString(L, -1, "data")) orelse return JsonError.BadHandlerReturn;
+ const data = try allocator.dupe(u8, data_slice);
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ errdefer allocator.free(data);
+
+ try parts.append(allocator, .{ .media = .{ .media_type = media_type, .data = data } });
+ }
+ } else if (at != T_NIL) {
+ return JsonError.BadHandlerReturn;
+ }
+
+ const items = try parts.toOwnedSlice(allocator);
+ return .{ .items = items };
+}
+
+/// Read string field `name` from the table at `tbl_idx`. Leaves the value
+/// on the stack (caller pops after copying); null if absent.
+fn optTableString(L: *c.lua_State, tbl_idx: c_int, name: [*:0]const u8) !?[]const u8 {
+ const t = c.lua_getfield(L, tbl_idx, name);
+ if (t == T_NIL) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return null;
+ }
+ if (t != T_STRING) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return JsonError.BadHandlerReturn;
+ }
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, -1, &len);
+ if (ptr == null) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return JsonError.BadHandlerReturn;
+ }
+ return ptr[0..len];
+}
+
+/// Serialize the Lua table at `idx` to a JSON string (arena-owned).
+fn serializeSchema(L: *c.lua_State, idx: c_int, arena: std.mem.Allocator) ![]const u8 {
+ var aw: std.Io.Writer.Allocating = .init(arena);
+ var s: std.json.Stringify = .{ .writer = &aw.writer };
+ try writeLuaValueAsJson(L, idx, &s);
+ return aw.written();
+}
+
+const SchemaJsonError = error{ UnsupportedLuaType, UnsupportedLuaKey, WriteFailed };
+
+fn writeLuaValueAsJson(L: *c.lua_State, idx: c_int, w: *std.json.Stringify) SchemaJsonError!void {
+ switch (c.lua_type(L, idx)) {
+ T_NIL => w.write(null) catch return error.WriteFailed,
+ T_BOOLEAN => w.write(c.lua_toboolean(L, idx) != 0) catch return error.WriteFailed,
+ T_NUMBER => {
+ var isnum: c_int = 0;
+ const as_int = c.lua_tointegerx(L, idx, &isnum);
+ if (isnum != 0)
+ w.write(as_int) catch return error.WriteFailed
+ else
+ w.write(c.lua_tonumberx(L, idx, null)) catch return error.WriteFailed;
+ },
+ T_STRING => {
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, idx, &len);
+ w.write(ptr[0..len]) catch return error.WriteFailed;
+ },
+ T_TABLE => try writeLuaTableAsJson(L, idx, w),
+ else => return error.UnsupportedLuaType,
+ }
+}
+
+fn writeLuaTableAsJson(L: *c.lua_State, idx_in: c_int, w: *std.json.Stringify) SchemaJsonError!void {
+ const abs = c.lua_absindex(L, idx_in);
+ const len = c.lua_rawlen(L, abs);
+ if (len > 0) {
+ w.beginArray() catch return error.WriteFailed;
+ var i: c.lua_Integer = 1;
+ while (i <= @as(c.lua_Integer, @intCast(len))) : (i += 1) {
+ _ = c.lua_rawgeti(L, abs, i);
+ try writeLuaValueAsJson(L, -1, w);
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ }
+ w.endArray() catch return error.WriteFailed;
+ return;
+ }
+ w.beginObject() catch return error.WriteFailed;
+ c.lua_pushnil(L);
+ while (c.lua_next(L, abs) != 0) {
+ if (c.lua_type(L, -2) != T_STRING) {
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ return error.UnsupportedLuaKey;
+ }
+ var klen: usize = 0;
+ const kptr = c.lua_tolstring(L, -2, &klen);
+ w.objectField(kptr[0..klen]) catch return error.WriteFailed;
+ try writeLuaValueAsJson(L, -1, w);
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ }
+ w.endObject() catch return error.WriteFailed;
+}
+
+// ===========================================================================
+// Stack / argument helpers
+// ===========================================================================
+
+fn checkAgent(L: *c.lua_State, idx: c_int) *AgentBox {
+ return @ptrCast(@alignCast(c.luaL_checkudata(L, idx, AGENT_MT)));
+}
+
+fn checkStream(L: *c.lua_State, idx: c_int) *StreamBox {
+ return @ptrCast(@alignCast(c.luaL_checkudata(L, idx, STREAM_MT)));
+}
+
+/// Raise a Lua error with a static message. Never returns (longjmp), typed
+/// `c_int` so callers can `return` it.
+fn luaErr(L: *c.lua_State, msg: [:0]const u8) c_int {
+ _ = c.luaL_error(L, "%s", msg.ptr);
+ return 0;
+}
+
+fn requiredString(L: *c.lua_State, tbl_idx: c_int, name: [:0]const u8) ConfigError![]const u8 {
+ const t = c.lua_getfield(L, tbl_idx, name.ptr);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return error.MissingField;
+ if (t != T_STRING) return error.BadField;
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, -1, &len);
+ if (ptr == null) return error.BadField;
+ return ptr[0..len];
+}
+
+fn optString(L: *c.lua_State, tbl_idx: c_int, name: [:0]const u8) ConfigError!?[]const u8 {
+ const t = c.lua_getfield(L, tbl_idx, name.ptr);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return null;
+ if (t != T_STRING) return error.BadField;
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, -1, &len);
+ if (ptr == null) return error.BadField;
+ return ptr[0..len];
+}
+
+/// An optional positional string argument (for compact's override/extra).
+fn optArgString(L: *c.lua_State, idx: c_int) ?[]const u8 {
+ if (c.lua_type(L, idx) != T_STRING) return null;
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, idx, &len);
+ if (ptr == null) return null;
+ return ptr[0..len];
+}
+
+fn optU32(L: *c.lua_State, tbl_idx: c_int, name: [:0]const u8) ConfigError!?u32 {
+ const v = try optInteger(L, tbl_idx, name) orelse return null;
+ if (v < 0 or v > std.math.maxInt(u32)) return error.BadField;
+ return @intCast(v);
+}
+
+fn optU64(L: *c.lua_State, tbl_idx: c_int, name: [:0]const u8) ConfigError!?u64 {
+ const v = try optInteger(L, tbl_idx, name) orelse return null;
+ if (v < 0) return error.BadField;
+ return @intCast(v);
+}
+
+fn optInteger(L: *c.lua_State, tbl_idx: c_int, name: [:0]const u8) ConfigError!?c.lua_Integer {
+ const t = c.lua_getfield(L, tbl_idx, name.ptr);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return null;
+ if (t != T_NUMBER) return error.BadField;
+ var isnum: c_int = 0;
+ const v = c.lua_tointegerx(L, -1, &isnum);
+ if (isnum == 0) return error.BadField;
+ return v;
+}
+
+fn optNumber(L: *c.lua_State, tbl_idx: c_int, name: [:0]const u8) ConfigError!?f64 {
+ const t = c.lua_getfield(L, tbl_idx, name.ptr);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return null;
+ if (t != T_NUMBER) return error.BadField;
+ return c.lua_tonumberx(L, -1, null);
+}
+
+fn optBool(L: *c.lua_State, tbl_idx: c_int, name: [:0]const u8) ConfigError!?bool {
+ const t = c.lua_getfield(L, tbl_idx, name.ptr);
+ defer c.lua_settop(L, c.lua_gettop(L) - 1);
+ if (t == T_NIL) return null;
+ if (t != T_BOOLEAN) return error.BadField;
+ return c.lua_toboolean(L, -1) != 0;
+}
+
+fn setStringField(L: *c.lua_State, key: [:0]const u8, value: []const u8) void {
+ _ = c.lua_pushlstring(L, value.ptr, value.len);
+ c.lua_setfield(L, -2, key.ptr);
+}
+
+fn setIntField(L: *c.lua_State, key: [:0]const u8, value: c.lua_Integer) void {
+ c.lua_pushinteger(L, value);
+ c.lua_setfield(L, -2, key.ptr);
+}
+
+// ===========================================================================
+// Tests
+// ===========================================================================
+
+const testing = std.testing;
+
+fn newTestState() !*c.lua_State {
+ const L = c.luaL_newstate() orelse return error.LuaInitFailed;
+ c.luaL_openlibs(L);
+ _ = luaopen_panto(L);
+ c.lua_setglobal(L, "panto");
+ return L;
+}
+
+fn runScript(L: *c.lua_State, src: [:0]const u8) !void {
+ if (c.luaL_loadstring(L, src.ptr) != 0 or c.lua_pcallk(L, 0, c.LUA_MULTRET, 0, 0, null) != 0) {
+ var len: usize = 0;
+ const msg = c.lua_tolstring(L, -1, &len);
+ if (msg != null) std.debug.print("lua error: {s}\n", .{msg[0..len]});
+ return error.LuaScriptFailed;
+ }
+}
+
+test "luaopen_panto returns a module table with agent + _VERSION" {
+ const L = c.luaL_newstate() orelse return error.LuaInitFailed;
+ defer c.lua_close(L);
+ c.luaL_openlibs(L);
+
+ try testing.expectEqual(@as(c_int, 1), luaopen_panto(L));
+ try testing.expectEqual(@as(c_int, T_TABLE), c.lua_type(L, -1));
+ _ = c.lua_getfield(L, -1, "agent");
+ try testing.expectEqual(@as(c_int, T_FUNCTION), c.lua_type(L, -1));
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+ _ = c.lua_getfield(L, -1, "_VERSION");
+ try testing.expectEqual(@as(c_int, T_STRING), c.lua_type(L, -1));
+}
+
+test "luaopen_panto returns a FRESH table each call (not a shared singleton)" {
+ const L = c.luaL_newstate() orelse return error.LuaInitFailed;
+ defer c.lua_close(L);
+ c.luaL_openlibs(L);
+
+ _ = luaopen_panto(L);
+ _ = luaopen_panto(L);
+ _ = c.lua_pushstring(L, "marker");
+ c.lua_setfield(L, -2, "_probe");
+ _ = c.lua_getfield(L, -2, "_probe");
+ try testing.expectEqual(@as(c_int, T_NIL), c.lua_type(L, -1));
+}
+
+test "agent: missing required fields raises (caught by pcall)" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local ok, err = pcall(function() return panto.agent { api_style = "openai_chat" } end)
+ \\assert(ok == false and type(err) == "string", "expected failure")
+ \\assert(err:find("panto.agent"), "expected contextual message")
+ );
+}
+
+test "agent: unknown api_style raises" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local ok = pcall(function()
+ \\ return panto.agent { api_style="nope", api_key="k", base_url="u", model="m" }
+ \\end)
+ \\assert(ok == false, "expected unknown api_style to fail")
+ );
+}
+
+test "agent: bad enum value raises" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local ok = pcall(function()
+ \\ return panto.agent {
+ \\ api_style="openai_chat", api_key="k", base_url="u", model="m",
+ \\ reasoning="banana",
+ \\ }
+ \\end)
+ \\assert(ok == false, "expected bad enum to fail")
+ );
+}
+
+test "agent: full config surface parses (anthropic + compaction + retry)" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local a = panto.agent {
+ \\ api_style = "anthropic_messages",
+ \\ api_key = "k", base_url = "http://127.0.0.1:1", model = "m",
+ \\ max_tokens = 1000,
+ \\ thinking = "adaptive", effort = "high",
+ \\ thinking_budget_tokens = 2048, thinking_interleaved = true,
+ \\ api_version = "2023-06-01",
+ \\ compaction = { keep_verbatim = 5000, prompt = "summarize" },
+ \\ retry = { max_attempts = 2, initial_delay_ms = 100, max_delay_ms = 500, multiplier = 1.5, jitter = false },
+ \\}
+ \\assert(type(a) == "userdata")
+ \\assert(type(a.session_id) == "function")
+ \\assert(type(a:session_id()) == "string")
+ );
+}
+
+test "agent: methods exist and stream surface works" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local a = panto.agent { api_style="openai_chat", api_key="k", base_url="http://127.0.0.1:1", model="m" }
+ \\for _, m in ipairs({"run","register_tool","set_config","add_system_message","set_system_prompt","compact","session_id"}) do
+ \\ assert(type(a[m]) == "function", "missing method "..m)
+ \\end
+ \\local s = a:run("hi")
+ \\assert(type(s) == "userdata")
+ \\local f, st, ctrl = s:events()
+ \\assert(type(f) == "function" and st == s and ctrl == nil)
+ );
+}
+
+test "agent: set_config swaps without error; system prompt setters work" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local a = panto.agent { api_style="openai_chat", api_key="k", base_url="http://127.0.0.1:1", model="m" }
+ \\a:add_system_message("be terse")
+ \\a:set_system_prompt("you are a test")
+ \\a:set_config { api_style="anthropic_messages", api_key="k2", base_url="http://127.0.0.1:2", model="m2" }
+ \\-- another swap, to exercise old-config retention
+ \\a:set_config { api_style="openai_chat", api_key="k3", base_url="http://127.0.0.1:3", model="m3" }
+ );
+}
+
+test "register_tool without luv fails loud at registration" {
+ // The test binary links Lua but NOT luv, so require('luv') fails. We
+ // assert that surfaces as a clear error at register time, not later.
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local a = panto.agent { api_style="openai_chat", api_key="k", base_url="http://127.0.0.1:1", model="m" }
+ \\local ok, err = pcall(function()
+ \\ a:register_tool {
+ \\ name="echo", description="echoes", schema={ type="object" },
+ \\ handler=function(input) return "ok" end,
+ \\ }
+ \\end)
+ \\assert(ok == false, "expected register_tool to fail without luv")
+ \\assert(err:find("luv"), "error should mention luv: "..tostring(err))
+ );
+}
+
+test "conversation: build standalone, inspect via messages()" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local conv = panto.conversation()
+ \\assert(type(conv) == "userdata")
+ \\conv:add_system_message("be terse")
+ \\conv:add_user_message("hello")
+ \\conv:add_user_message("again")
+ \\assert(conv:len() == 3, "expected 3 messages, got "..conv:len())
+ \\assert(#conv == 3, "__len should work too")
+ \\local m = conv:messages()
+ \\assert(m[1].role == "system" and m[1].blocks[1].type == "system")
+ \\assert(m[1].blocks[1].text == "be terse")
+ \\assert(m[2].role == "user" and m[2].blocks[1].text == "hello")
+ \\assert(m[3].blocks[1].text == "again")
+ );
+ try runScript(L, "collectgarbage('collect')"); // owned conv freed cleanly
+}
+
+test "conversation: full-fidelity tool turn round-trips through messages()" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local conv = panto.conversation()
+ \\conv:add_user_message("use a tool")
+ \\conv:add_assistant_message {
+ \\ blocks = {
+ \\ { type="thinking", text="hmm", signature="sig" },
+ \\ { type="text", text="calling" },
+ \\ { type="tool_use", id="c1", name="echo", input='{"m":"x"}' },
+ \\ },
+ \\ usage = { input=10, output=20, reasoning=5 },
+ \\}
+ \\conv:add_user_blocks {
+ \\ { type="tool_result", tool_use_id="c1", is_error=false,
+ \\ parts = { { text="echoed" }, { media_type="image/png", data="AAAA" } } },
+ \\ { type="text", text="queued note" },
+ \\}
+ \\assert(conv:len() == 3)
+ \\local m = conv:messages()
+ \\-- assistant message: usage + three typed blocks
+ \\assert(m[2].role == "assistant")
+ \\assert(m[2].usage.input == 10 and m[2].usage.reasoning == 5)
+ \\assert(m[2].blocks[1].type == "thinking" and m[2].blocks[1].signature == "sig")
+ \\assert(m[2].blocks[3].type == "tool_use" and m[2].blocks[3].id == "c1")
+ \\assert(m[2].blocks[3].input == '{"m":"x"}')
+ \\-- user tool-result message: result block + queued text
+ \\assert(m[3].blocks[1].type == "tool_result" and m[3].blocks[1].tool_use_id == "c1")
+ \\assert(#m[3].blocks[1].parts == 2)
+ \\assert(m[3].blocks[1].parts[1].text == "echoed")
+ \\assert(m[3].blocks[1].parts[2].media_type == "image/png" and m[3].blocks[1].parts[2].data == "AAAA")
+ \\assert(m[3].blocks[2].type == "text" and m[3].blocks[2].text == "queued note")
+ \\-- lossless replay into a fresh conversation
+ \\local c2 = panto.conversation()
+ \\for _, msg in ipairs(m) do
+ \\ if msg.role == "assistant" then c2:add_assistant_message { blocks = msg.blocks, usage = msg.usage }
+ \\ elseif msg.role == "user" then c2:add_user_blocks(msg.blocks) end
+ \\end
+ \\assert(c2:len() == conv:len(), "round-trip length mismatch")
+ \\local m2 = c2:messages()
+ \\assert(m2[2].blocks[3].id == "c1" and m2[3].blocks[1].parts[2].data == "AAAA")
+ );
+ try runScript(L, "collectgarbage('collect')");
+}
+
+test "conversation: malformed block raises" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local conv = panto.conversation()
+ \\local ok = pcall(function() conv:add_user_blocks { { type="tool_use" } } end) -- missing id/name
+ \\assert(ok == false, "tool_use without id/name should raise")
+ \\local ok2 = pcall(function() conv:add_user_blocks { { type="frobnicate" } } end)
+ \\assert(ok2 == false, "unknown block type should raise")
+ );
+}
+
+test "conversation: adopt into agent for resumption, then operate via agent:conversation()" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local conv = panto.conversation()
+ \\conv:add_system_message("resumed prompt")
+ \\conv:add_user_message("earlier question")
+ \\local a = panto.agent {
+ \\ api_style="openai_chat", api_key="k", base_url="http://127.0.0.1:1", model="m",
+ \\ conversation = conv,
+ \\}
+ \\-- The standalone handle is now adopted; operating on it must raise.
+ \\local ok = pcall(function() conv:add_user_message("nope") end)
+ \\assert(ok == false, "adopted conversation should reject mutation")
+ \\-- The live view reflects the adopted history.
+ \\local live = a:conversation()
+ \\assert(live:len() == 2, "expected 2 adopted messages, got "..live:len())
+ \\live:add_system_message("added live")
+ \\assert(live:len() == 3)
+ \\assert(a:conversation():messages()[3].blocks[1].text == "added live")
+ );
+ try runScript(L, "collectgarbage('collect')");
+}
+
+test "conversation: reusing an adopted conversation in a second agent is rejected" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local conv = panto.conversation()
+ \\conv:add_user_message("x")
+ \\local a1 = panto.agent { api_style="openai_chat", api_key="k", base_url="http://127.0.0.1:1", model="m", conversation = conv }
+ \\local ok = pcall(function()
+ \\ return panto.agent { api_style="openai_chat", api_key="k", base_url="http://127.0.0.1:1", model="m", conversation = conv }
+ \\end)
+ \\assert(ok == false, "an already-adopted conversation must not be adopted again")
+ );
+}
+
+test "stream: a turn against an unreachable host surfaces as a Lua error" {
+ const L = try newTestState();
+ defer c.lua_close(L);
+ try runScript(L,
+ \\local a = panto.agent { api_style="openai_chat", api_key="k", base_url="http://127.0.0.1:1", model="m" }
+ \\local s = a:run("hi")
+ \\local ok, err = pcall(function() for ev in s:events() do end end)
+ \\assert(ok == false and type(err) == "string", "unreachable host should raise")
+ );
+}
+
+test "json round-trip helpers: schema serialize + input parse" {
+ const L = c.luaL_newstate() orelse return error.LuaInitFailed;
+ defer c.lua_close(L);
+ c.luaL_openlibs(L);
+
+ // serializeSchema on a table.
+ try runScript(L, "schema = { type = \"object\", properties = { x = { type = \"number\" } } }");
+ _ = c.lua_getglobal(L, "schema");
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const json = try serializeSchema(L, -1, arena.allocator());
+ try testing.expect(std.mem.indexOf(u8, json, "\"type\"") != null);
+ try testing.expect(std.mem.indexOf(u8, json, "\"object\"") != null);
+ c.lua_settop(L, c.lua_gettop(L) - 1);
+
+ // pushJsonAsLua + readHandlerResult round trip.
+ try pushJsonAsLua(L, arena.allocator(), "{\"msg\":\"hello\"}");
+ _ = c.lua_getfield(L, -1, "msg");
+ var len: usize = 0;
+ const ptr = c.lua_tolstring(L, -1, &len);
+ try testing.expectEqualStrings("hello", ptr[0..len]);
+}
generated by cgit v1.3 (git 2.53.0) at 2026-07-09 08:38:19 +0000