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, and spec.reasoning_effort explicitly selects a known or provider-defined effort supported by that model. Omitted effort starts at "off" and reconciles to the selected model's advertised levels. 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, active tool list, and reasoning effort. 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. Explicit reasoning effort must be supported by the selected model; omitted effort inherits the session's effort and reconciles it to the selected model's advertised levels. 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. During an error pause, stops automatic resume and cancels foreground busy work without discarding queued messages. If queued prompt messages are waiting during an active 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.continuation_state¶
Types: smelt.engine.ContinuationState
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Return the current session's continuation token and pause state. A new turn, cancellation, or session change invalidates scheduled continuations.
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. Includes prompt inputs such as AGENTS.md, skills, and --system-prompt. While the agent is working, the reload waits until idle without dismissing open modals. When idle, 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.resume_paused¶
Tier: UiHost - Requires a terminal UI; calling these from headless mode raises.
Resume the interrupted conversation with its command-scoped overrides, without adding a user message or advancing the turn queue. Returns false if the token is stale, the session is not paused, or execution is blocked by busy work or a modal. The token must come from continuation_state; callers choose the retry timing.
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.