claude-agent-sdk 0.16.9 → 0.17.0

data/lib/claude_agent_sdk/session_store.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'sessions'
+require_relative 'session_summary'
+
+module ClaudeAgentSDK
+  # Controls when transcript-mirror entries are flushed to a SessionStore.
+  #
+  # - "batched" (default): buffer entries and flush once per turn (on the
+  #   `result` message) or when the pending buffer exceeds 500 entries / 1 MiB.
+  # - "eager": trigger a background flush after every transcript_mirror frame
+  #   so SessionStore#append sees entries in near real time.
+  SESSION_STORE_FLUSH_MODES = %w[batched eager].freeze
+
+  # 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)
+  class SessionStore
+    # 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).
+    def self.implements?(store, method)
+      return false unless store.respond_to?(method)
+
+      store.method(method).owner != SessionStore
+    rescue NameError
+      false
+    end
+
+    # 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["uuid"] when present, since a retried/overlapping batch may repeat
+    # a prior write.
+    def append(_key, _entries)
+      raise NotImplementedError, "#{self.class} must implement #append"
+    end
+
+    # Load a full session for resume, or nil for a key that was never written.
+    # Required.
+    def load(_key)
+      raise NotImplementedError, "#{self.class} must implement #load"
+    end
+
+    # List sessions for a project_key as [{ 'session_id', 'mtime' }]. Optional —
+    # if unimplemented, list_sessions_from_store raises.
+    def list_sessions(_project_key)
+      raise NotImplementedError
+    end
+
+    # 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.
+    def list_session_summaries(_project_key)
+      raise NotImplementedError
+    end
+
+    # Delete a session. Deleting a main-transcript key (no subpath) must cascade
+    # to all subkeys. Optional — if unimplemented, deletion is a no-op.
+    def delete(_key)
+      raise NotImplementedError
+    end
+
+    # List all subpath keys under a session (e.g. subagent transcripts).
+    # Optional — if unimplemented, resume only materializes the main transcript.
+    def list_subkeys(_key)
+      raise NotImplementedError
+    end
+  end
+
+  # In-memory SessionStore for testing and development. Data is lost when the
+  # process exits — not suitable for production.
+  class InMemorySessionStore < SessionStore
+    def initialize
+      super
+      @store = {}
+      @mtimes = {}
+      @summaries = {}
+      @last_mtime = 0
+      # The SessionStore#append contract requires per-key thread-safety, and two
+      # concurrent sessions can share one store (each with its own batcher and
+      # semaphore, so nothing serializes appends across them). Guard all access.
+      @mutex = Mutex.new
+    end
+
+    def append(key, entries)
+      # Same guard as the reference adapters: append(key, []) must not create a
+      # phantom key (load would return [] instead of nil and the session would
+      # appear in listings).
+      return if entries.nil? || entries.empty?
+
+      @mutex.synchronize do
+        k = key_to_string(key)
+        (@store[k] ||= []).concat(entries)
+        now_ms = next_mtime
+        # Maintain the per-session summary sidecar incrementally so
+        # #list_session_summaries never re-reads. Subagent subpaths don't
+        # contribute to the main session's summary.
+        if main_transcript_key?(key)
+          sk = [key['project_key'], key['session_id']]
+          folded = SessionSummary.fold_session_summary(@summaries[sk], key, entries)
+          # Stamp with this adapter's storage write time — the SAME clock
+          # #list_sessions exposes, so the fast-path staleness check works.
+          folded['mtime'] = now_ms
+          @summaries[sk] = folded
+        end
+        @mtimes[k] = now_ms
+      end
+      nil
+    end
+
+    def load(key)
+      @mutex.synchronize do
+        entries = @store[key_to_string(key)]
+        entries&.dup
+      end
+    end
+
+    def list_sessions(project_key)
+      prefix = "#{project_key}/"
+      results = []
+      @mutex.synchronize do
+        @store.each_key do |k|
+          next unless k.start_with?(prefix)
+
+          rest = k[prefix.length..]
+          # Only main transcripts (no subpath, so no second '/').
+          results << { 'session_id' => rest, 'mtime' => @mtimes[k] || 0 } unless rest.include?('/')
+        end
+      end
+      results
+    end
+
+    def list_session_summaries(project_key)
+      @mutex.synchronize do
+        # Return COPIES, not the internal summary objects: #load dups, so this
+        # must too, or a caller mutating a returned summary's data would corrupt
+        # the sidecar that the next fold builds on.
+        @summaries.filter_map do |(pk, _sid), summary|
+          next unless pk == project_key
+
+          { 'session_id' => summary['session_id'], 'mtime' => summary['mtime'], 'data' => summary['data'].dup }
+        end
+      end
+    end
+
+    def delete(key)
+      @mutex.synchronize do
+        k = key_to_string(key)
+        @store.delete(k)
+        @mtimes.delete(k)
+        # Deleting the main transcript cascades to its subkeys so they aren't
+        # orphaned. A targeted delete with an explicit subpath removes only that
+        # one entry. An empty-string subpath is treated as "no subpath" (main),
+        # consistent with key_to_string / append, so it cascades like nil.
+        next unless main_transcript_key?(key)
+
+        @summaries.delete([key['project_key'], key['session_id']])
+        prefix = "#{key['project_key']}/#{key['session_id']}/"
+        @store.keys.select { |sk| sk.start_with?(prefix) }.each do |sk|
+          @store.delete(sk)
+          @mtimes.delete(sk)
+        end
+      end
+      nil
+    end
+
+    def list_subkeys(key)
+      prefix = "#{key['project_key']}/#{key['session_id']}/"
+      @mutex.synchronize do
+        @store.keys.select { |k| k.start_with?(prefix) }.map { |k| k[prefix.length..] }
+      end
+    end
+
+    # -- Test helpers --
+
+    # All entries for a key (empty array if absent).
+    def get_entries(key)
+      @mutex.synchronize { (@store[key_to_string(key)] || []).dup }
+    end
+
+    # Number of stored sessions (main transcripts only).
+    def size
+      @mutex.synchronize do
+        @store.keys.count do |k|
+          first_slash = k.index('/')
+          first_slash && !k[(first_slash + 1)..].include?('/')
+        end
+      end
+    end
+
+    def clear
+      @mutex.synchronize do
+        @store.clear
+        @mtimes.clear
+        @summaries.clear
+        @last_mtime = 0
+      end
+    end
+
+    private
+
+    # True for a main-transcript key: no subpath, or an empty-string subpath
+    # (which key_to_string already folds into the main key).
+    def main_transcript_key?(key)
+      sub = key['subpath']
+      sub.nil? || sub.empty?
+    end
+
+    def key_to_string(key)
+      parts = [key['project_key'], key['session_id']]
+      subpath = key['subpath']
+      parts << subpath if subpath && !subpath.empty?
+      parts.join('/')
+    end
+
+    # Storage write time in Unix epoch ms, strictly monotonically increasing so
+    # back-to-back appends always produce distinct mtimes (real backends get
+    # this from commit ordering).
+    def next_mtime
+      now_ms = (Time.now.to_f * 1000).to_i
+      now_ms = @last_mtime + 1 if now_ms <= @last_mtime
+      @last_mtime = now_ms
+      now_ms
+    end
+  end
+
+  # Internal SessionStore support functions (path mapping, option validation).
+  module SessionStores
+    module_function
+
+    # Derive a SessionKey from an absolute transcript file path.
+    #
+    #   Main:     <projects_dir>/<project_key>/<session_id>.jsonl
+    #   Subagent: <projects_dir>/<project_key>/<session_id>/subagents/agent-<id>.jsonl
+    #
+    # Returns nil if +file_path+ is not under +projects_dir+ or has an
+    # unrecognized shape.
+    def file_path_to_session_key(file_path, projects_dir)
+      # A frame with a missing/non-String filePath would make Pathname.new raise
+      # TypeError (not the ArgumentError handled below), which propagates out of
+      # do_flush and drops the entire coalesced drain batch. Treat it as
+      # "not under projects_dir" so only the bad frame is skipped.
+      return nil unless file_path.is_a?(String) && !file_path.empty?
+
+      begin
+        rel = Pathname.new(file_path).relative_path_from(Pathname.new(projects_dir)).to_s
+      rescue ArgumentError
+        # Different drives on Windows — treat as "not under projects_dir".
+        return nil
+      end
+
+      parts = rel.split('/')
+      # Reject paths that escape projects_dir: a leading ".." *segment* (exact
+      # match, so a legitimate dir like "..foo" still maps), the "." self-ref,
+      # or an absolute path. Comparing parts[0] rather than rel.start_with?("..")
+      # avoids the "..foo" false positive that would silently drop valid frames.
+      return nil if parts.empty? || parts[0] == '..' || rel == '.' || Pathname.new(rel).absolute?
+      return nil if parts.length < 2
+
+      project_key = parts[0]
+      second = parts[1]
+
+      # Main transcript: <project_key>/<session_id>.jsonl
+      return { 'project_key' => project_key, 'session_id' => second.delete_suffix('.jsonl') } if parts.length == 2 && second.end_with?('.jsonl')
+
+      # Subagent transcript: <project_key>/<session_id>/subagents/.../agent-<id>.jsonl
+      if parts.length >= 4
+        subpath_parts = parts[2..]
+        subpath_parts[-1] = subpath_parts[-1].delete_suffix('.jsonl')
+        # Subpaths are always /-joined so keys are portable across platforms.
+        return { 'project_key' => project_key, 'session_id' => second, 'subpath' => subpath_parts.join('/') }
+      end
+
+      nil
+    end
+
+    # Raise ArgumentError for invalid session_store option combinations. Called
+    # before subprocess spawn so misconfiguration fails fast.
+    def validate_session_store_options(options)
+      store = options.session_store
+      return if store.nil?
+
+      # #append/#load are required, but a subclass inheriting the base stubs
+      # would only fail at first use — with NotImplementedError, a ScriptError
+      # that rescue StandardError layers don't catch. Fail fast here instead.
+      %i[append load].each do |method|
+        raise ArgumentError, "session_store must implement ##{method}" unless SessionStore.implements?(store, method)
+      end
+
+      flush = options.session_store_flush.to_s
+      unless SESSION_STORE_FLUSH_MODES.include?(flush)
+        raise ArgumentError,
+              "invalid session_store_flush: #{options.session_store_flush.inspect} " \
+              "(expected one of #{SESSION_STORE_FLUSH_MODES.join(', ')})"
+      end
+
+      # When resume is explicitly set, list_sessions is provably never called
+      # (resume wins over continue), so a minimal store is fine.
+      if options.continue_conversation && options.resume.nil? && !SessionStore.implements?(store, :list_sessions)
+        raise ArgumentError,
+              'continue_conversation with session_store requires the store to implement #list_sessions'
+      end
+
+      return unless options.enable_file_checkpointing
+
+      raise ArgumentError,
+            'session_store cannot be combined with enable_file_checkpointing ' \
+            '(checkpoints are local-disk only and would diverge from the mirrored transcript)'
+    end
+
+    # Path to the rel-from base where session transcripts live, honoring a
+    # CLAUDE_CONFIG_DIR override passed to the subprocess via options.env.
+    # Mirrors Sessions#config_dir but consults an explicit env override first.
+    #
+    # Presence is detected by KEY, not value: the transport treats an explicit
+    # nil value as "unset the var for the child", so the CLI then writes under
+    # the default ~/.claude — not under the parent's CLAUDE_CONFIG_DIR. Empty
+    # strings get the same treatment (the Node CLI treats "" as unset).
+    def projects_dir(env_override = nil)
+      if env_override.respond_to?(:key?) &&
+         (env_override.key?('CLAUDE_CONFIG_DIR') || env_override.key?(:CLAUDE_CONFIG_DIR))
+        override = env_override['CLAUDE_CONFIG_DIR'] || env_override[:CLAUDE_CONFIG_DIR]
+        override = nil if override.respond_to?(:empty?) && override.empty?
+        return File.join(override || File.expand_path('~/.claude'), 'projects')
+      end
+
+      File.join(Sessions.config_dir, 'projects')
+    end
+  end
+end

data/lib/claude_agent_sdk/session_summary.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative 'sessions'
+
+module ClaudeAgentSDK
+  # Incremental session-summary derivation for SessionStore adapters.
+  #
+  # fold_session_summary lets a store maintain a per-session summary sidecar
+  # incrementally inside #append so list_sessions_from_store can fetch all
+  # metadata in a single #list_session_summaries call instead of N per-session
+  # #load calls. Every derived field is append-incremental (set-once or
+  # last-wins) so adapters never need to re-read previously appended entries.
+  #
+  # All structures use STRING keys throughout: entries are raw JSONL objects
+  # (string keys from JSON), and the summary's opaque +data+ dict is persisted
+  # verbatim by adapters — string keys survive a JSON round-trip (Postgres
+  # JSONB, Redis) losslessly, whereas symbol keys would not.
+  module SessionSummary
+    # JSONL entry keys -> summary data keys for last-wins string fields. Each
+    # appended entry overwrites the previous value when present.
+    LAST_WINS_FIELDS = {
+      'customTitle' => 'custom_title',
+      'aiTitle' => 'ai_title',
+      'lastPrompt' => 'last_prompt',
+      'summary' => 'summary_hint',
+      'gitBranch' => 'git_branch'
+    }.freeze
+
+    module_function
+
+    # Fold a batch of appended entries into the running summary for +key+.
+    #
+    # Stores call this from inside #append to keep a summary sidecar up to date
+    # without re-reading the transcript. +prev+ is the previous summary for the
+    # same key (or nil for the first append).
+    #
+    # Do NOT call this for keys with a +subpath+ — subagent transcripts must
+    # not contribute to the main session's summary. Guard with
+    # `if key['subpath'].nil?` before calling.
+    #
+    # +mtime+ is NOT touched by the fold — it is the sidecar's storage write
+    # time and must be stamped by the adapter after persisting (sharing a clock
+    # with the mtime returned by SessionStore#list_sessions). For a new session
+    # (prev nil) the fold returns mtime 0 as a placeholder for the adapter to
+    # overwrite.
+    #
+    # @param prev [Hash, nil] previous summary entry for this key
+    # @param key [Hash] the SessionKey (string keys)
+    # @param entries [Array<Hash>] newly appended transcript entries
+    # @return [Hash] the updated summary entry ({ 'session_id', 'mtime', 'data' })
+    def fold_session_summary(prev, key, entries)
+      summary = if prev
+                  { 'session_id' => prev['session_id'], 'mtime' => prev['mtime'], 'data' => prev['data'].dup }
+                else
+                  { 'session_id' => key['session_id'], 'mtime' => 0, 'data' => {} }
+                end
+      data = summary['data']
+
+      entries.each do |entry|
+        next unless entry.is_a?(Hash)
+
+        data['is_sidechain'] = (entry['isSidechain'] == true) unless data.key?('is_sidechain')
+
+        # created_at is set-once, so skip the (regex + Time.iso8601) parse for
+        # every entry after the first timestamped one — folds run over whole
+        # transcripts on the store read paths.
+        ms = data.key?('created_at') ? nil : Sessions.parse_iso_timestamp_ms(entry['timestamp'])
+        data['created_at'] = ms if ms
+
+        unless data.key?('cwd')
+          cwd = entry['cwd']
+          data['cwd'] = cwd if cwd.is_a?(String) && !cwd.empty?
+        end
+
+        fold_first_prompt(data, entry)
+
+        LAST_WINS_FIELDS.each do |src, dst|
+          val = entry[src]
+          data[dst] = val if val.is_a?(String)
+        end
+
+        next unless entry['type'] == 'tag'
+
+        tag_val = entry['tag']
+        if tag_val.is_a?(String) && !tag_val.empty?
+          data['tag'] = tag_val
+        else
+          # Empty string or absent tag clears the tag.
+          data.delete('tag')
+        end
+      end
+
+      summary
+    end
+
+    # Convert a summary entry to SDKSessionInfo. Returns nil for sidechain
+    # sessions or sessions with no extractable summary, matching the disk
+    # lite-parse's filtering in Sessions#build_session_info.
+    #
+    # @param entry [Hash] a summary entry from SessionStore#list_session_summaries
+    # @param project_path [String, nil] fallback cwd
+    # @return [SDKSessionInfo, nil]
+    def summary_entry_to_sdk_info(entry, project_path)
+      data = entry['data'] || {}
+      return nil if data['is_sidechain']
+
+      first_prompt = presence(data['first_prompt_locked'] ? data['first_prompt'] : data['command_fallback'])
+      custom_title = presence(data['custom_title']) || presence(data['ai_title'])
+      summary = custom_title || presence(data['last_prompt']) || presence(data['summary_hint']) || first_prompt
+      return nil unless summary
+
+      SDKSessionInfo.new(
+        session_id: entry['session_id'],
+        summary: summary,
+        last_modified: entry['mtime'],
+        # file_size is a JSONL byte count — meaningful only for the local-disk
+        # path. Stores have no equivalent.
+        file_size: nil,
+        custom_title: custom_title,
+        first_prompt: first_prompt,
+        git_branch: presence(data['git_branch']),
+        cwd: presence(data['cwd']) || presence(project_path),
+        tag: presence(data['tag']),
+        created_at: data['created_at']
+      )
+    end
+
+    # Python's `x or None`: nil for nil/empty-string, else the value.
+    def presence(val)
+      return nil if val.nil?
+      return nil if val.is_a?(String) && val.empty?
+
+      val
+    end
+
+    # Replicate Sessions#extract_first_prompt_from_head for a single parsed
+    # entry. Mutates +data+ in place: sets first_prompt + first_prompt_locked on
+    # a real match, or stashes a command_fallback for slash-command messages.
+    #
+    # The newline normalization (gsub(/\n+/, ' ')) and no-rstrip truncation
+    # deliberately match the disk extractor (not Python's per-char replace) so
+    # the Ruby store path and disk path produce identical first_prompt values
+    # for the same transcript.
+    def fold_first_prompt(data, entry)
+      return if data['first_prompt_locked']
+      return unless entry['type'] == 'user'
+      return if entry['isMeta'] == true || entry['isCompactSummary'] == true
+
+      message = entry['message']
+      if message.is_a?(Hash)
+        content = message['content']
+        return if content.is_a?(Array) && content.any? { |b| b.is_a?(Hash) && b['type'] == 'tool_result' }
+      end
+
+      entry_text_blocks(entry).each do |raw|
+        text = raw.gsub(/\n+/, ' ').strip
+        next if text.empty?
+
+        if (match = Sessions::COMMAND_NAME_RE.match(text))
+          data['command_fallback'] ||= match[1]
+          next
+        end
+        next if text.match?(Sessions::SKIP_FIRST_PROMPT_PATTERN)
+
+        data['first_prompt'] = text.length > 200 ? "#{text[0, 200]}…" : text
+        data['first_prompt_locked'] = true
+        break
+      end
+    end
+
+    # Extract text strings from a type=="user" entry's message content.
+    def entry_text_blocks(entry)
+      message = entry['message']
+      return [] unless message.is_a?(Hash)
+
+      content = message['content']
+      case content
+      when String then [content]
+      when Array
+        content.filter_map { |b| b['text'] if b.is_a?(Hash) && b['type'] == 'text' && b['text'].is_a?(String) }
+      else []
+      end
+    end
+
+    private_class_method :presence, :fold_first_prompt, :entry_text_blocks
+  end
+end