HistoryStore
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:156
A thin, fail-soft wrapper over a node:sqlite connection holding the session history.
Obtain one via openHistoryStore (which returns null if the DB can’t be opened). Every
method is defensive: on any SQLite error it returns a safe empty/zero result rather than
throwing, so callers on a run’s hot path never have to guard.
Methods
Section titled “Methods”close()
Section titled “close()”close():
void
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:579
Close the underlying connection (fail-soft).
Returns
Section titled “Returns”void
getConversationThread()
Section titled “getConversationThread()”getConversationThread(
conversationId):SessionRecord[]
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:479
GS2-19 — all turns of one conversation in chronological (insert) order, so a search hit can be expanded into the whole thread it belonged to. Fail-soft ([] on error / unknown id).
Parameters
Section titled “Parameters”conversationId
Section titled “conversationId”number
Returns
Section titled “Returns”insights()
Section titled “insights()”insights(
topN?):HistoryInsights
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:501
Aggregate token/cost totals, a top-tool tally, and a per-command breakdown over the whole
store. Tool tallying reads each row’s JSON tools array in JS (robust to nulls). Fail-soft:
returns a zeroed summary on any error.
Parameters
Section titled “Parameters”number = 10
Returns
Section titled “Returns”listConversations()
Section titled “listConversations()”listConversations(
limit?):ConversationSummary[]
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:436
GS2-19 — conversations newest-first, each with its turn count, timespan, and a preview of the
last turn. This is the top-level unit for gth history list (the turn-grained listRecent
remains for callers that want raw turns). Fail-soft ([] on error).
Empty conversations are excluded (HAVING COUNT(s.id) > 0): a session opens its conversation
at start (before any turn), so one that exits with zero turns would otherwise show as a
contentless turnCount: 0 row. The LEFT JOIN still keeps every conversation that has ≥1 turn —
including back-filled 1-turn conversations, whose single turn satisfies the HAVING.
Parameters
Section titled “Parameters”limit?
Section titled “limit?”number = 20
Returns
Section titled “Returns”listRecent()
Section titled “listRecent()”listRecent(
limit?):SessionSearchResult[]
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:404
Most recent sessions, newest first. Fail-soft ([] on error).
Parameters
Section titled “Parameters”limit?
Section titled “limit?”number = 20
Returns
Section titled “Returns”openConversation()
Section titled “openConversation()”openConversation(
meta?):number|null
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:293
GS2-19 — open a new conversation and return its id (or null on any error). Interactive
sessions call this once at start, then pass the id on every record so all the session’s
turns group under it. A single-shot run does not need this: record opens a 1-turn
conversation itself when no conversationId is supplied.
Parameters
Section titled “Parameters”ConversationMeta = {}
Returns
Section titled “Returns”number | null
record()
Section titled “record()”record(
rec):number|null
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:312
Persist one session and its full-text index entry. Returns the new row id, or null on any
error (the run continues regardless). The two inserts run in a transaction so a failure can’t
leave the FTS index out of sync with the base table.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”number | null
search()
Section titled “search()”search(
query,limit?):SessionSearchResult[]
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:373
Full-text search over prompt/response/command/project, best match first (FTS5 rank). User
text is sanitised via toFtsMatchQuery; an empty or all-punctuation query returns [].
Any SQLite error yields [] (fail-soft).
Parameters
Section titled “Parameters”string
limit?
Section titled “limit?”number = 20
Returns
Section titled “Returns”open()
Section titled “open()”
staticopen(dbPath,options?):HistoryStore|null
Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/src/history/historyStore.ts:168
Open (and lazily initialise) the store at dbPath. Returns null on any failure — a missing
file when create is false, an unopenable/locked/corrupt DB, or a schema-init error — so the
caller can simply skip history without a try/catch.
Parameters
Section titled “Parameters”dbPath
Section titled “dbPath”string
options?
Section titled “options?”Returns
Section titled “Returns”HistoryStore | null