Reference

Lua extensions

require("panto")

panto's standard tools are Lua extensions, and your own extensions use the same loader. A source file returns one entry, one tool declaration, or a list of them; activation then registers tools, slash commands, and UI-event handlers into the live session.

Overview

Extension source files are evaluated first and activated later. A file must return one of these shapes:

{ name, activate }

A named entry whose activate() function performs registration when the entry survives policy and shadowing.

{ name, description, schema, handler }

Sugar form for a single tool entry. Activation registers it as a tool automatically.

{ ... , ... }

A list of entries or tool declarations returned from one file.

Inside activate(), use local panto = require("panto") and the panto.ext table:

register_tool

register_command

on / emit

Subscribe to transcript/UI lifecycle events or fire custom ones.

Loading extensions

panto scans both extensions/ and tools/ directories at each layer:

Layer	Location
base	$XDG_DATA_HOME/panto/agent/{extensions,tools}
user	$XDG_CONFIG_HOME/panto/{extensions,tools} · else ~/.config/panto/{extensions,tools}
project	./.panto/{extensions,tools}

Additional sources can come from [extensions] paths and [extensions] rocks. Cross-layer precedence is project > user > base. Within one layer, canonical directories beat extra paths, which beat rocks. Identity is the returned entry's name, not the filename.

Eval is side-effect free

Every candidate file is evaluated before policy and shadowing are resolved, including entries that will later be denied. Put side effects in activate(), not at top level.

register_tool

The simplest way to define a tool is to return the sugar form directly:

.panto/tools/echo.lualua

return {
+  name = "echo",
+  description = "Echo back the given message.",
+  schema = {
+    type = "object",
+    properties = {
+      message = { type = "string" },
+    },
+    required = { "message" },
+  },
+  handler = function(input)
+    return "echo: " .. input.message
+  end,
+}

Use register_tool inside activate() when you want one entry to register multiple tools or commands together.

register_command

Slash commands are typically registered from an explicit entry:

.panto/extensions/greet.lualua

return {
+  name = "greet",
+  activate = function()
+    local panto = require("panto")
+    panto.ext.register_command {
+      name = "greet",
+      description = "Print a greeting.",
+      handler = function(args)
+        local who = args ~= "" and args or "world"
+        io.write("\n[greet] hello, " .. who .. "!\n")
+      end,
+    }
+  end,
+}

Events: on & emit

panto.ext.on(name, handler) subscribes to transcript/UI lifecycle events. The handler receives an event userdata with snake-case methods get_component() and set_component(), plus payload fields such as tool_name, delta, text, id, input, output, cwd, and model.

Event family	Names
tool	tool, tool_details, tool_delta, tool_call_complete, tool_result, tool_collapse
thinking	thinking, thinking_delta, thinking_complete
assistant text	assistant_text, assistant_text_delta, assistant_text_complete
single-shot	user_message, session_start, compaction
custom	whatever you emit via `panto.ext.emit`

A few payload fields are writable during dispatch: user_message.text, tool_call_complete.input (assign a Lua table; panto serializes it to JSON), and tool_result.output.

.panto/extensions/skill-badge.lualua

return {
+  name = "skill-badge",
+  activate = function()
+    local panto = require("panto")
+    panto.ext.on("tool_details", function(e)
+      if e.tool_name ~= "skill" then return end
+      local inner = e:get_component()
+      e:set_component({
+        render = function(self, width)
+          local lines = inner:render(width)
+          lines[#lines + 1] = "▸ running skill"
+          return lines
+        end,
+      })
+    end)
+  end,
+}

Lua components

A Lua component is a table passed to set_component(). The required method is render(self, width), which returns an array of strings. handleInput(self, data) is optional. Differential repaint is cache-derived automatically; you do not need to implement firstLineChanged yourself.

Runtime & luarocks

panto embeds a pinned Lua and luarocks runtime and ships luv as its core async dependency. Extra rocks may be loaded as extension sources via [extensions] rocks and installed with panto update, or added manually with panto lua.

shellbash

panto update
+panto lua -e 'arg[0]="luarocks"; require("luarocks.cmd").run_command("install","lpeg")'