smelt.engine¶
Tier: Mixed - Contains both Host and UiHost functions; each function below lists its exact tier.
Classification: Supported - Primary alpha facade for user config and plugins.
LLM engine control - cancel, ask, inherited ask, submit commands, and request tool approval. UiHost-only.
smelt.engine.ask¶
Types: smelt.engine.AskSpec
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
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 (response, err), where response is a structured assistant message table on success. Returns the request id.
smelt.engine.ask_inherited¶
Types: smelt.engine.InheritedAskSpec
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Run an auxiliary LLM request that inherits the current session's assembled system prompt and active tool list. When spec.messages is omitted or empty, the live model-visible history is inherited exactly; otherwise the supplied full protocol::Message rows override the inherited history while preserving the same prompt structure. spec.on_response fires once with (response, err), where response is a structured assistant message table on success. Returns the request id.
smelt.engine.cancel¶
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Cancel the in-flight turn or foreground/background work. If queued prompt messages are waiting during a turn, restores them to the prompt instead of cancelling. In-flight smelt.engine.ask requests are unaffected and may still fire callbacks unless their lifecycle guard expires.
smelt.engine.has_active_turn¶
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Return true while a turn is being prepared, persisted, executed, or finalized.
smelt.engine.is_running¶
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
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¶
Types: smelt.engine.AskMessage, smelt.Reg
Tier: Host - Available in every runtime, including headless mode.
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 - with { action = "replace", messages = messages } (engine swaps it in and retries the turn), { action = "abort", message = message } (engine aborts with that terminal error), or nil / { action = "continue" } (engine continues without recovery). 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.on_prepare_request¶
Types: smelt.engine.PrepareRequest, smelt.Reg
Tier: Host - Available in every runtime, including headless mode.
Register a hook the engine calls immediately before each provider request. hook receives { messages, estimated_tokens, estimated_context_tokens } and a reply callback the hook MUST call exactly once - with { action = "replace", messages = messages } (engine swaps it in before sampling), { action = "replace", source = "model_history" } (engine uses the current checkpointed session model history), { action = "abort", message = message } (engine aborts with that terminal error), or nil / { action = "continue" } (engine sends the original request). messages is built lazily when the hook reads it. Returns a Reg whose :remove() drops the hook.
smelt.engine.reload¶
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Queue a transactional Lua reload for the next safe point. The candidate evaluates in a fresh Lua runtime and replaces commands, keymaps, tools, hooks, timers, signals, providers, settings, and generation-owned UI resources only after loading and runtime resolution succeed. An open modal is dismissed before the request is queued.
smelt.engine.reload_when_idle¶
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Schedule a full config reload for the next safe idle point, including prompt inputs such as AGENTS.md, skills, and --system-prompt. Returns true when this call queued a new reload and false when one was already pending.
smelt.engine.submit_command¶
Types: smelt.engine.CommandOverrides
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Start an agent turn from a Lua-defined custom command (/name). display overrides the transcript label while name remains the command id. Queues behind the active turn if the agent is already running. See smelt.engine.CommandOverrides for the override shape.
smelt.engine.submit_command_continuation¶
fun(name: string, body: string, overrides: smelt.engine.CommandOverrides?, display: string?, continuation_token: integer?): boolean
Types: smelt.engine.CommandOverrides
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Start an idle custom-command continuation without using the prompt queue. Returns false instead of queuing when a turn, compaction, or busy token is active or when continuation_token does not match the most recent completed turn. When it starts, the work elapsed timer carries forward from that completed turn.
smelt.engine.summary_prefix¶
Tier: Host - Available in every runtime, including headless mode.
Return the canonical compaction-summary prefix used when a checkpoint summary is represented as a user message.