Reference

Lua extensions

Add tools, slash commands, provider protocols, and TUI hooks in Lua. Policy and config layers live in configuration; install and update commands in the command line.

Quick start

Save this file and start panto, then type /greet you.

local panto = require("panto") -- there is no global

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

The entry name drives shadowing and allow/deny policy; it need not match what it registers.

Loading extensions

panto scans extensions/ and tools/ at startup; both share one entry namespace. Precedence, highest first:

• A source is a .lua file or a directory with init.lua; directories can require sibling modules.
• Symlinks are followed. Dotfiles and _-prefixed files are skipped.
• Each layer can add [extensions].paths (relative to the project) and [extensions].rocks.
• Within a layer: directories beat paths beat rocks. Higher precedence shadows the same name.
• Missing configured rocks install at startup; each is required by the first token of its spec.

Allow and deny

[extensions].allow and deny match entry names; no match allows. A denied entry denies everything it registers.

Rules accumulate across layers: higher layer wins, then the more specific pattern, then deny on a tie. Format: extension policy.

Load errors

Paths: panto.ext.dirs

Plain data, ready before evaluation. Build paths from it instead of reading HOME or XDG_*.

for _, layer in ipairs(require("panto").ext.dirs.layers) do
  print(layer.name, layer.dir .. "/skills")
end

Lifetime

One Lua state lasts a TUI session; switching sessions loses globals. Registered themes survive.

register_tool

Give the model a tool: return a declaration from a source, or register it during activation.

return {
  name = "echo",
  description = "Echo a message.",
  schema = {
    type = "object",
    properties = { message = { type = "string" } },
    required = { "message" },
  },
  handler = function(input, context)
    return context.tool_name .. ": " .. input.message
  end,
}

register_command

Add a slash command; see the Quick start.

To hand the terminal to a program, call run_foreground; it works only inside a TUI slash-command handler. panto restores the terminal, runs it with inherited stdio, then redraws.

handler = function()
  local r = panto.ext.run_foreground { argv = { "lazygit" } }
  -- r.success, plus one of r.exit_code, r.signal, r.stopped, r.unknown
end,

argv must be a non-empty dense array (no gaps) of NUL-free strings, starting with a non-empty program name.

Events: on & emit

Observe lifecycle events or customize render events. Render events use the render_ prefix; they are emitted by the host session’s presentation path, including print mode (where rendered output is discarded), not by Lua-built agents. session_start fires for the primary session and on the first run of each Lua-built agent; on a child agent it carries only session_id and resumed (the primary event also has version, cwd, and model). tool_result fires once per call dispatched through the Lua tool source, after its batch settles. In these per-agent callbacks, panto.ext.agent resolves to the agent that emitted the event.

Each event has name and its documented fields. App render_ events and .custom events support get_component()/set_component(). A custom event starts without a component, so get_component() returns nil and set_component() can install one; this includes session_ready, session_end, and suspend. Typed-payload events session_start, turn_*, command_*, tool_result, and server_request have no component; either method raises event '<name>' has no component. Empty optional strings read as nil.

The former session_start header component event is now render_header; session_start remains a lifecycle event without a component. The former compaction component event is now render_compaction. The user_message event is removed; use read-only render_user_message to observe the transcript. Render events also replace the old unprefixed thinking, assistant-text, and tool component events.

Tool render events fire in this order. render_tool fires when a tool-use block starts, before its name is known; render_tool_details supplies the resolved name. Collapse changes can occur separately. Empty optional strings read as nil.

tool_result is the lifecycle notification; its writable output is applied before the result is returned to the agent. render_tool_result is the separate TUI display boundary.

Rewriting events

Only these two lifecycle fields are writable. Later handlers see earlier writes; the last write wins. Render events, including render_tool_call_complete.input, are read-only. A tool_result.output override is applied only to a successful tool result: it replaces all text parts with one text part and preserves media parts. On failure the override is ignored.

local panto = require("panto")
panto.ext.on("server_request", function(event)
  local request = panto.ext.json.decode(event.request_json)
  if request then
    request.model = "provider:alias"
    event.request_json = panto.ext.json.encode(request)
  end
end)

Lua components

Replace or wrap the TUI component for an event.

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

Component methods are unavailable on typed-payload lifecycle events (session_start, turn_*, command_*, tool_result, and server_request); calling either raises event '<name>' has no component. On custom events, including session_ready, session_end, and suspend, get_component() returns nil until a component is set, and set_component() works.

Render errors show a diagnostic row. Keep component callbacks synchronous; don’t await while rendering or handling input. Mounting, unmounting, changing input modes, or calling a component handle’s set_pinned from render() raises a Lua error.

Standalone mounts

panto.ext.mount(component, "above_input") places a Lua component above the input, independently of transcript events. It must implement render(self, width); multiple mounts appear in insertion order.

Exclusive input modes

panto.ext.input_mode { keys, on_exit? } temporarily takes TUI input for a custom interaction. Key and exit callbacks run synchronously and must not yield.

Malformed specs raise a Lua error: keys must be a nonempty array of entries with unique, non-reserved canonical chords and function run callbacks; desc must be a string or nil, and on_exit a function or nil. nil, reason is returned for a valid mode that cannot take input, such as when another mode, modal, turn, session switch, or missing TUI prevents it.

Chords use canonical lowercase modifiers in ctrl+alt+shift+ order followed by a printable character or named key: space, enter, escape, tab, backspace, delete, up, down, left, right, home, end, page_up, page_down, or f1–f12. Shift applies to named keys (including space), not printable letters. Only Ctrl+C, Ctrl+D, Ctrl+Z, Ctrl+H, Ctrl+I, Ctrl+J, and Ctrl+M are reserved from modes. Undeclared keys and pastes are swallowed; Ctrl+C/D/Z retain their host behavior.

A mode may return nil, reason instead of a handle: mode, modal, turn, switching, or no_tui. An input mode exits as closed only when its handle's close() is called; Esc is dispatched like any other key and swallowed unless the mode declares an escape chord. It exits as turn when a turn begins, modal when a modal opens, session when switching sessions, teardown when the runtime ends, or error if a key callback fails; the error message is passed as message.

Protocol providers

Implement a model wire protocol in Lua, then select it in your provider config.

local panto = require("panto")
return {
  name = "demo-provider",
  activate = function()
    panto.ext.register_protocol {
      name = "demo",
      effort_levels = { { label = "quick", detail = "short response" } },
      open = function(request)
        local sent = false
        return {
          next = function(self)
            if sent then return { type = "done" } end
            sent = true
            return { type = "text_delta", text = "Hello from " .. request.model }
          end,
          close = function(self) end,
        }
      end,
    }
  end,
}

register_protocol fields

The request

The stream

Protocol callbacks run synchronously; never block or await.

Agents, jobs & submissions

Steer the live agent, or build your own.

The host agent

The host agent is the live agent: the child inside a child-agent tool, otherwise the session agent. Queue a string or content blocks:

local agent = require("panto").ext.agent
agent:submit("Please check the generated file")         -- at the next safe tool boundary
agent:submit("Summarize the result", { followup = true }) -- after the turn ends

It’s borrowed: you can’t close it or change its tools or config. It is unavailable under panto serve.

Owned agents

Streams close when collected. After an agent adopts a conversation, use the agent’s conversation view instead of the original userdata.

For built-in OpenAI Chat and Anthropic Messages streams, EOF counts as truncated only if neither completion signal arrived: finish_reason or [DONE] for Chat, stop_reason or message_stop for Messages. Such malformed streams fail as ProviderStreamMalformed (and may be retried by the configured policy); partial assistant turns are not committed as complete.

Background jobs: run_async

Returns job, err. The job’s methods are listed below.

Jobs refuse borrowed agents, a second live job, and agents with register_tool handlers (use a shared tool source). Conversation edits are refused while a job is live.

For Agent, Decider, and Extractor async calls, optional wake_fd must be a valid non-blocking FD. Keep it open with unchanged flags until job:close() returns; wake bytes are best-effort and may be dropped. Agent jobs signal published events; Decider and Extractor jobs signal settlement. close() cancels if needed and joins the worker. Call job:close() before decider:close() or extractor:close(); closing either owner while an async job remains open raises a Lua error. HTTP cancellation starts only after connection and TLS setup; DNS, TCP connect, and TLS handshake are not cancellable, and api_timeout_ms starts after setup, so close() may remain blocked there.

Deciders

The v0.6.0 panto.decider { llm = config } (or another backend arm) replaces the v0.5.0 panto.evaluator/:evaluate API. It answers named structured questions in one request. Choose exactly one config arm: llm, system_one, typesafe, cloudflare, or openai_decisions. The llm arm takes the existing agent config; extension-protocol configs fail with UnsupportedProviderForDecider when deciding. HTTP arms require a non-empty model and accept optional api_key, extra_headers (an array of { name, value }), retry ({ max_attempts?, initial_delay_ms?, max_delay_ms?, multiplier?, jitter? }), and api_timeout_ms; set api_key = false for explicit no-auth. System One and TypeSafe take exactly one of base_url or full_url; the former appends /v1/systemone, the latter is an exact endpoint. Cloudflare requires url; OpenAI Decisions requires base_url and appends /decisions.

decide() blocks while the request runs and returns its result; invalid requests and provider or transport failures raise Lua errors. Use decide_async() for a job instead.

local panto = require("panto")
local decider = panto.decider {
  system_one = { base_url = "https://example.test", model = "decision-model", api_key = false },
}
local result = decider:decide {
  input = "A customer requested a refund after 40 days.",
  questions = {
    { id = "eligible", type = "binary", instructions = "Is the refund eligible?" },
    { id = "severity", type = "score", instructions = "Rate the issue.",
      scale = { { label = "low" }, { label = "medium" }, { label = "high" } } },
  },
}
print(result.answers.eligible.probability)
decider:close()

Extractors

panto.extractor { cloudflare = config } (or llm = config) extracts named, typed values from text. Choose exactly one cloudflare or llm config arm. Cloudflare requires url and a non-empty model; other HTTP settings follow the Decider conventions. Extension-protocol configs in the LLM arm fail with UnsupportedProviderForExtractor.

extract() blocks while the request runs and returns its result; invalid requests and provider or transport failures raise Lua errors. Use extract_async() for a job instead.

local extractor = require("panto").extractor {
  cloudflare = { url = "https://example.test/extract", model = "extractor", api_key = false },
}
local result = extractor:extract {
  input = "Invoice INV-2291 totals $1080.",
  fields = { { id = "invoice", kind = "text" }, { id = "total", kind = "number", unit = "USD" } },
}
print(result.answers[1].id, result.answers[1].value)
extractor:close()

Sessions & transcripts

Read stored sessions and build conversations.

A custom store is a Lua table passed as store. Implement the methods above plus:

• create
• append_messages
• update_message_metadata
• Both load methods must return an owned conversation or nil.

Text, JSON, highlighting & themes

Utilities for rendering, JSON, themes, and host queries.

• Source highlighting ends with ESC[39m; reapply your foreground color after it. Markdown display rendering closes an OSC 8 link only if one was emitted and appends ESC[0m only if styled output was emitted.
• Call style() while rendering to follow live theme changes.
• Re-registering identical theme values is harmless; different values under the same name fail.

Session and models

These host queries return nil, error when unavailable.

resume is applied after the calling extension returns because it replaces the Lua runtime. Code after the call still runs against the outgoing session and must not await. It is refused mid-turn, while another switch is pending, for the current session, or when switching is unavailable (including print mode).

Extension state

panto.ext.state.get(path) and set(path, value) access persistent TOML-compatible values in state.toml, under extension_state, independently of config. Paths are dotted keys; prefix them with your extension name to avoid collisions. A missing get returns nil and setting nil deletes the value. set returns true on success; both calls return nil, error on failure. State updates use the persistent sibling lock file state.toml.lock; don’t remove it while panto may be writing. Available in interactive and print sessions and panto lua; unavailable in configuration hooks and panto serve (calls return nil, error with state: remembered state is unavailable in this context).

local state = require("panto").ext.state
state.set("my_extension.reader.wpm", 350)
local wpm = state.get("my_extension.reader.wpm")

Config: panto.ext.config

Read your own settings from a plain copy of the merged raw config.toml, ready before evaluation or activation.

• Unknown keys are included.
• ${env:...} placeholders stay literal; literal values remain visible.
• TOML dates and times become strings.

Layer and file rules: configuration.

Runtime & luarocks

panto embeds Lua 5.4.7 and LuaRocks 3.13.0, and installs luv 1.52.1 bound to its own event loop. Use that loop; don’t create another.

No other rocks ship; install libraries as dependencies or into panto’s tree.

• Every configured rock loads as an extension; a library that returns no valid entry logs a load failure each startup.
• Declare libraries in your extension’s rockspec to install them transitively, or use the command below.

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

Interpreter arguments: the CLI reference.