Class: ClaudeAgentSDK::SessionStore

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

Overview

Adapter for mirroring session transcripts to external storage.

The subprocess still writes to local disk; the adapter receives a secondary copy via SessionStore#append, and ‘resume` can materialize from the store via SessionStore#load when the local file is absent.

Only #append and #load are required. The remaining methods are optional: implementers may omit them, and the SDK probes for their presence via SessionStore.implements? before invoking (it never uses ‘is_a?` for this —a duck-typed adapter need not subclass SessionStore). The default implementations here raise NotImplementedError so subclasses inherit them as “absent” markers.

All keys/entries cross the adapter boundary as Hashes with STRING keys:

- SessionKey: { 'project_key' => String, 'session_id' => String,
                'subpath' => String (optional; omit for the main transcript) }
- entries: raw JSONL transcript objects (opaque pass-through blobs)
- list_sessions result: [{ 'session_id' => String, 'mtime' => Integer }]
- summary entries: { 'session_id', 'mtime', 'data' } (see SessionSummary)

Direct Known Subclasses

InMemorySessionStore

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.implements?(store, method) ⇒ Boolean

True if store overrides method rather than inheriting the base implementation that raises NotImplementedError. Works for both subclasses and duck-typed adapters (whose method owner is their own class).

Returns:

  • (Boolean) 


39
40
41
42
43
44
45
 
# File 'lib/claude_agent_sdk/session_store.rb', line 39

def self.implements?(store, method)
  return false unless store.respond_to?(method)

  store.method(method).owner != SessionStore
rescue NameError
  false
end

Instance Method Details

#append(_key, _entries) ⇒ Object

Mirror a batch of transcript entries. Called AFTER the subprocess’s local write succeeds. Required.

Appends for a given key are normally serialized by the batcher, but if an #append exceeds the send timeout the batcher abandons that (still-running) call and proceeds, so a later #append for the SAME key can overlap it. Implementations must therefore be thread-safe per key (a per-call connection — Postgres/Redis/etc. — satisfies this) and should dedupe by entry when present, since a retried/overlapping batch may repeat a prior write.

Raises:

  • (NotImplementedError) 


57
58
59
 
# File 'lib/claude_agent_sdk/session_store.rb', line 57

def append(_key, _entries)
  raise NotImplementedError, "#{self.class} must implement #append"
end

#delete(_key) ⇒ Object

Delete a session. Deleting a main-transcript key (no subpath) must cascade to all subkeys. Optional — if unimplemented, deletion is a no-op.

Raises:

  • (NotImplementedError) 


82
83
84
 
# File 'lib/claude_agent_sdk/session_store.rb', line 82

def delete(_key)
  raise NotImplementedError
end

#list_session_summaries(_project_key) ⇒ Object

Return incrementally-maintained summaries for all sessions in one call. Optional — if unimplemented, list_sessions_from_store falls back to list_sessions + per-session load.

Raises:

  • (NotImplementedError) 


76
77
78
 
# File 'lib/claude_agent_sdk/session_store.rb', line 76

def list_session_summaries(_project_key)
  raise NotImplementedError
end

#list_sessions(_project_key) ⇒ Object

List sessions for a project_key as [{ ‘session_id’, ‘mtime’ }]. Optional —if unimplemented, list_sessions_from_store raises.

Raises:

  • (NotImplementedError) 


69
70
71
 
# File 'lib/claude_agent_sdk/session_store.rb', line 69

def list_sessions(_project_key)
  raise NotImplementedError
end

#list_subkeys(_key) ⇒ Object

List all subpath keys under a session (e.g. subagent transcripts). Optional — if unimplemented, resume only materializes the main transcript.

Raises:

  • (NotImplementedError) 


88
89
90
 
# File 'lib/claude_agent_sdk/session_store.rb', line 88

def list_subkeys(_key)
  raise NotImplementedError
end

#load(_key) ⇒ Object

Load a full session for resume, or nil for a key that was never written. Required.

Raises:

  • (NotImplementedError) 


63
64
65
 
# File 'lib/claude_agent_sdk/session_store.rb', line 63

def load(_key)
  raise NotImplementedError, "#{self.class} must implement #load"
end