Kward

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

  • #cwd ⇒ String readonly

    Workspace directory this store lists and creates sessions for.

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

#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 



452
453
454
 
# File 'lib/kward/session_store.rb', line 452

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 



389
390
391
392
393
394
395
396
397
 
# File 'lib/kward/session_store.rb', line 389

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 



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

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 



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

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 



438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/kward/session_store.rb', line 438

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



369
370
371
372
373
374
375
376
377
378
379
 
# File 'lib/kward/session_store.rb', line 369

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.



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

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 



213
214
215
216
217
218
219
 
# File 'lib/kward/session_store.rb', line 213

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 



221
222
223
224
225
226
227
228
229
230
 
# File 'lib/kward/session_store.rb', line 221

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:



241
242
243
244
245
246
247
248
249
 
# File 'lib/kward/session_store.rb', line 241

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



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

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



350
351
352
353
354
355
356
357
358
359
 
# File 'lib/kward/session_store.rb', line 350

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 



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

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.



266
267
268
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
 
# File 'lib/kward/session_store.rb', line 266

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"]
  )
  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:



309
310
311
312
 
# File 'lib/kward/session_store.rb', line 309

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



341
342
343
344
345
 
# File 'lib/kward/session_store.rb', line 341

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.



315
316
317
318
319
320
 
# File 'lib/kward/session_store.rb', line 315

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



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

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 



361
362
363
 
# File 'lib/kward/session_store.rb', line 361

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



406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/kward/session_store.rb', line 406

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) 


422
423
424
 
# File 'lib/kward/session_store.rb', line 422

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



254
255
256
257
258
259
 
# File 'lib/kward/session_store.rb', line 254

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



400
401
402
403
 
# File 'lib/kward/session_store.rb', line 400

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