smelt.session¶

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

Current session metadata, turn list, message snapshots, rewind, and persisted session management. UiHost-only.

smelt.session.context_tokens¶

fun(): integer?

Most recent prompt-token count reported by the provider, or nil if no turn has completed yet.

smelt.session.context_window¶

fun(): integer?

Configured context-window size in tokens for the active model. nil when the model entry has no declared limit.

smelt.session.cost¶

fun(): number

Cumulative session cost in USD across every model call this session has made.

smelt.session.created_at_ms¶

fun(): integer

Unix-epoch timestamp (milliseconds) at which this session was started.

smelt.session.cwd¶

fun(): string

Working directory the session was launched from. Stable across the session.

smelt.session.delete¶

fun(id: string): nil

Delete the persisted session with id. Refuses to delete the currently active session.

smelt.session.dir¶

fun(): string

Absolute path of the on-disk session directory (transcript JSONL, attachments, ledger).

smelt.session.fork¶

fun(): nil

Fork the current session: clone its messages into a new session id and switch to it. Useful for branching off an experiment without losing the original timeline.

smelt.session.id¶

fun(): string

Stable session id (matches the on-disk session filename).

smelt.session.list¶

fun(): table

List persisted sessions other than the current one. Each row carries id, title, subtitle, cwd, parent_id, updated_at_ms, created_at_ms, and size_bytes when available.

smelt.session.load¶

fun(id: string): nil

Switch the UI to the persisted session with id. Replays its message log and resets transient state.

smelt.session.reset¶

fun(): nil

Cancel any in-flight agent and clear the session to a blank slate. Logs an agent_stop event with reason user_cancel_and_clear.

smelt.session.rewind_to¶

fun(block_idx: integer?, opts: table?): nil

Rewind the session to a prior user turn. block_idx = nil rewinds to before the first turn; opts.restore_vim_insert = true re-enters vim insert mode after the rewind.

smelt.session.system¶

fun(): string

Currently-assembled system prompt sent on the next turn. Reflects every prompt section (base, skills, instructions). Useful for auxiliary LLM calls that want to share the main turn's prompt-cache slot.

smelt.session.text¶

fun(id: string): string?

Return the searchable plain-text blob for session id (user + assistant text only; reasoning, tool output, and system messages excluded). Returns nil when the session is missing. Reads the content.txt sidecar; falls back to rebuilding from session.json and caching the sidecar for legacy sessions.

smelt.session.texts¶

fun(ids: string[]): table

Parallel batch read of session.text(id) for many ids. Returns a table keyed by id; missing sessions are omitted. Use this when a picker needs to search across all sessions — the heavy IO happens on a worker pool rather than serializing on the Lua thread.

smelt.session.tokens¶

fun(): table

Cumulative token usage across every turn this session has made. Returns a table with input, output, cache_read, cache_write, reasoning, total (input + output), and cache_hit_ratio (cache_read / (input + cache_read), nil if no input observed yet).

smelt.session.turns¶

fun(): table

Return user turns as { block_idx, label } rows where label is the first line of the user message. Used by the rewind dialog.