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.



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

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



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

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



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

def cwd
  @cwd
end

Class Method Details

.safe_cwd(cwd) ⇒ Object 



480
481
482
 
# File 'lib/kward/session_store.rb', line 480

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 



401
402
403
404
405
406
407
408
409
 
# File 'lib/kward/session_store.rb', line 401

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 



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

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 



459
460
461
462
463
464
 
# File 'lib/kward/session_store.rb', line 459

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 



466
467
468
469
470
471
472
473
474
475
476
477
478
 
# File 'lib/kward/session_store.rb', line 466

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



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

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

#capture_branch(path) ⇒ Hash

Returns the complete persisted active branch for an explicit export-like consumer. Unlike #load, this does not attach a conversation or mutate the session file.

Returns:

  • (Hash) —

    session metadata, saved system-prompt snapshots, and active branch records



448
449
450
451
452
453
454
455
456
457
 
# File 'lib/kward/session_store.rb', line 448

def capture_branch(path)
  resolved_path = resolve_session_path(path)
  records = records_from_file(resolved_path)
  {
    path: resolved_path,
    header: session_header(records, resolved_path),
    system_prompts: records.select { |record| record["type"] == "system_prompt" },
    entries: branch_records(records)
  }
end

#capture_candidates ⇒ Object

Lists all persisted sessions under this config directory for an explicit user-selected operation such as skill capture. Unlike #recent, this is not scoped to the store's current workspace.



321
322
323
324
325
326
 
# File 'lib/kward/session_store.rb', line 321

def capture_candidates
  pattern = File.join(@config_dir, "sessions", "**", "*.jsonl")
  Dir.glob(pattern).filter_map { |path| session_info(path) }.sort_by(&:modified_at).reverse
rescue StandardError
  []
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.



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
215
 
# File 'lib/kward/session_store.rb', line 189

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 



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

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 



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

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:



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

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 = persistence_copy(messages)
  persisted.each { |message| session.append_message(message) }
  conversation = Conversation.new(messages: persistence_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



439
440
441
 
# File 'lib/kward/session_store.rb', line 439

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



362
363
364
365
366
367
368
369
370
371
 
# File 'lib/kward/session_store.rb', line 362

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 



336
337
338
 
# File 'lib/kward/session_store.rb', line 336

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.



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
307
 
# File 'lib/kward/session_store.rb', line 270

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, Array<String>, nil) (defaults to: nil) —

    live empty session path(s) to preserve while omitting them from results

Returns:



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

def recent(limit: 20, keep_empty_path: nil)
  recent_sessions(limit: limit, keep_empty_path: keep_empty_path)
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



355
356
357
 
# File 'lib/kward/session_store.rb', line 355

def recent_tree(limit: 20, keep_empty_path: nil)
  decorate_tree(recent_sessions(limit: limit, keep_empty_path: keep_empty_path))
end

#remember_last_session(session) ⇒ Object

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



329
330
331
332
333
334
 
# File 'lib/kward/session_store.rb', line 329

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



341
342
343
344
345
346
347
348
349
350
 
# File 'lib/kward/session_store.rb', line 341

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 



373
374
375
 
# File 'lib/kward/session_store.rb', line 373

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



418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/kward/session_store.rb', line 418

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) 


434
435
436
 
# File 'lib/kward/session_store.rb', line 434

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



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

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



412
413
414
415
 
# File 'lib/kward/session_store.rb', line 412

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