claude-agent-sdk 0.35.0 → 0.37.0

data/lib/claude_agent_sdk/session_store.rb

@@ -56,8 +56,8 @@ module ClaudeAgentSDK
   # mode) and a cancelled append may remain permanently half-applied in the
   # store. The drop is surfaced (MirrorErrorMessage, batches_dropped?) and
   # the local transcript remains the source of truth; the
-  # dedupe-by-entry-uuid recommendation above stays advisory. The method is deliberately NOT defined here: the SDK probes
-  # `respond_to?(:callback_scheduling)` (see
+  # dedupe-by-entry-uuid recommendation above stays advisory. The method is
+  # deliberately NOT defined here: the SDK probes `respond_to?(:callback_scheduling)` (see
   # SessionStores.store_callback_scheduling), so pure duck-typed adapters
   # stay minimal, and an app can opt a third-party fiber-native adapter in
   # via a singleton method (`def store.callback_scheduling = :inline`).
@@ -94,13 +94,13 @@ module ClaudeAgentSDK
     end
 
     # List sessions for a project_key as [{ 'session_id', 'mtime' }]. Optional —
-    # if unimplemented, list_sessions_from_store raises.
+    # if unimplemented, list_sessions(session_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
+    # Optional — if unimplemented, list_sessions(session_store:) falls back to
     # list_sessions + per-session load.
     def list_session_summaries(_project_key)
       raise NotImplementedError
@@ -290,6 +290,8 @@ module ClaudeAgentSDK
   end
 
   # Internal SessionStore support functions (path mapping, option validation).
+  #
+  # @api private
   module SessionStores
     STORE_CALLBACK_SCHEDULING_MODES = %i[thread inline].freeze
 
@@ -349,7 +351,9 @@ module ClaudeAgentSDK
       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')
+      if parts.length == 2 && second.end_with?('.jsonl')
+        return { 'project_key' => project_key, 'session_id' => second.delete_suffix('.jsonl') }
+      end
 
       # Subagent transcript: <project_key>/<session_id>/subagents/.../agent-<id>.jsonl
       if parts.length >= 4
@@ -396,27 +400,37 @@ module ClaudeAgentSDK
             '(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.
+    # Path to the rel-from base where the CLI subprocess writes session
+    # transcripts: its CLAUDE_CONFIG_DIR, else ~/.claude under the home the
+    # CHILD sees. Mirrors Sessions#config_dir but resolves both through the
+    # options.env passed to the subprocess.
     #
     # 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).
+    # strings get the same treatment (the Node CLI treats "" as unset). A HOME
+    # in options.env likewise moves that default (see Sessions.home_dir).
+    #
+    # Returns nil when the default is needed but there is no usable home
+    # (#120). This runs at connect for every session with a session_store, so
+    # raising (as Sessions.config_dir does) would abort a fresh session over
+    # its secondary copy; the TranscriptMirrorBatcher instead reports the
+    # frames it cannot key as MirrorErrorMessage.
     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?
-        # NFC like Python's _get_projects_dir(env_override) — a decomposed
-        # Unicode override would otherwise mismatch the NFC paths used for
-        # the mirror's projects-dir prefix comparison and drop every frame.
-        override = override.unicode_normalize(:nfc) if override
-        return File.join(override || File.expand_path('~/.claude'), 'projects')
-      end
-
-      File.join(Sessions.config_dir, 'projects')
+      override = if env_override.respond_to?(:key?) &&
+                    (env_override.key?('CLAUDE_CONFIG_DIR') || env_override.key?(:CLAUDE_CONFIG_DIR))
+                   env_override['CLAUDE_CONFIG_DIR'] || env_override[:CLAUDE_CONFIG_DIR]
+                 else
+                   ENV.fetch('CLAUDE_CONFIG_DIR', nil)
+                 end
+      override = nil if override.respond_to?(:empty?) && override.empty?
+      # NFC like Python's _get_projects_dir(env_override) — a decomposed
+      # Unicode override would otherwise mismatch the NFC paths used for
+      # the mirror's projects-dir prefix comparison and drop every frame.
+      return File.join(override.unicode_normalize(:nfc), 'projects') if override
+
+      home = Sessions.home_dir(env_override)
+      home && File.join(home, '.claude', 'projects').unicode_normalize(:nfc)
     end
   end
 end

data/lib/claude_agent_sdk/session_summary.rb

@@ -7,7 +7,7 @@ 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
+  # incrementally inside #append so list_sessions(session_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.
@@ -16,6 +16,8 @@ module ClaudeAgentSDK
   # (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.
+  #
+  # @api private
   module SessionSummary
     # JSONL entry keys -> summary data keys for last-wins string fields. Each
     # appended entry overwrites the previous value when present.
@@ -49,7 +51,7 @@ module ClaudeAgentSDK
     # @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)
+    def fold_session_summary(prev, key, entries) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- incremental fold over every summary field
       summary = if prev
                   { 'session_id' => prev['session_id'], 'mtime' => prev['mtime'], 'data' => prev['data'].dup }
                 else
@@ -69,8 +71,10 @@ module ClaudeAgentSDK
         data['created_at'] = ms if ms
 
         unless data.key?('cwd')
+          # First non-blank cwd (Sessions.presence: whitespace-only and
+          # invalidly encoded count as blank, as on the disk path).
           cwd = entry['cwd']
-          data['cwd'] = cwd if cwd.is_a?(String) && !cwd.empty?
+          data['cwd'] = cwd if cwd.is_a?(String) && presence(cwd)
         end
 
         fold_first_prompt(data, entry)
@@ -113,7 +117,10 @@ module ClaudeAgentSDK
       SDKSessionInfo.new(
         session_id: entry['session_id'],
         summary: summary,
-        last_modified: entry['mtime'],
+        # Integer epoch ms as documented, whatever shape the adapter stamped
+        # (ISO String, numeric String, Float, Time) — the value the listing
+        # orders by. Python passes entry["mtime"] through raw.
+        last_modified: Sessions.epoch_ms_mtime(entry['mtime']),
         # file_size is a JSONL byte count — meaningful only for the local-disk
         # path. Stores have no equivalent.
         file_size: nil,
@@ -142,7 +149,7 @@ module ClaudeAgentSDK
     # 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)
+    def fold_first_prompt(data, entry) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- must match the disk first-prompt extractor rule for rule
       return if data['first_prompt_locked']
       return unless entry['type'] == 'user'
       return if entry['isMeta'] == true || entry['isCompactSummary'] == true

data/lib/claude_agent_sdk/sessions.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'open3'
 require 'pathname'
+require_relative 'errors'
 require_relative 'session_store'
 require_relative 'session_summary'
 require_relative 'transcript_mirror_batcher'
@@ -82,7 +83,9 @@ module ClaudeAgentSDK
   end
 
   # Session browsing functions
-  module Sessions # rubocop:disable Metrics/ModuleLength
+  #
+  # @api private
+  module Sessions # rubocop:disable Metrics/ModuleLength -- session listing/reading functions share private helpers
     LITE_READ_BUF_SIZE = 65_536
     MAX_SANITIZED_LENGTH = 200
 
@@ -176,11 +179,53 @@ module ClaudeAgentSDK
     # Get the Claude config directory (respects CLAUDE_CONFIG_DIR; an empty
     # value is treated as unset, matching the Node CLI and the Python SDK).
     # NFC-normalized on both branches like Python's _get_claude_config_home_dir.
+    #
+    # @raise [ConfigDirError] when CLAUDE_CONFIG_DIR is unset and there is no
+    #   usable home directory (see .home_dir) for the default ~/.claude.
+    #   Python raises too (Path.home() -> RuntimeError); `~` expansion here
+    #   raised a bare ArgumentError from deep inside every disk session API.
     def config_dir
       dir = ENV.fetch('CLAUDE_CONFIG_DIR', nil)
       return dir.unicode_normalize(:nfc) if dir && !dir.empty?
 
-      File.expand_path('~/.claude').unicode_normalize(:nfc)
+      home = home_dir
+      unless home
+        raise ConfigDirError,
+              'Cannot locate the Claude config directory: CLAUDE_CONFIG_DIR is unset and the home directory ' \
+              'could not be resolved (HOME is unset, empty or relative, and the user has no passwd entry). ' \
+              'Set CLAUDE_CONFIG_DIR to the directory holding your Claude Code data (normally ~/.claude).'
+      end
+
+      File.join(home, '.claude').unicode_normalize(:nfc)
+    end
+
+    # A usable home directory, or nil when there is none. The ONE definition
+    # of "home" for the SDK (CLI discovery, disk session APIs, the transcript
+    # mirror, store-backed resume seeding).
+    #
+    # Without +env+, the parent process's home: Dir.home raises ArgumentError
+    # when HOME is unset and the uid has no passwd entry (docker --user in a
+    # minimal image), and returns an empty or relative HOME verbatim — a path
+    # under "" or a cwd-relative dir is not where the user's data lives (and
+    # a relative CLI hit would be spawned from options.cwd, i.e. a different
+    # file), so both read as "no home".
+    #
+    # With +env+ (a ClaudeAgentOptions#env Hash), the home the CLI CHILD will
+    # see: a HOME key there wins, by key presence like the CLAUDE_CONFIG_DIR
+    # override, and must be absolute. An explicit nil (the transport unsets
+    # HOME for the child, which then falls back to its passwd entry) is also
+    # treated as no home rather than guessing that entry.
+    #
+    # @api private
+    def home_dir(env = nil)
+      home = if env.respond_to?(:key?) && (env.key?('HOME') || env.key?(:HOME))
+               env['HOME'] || env[:HOME]
+             else
+               Dir.home
+             end
+      home if home.is_a?(String) && File.absolute_path?(home)
+    rescue ArgumentError
+      nil
     end
 
     # Find the project directory for a given path
@@ -239,7 +284,11 @@ module ClaudeAgentSDK
     # top-level shape can't be checked, and dropping it would regress the
     # common case of a true entry cut by the 64KB window. Unverified blanks
     # cannot clear a previously verified value: they may be nested tool inputs.
-    def extract_top_level_string_field(text, key, last: false)
+    #
+    # +skip_blank+ passes over verified blank values too, for set-once fields
+    # the store fold only takes when non-blank (cwd): there a blank entry is
+    # absent, not a clearing entry.
+    def extract_top_level_string_field(text, key, last: false, skip_blank: false)
       positions = field_match_positions(text, key)
       positions.reverse! if last
       parsed_lines = {}
@@ -250,9 +299,9 @@ module ClaudeAgentSDK
         end
         if entry
           value = entry[key]
-          return value if value.is_a?(String)
+          return value if value.is_a?(String) && (!skip_blank || presence(value))
 
-          next # parseable line without a top-level string value: nested/false match
+          next # parseable line without a usable top-level string value: nested/false match
         end
         value = extract_json_string_value(text, value_start)
         value = presence(unescape_json_string(value)) if value
@@ -334,6 +383,8 @@ module ClaudeAgentSDK
     # a NoMethodError from deep inside (`123.match?`, `123.empty?`) — and so
     # does an invalidly encoded String, on which the regexp match itself
     # raises ArgumentError ("invalid byte sequence").
+    #
+    # @api private
     def valid_session_id?(session_id)
       session_id.is_a?(String) && session_id.valid_encoding? && session_id.match?(UUID_RE)
     end
@@ -352,12 +403,26 @@ module ClaudeAgentSDK
     # bare ArgumentError. Coerce defensively wherever an adapter mtime is
     # ordered or compared: numeric strings and ISO-8601 both order
     # correctly; anything else sorts last rather than crashing.
+    #
+    # A Time (e.g. an ActiveRecord updated_at) counts as its instant in epoch
+    # ms. Non-finite values (Infinity, "1e400") also read as 0: they cannot be
+    # ordered against real clocks nor reported as epoch ms.
     def sortable_mtime(value)
-      case value
-      when Numeric then value
-      when String then Float(value, exception: false) || parse_iso_timestamp_ms(value) || 0
-      else 0
-      end
+      ms = case value
+           when Numeric then value
+           when Time then value.to_r * 1000
+           when String then Float(value, exception: false) || parse_iso_timestamp_ms(value)
+           end
+      ms.is_a?(Numeric) && ms.real? && ms.finite? ? ms : 0
+    end
+
+    # An adapter mtime as SDKSessionInfo#last_modified promises it: Integer
+    # epoch milliseconds. Same coercion as sortable_mtime (so a row reports
+    # the value it is ordered by), truncated to whole milliseconds.
+    #
+    # @api private
+    def epoch_ms_mtime(value)
+      sortable_mtime(value).to_i
     end
 
     # Sort key shared by every session listing, disk and store: newest first,
@@ -365,12 +430,14 @@ module ClaudeAgentSDK
     # the secondary key equal mtimes (coarse adapter clocks, bulk imports)
     # ordered arbitrarily between calls and offset/limit paging could skip or
     # repeat sessions; one key also keeps the two paths in the same order.
+    #
+    # @api private
     def listing_sort_key(mtime, session_id)
       [-sortable_mtime(mtime), session_id.to_s]
     end
 
     # Extract the first meaningful user prompt from the head of a JSONL file
-    def extract_first_prompt_from_head(head)
+    def extract_first_prompt_from_head(head) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- first-prompt skip rules, matched by the store fold
       command_fallback = nil
 
       head.each_line do |line|
@@ -482,7 +549,7 @@ module ClaudeAgentSDK
       [head, tail]
     end
 
-    def build_session_info(file_path, head, tail, stat, project_path)
+    def build_session_info(file_path, head, tail, stat, project_path) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- one optional field per SDKSessionInfo attribute
       # User-set title (customTitle) wins over AI-generated title (aiTitle).
       # Consult the head only when the tail has no occurrence of that field.
       # Normalize blanks AFTER choosing the latest occurrence: an explicit
@@ -495,7 +562,9 @@ module ClaudeAgentSDK
                               extract_top_level_string_field(head, 'customTitle', last: true)) ||
                      presence(extract_top_level_string_field(tail, 'aiTitle', last: true) ||
                               extract_top_level_string_field(head, 'aiTitle', last: true))
-      first_prompt = extract_first_prompt_from_head(head)
+      # nil, not '', when there is no prompt — the store path's answer, and
+      # Python's (`_extract_first_prompt_from_head(head) or None`).
+      first_prompt = presence(extract_first_prompt_from_head(head))
       # lastPrompt tail entry shows what the user was most recently doing.
       summary = custom_title ||
                 presence(extract_top_level_string_field(tail, 'lastPrompt', last: true)) ||
@@ -528,7 +597,11 @@ module ClaudeAgentSDK
         # (SessionSummary.summary_entry_to_sdk_info) reports it.
         git_branch: presence(extract_json_string_field(tail, 'gitBranch', last: true) ||
                              extract_json_string_field(head, 'gitBranch', last: false)),
-        cwd: presence(extract_json_string_field(head, 'cwd', last: false)) || project_path,
+        # The first non-blank TOP-LEVEL cwd, exactly what the store fold keeps
+        # (set-once, blank skipped): taking the first match even when blank
+        # fell back to the project path where the store read a later entry's
+        # cwd, and the raw scan also matched cwd keys nested in tool inputs.
+        cwd: extract_top_level_string_field(head, 'cwd', skip_blank: true) || project_path,
         tag: tag_value,
         created_at: created_at
       )
@@ -927,7 +1000,7 @@ module ClaudeAgentSDK
     # NotImplementedError (caller falls back to the slow path). Sessions missing
     # a sidecar or whose sidecar is stale (summary.mtime < the session's current
     # mtime) are routed through gap-fill so the fold is recomputed from source.
-    def list_sessions_via_summaries(store, project_key, project_path, limit, offset)
+    def list_sessions_via_summaries(store, project_key, project_path, limit, offset) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- fast path plus stale/missing-sidecar gap-fill
       begin
         # Array(): a non-conformant store returning nil (e.g. a NULL JSONB read)
         # degrades to gap-fill instead of crashing on nil.each, matching the
@@ -975,7 +1048,7 @@ module ClaudeAgentSDK
     # leaves a short page; loads stay bounded to ~offset + limit + (the dropped
     # placeholders encountered before the page fills), preserving the fast
     # path's "don't load every session" intent.
-    def paginate_resolving_gaps(store, project_key, project_path, slots, limit, offset)
+    def paginate_resolving_gaps(store, project_key, project_path, slots, limit, offset) # rubocop:disable Metrics/ParameterLists -- pagination state threaded explicitly
       offset = 0 unless offset&.positive?
       results = []
       skipped = 0
@@ -1011,7 +1084,7 @@ module ClaudeAgentSDK
         # its mtime) rather than aborting the whole listing — matches the disk
         # path's per-file rescue and the store path's degrade-the-row contract.
         warn "Claude SDK: [SessionStore] gap-fill load failed for session #{sid}: #{e.message}"
-        return SDKSessionInfo.new(session_id: sid, summary: '', last_modified: slot[:mtime])
+        return SDKSessionInfo.new(session_id: sid, summary: '', last_modified: epoch_ms_mtime(slot[:mtime]))
       end
       return nil if entries.nil? || entries.empty?
 
@@ -1288,7 +1361,9 @@ module ClaudeAgentSDK
       return [] unless File.directory?(projects_dir)
 
       all_sessions = []
-      Dir.children(projects_dir).each do |child|
+      # Sorted: the scan order is deduplicate_sessions' last tiebreak, and
+      # Dir.children returns filesystem order.
+      Dir.children(projects_dir).sort.each do |child|
         dir = File.join(projects_dir, child)
         next unless File.directory?(dir)
 
@@ -1298,15 +1373,26 @@ module ClaudeAgentSDK
       deduplicate_sessions(all_sessions)
     end
 
+    # One entry per session_id when the same session sits in several project
+    # dirs (copied config dirs, worktrees). The newest last_modified wins; on
+    # equal mtimes the larger file (the more complete copy), and then the
+    # copy scanned first — project dirs in name order for the global listing,
+    # worktrees in `git worktree list` order (main worktree first) for a
+    # directory listing. Python keeps the first copy seen in iterdir() order
+    # (sessions.py _deduplicate_by_session_id), which is arbitrary on a tie.
     def deduplicate_sessions(sessions)
       by_id = {}
       sessions.each do |s|
         existing = by_id[s.session_id]
-        by_id[s.session_id] = s if existing.nil? || s.last_modified > existing.last_modified
+        by_id[s.session_id] = s if existing.nil? || (dedup_rank(s) <=> dedup_rank(existing)).positive?
       end
       by_id.values
     end
 
+    def dedup_rank(session)
+      [session.last_modified, session.file_size.to_i]
+    end
+
     # Probe git for the worktree list with a hard 5-second cap. A stale
     # git lock or hung network mount must not block the listing path
     # forever. Stdlib `Timeout.timeout` raises across threads via
@@ -1315,7 +1401,7 @@ module ClaudeAgentSDK
     # threads (so a full pipe buffer can't deadlock git) and SIGKILL the
     # child if the deadline passes. Matches Python's
     # `subprocess.run(..., timeout=5)`.
-    def detect_worktrees(path)
+    def detect_worktrees(path) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- bounded git subprocess: drained pipes, deadline kill
       stdin, stdout, stderr, wait_thr = Open3.popen3('git', '-C', path, 'worktree', 'list', '--porcelain')
       stdin.close
 
@@ -1544,12 +1630,12 @@ module ClaudeAgentSDK
 
     private_class_method :get_session_info_for_directory,
                          :list_sessions_for_directory, :list_all_sessions,
-                         :deduplicate_sessions,
+                         :deduplicate_sessions, :dedup_rank,
                          :find_session_file, :stat_candidate, :resolve_subagents_dir,
                          :collect_agent_files, :parse_jsonl_entries,
                          :build_conversation_chain, :walk_to_leaf, :walk_to_root,
                          :filter_visible_messages, :read_head_tail, :build_session_info, :user_entry_texts,
-                         :valid_session_id?, :valid_agent_id?, :listing_sort_key, :sidechain_head?,
+                         :valid_agent_id?, :sidechain_head?,
                          :list_sessions_via_summaries, :paginate_resolving_gaps, :resolve_gap_slot,
                          :derive_info_from_entries, :mtime_from_entries, :apply_sort_limit_offset,
                          :filter_transcript_entries, :entries_to_messages,
@@ -1557,7 +1643,9 @@ module ClaudeAgentSDK
                          :import_subagent_files, :append_jsonl_file_in_batches, :collect_jsonl_files,
                          :read_agent_metadata_sidecar, :parent_ids_from_agent_metadata
 
-    # These remain accessible for SessionMutations:
-    # config_dir, sanitize_path, find_project_dir, detect_worktrees
+    # These remain accessible for SessionMutations / SessionResume:
+    # config_dir, sanitize_path, find_project_dir, detect_worktrees,
+    # valid_session_id? (mutation boundary checks), listing_sort_key
+    # (--continue candidate order)
   end
 end

data/lib/claude_agent_sdk/streaming.rb

@@ -21,7 +21,7 @@ module ClaudeAgentSDK
         parent_tool_use_id: parent_tool_use_id,
         session_id: session_id
       }
-      JSON.generate(message) + "\n"
+      "#{JSON.generate(message)}\n"
     end
 
     # Create an Enumerator from an array of messages