Skip to content
Kward Search API index

Class: Kward::SessionStore

Inherits:
Object
  • Object
show all
Defined in:
lib/kward/session_store.rb

Overview

JSONL-backed persistence for CLI and RPC conversations.

A session file is an append-only event log: a header record, message/tree records, metadata changes, memory state, tool execution metadata, labels, and branch navigation. SessionStore owns disk layout and reconstruction of a Conversation; frontends own when to create, resume, clone, compact, or delete sessions.

The tree fields (id, parentId, leaf records, labels) are part of the persisted user-data contract. Keep backward compatibility in mind before changing record shapes, and prefer adding records over rewriting existing files.

Defined Under Namespace

Classes: Session, SessionInfo

Constant Summary collapse

VERSION = 
2
LAST_SESSION_FILENAME = 
"last_session.json"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config_dir: ConfigFiles.config_dir, cwd: Dir.pwd) ⇒ SessionStore

Creates an object for JSONL session persistence.



173
174
175
176
 
# File 'lib/kward/session_store.rb', line 173

def initialize(config_dir: ConfigFiles.config_dir, cwd: Dir.pwd)
  @config_dir = config_dir
  @cwd = File.expand_path(cwd)
end

Instance Attribute Details

#config_dir ⇒ String (readonly)

Returns configuration directory containing session and tab files.

Returns:

  • (String) —

    configuration directory containing session and tab files



182
183
184
 
# File 'lib/kward/session_store.rb', line 182

def config_dir
  @config_dir
end

#cwd ⇒ String (readonly)

Returns workspace directory this store lists and creates sessions for.

Returns:

  • (String) —

    workspace directory this store lists and creates sessions for



179
180
181
 
# File 'lib/kward/session_store.rb', line 179

def cwd
  @cwd
end

Class Method Details

.safe_cwd(cwd) ⇒ Object 



456
457
458
 
# File 'lib/kward/session_store.rb', line 456

def self.safe_cwd(cwd)
  "--#{File.expand_path(cwd).sub(%r{\A[/\\]}, "").gsub(%r{[/\\:]}, "-")}--"
end

Instance Method Details

#append_label_change(path, entry_id, label) ⇒ Object 



393
394
395
396
397
398
399
400
401
 
# File 'lib/kward/session_store.rb', line 393

def append_label_change(path, entry_id, label)
  append_record(path, {
    type: "label",
    id: next_entry_id(path),
    timestamp: Time.now.utc.iso8601(3),
    targetId: entry_id.to_s,
    label: label.to_s.strip.empty? ? nil : label.to_s.strip
  })
end

#append_leaf_change(path, leaf_id) ⇒ Object 



385
386
387
388
389
390
391
 
# File 'lib/kward/session_store.rb', line 385

def append_leaf_change(path, leaf_id)
  append_record(path, {
    type: "leaf",
    timestamp: Time.now.utc.iso8601(3),
    targetId: leaf_id
  })
end

#append_record(path, record) ⇒ Object 



435
436
437
438
439
440
 
# File 'lib/kward/session_store.rb', line 435

def append_record(path, record)
  File.open(path, "a", 0o600) do |file|
    file.write(JSON.generate(record))
    file.write("\n")
  end
end

#append_system_prompt_snapshot(path, system_message, reason: "changed") ⇒ Object 



442
443
444
445
446
447
448
449
450
451
452
453
454
 
# File 'lib/kward/session_store.rb', line 442

def append_system_prompt_snapshot(path, system_message, reason: "changed")
  content = MessageAccess.content(system_message).to_s
  return if content.empty?
  return if latest_system_prompt_hash(records_from_file(path)) == system_prompt_hash(content)

  append_record(path, {
    type: "system_prompt",
    timestamp: Time.now.utc.iso8601(3),
    reason: reason.to_s,
    hash: system_prompt_hash(content),
    content: content
  })
end

#build_tree_record(path, type, parent_id, fields = {}) ⇒ Hash

Builds a persisted tree record and assigns a stable entry id to messages.

Returns:

  • (Hash) —

    JSONL-ready tree record



373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/kward/session_store.rb', line 373

def build_tree_record(path, type, parent_id, fields = {})
  message = fields[:message]
  id = message_entry_id(message) || next_entry_id(path)
  assign_message_entry_id(message, id) if message.is_a?(Hash)
  {
    type: type,
    id: id,
    parentId: parent_id,
    timestamp: Time.now.utc.iso8601(3)
  }.merge(fields).delete_if { |_key, value| value.nil? }
end

#create(provider: nil, model: nil, reasoning_effort: nil, parent_id: nil, parent_path: nil) ⇒ Object

Creates a new empty session file for the store's workspace directory.

Parent fields record clone/fork ancestry; they do not imply live coupling between files after creation.



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/kward/session_store.rb', line 188

def create(provider: nil, model: nil, reasoning_effort: nil, parent_id: nil, parent_path: nil)
  dir = session_dir
  FileUtils.mkdir_p(dir, mode: 0o700)
  created_at = Time.now.utc
  id = SecureRandom.uuid
  path = File.join(dir, "#{created_at.iso8601(3).tr(':', '-')}_#{id}.jsonl")
  header = {
    type: "session",
    version: VERSION,
    id: id,
    timestamp: created_at.iso8601(3),
    cwd: @cwd,
    provider: provider.to_s,
    model: model.to_s,
    reasoningEffort: reasoning_effort.to_s,
    parentId: parent_id.to_s,
    parentPath: parent_path.to_s
  }.delete_if { |_key, value| value.to_s.empty? }

  File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
    file.write(JSON.generate(header))
    file.write("\n")
  end
  File.chmod(0o600, path)

  Session.new(store: self, id: id, path: path, cwd: @cwd, created_at: created_at, parent_id: parent_id, parent_path: parent_path, leaf_id: nil)
end

#create_from_conversation(conversation, parent_session: nil) ⇒ Object 



216
217
218
219
220
221
222
 
# File 'lib/kward/session_store.rb', line 216

def create_from_conversation(conversation, parent_session: nil)
  session = create(provider: conversation.provider, model: conversation.model, reasoning_effort: conversation.reasoning_effort, parent_id: parent_session&.id, parent_path: parent_session&.path)
  session.rename(parent_session.name) unless parent_session&.name.to_s.strip.empty?
  persisted_messages(conversation).each { |message| session.append_message(message) }
  session.attach(conversation)
  session
end

#create_independent_from_conversation(conversation, parent_session: nil) ⇒ Object 



224
225
226
227
228
229
230
231
232
233
 
# File 'lib/kward/session_store.rb', line 224

def create_independent_from_conversation(conversation, parent_session: nil)
  create_independent_from_messages(
    persisted_messages(conversation),
    read_paths: Array(conversation.read_paths),
    provider: conversation.provider,
    model: conversation.model,
    reasoning_effort: conversation.reasoning_effort,
    parent_session: parent_session
  )
end

#create_independent_from_messages(messages, read_paths: [], provider: nil, model: nil, reasoning_effort: nil, parent_session: nil) ⇒ Array(Session, Conversation)

Creates a new session containing an independent copy of selected messages.

Used by clone/fork flows where the new conversation must preserve selected history but then diverge without mutating the source session file.

Parameters:

  • messages (Array<Hash>) —

    messages to persist into the new session

  • read_paths (Array<String>) (defaults to: []) —

    restored read-before-write paths

  • parent_session (Session, nil) (defaults to: nil) —

    optional source session metadata

Returns:



244
245
246
247
248
249
250
251
252
 
# File 'lib/kward/session_store.rb', line 244

def create_independent_from_messages(messages, read_paths: [], provider: nil, model: nil, reasoning_effort: nil, parent_session: nil)
  session = create(provider: provider, model: model, reasoning_effort: reasoning_effort, parent_id: parent_session&.id, parent_path: parent_session&.path)
  session.rename(parent_session.name) unless parent_session&.name.to_s.strip.empty?
  persisted = deep_copy(messages)
  persisted.each { |message| session.append_message(message) }
  conversation = Conversation.new(messages: deep_copy(persisted), read_paths: read_paths, workspace_root: @cwd, provider: provider, model: model, reasoning_effort: reasoning_effort)
  session.attach(conversation)
  [session, conversation]
end

#current_leaf(path) ⇒ String?

Returns current active tree leaf id.

Returns:

  • (String, nil) —

    current active tree leaf id



431
432
433
 
# File 'lib/kward/session_store.rb', line 431

def current_leaf(path)
  current_leaf_id(records_from_file(resolve_session_path(path)))
end

#delete_unused_session(session) ⇒ Boolean

Deletes an empty unnamed session file.

Returns:

  • (Boolean) —

    true when a file was removed



354
355
356
357
358
359
360
361
362
363
 
# File 'lib/kward/session_store.rb', line 354

def delete_unused_session(session)
  path = session.path
  return false if session_named?(session)
  return false unless unused_session_file?(path)

  File.delete(path)
  true
rescue StandardError
  false
end

#last_session_path ⇒ Object 



326
327
328
 
# File 'lib/kward/session_store.rb', line 326

def last_session_path
  File.join(session_dir, LAST_SESSION_FILENAME)
end

#load(path, workspace: Workspace.new, provider: nil, model: nil, reasoning_effort: nil) ⇒ Object

Loads a session file and reconstructs its current conversation leaf.

workspace is used both for the active root and to restore read-before-write paths from successful read tool results. If a session moved workspaces, load it through session_location first so the original cwd is respected.



269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/kward/session_store.rb', line 269

def load(path, workspace: Workspace.new, provider: nil, model: nil, reasoning_effort: nil)
  resolved_path = resolve_session_path(path)
  records = records_from_file(resolved_path)
  header = session_header(records, resolved_path)

  leaf_id = current_leaf_id(records)
  messages = restored_messages(records)
  name = session_name(records)
  read_paths = restored_read_paths(messages, workspace)
  memory_state = restored_memory_state(records)

  runtime = session_runtime(records, header)
  conversation = Conversation.new(
    messages: messages,
    read_paths: read_paths,
    workspace_root: workspace.root,
    provider: runtime["provider"] || provider,
    model: runtime["model"] || model,
    reasoning_effort: runtime["reasoningEffort"] || reasoning_effort,
    session_memories: memory_state["sessionMemories"],
    last_memory_retrieval: memory_state["lastRetrieval"]
  )
  restore_tool_output_artifacts(records, conversation)
  conversation.mark_last_entry_compaction! if latest_record_type(records) == "compaction"
  session = Session.new(
    store: self,
    id: header["id"],
    path: resolved_path,
    cwd: header["cwd"].to_s,
    created_at: parse_time(header["timestamp"]) || File.mtime(resolved_path),
    name: name,
    parent_id: header["parentId"],
    parent_path: header["parentPath"],
    leaf_id: leaf_id
  )
  session.attach(conversation)
  [session, conversation]
end

#recent(limit: 20, keep_empty_path: nil) ⇒ Array<SessionInfo>

Lists recent non-empty sessions for this workspace.

Parameters:

  • limit (Integer, nil) (defaults to: 20) —

    maximum number of sessions, or nil for all

  • keep_empty_path (String, nil) (defaults to: nil) —

    empty session path to keep visible

Returns:



313
314
315
316
 
# File 'lib/kward/session_store.rb', line 313

def recent(limit: 20, keep_empty_path: nil)
  sessions = recent_sessions(keep_empty_path: keep_empty_path)
  limit ? sessions.first(limit) : sessions
end

#recent_tree(limit: 20, keep_empty_path: nil) ⇒ Array<SessionInfo>

Lists recent sessions decorated with parent/branch display metadata.

Returns:

  • (Array<SessionInfo>) —

    recent sessions with tree depth fields



345
346
347
348
349
 
# File 'lib/kward/session_store.rb', line 345

def recent_tree(limit: 20, keep_empty_path: nil)
  sessions = recent_sessions(keep_empty_path: keep_empty_path)
  sessions = sessions.first(limit) if limit
  decorate_tree(sessions)
end

#remember_last_session(session) ⇒ Object

Persists the last active session pointer for workspace auto-resume.



319
320
321
322
323
324
 
# File 'lib/kward/session_store.rb', line 319

def remember_last_session(session)
  return unless session&.path

  FileUtils.mkdir_p(session_dir, mode: 0o700)
  PrivateFile.write_json(last_session_path, { "path" => File.expand_path(session.path), "timestamp" => Time.now.utc.iso8601(3) })
end

#remembered_last_session_path ⇒ String?

Returns remembered session path when the file still exists.

Returns:

  • (String, nil) —

    remembered session path when the file still exists



331
332
333
334
335
336
337
338
339
340
 
# File 'lib/kward/session_store.rb', line 331

def remembered_last_session_path
  return nil unless File.file?(last_session_path)

  path = JSON.parse(File.read(last_session_path))["path"].to_s
  return nil if path.empty? || !File.file?(path)

  path
rescue JSON::ParserError
  nil
end

#session_dir ⇒ Object 



365
366
367
 
# File 'lib/kward/session_store.rb', line 365

def session_dir
  File.join(@config_dir, "sessions", self.class.safe_cwd(@cwd))
end

#session_entries(path) ⇒ Array<Hash>

Returns flat tree records with resolved labels attached.

Returns:

  • (Array<Hash>) —

    flat tree records with resolved labels attached



410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/kward/session_store.rb', line 410

def session_entries(path)
  records = records_from_file(resolve_session_path(path))
  labels = labels_by_target(records)
  timestamps = label_timestamps_by_target(records)
  records.select { |record| tree_entry_record?(record) }.map do |record|
    id = record["id"].to_s
    record.dup.tap do |copy|
      copy["resolvedLabel"] = labels[id] if labels.key?(id)
      copy["labelTimestamp"] = timestamps[id] if timestamps.key?(id)
    end
  end
end

#session_entry(path, entry_id) ⇒ Hash?

Finds one persisted tree entry by id.

Returns:

  • (Hash, nil) 


426
427
428
 
# File 'lib/kward/session_store.rb', line 426

def session_entry(path, entry_id)
  session_entries(path).find { |record| record["id"].to_s == entry_id.to_s }
end

#session_location(path) ⇒ Hash

Resolves a user-provided path and returns the stored workspace location.

Returns:

  • (Hash) —

    :path and :cwd for loading the session safely



257
258
259
260
261
262
 
# File 'lib/kward/session_store.rb', line 257

def session_location(path)
  resolved_path = resolve_session_path(path)
  records = records_from_file(resolved_path)
  header = session_header(records, resolved_path)
  { path: resolved_path, cwd: header["cwd"].to_s.empty? ? @cwd : header["cwd"].to_s }
end

#session_tree(path) ⇒ Array<Hash>

Returns nested session tree roots for the given session file.

Returns:

  • (Array<Hash>) —

    nested session tree roots for the given session file



404
405
406
407
 
# File 'lib/kward/session_store.rb', line 404

def session_tree(path)
  records = records_from_file(resolve_session_path(path))
  build_session_tree(records)
end