lua libraries
Bundled modules seeded into ~/.bone-rust/lua/lib/ at startup. require them from any tool, command, or init.lua:
local history = require("history")
local pane = require("ui.pane")
local menu = require("ui.menu")
history
Conversation history helpers over ctx.db.query (raw SQL on the session DB).
| function | signature | returns |
|---|---|---|
| list | (ctx, limit?) | recent conversations, newest first — { id, provider, model, started_at, ended_at }. Default 20, max 100. |
| messages | (ctx, id, limit?) | messages for a conversation — { seq, role, content, tool_name, tool_call_id, tool_calls }. Default 200, max 1000. |
ui.pane
Reusable pane object + shared helpers for interactive bottom panes. Works over the channel transport, so rendering continues even while a tool blocks on ctx.ui.key().
| function | signature | returns |
|---|---|---|
| span | (text, fg?, modifiers?) | styled segment { text, fg, modifiers } |
| line | (...spans) | { spans } — one display row |
| clamp | (n, lo, hi) | n clamped to [lo, hi] |
| wait_key | (ctx) | one KeyEvent, or nil on cancel/error |
| key_name | (key) | the .code field ("Char", "Up", "Esc", …) |
| is_text_key | (key) | true if a plain character key |
| new | (ctx, opts?) | a Pane object — opts = { id?, title?, visible_rows? } |
Pane methods: :set_title(s), :set_lines(lines, visible_rows?), :close(), :wait_key(), :key_loop(fn) (loops reading keys until fn returns truthy).
local pane = require("ui.pane")
local p = pane.new(ctx, { title = "search" })
p:set_lines({ pane.line(pane.span("hit any key", "cyan")) })
local k = p:wait_key()
p:close()
ui.menu
Interactive select / multi-select / text-input panes built on ui.pane. All block until the user picks or cancels (Esc / Ctrl+C).
| function | signature | returns |
|---|---|---|
| select | (ctx, spec) | { value } or { cancelled = true } |
| multi_select | (ctx, spec) | { values } or { cancelled = true } |
| text_input | (ctx, spec) | { value } or { cancelled = true } |
| clear | (ctx) | close any open menu pane |
spec common fields: title, question, options (array), default, allow_custom, initial. multi_select returns values as an array.
local menu = require("ui.menu")
local r = menu.select(ctx, {
question = "Deploy where?",
options = { "staging", "prod" },
})
if r.cancelled then return end
ctx.ui.notice("deploying to " .. r.value)
ui.spinners
Spinner frame + thinking-text presets consumed by the Rust renderer. Not usually called directly — selected via config/status.yaml.
| key | options |
|---|---|
| spinners | braille, triangle, pipe, kaomoji, typing, waveline, dots_text, progblock |
| texts | thinking, pondering, processing |
bundled commands
Shipped in core/defaults/lua/commands/ and seeded into ~/.bone-rust/lua/commands/:
| command | description |
|---|---|
| /compact | manual context compaction. Summarizes older messages via a sub-agent, keeping recent ones verbatim. Auto-triggers when context exceeds auto_compact_tokens (general.yaml). |
| /config | interactive tabbed settings editor. /config tools reload rescans the tools dir. |
| /usage | token stats for the current session — sent/received/cached, cost, context length, per-provider breakdown. |