Skip to content

Types

Records and string-literal unions referenced from the namespace pages. Generated from #[derive(LuaOpts)] and #[derive(LuaAlias)] sites in Rust.

Classes

smelt.Reg

Registration handle returned by every reactive-subscription API. :remove() undoes the binding (frees the underlying callback / cancels the timer / drops the subscription). Idempotent: subsequent calls return false.

Field Type Required Description
remove fun(): boolean yes Undo the registration. Returns true the first time; false on subsequent calls or when the underlying target is already gone.

smelt.buf.Buf

Buffer handle returned by smelt.buf.new(opts?). Setter methods return the same handle for chaining.

Field Type Required Description
source fun(s: string?): any yes Read or write the buffer's full source. Without arg returns the source string (or nil if the buffer is gone). With arg replaces the source and returns the handle for chaining.
lines fun(arr: string[]?): any yes Read or write the buffer as a string array. Without arg returns the lines; with arg replaces all lines and returns the handle for chaining.
line fun(idx: integer): string? yes Read a single line by 1-based index. nil if out of range or the buffer is gone.
styled fun(lines: table): smelt.buf.Buf yes Replace the buffer with a list of styled lines ({ { text, style?, syntax? }, ... }). Returns the handle for chaining.
readonly fun(val: boolean?): any yes Read or write the readonly flag. With arg, returns the handle for chaining.
mark fun(ns: integer, row: integer, col: integer, opts: smelt.buf.MarkOpts?): integer yes Place a highlight or virt-text extmark at (row, col). Row is 1-based; col and opts.end_col are byte offsets into the line — the same unit as #s, string.find, and string.sub. Off-boundary bytes snap to the nearest UTF-8 char boundary; out-of-range bytes clamp to the line end. Returns the new extmark id. Allocate ns via smelt.ns(name).
clear_ns fun(ns: integer, start: integer?, end_: integer?): smelt.buf.Buf yes Drop every extmark owned by ns between [start, end) (1-based, exclusive end). Defaults clear the whole buffer. Returns the handle for chaining.

smelt.buf.MarkOpts

Options accepted by buf:mark(ns, row, col, opts). Mirrors a useful subset of nvim_buf_set_extmark's keyset; pick highlight or virt-text fields, not both.

Field Type Required Description
id integer Retarget an existing mark by id instead of allocating a new one.
end_row integer 1-based end row (inclusive). nil keeps the mark single-line.
end_col integer End byte offset for highlight ranges (exclusive). Same unit as col — bytes into the line, matching #s and string.find.
priority integer Higher-priority marks paint over lower-priority ones.
right_gravity boolean If true, the mark sticks with text inserted to its right.
end_right_gravity boolean Right-gravity flag for the end-of-range cursor.
hl_group string Theme group whose style is applied as the highlight base.
fg string Theme group whose foreground overrides hl_group.
bg string Theme group whose background overrides hl_group.
bold boolean Force-bold the highlight.
dim boolean Force-dim the highlight.
italic boolean Force-italic the highlight.
hl_eol boolean Extend the highlight past the last column to fill the EOL.
on_cursor_row boolean Paint only on the window's cursor row. Decorates the selected list item without re-rendering on every move.
virt_text string Virtual-text chunk to render alongside the line.
virt_text_hl string Theme group applied to the virt-text chunk.
virt_text_pos smelt.buf.VirtTextPos Where the virt-text appears relative to the line.
selectable boolean If false, the range is skipped by mouse selection.
yank_as string Override the yanked string when the user copies this range.

smelt.builtins.Selector

Selector accepted by smelt.builtins.disable / enable. Each list is a set of bundled module short-names — see the table below for the smelt.<dotted> form each one expands to. | field | expansion | |---|---| | tools = { "web_search" } | smelt.tools.web_search | | commands = { "compact" } | smelt.commands.compact | | plugins = { "predict" } | smelt.plugins.predict | | dialogs = { "resume" } | smelt.dialogs.resume | | modules = { "smelt.foo.bar" } | passed through verbatim |

Field Type Required Description
tools string[] Short tool names under smelt.tools.* (e.g. "bash", "web_search").
commands string[] Short command names under smelt.commands.* (e.g. "compact").
plugins string[] Short plugin names under smelt.plugins.* (e.g. "predict").
dialogs string[] Short dialog names under smelt.dialogs.* (e.g. "resume").
modules string[] Fully-qualified smelt.<dotted> module names, passed through verbatim.

smelt.cell.Cell

Sticky handle returned by smelt.cell(name). Setters return the handle for chaining; :subscribe returns a Reg.

Field Type Required Description
get fun(): any yes Return the current cell value, or nil when the cell isn't declared.
set fun(value: any): smelt.cell.Cell yes Publish a new value. Returns the handle for chaining.
subscribe fun(handler: fun(value: any)): smelt.Reg yes Register handler(value) to fire on every set. Returns a Reg whose :remove() drops the subscription. No-op when called before the host pointer is live (e.g. the pre-TUI plugin pass) — the module body re-runs inside bring_up_lua where the bind takes effect.
name fun(): string yes Return the cell name.

smelt.cli.RegisterFlagOpts

Flag specification accepted by smelt.cli.register_flag.

Field Type Required Description
name string yes Flag name without --. Used as the key for smelt.cli.get.
kind smelt.cli.FlagKind yes "boolean" (default false), "string", or "integer".
default any Default value when the flag is absent from argv. Type must match kind.
short string Short flag character (e.g. "u" for -u). Optional.
long string Long flag name override. Defaults to name when absent.
description string Human-readable description for --help.
value_optional boolean String/Integer flags only. When true, the flag may be passed without a value (smelt -r valid alongside smelt -r abc); the value-less form yields "" for String and 0 for Integer. Defaults to false. Ignored for Boolean flags.

smelt.cmd.RegisterOpts

Options accepted by smelt.cmd.register.

Field Type Required Description
desc string Human-readable description shown in /help and the slash-command picker.
args string[] Positional argument labels used for help text and completion hints.
while_busy boolean If true, the command can be invoked while an agent turn is running. Defaults to true.
queue_when_busy boolean If true, busy invocations are queued instead of rejected. Defaults to false.
startup_ok boolean If true, the command may run before the runtime has finished bootstrapping. Defaults to false.
hidden boolean If true, the command is hidden from /help and the picker (still callable). Defaults to false.

smelt.engine.AskError

Typed error table delivered to on_response when the underlying provider call fails. kind is a stable string the caller can branch on; message is a human-readable single-line description. The struct exists purely as a doc / LuaCATS schema target — the actual table is built in LuaRuntime::fire_ask_callback because it lands on a callback path that bypasses FromLua decoding.

Field Type Required Description
kind string yes One of "network" | "rate_limited" | "quota" | "invalid_response" | "context_window" | "cancelled" | "other".
message string yes Human-readable single-line description (newlines collapsed to spaces).

smelt.engine.AskMessage

One message in a smelt.engine.ask conversation.

Field Type Required Description
role string yes Either "user" or "assistant". Other roles are silently dropped.
content string yes Message body as plain text.

smelt.engine.AskResponseFormat

Structured JSON-output specification for smelt.engine.ask.

Field Type Required Description
name string yes Schema name (used by some providers as the response_format label).
schema table yes JSON schema describing the expected response shape. Accepts a Lua table that round-trips through lua_table_to_json into a JSON value.

smelt.engine.AskSpec

Spec for smelt.engine.ask.

Field Type Required Description
system string System prompt sent before the conversation. Optional when inherit_session = true (the current session's system prompt is substituted in that case).
messages smelt.engine.AskMessage[] Prior turns. Each message is { role = "user"|"assistant", content = "..." }.
question string Single-shot question appended as a final user message after messages.
inherit_session boolean When true, override system with the current session's assembled system prompt and prepend the live session.messages (full message shape including tool turns) plus the active tool list. The request then shares the Anthropic prefix cache with the main turn. Used by the compaction summariser to keep its prompt off the cache miss path.
model string Model reference ("provider/model" or a bare name resolved against the configured providers). When nil, falls back to the primary model.
response_format smelt.engine.AskResponseFormat JSON-schema response constraint.
reasoning_effort smelt.reasoning.Effort Reasoning effort for the request; defaults to "off".
on_response fun(arg1: string, arg2: smelt.engine.AskError?) Fires once with (content, err). On success err is nil and content carries the assistant text. On failure err is a smelt.engine.AskError table and content is "".

smelt.engine.CommandOverrides

Front-matter override block accepted by smelt.engine.submit_command. Mirrors what plugin commands set in their markdown header. Tool-name keys (e.g. bash, edit) become per-subcommand pattern buckets.

Field Type Required Description
description string Override the command description shown in /help.
provider string Force a specific provider for this command's turn.
model string Force a specific model id.
temperature number Sampling temperature override.
top_p number Nucleus-sampling cutoff override.
top_k integer Top-k sampling cutoff override.
min_p number Minimum-probability cutoff override.
repeat_penalty number Repeat-penalty override.
reasoning_effort string Reasoning-effort override; one of the smelt.reasoning.Effort strings.
tools smelt.engine.RuleOverride Per-tool allow/ask/deny patterns for the duration of the turn.
[string] smelt.engine.RuleOverride Per-subcommand pattern buckets keyed by tool name.

smelt.engine.RuleOverride

Subcommand rule override accepted inside CommandOverrides. Mirrors the front-matter { allow?, ask?, deny? } shape.

Field Type Required Description
allow string[] Patterns that auto-allow.
ask string[] Patterns that always prompt.
deny string[] Patterns that auto-deny.

smelt.mcp.Config

MCP server config accepted by smelt.mcp.register.

Field Type Required Description
type string Server kind. Only "local" (the default) is supported.
command string|string[] Executable + leading argv. Either a string ("my-server") or a list ({"my-server", "--flag"}).
args string[] Trailing arguments appended after command.
env table<string, string> Extra environment variables to set on the child process.
timeout integer Request timeout in milliseconds. Defaults to 30000.
enabled boolean Whether the server is enabled. Defaults to true.

smelt.overlay.Overlay

Overlay handle returned by smelt.overlay.new(opts).

Field Type Required Description
close fun(): nil yes Close the overlay. No-op if already closed.
key fun(chord: string, func: fun(value: table)): smelt.Reg yes Bind func to chord on this overlay. Fires when any leaf of the overlay holds focus, after a per-window keymap miss but before global Lua keymaps. Returns a Reg whose :remove() undoes the binding.

smelt.paint.Paint

Opaque handle returned by smelt.paint.register. Usable directly in smelt.overlay.layout.leaf(handle, opts) (it stands in for a Win in layout leaves).

Field Type Required Description
remove fun(): boolean yes Drop the paint callback. Returns true if it was still registered. Subsequent paints of this id no-op.
rect fun(): any yes Return the paint leaf's current screen rect as { row, col, width, height }, or nil until the first render lays it out.
on fun(event: smelt.paint.Event, func: fun(value: table)): smelt.Reg yes Subscribe func to event on this paint leaf. Returns a Reg handle whose :remove() undoes the subscription.

smelt.paint.Slice

Grid slice passed to paint callbacks. Methods delegate to the live grid slice for the current frame; out-of-scope calls fail cleanly.

Field Type Required Description
width fun(): integer yes Return the slice width in cells.
height fun(): integer yes Return the slice height in cells.
set fun(row: integer, col: integer, ch: string, style: table?): nil yes Write a single character with optional style at (row, col).
put_str fun(row: integer, col: integer, text: string, style: table?): nil yes Write a string with optional style at (row, col).
fill_rect fun(row: integer, col: integer, w: integer, h: integer, ch: string?, style: table?): nil yes Fill a rectangle with an optional character and style.

smelt.permissions.ModePerms

Permission slots that apply within a single agent mode. The fixed tools key controls the tool itself; any additional key is treated as a subcommand bucket and routed through that tool's subpattern parser (e.g. bash = { allow = { "git status" } }).

Field Type Required Description
tools smelt.permissions.RuleSet Per-tool allow/ask/deny patterns.
[string] smelt.permissions.RuleSet Subcommand patterns keyed by tool name ("bash", "edit", …).

smelt.permissions.RuleSet

allow/ask/deny pattern arrays accepted by every permission slot.

Field Type Required Description
allow string[] Patterns that auto-allow without prompting.
ask string[] Patterns that always prompt.
deny string[] Patterns that auto-deny.

smelt.permissions.RulesSpec

Spec for smelt.permissions.set_rules. Each mode falls back to default (and then to host-level rules) when its slot is nil.

Field Type Required Description
default smelt.permissions.ModePerms Baseline rules applied unless a mode-specific slot overrides.
normal smelt.permissions.ModePerms Rules active while the agent is in normal mode.
plan smelt.permissions.ModePerms Rules active while the agent is in plan mode.
apply smelt.permissions.ModePerms Rules active while the agent is in apply mode.
yolo smelt.permissions.ModePerms Rules active while the agent is in yolo mode.

smelt.permissions.SessionEntry

A single session permission entry (one approved tool/pattern pair).

Field Type Required Description
tool string yes Tool name the rule applies to (e.g. "shell").
pattern string yes Pattern matched against the tool's argument bucket.

smelt.permissions.SyncSpec

Spec for smelt.permissions.sync.

Field Type Required Description
session smelt.permissions.SessionEntry[] Session entries; applied for this run only.
workspace smelt.permissions.WorkspaceRule[] Workspace rules; persisted to disk under the current cwd.

smelt.permissions.WorkspaceRule

A workspace permission rule (one tool with N patterns, persisted to disk).

Field Type Required Description
tool string yes Tool name the rule applies to.
patterns string[] yes Patterns granted for this tool.

smelt.picker.Picker

Picker handle returned by smelt.picker.new(opts). Setter methods return the same handle for chaining.

Field Type Required Description
win fun(): smelt.win.Win yes Return the underlying Win handle (use win:key(...), win:on(...) to bind input).
close fun(): nil yes Close the picker overlay. No-op if already closed.
items fun(items: table): smelt.picker.Picker yes Replace the picker's items. Each entry is a string or { label, description?, ansi_color?, prefix?, ... }. Selection resets to row 0. Returns the handle for chaining.
selected fun(idx: integer?): any yes Read or write the current logical selection (0-based). Without arg returns the index (nil if the picker is empty); with arg sets the selection and returns the handle for chaining.
move fun(delta: integer): smelt.picker.Picker yes Move the picker's cursor by delta rows (clamped to the buffer's line count). Returns the handle for chaining.

smelt.provider.Config

Spec accepted by smelt.provider.register.

Field Type Required Description
type string Provider kind tag ("openai", "anthropic", etc.).
api_base string Base URL the engine talks to.
api_key_env string Environment variable that holds the bearer token.
models string|smelt.provider.Model[] Models offered by this provider.

smelt.provider.Model

One model entry in a provider's models list. Plugin authors can pass either a bare model id string or a full table — the wrapper handles both forms transparently.

Field Type Required Description
name string Model id as it appears in API requests.
temperature number Default sampling temperature.
top_p number Default nucleus-sampling cutoff.
top_k integer Default top-k sampling cutoff.
min_p number Default minimum-probability cutoff.
repeat_penalty number Default repeat penalty.
tool_calling boolean Whether the model supports tool calls.
input_cost number Cost per input token in USD.
output_cost number Cost per output token in USD.
cache_read_cost number Cost per cache-read token in USD.
cache_write_cost number Cost per cache-write token in USD.

smelt.statusline.RegisterOpts

Options accepted by smelt.statusline.register.

Field Type Required Description
align string "right" makes the source's segments default to the right strip. Defaults to left.

smelt.theme.ColorDecl

Color value. Set ansi (256-color palette index) or rgb ({R, G, B} triple) for a direct color, or dark / light (themselves ColorDecls) for a branch that resolves against the terminal background. A matching-side branch wins over the direct fields.

Field Type Required Description
ansi integer ANSI 256-color palette index for the default (non-branched) case.
rgb integer[] [r, g, b] sRGB triple for the default (non-branched) case.
light smelt.theme.ColorDecl Color this branch resolves to when is_light == true.
dark smelt.theme.ColorDecl Color this branch resolves to when is_light == false.

smelt.theme.StyleDecl

Style table for a single highlight group. Every field is optional — unset fields stay at Style::default(). Pass a string in place of this struct (at the group-map level) to alias another group.

Field Type Required Description
fg smelt.theme.ColorDecl Foreground color.
bg smelt.theme.ColorDecl Background color.
bold boolean Bold text.
italic boolean Italic text.
dim boolean Dim / faint text.
underline boolean Underline.
crossedout boolean Strikethrough.

smelt.theme.ThemeSpec

Flat map keyed by highlight-group name (Comment, Visual, SmeltAccent, …). Each value is either a StyleDecl table or a string referencing another group in the same spec. Every themable color (foreground, background, diff row fills, scrollbar colors, mode indicators) is just a group.

Field Type Required Description
[string] string | smelt.theme.StyleDecl Style table or alias string for the group named by the key.

smelt.tools.PermissionDefaults

Per-mode default decisions installed by smelt.tools.register. Each missing field falls through to the host's generic rules.

Field Type Required Description
normal smelt.tools.Decision Decision applied in normal mode.
plan smelt.tools.Decision Decision applied in plan mode.
apply smelt.tools.Decision Decision applied in apply mode.
yolo smelt.tools.Decision Decision applied in yolo mode.

smelt.tools.ToolDef

Plugin tool definition passed to smelt.tools.register. execute is required; the remaining hooks are optional and are invoked at well-defined points during a tool turn — see the field docs for each callback's contract.

Field Type Required Description
name string yes Tool name; used as the engine-facing identifier.
execute function yes Required handler: execute(args, ctx) — returns the tool result.
description string Human-readable description shown to the model.
parameters table JSON-schema parameters table passed through to the model.
permission_defaults smelt.tools.PermissionDefaults Per-mode default decisions.
default_allow string[] Subcommand patterns that auto-allow without prompting.
subpattern_parser string Built-in subpattern parser kind (e.g. "bash").
modes table Agent modes the tool is available in; nil means all modes.
execution_mode string "concurrent" (default) or "sequential".
summary function summary(args) -> string | styled_lines | nil — styled label rendered in the transcript header AND confirm dialog body header. Plain string is auto-wrapped as one plain span; the styled-lines form is { { { text, syntax?, style? }, ... }, ... } — same span shape as buf:styled.
approval_patterns function approval_patterns(args, ctx) -> string[] — patterns offered as one-click approvals.
preflight function preflight(args, ctx) -> table? — validation hook; nil result skips.
render function render(buf, args, result) — custom transcript render.
paths_for_workspace function paths_for_workspace(args) -> string[] — files this invocation will touch.
preview function preview(args) -> smelt.layout — pre-execute preview render. Returns the same smelt.layout value the render callback returns; the confirm dialog renders it directly into the preview pane.
decide function decide(args, mode) -> smelt.tools.Decision? — per-call decision; nil falls through to generic permissions.
override boolean Replace a core tool of the same name (advanced).

smelt.win.Win

Window handle returned by smelt.win.new(buf, opts?). Setter methods return the same handle for chaining.

Field Type Required Description
close fun(): nil yes Close the overlay leaf. No-op if the window is already closed.
focus fun(): nil yes Move keyboard focus to this window. No-op if the window is not focusable.
buf fun(): smelt.buf.Buf? yes Return the backing Buf handle, or nil if the window is gone.
rect fun(): any yes Return the window's current viewport rect as { row, col, width, height }, or nil until the first render lays it out.
content_width fun(): any yes Return the inner-content width in cells (gutter and pad_left/pad_right already subtracted), or nil until the first render lays the window out. Use this instead of rect().width when fitting text into the window's actual content budget.
cursor fun(row: integer?): any yes Read or write the cursor row (0-based). Without arg returns the row; with arg sets and returns the handle for chaining.
move_cursor fun(delta: integer): smelt.win.Win yes Move the cursor by delta rows (clamped to the buffer's line count). Returns the handle for chaining.
key fun(chord: string, func: fun(value: table)): smelt.Reg yes Bind func to chord on this window. Returns a Reg handle whose :remove() undoes the binding. Raises on unknown chords.
on fun(event: smelt.win.Event, func: fun(value: table)): smelt.Reg yes Subscribe func to event on this window. Returns a Reg handle whose :remove() undoes the subscription.
link_scroll fun(others: smelt.win.Win): smelt.win.Win yes Link scroll_top between this window and the variadic others. Closing any member auto-removes it. Returns the handle for chaining.
scroll fun(arg: any): any yes Read or write the window's scroll state. No arg returns { top, follow, total, viewport } (total is the buffer's line count; viewport is the leaf's height). An integer sets scroll_top and clears the pin-to-tail flag. The literal string "tail" re-pins the viewport to the buffer's tail.

Aliases

smelt.buf.VirtTextPos

Where a virtual-text chunk is rendered relative to the line.

Variants: "inline" | "overlay" | "right_align" | "eol"

smelt.cell.Name

Name of a reactive cell. Open alias — plugin-defined cells declared via smelt.cell.new are accepted alongside the well-known runtime cells listed here.

Open alias — accepts any string. Well-known names: "agent_mode" | "block_done" | "branch" | "cmd_post" | "cmd_pre" | "confirm_requested" | "confirm_resolved" | "confirms_pending" | "cwd" | "errors" | "history" | "input_submit" | "model" | "now" | "reasoning" | "session_ended" | "session_started" | "session_title" | "shutdown" | "spinner_frame" | "stream_delta" | "tokens_used" | "tool_end" | "tool_start" | "turn_complete" | "turn_end" | "turn_error" | "turn_start" | "vim_mode".

smelt.cli.FlagKind

Type of CLI flag declared via smelt.cli.register_flag. Matches the subset of clap that we expose to Lua.

Variants: "boolean" | "string" | "integer"

smelt.mode.Mode

Agent mode string literal.

Variants: "normal" | "plan" | "apply" | "yolo"

smelt.paint.Event

Paint-leaf events accepted by paint:on(event, fn).

Variants: "press" | "release" | "drag"

smelt.reasoning.Effort

Reasoning effort level string literal.

Variants: "off" | "low" | "medium" | "high" | "max"

smelt.tools.Decision

Decision string accepted by decide callbacks and permission_defaults. Matches protocol::Decision::{Allow, Ask, Deny} — the engine's Error(_) variant is not exposed.

Variants: "allow" | "ask" | "deny"

smelt.vim.Mode

Vim mode string literal.

Variants: "insert" | "normal" | "visual" | "visual_line"

smelt.win.Event

Window-event names accepted by win:on(event, fn). Maps onto the internal WinEvent enum.

Variants: "open" | "close" | "focus" | "blur" | "selection_changed" | "submit" | "text_changed" | "dismiss" | "tick" | "press" | "release" | "drag" | "scrolled" | "resized"