smelt.engine¶

Tier: UiHost — Requires a terminal UI; calling these from headless mode raises.

LLM engine control — cancel, ask, submit commands, and request tool approval. UiHost-only.

smelt.engine.ask¶

fun(spec: smelt.engine.AskSpec): integer

Types: smelt.engine.AskSpec

Run an out-of-band LLM request without touching the main turn. spec.model selects an alternate model (defaults to the primary), spec.response_format enforces a JSON schema, spec.reasoning_effort controls effort (defaults to "off"). spec.on_response fires once with (content, err); on context-window errors err.kind = "context_window" so callers can compose retries in Lua (see smelt.engine.ask_with_trim). Returns the request id.

smelt.engine.ask_with_trim¶

fun(spec: table): integer

Wrap smelt.engine.ask with a trim-and-retry loop for context-window errors: drops the oldest message from spec.messages and re-issues the request up to spec.max_trims times (default 20). spec accepts every field smelt.engine.ask accepts, plus max_trims. The engine itself is one-shot; composition lives here so the policy stays visible.

smelt.engine.cancel¶

fun(): nil

Cancel the in-flight turn. In-flight background smelt.engine.ask requests are unaffected and will still fire their callbacks; plugins owning smelt.spinner.busy tokens are responsible for releasing them.

smelt.engine.is_running¶

fun(): boolean

Return true if an agent turn is currently in flight (a request is being streamed or a tool is executing).

smelt.engine.on_context_limit¶

fun(hook: fun(arg1: smelt.engine.AskMessage[], arg2: fun(value: smelt.engine.AskMessage[]?))): smelt.Reg

Types: smelt.engine.AskMessage, smelt.Reg

Register a recovery hook the engine calls when a provider returns a context-window error mid-turn. hook receives the conversation so far (excluding the system prompt) and a reply callback the hook MUST call exactly once — either with a shorter messages array (engine swaps it in and retries the turn) or nil (engine aborts with the existing TurnError). The first registered hook to call reply wins; later hooks are ignored. Returns a Reg whose :remove() drops the hook. Bundled compact.lua registers a hook that runs the standard summarization flow.

smelt.engine.reload¶

fun(): nil

Re-evaluate every Lua surface: clears every command, keymap, statusline source, tool, hook, timer, and cell subscriber, wipes non-stdlib package.loaded entries, then re-runs the bundled autoload modules, init.lua, global plugins, and .smelt/init.lua + .smelt/plugins/*. early.lua is intentionally skipped — its CLI-flag and smelt.builtins.disable effects are startup-only.

smelt.engine.submit_command¶

fun(name: string, body: string, overrides: smelt.engine.CommandOverrides?): nil

Types: smelt.engine.CommandOverrides

Start an agent turn from a Lua-defined custom command (/name). Notifies and no-ops if an agent is already running. See smelt.engine.CommandOverrides for the override shape.