Class: Clacky::SessionManager

Inherits:
Object
  • Object
show all
Defined in:
lib/clacky/session_manager.rb

Constant Summary collapse

SESSIONS_DIR = 
File.join(Dir.home, ".clacky", "sessions")
GROUPED_SOURCES = 
%w[cron ext].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(sessions_dir: nil) ⇒ SessionManager

Returns a new instance of SessionManager.



22
23
24
25
 
# File 'lib/clacky/session_manager.rb', line 22

def initialize(sessions_dir: nil)
  @sessions_dir = sessions_dir || SESSIONS_DIR
  ensure_sessions_dir
end

Class Method Details

.cleanup_orphan_snapshots(sessions_dir: SESSIONS_DIR, snapshots_root: nil) ⇒ Object

Remove Time Machine snapshots that no longer belong to any known session. Snapshots are keyed by full session_id; session files are named by the 8-char id prefix, so a snapshot dir is an orphan when its prefix matches no active or trashed session file. Returns the count of removed dirs.



464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
 
# File 'lib/clacky/session_manager.rb', line 464

def self.cleanup_orphan_snapshots(sessions_dir: SESSIONS_DIR, snapshots_root: nil)
  snapshots_root ||= File.join(Dir.home, ".clacky", "snapshots")
  return 0 unless Dir.exist?(snapshots_root)

  require_relative "utils/trash_directory"
  known = _session_id_prefixes(File.join(sessions_dir, "*.json"))
  trash_dir = Clacky::TrashDirectory.sessions_trash_dir
  known += _session_id_prefixes(File.join(trash_dir, "*.json")) if Dir.exist?(trash_dir)
  known = known.to_set

  removed = 0
  Dir.children(snapshots_root).each do |name|
    dir = File.join(snapshots_root, name)
    next unless File.directory?(dir)
    next if known.include?(name[0, 8])

    FileUtils.rm_rf(dir)
    removed += 1
  end
  removed
end

.generate_id ⇒ Object

Generate a new unique session ID (16-char hex string). This is the single authoritative source for session IDs — all components (Agent, SessionRegistry) should receive an ID generated here rather than creating their own.



18
19
20
 
# File 'lib/clacky/session_manager.rb', line 18

def self.generate_id
  SecureRandom.hex(8)
end

Instance Method Details

#all_sessions(current_dir: nil, limit: nil) ⇒ Object

All sessions from disk, newest-first (sorted by last activity / updated_at, falling back to created_at for legacy sessions without updated_at). Optional filters:

current_dir: (String) if given, sessions matching working_dir come first
limit:       (Integer) max number of sessions to return


200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/clacky/session_manager.rb', line 200

def all_sessions(current_dir: nil, limit: nil)
  sessions = Dir.glob(File.join(@sessions_dir, "*.json")).filter_map do |filepath|
    load_session_file(filepath)
  end.sort_by { |s| s[:updated_at] || s[:created_at] || "" }.reverse

  if current_dir
    current_sessions = sessions.select { |s| s[:working_dir] == current_dir }
    other_sessions   = sessions.reject { |s| s[:working_dir] == current_dir }
    sessions = current_sessions + other_sessions
  end

  limit ? sessions.first(limit) : sessions
end

#chunks_for_current(session_id, created_at) ⇒ Array<Hash>

Discover all chunk MD files on disk for a given session. Returns them sorted by chunk index ascending (oldest first).

Parameters:

  • session_id (String) —

    full session id (or at least first 8 chars)

  • created_at (String) —

    ISO-8601 timestamp used in the base filename

Returns:

  • (Array<Hash>) —

    each with :index, :path, :basename, :topics



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/clacky/session_manager.rb', line 122

def chunks_for_current(session_id, created_at)
  return [] unless session_id && created_at

  base = chunk_base_name(session_id, created_at)
  pattern = File.join(@sessions_dir, "#{base}-chunk-*.md")

  Dir.glob(pattern).filter_map do |path|
    basename = File.basename(path)
    # Extract integer index from "<base>-chunk-<N>.md"
    m = basename.match(/-chunk-(\d+)\.md\z/)
    next nil unless m

    {
      index: m[1].to_i,
      path: path,
      basename: basename,
      topics: read_chunk_topics(path)
    }
  end.sort_by { |c| c[:index] }
end

#cleanup(days: 90) ⇒ Object

Delete sessions not accessed within the given number of days (default: 90). Returns count of deleted sessions.



319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/clacky/session_manager.rb', line 319

def cleanup(days: 90)
  cutoff = Time.now - (days * 24 * 60 * 60)
  deleted = 0
  Dir.glob(File.join(@sessions_dir, "*.json")).each do |filepath|
    session = load_session_file(filepath)
    next unless session
    if Time.parse(session[:updated_at]) < cutoff
      _hard_delete_session_with_chunks(filepath)
      deleted += 1
    end
  end
  deleted
end

#cleanup_by_count(keep:, grouped_keep: 200) ⇒ Object

Keep only the most recent N non-pinned sessions by created_at; the rest are soft-deleted (moved to the session trash, recoverable). Pinned sessions are never deleted and do not count toward the cap. Returns count of soft-deleted sessions.



337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/clacky/session_manager.rb', line 337

def cleanup_by_count(keep:, grouped_keep: 200)
  # Fast path: if total session files can't exceed any single group's cap,
  # skip the expensive all_sessions() full-scan (read + JSON.parse every file).
  # min() is correct because groups are mutually exclusive — any single
  # group's count ≤ non_pinned ≤ file_count ≤ min(keep, grouped_keep).
  file_count = Dir.glob(File.join(@sessions_dir, "*.json")).size
  return 0 if file_count <= [keep, grouped_keep].min

  non_pinned = all_sessions.reject { |s| s[:pinned] }

  groups = non_pinned.group_by do |s|
    (s[:project_id] || !GROUPED_SOURCES.include?(s[:source].to_s)) ? "regular" : s[:source].to_s
  end

  victims = groups.flat_map do |source, sessions|
    sessions[(source == "regular" ? keep : grouped_keep)..] || []
  end

  victims.each { |session| soft_delete(session[:session_id]) }
  victims.size
end

#cleanup_trash(days: 90) ⇒ Object

Clean up soft-deleted sessions older than :days (default: 90).



388
389
390
391
 
# File 'lib/clacky/session_manager.rb', line 388

def cleanup_trash(days: 90)
  require_relative "tools/trash_manager"
  Clacky::Tools::TrashManager.empty_trash_sessions(sessions_dir: @sessions_dir, days: days)
end

#delete(session_id) ⇒ Object

Soft-delete: move session JSON + chunks to the session trash directory. Returns true if found and moved, false if not found.



81
82
83
 
# File 'lib/clacky/session_manager.rb', line 81

def delete(session_id)
  soft_delete(session_id)
end

#ensure_sessions_dir ⇒ Object 



394
395
396
 
# File 'lib/clacky/session_manager.rb', line 394

def ensure_sessions_dir
  FileUtils.mkdir_p(@sessions_dir) unless Dir.exist?(@sessions_dir)
end

#files_for(session_id) ⇒ Object

Return the on-disk files associated with a session: the main JSON file and any "base-chunk-*.md" archive files. Used by the export / download endpoint so the UI can bundle everything a user may need for debugging. Returns nil if the session is not found, or a Hash:

{
session:   Hash,        # the loaded session metadata
json_path: String,      # absolute path to session.json
chunks:    [String]     # sorted absolute paths to chunk *.md files
}


94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/clacky/session_manager.rb', line 94

def files_for(session_id)
  session = all_sessions.find { |s| s[:session_id].to_s.start_with?(session_id.to_s) }
  return nil unless session

  json_path = File.join(@sessions_dir, generate_filename(session[:session_id], session[:created_at]))
  return nil unless File.exist?(json_path)

  base   = File.basename(json_path, ".json")
  chunks = Dir.glob(File.join(@sessions_dir, "#{base}-chunk-*.md")).sort

  { session: session, json_path: json_path, chunks: chunks }
end

#fork(session_id) ⇒ Object

Fork a session: create a copy with new id, "(copy)" name suffix, and reset stats. Returns the forked session data hash, or nil if the original is not found.



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/clacky/session_manager.rb', line 60

def fork(session_id)
  original = load(session_id)
  return nil unless original

  forked = original.dup
  forked[:session_id]  = self.class.generate_id
  forked[:created_at]  = Time.now.iso8601
  forked[:updated_at]  = Time.now.iso8601
  forked[:pinned]      = false
  forked[:name]        = "#{original[:name] || "Unnamed session"} (copy)"
  forked[:stats] = (original[:stats] || {}).merge(
    total_tasks: 0, total_iterations: 0, total_cost_usd: 0.0,
    last_status: nil, last_error: nil
  )

  save(forked)
  forked
end

#generate_filename(session_id, created_at) ⇒ Object 



398
399
400
 
# File 'lib/clacky/session_manager.rb', line 398

def generate_filename(session_id, created_at)
  "#{chunk_base_name(session_id, created_at)}.json"
end

#last_saved_path ⇒ Object

Path of the last saved session file.



49
50
51
 
# File 'lib/clacky/session_manager.rb', line 49

def last_saved_path
  @last_saved_path
end

#latest_for_directory(working_dir) ⇒ Object

Return the most recent session for a given working directory, or nil.



313
314
315
 
# File 'lib/clacky/session_manager.rb', line 313

def latest_for_directory(working_dir)
  all_sessions(current_dir: working_dir).first
end

#list_trash_sessions ⇒ Object

List all soft-deleted sessions (newest-first).



376
377
378
379
 
# File 'lib/clacky/session_manager.rb', line 376

def list_trash_sessions
  require_relative "tools/trash_manager"
  Clacky::Tools::TrashManager.list_trash_sessions(sessions_dir: @sessions_dir)
end

#load(session_id) ⇒ Object

Load a specific session by ID. Returns nil if not found.



54
55
56
 
# File 'lib/clacky/session_manager.rb', line 54

def load(session_id)
  all_sessions.find { |s| s[:session_id].to_s.start_with?(session_id.to_s) }
end

#load_session_file(filepath) ⇒ Object 



454
455
456
457
458
 
# File 'lib/clacky/session_manager.rb', line 454

def load_session_file(filepath)
  JSON.parse(File.read(filepath), symbolize_names: true)
rescue JSON::ParserError, Errno::ENOENT
  nil
end

#next_chunk_index(session_id, created_at) ⇒ Object

Next unused chunk index for a session, derived from disk. This is the ONLY correct way to compute the next chunk index — counting compressed_summary messages in history caps at 1 after the second compression (rebuild keeps only the latest summary) and in-memory counters reset on process restart.



148
149
150
151
 
# File 'lib/clacky/session_manager.rb', line 148

def next_chunk_index(session_id, created_at)
  existing = chunks_for_current(session_id, created_at)
  (existing.map { |c| c[:index] }.max || 0) + 1
end

#permanent_delete_trash_session(session_id) ⇒ Object

Permanently delete one session from the trash — cannot be undone.



382
383
384
385
 
# File 'lib/clacky/session_manager.rb', line 382

def permanent_delete_trash_session(session_id)
  require_relative "tools/trash_manager"
  Clacky::Tools::TrashManager.permanent_delete_trash_session(session_id, sessions_dir: @sessions_dir)
end

#read_chunk(chunk_path) ⇒ Object

Read the raw markdown of a chunk file. Returns nil if missing.



169
170
171
172
 
# File 'lib/clacky/session_manager.rb', line 169

def read_chunk(chunk_path)
  return nil unless chunk_path && File.exist?(chunk_path)
  File.read(chunk_path)
end

#restore_session(session_id) ⇒ Object

Restore a soft-deleted session back to the active sessions directory.



370
371
372
373
 
# File 'lib/clacky/session_manager.rb', line 370

def restore_session(session_id)
  require_relative "tools/trash_manager"
  Clacky::Tools::TrashManager.restore_session(session_id, sessions_dir: @sessions_dir)
end

#save(session_data) ⇒ Object

Save a session. Returns the file path.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/clacky/session_manager.rb', line 28

def save(session_data)
  filename = generate_filename(session_data[:session_id], session_data[:created_at])
  filepath = File.join(@sessions_dir, filename)

  File.write(filepath, JSON.pretty_generate(session_data))
  FileUtils.chmod(0o600, filepath)

  @last_saved_path = filepath

  # Keep only the most recent 200 sessions (best-effort, never block save)
  begin
    cleanup_by_count(keep: 200, grouped_keep: 200)
    cleanup_trash(days: 8)
  rescue Exception # rubocop:disable Lint/RescueException
    # Cleanup is non-critical; swallow all errors (including AgentInterrupted)
  end

  filepath
end

#search_content(query, timeout: 5) ⇒ Object

Full-text grep over session JSON + chunk MD files. Case-sensitive: BSD grep -i is ~30x slower; Chinese has no case. Returns Hash<short_id String => snippet String> (snippet around the first match).



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/clacky/session_manager.rb', line 217

def search_content(query, timeout: 5)
  q = query.to_s
  return {} if q.strip.length < 2

  files = Dir.glob(File.join(@sessions_dir, "*.json")) +
          Dir.glob(File.join(@sessions_dir, "*-chunk-*.md"))
  return {} if files.empty?

  result = {}
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
  each_grep_batch(files) do |batch|
    remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
    break if remaining <= 0
    out = run_with_timeout({ "LC_ALL" => "C" },
                           "grep", "-H", "-F", "-m", "1", "--",
                           q, *batch,
                           timeout: remaining)
    next unless out
    out.each_line do |line|
      path, _, rest = line.chomp.partition(":")
      next if path.empty? || rest.empty?
      sid = extract_short_id(File.basename(path))
      next unless sid
      next if result.key?(sid)
      result[sid] = build_snippet(rest, q)
    end
  end
  result
end

#soft_delete(session_id) ⇒ Object

Soft-delete: stamp deleted_at, move JSON + chunks to sessions-trash/.



364
365
366
367
 
# File 'lib/clacky/session_manager.rb', line 364

def soft_delete(session_id)
  require_relative "tools/trash_manager"
  Clacky::Tools::TrashManager.soft_delete_session(session_id, sessions_dir: @sessions_dir)
end

#split_chunk_md(raw) ⇒ Object

Split raw chunk markdown into [front_matter_hash, body_string]. front_matter_hash preserves insertion order; body is everything after the closing "---". Returns [nil, raw] when there is no leading block.



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/clacky/session_manager.rb', line 177

def split_chunk_md(raw)
  return [nil, raw.to_s] unless raw.to_s.start_with?("---")

  fm_end = raw.index("\n---\n", 4)
  return [nil, raw] unless fm_end

  fm_text = raw[4...fm_end]
  body    = raw[(fm_end + 5)..] || ""

  fm = {}
  fm_text.each_line do |line|
    k, _, v = line.chomp.partition(":")
    next if k.strip.empty?
    fm[k.strip] = v.strip
  end
  [fm, body]
end

#write_chunk(session_id, created_at, chunk_index, md_content) ⇒ Object

Write a chunk MD file to disk. Returns the absolute path. Caller is responsible for generating the MD content — this method only handles filesystem concerns (path assembly, write, chmod).



156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/clacky/session_manager.rb', line 156

def write_chunk(session_id, created_at, chunk_index, md_content)
  return nil unless session_id && created_at

  base = chunk_base_name(session_id, created_at)
  chunk_path = File.join(@sessions_dir, "#{base}-chunk-#{chunk_index}.md")

  File.write(chunk_path, md_content)
  FileUtils.chmod(0o600, chunk_path)

  chunk_path
end