history:add(payload) -> ok

Add a pre-built entry to history

Accepts a payload table with at minimum a cmd field. The caller is responsible for building metadata and filtering unwanted entries. Persists via store if configured.

history:stash(entry)

Stash the current input for later retrieval

history:get() -> cmd

Get the command at the current history position

Returns the stashed entry when position is 0 (most recent), otherwise returns the command string at the current position.

history:up() -> moved

Move one entry back in history, skipping consecutive duplicates

history:down() -> moved

Move one entry forward in history, skipping consecutive duplicates

history:load()

Load history entries from the backing store

Loads entries from the configured store into the in-memory history. Returns nothing on success. Returns nil, err_string if the store cannot be read.

history:entries() -> entries

Return the raw entries array

history:last_arg() -> arg

Get the last argument from the most recent command

history:recent(n) -> entries

Return the last N history entries as {cmd, exit} tables

history:entries_count() -> count

Return the total number of history entries

history:position_get() -> position

Return the current navigation position in history

new(mode, store) -> history

Create a new history instance

Creates a history object for the given mode (e.g. "shell", "lua"). If store is provided, history is persisted and loaded on creation.