claude-agent-sdk 0.16.9 → 0.17.0

data/lib/claude_agent_sdk/testing/session_store_conformance.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require_relative '../session_store'
+require_relative '../session_summary'
+
+module ClaudeAgentSDK
+  # Test helpers shipped in the gem for third-party SessionStore adapter authors.
+  module Testing # rubocop:disable Metrics/ModuleLength
+    # Raised by run_session_store_conformance when a behavioral contract fails.
+    class ConformanceError < StandardError; end
+
+    OPTIONAL_METHODS = %w[list_sessions list_session_summaries delete list_subkeys].freeze
+
+    module_function
+
+    # Assert the 15 SessionStore behavioral contracts against an adapter.
+    #
+    # Framework-agnostic: raises ConformanceError on the first violated
+    # contract, otherwise returns nil. Call it from any test framework, e.g.
+    #
+    #   it 'conforms' do
+    #     ClaudeAgentSDK::Testing.run_session_store_conformance(-> { MyStore.new })
+    #   end
+    #
+    # @param make_store [#call] invoked once per contract to provide isolation;
+    #   returns a fresh SessionStore (or duck-typed adapter).
+    # @param skip_optional [Array<String>] optional method names to skip.
+    #   Contracts for an optional method are also skipped automatically when the
+    #   store does not override it.
+    def run_session_store_conformance(make_store, skip_optional: [])
+      skip_optional = skip_optional.map(&:to_s)
+      invalid = skip_optional - OPTIONAL_METHODS
+      raise ConformanceError, "unknown optional methods in skip_optional: #{invalid}" unless invalid.empty?
+
+      fresh = -> { make_store.call }
+
+      probe = fresh.call
+      has_list_sessions = optional?(probe, 'list_sessions', skip_optional)
+      has_list_summaries = optional?(probe, 'list_session_summaries', skip_optional)
+      has_delete = optional?(probe, 'delete', skip_optional)
+      has_list_subkeys = optional?(probe, 'list_subkeys', skip_optional)
+
+      check_append_and_load(fresh, has_list_sessions)
+      check_list_sessions(fresh) if has_list_sessions
+      check_list_session_summaries(fresh, has_list_sessions, has_delete) if has_list_summaries
+      check_delete(fresh, has_list_subkeys, has_list_sessions) if has_delete
+      check_list_subkeys(fresh) if has_list_subkeys
+      nil
+    end
+
+    # -- Required: append + load -------------------------------------------
+
+    def check_append_and_load(fresh, has_list_sessions) # rubocop:disable Metrics/MethodLength
+      # 1. append then load returns same entries in same order.
+      store = fresh.call
+      store.append(key, [entry('uuid' => 'b', 'n' => 1), entry('uuid' => 'a', 'n' => 2)])
+      assert_eq(store.load(key), [entry('uuid' => 'b', 'n' => 1), entry('uuid' => 'a', 'n' => 2)],
+                'append then load must return the same entries in order')
+
+      # 2. load unknown key returns nil.
+      store = fresh.call
+      assert(store.load('project_key' => 'proj', 'session_id' => 'nope').nil?,
+             'load of an unwritten session must return nil')
+      store.append(key, [entry('uuid' => 'x', 'n' => 1)])
+      assert(store.load(key.merge('subpath' => 'nope')).nil?,
+             'load of an unwritten subpath must return nil')
+
+      # 3. multiple append calls preserve call order.
+      store = fresh.call
+      store.append(key, [entry('uuid' => 'z', 'n' => 1)])
+      store.append(key, [entry('uuid' => 'a', 'n' => 2), entry('uuid' => 'm', 'n' => 3)])
+      store.append(key, [entry('uuid' => 'b', 'n' => 4)])
+      assert_eq(store.load(key),
+                [entry('uuid' => 'z', 'n' => 1), entry('uuid' => 'a', 'n' => 2),
+                 entry('uuid' => 'm', 'n' => 3), entry('uuid' => 'b', 'n' => 4)],
+                'multiple appends must preserve call order')
+
+      # 4. append([]) is a no-op.
+      store = fresh.call
+      store.append(key, [entry('uuid' => 'a', 'n' => 1)])
+      store.append(key, [])
+      assert_eq(store.load(key), [entry('uuid' => 'a', 'n' => 1)], 'append([]) must be a no-op')
+
+      # 5. subpath keys are stored independently of main.
+      store = fresh.call
+      sub = key.merge('subpath' => 'subagents/agent-1')
+      store.append(key, [entry('uuid' => 'm', 'n' => 1)])
+      store.append(sub, [entry('uuid' => 's', 'n' => 1)])
+      assert_eq(store.load(key), [entry('uuid' => 'm', 'n' => 1)], 'main transcript must be independent of subpath')
+      assert_eq(store.load(sub), [entry('uuid' => 's', 'n' => 1)], 'subpath transcript must be independent of main')
+
+      # 6. project_key isolation.
+      store = fresh.call
+      store.append({ 'project_key' => 'A', 'session_id' => 's1' }, [entry('from' => 'A')])
+      store.append({ 'project_key' => 'B', 'session_id' => 's1' }, [entry('from' => 'B')])
+      assert_eq(store.load('project_key' => 'A', 'session_id' => 's1'), [entry('from' => 'A')],
+                'project_key A must be isolated')
+      assert_eq(store.load('project_key' => 'B', 'session_id' => 's1'), [entry('from' => 'B')],
+                'project_key B must be isolated')
+      return unless has_list_sessions
+
+      assert_eq(store.list_sessions('A').length, 1, 'project A must list one session')
+      assert_eq(store.list_sessions('B').length, 1, 'project B must list one session')
+    end
+
+    # -- Optional: list_sessions -------------------------------------------
+
+    def check_list_sessions(fresh)
+      # 7. list_sessions returns session_ids for project.
+      store = fresh.call
+      store.append({ 'project_key' => 'proj', 'session_id' => 'a' }, [entry('n' => 1)])
+      store.append({ 'project_key' => 'proj', 'session_id' => 'b' }, [entry('n' => 1)])
+      store.append({ 'project_key' => 'other', 'session_id' => 'c' }, [entry('n' => 1)])
+      sessions = store.list_sessions('proj')
+      assert_eq(sessions.map { |s| s['session_id'] }.sort, %w[a b], 'list_sessions must scope to the project')
+      assert(sessions.all? { |s| epoch_ms?(s['mtime']) }, 'list_sessions mtime must be epoch-ms (> 1e12)')
+      assert_eq(store.list_sessions('never-appended-project'), [], 'unknown project must list no sessions')
+
+      # 8. list_sessions excludes subagent subpaths.
+      store = fresh.call
+      store.append({ 'project_key' => 'proj', 'session_id' => 'main' }, [entry('n' => 1)])
+      store.append({ 'project_key' => 'proj', 'session_id' => 'main', 'subpath' => 'subagents/agent-1' },
+                   [entry('n' => 1)])
+      assert_eq(store.list_sessions('proj').map { |s| s['session_id'] }, ['main'],
+                'list_sessions must exclude subagent subpaths')
+    end
+
+    # -- Optional: list_session_summaries ----------------------------------
+
+    def check_list_session_summaries(fresh, has_list_sessions, has_delete)
+      # 14. persisted fold output round-trips through fold_session_summary.
+      store = fresh.call
+      summ_key = { 'project_key' => 'proj', 'session_id' => 'summ-sess' }
+      store.append(summ_key, [entry('timestamp' => '2024-01-01T00:00:00.000Z', 'customTitle' => 'first'),
+                              entry('timestamp' => '2024-01-01T00:00:01.000Z')])
+      store.append(summ_key, [entry('timestamp' => '2024-01-01T00:00:02.000Z', 'customTitle' => 'second')])
+      store.append({ 'project_key' => 'other', 'session_id' => 'elsewhere' },
+                   [entry('timestamp' => '2024-01-01T00:00:00.000Z')])
+
+      by_id = summaries_by_id(store, 'proj', ['summ-sess'],
+                              'list_session_summaries must return exactly one row per session, scoped to the project')
+      summ = by_id['summ-sess']
+      assert(epoch_ms?(summ['mtime']), 'summary mtime must be epoch-ms (> 1e12)')
+
+      if has_list_sessions
+        ls_by_id = store.list_sessions('proj').to_h { |e| [e['session_id'], e['mtime']] }
+        assert(summ['mtime'] >= ls_by_id['summ-sess'],
+               'summary mtime must share a clock with (and be >=) list_sessions mtime')
+      end
+
+      assert(summ['data'].is_a?(Hash), 'summary data must be a Hash')
+      refolded = SessionSummary.fold_session_summary(summ, summ_key, [entry('timestamp' => '2024-01-01T00:00:03.000Z')])
+      assert_eq(refolded['session_id'], 'summ-sess', 'refold must preserve session_id')
+      assert_eq(refolded['mtime'], summ['mtime'], 'fold must preserve prev mtime verbatim')
+
+      # Subagent appends must NOT affect the main session's summary.
+      store.append(summ_key.merge('subpath' => 'subagents/agent-1'),
+                   [entry('timestamp' => '2024-01-01T00:00:09.000Z', 'customTitle' => 'subagent')])
+      after_sub = summaries_by_id(store, 'proj', ['summ-sess'],
+                                  'list_session_summaries must still return one row per session after a subagent append')
+      assert_eq(after_sub['summ-sess']['data'], summ['data'], 'subagent appends must not change the main summary')
+      assert_eq(store.list_session_summaries('never-appended-project'), [], 'unknown project must list no summaries')
+
+      return unless has_delete
+
+      store.delete(summ_key)
+      assert_eq(store.list_session_summaries('proj'), [], 'delete must clear the session summary')
+    end
+
+    # -- Optional: delete --------------------------------------------------
+
+    def check_delete(fresh, has_list_subkeys, has_list_sessions) # rubocop:disable Metrics/MethodLength
+      # 9. delete main then load returns nil (delete of never-written is a no-op).
+      store = fresh.call
+      store.delete('project_key' => 'proj', 'session_id' => 'never-written')
+      store.append(key, [entry('n' => 1)])
+      store.delete(key)
+      assert(store.load(key).nil?, 'load after delete must return nil')
+
+      # 10. delete main cascades to subkeys; siblings/other projects survive.
+      store = fresh.call
+      sub1 = key.merge('subpath' => 'subagents/agent-1')
+      sub2 = key.merge('subpath' => 'subagents/agent-2')
+      other = { 'project_key' => 'proj', 'session_id' => 'sess2' }
+      other_proj = { 'project_key' => 'other-proj', 'session_id' => key['session_id'] }
+      [key, sub1, sub2, other, other_proj].each { |k| store.append(k, [entry('n' => 1)]) }
+
+      store.delete(key)
+
+      assert(store.load(key).nil?, 'delete must remove the main transcript')
+      assert(store.load(sub1).nil?, 'delete must cascade to subkey 1')
+      assert(store.load(sub2).nil?, 'delete must cascade to subkey 2')
+      assert((store.load(other) || []).length == 1, 'sibling session must survive delete')
+      assert((store.load(other_proj) || []).length == 1, 'other project must survive delete')
+      assert_eq(store.list_subkeys(key), [], 'list_subkeys must be empty after cascade delete') if has_list_subkeys
+      if has_list_sessions
+        listed = store.list_sessions(key['project_key']).map { |s| s['session_id'] }
+        assert(!listed.include?(key['session_id']), 'deleted session must not be listed')
+      end
+
+      # 15. delete with an empty-string subpath behaves as a main-transcript
+      # delete (empty subpath == "no subpath"), so it cascades to subkeys rather
+      # than orphaning them. Runs before test 11's has_list_subkeys early return.
+      store = fresh.call
+      [key, sub1, sub2].each { |k| store.append(k, [entry('n' => 1)]) }
+      store.delete(key.merge('subpath' => ''))
+      assert(store.load(key).nil?, 'delete with empty subpath must remove the main transcript')
+      assert(store.load(sub1).nil?, 'delete with empty subpath must cascade to subkeys')
+      if has_list_sessions
+        listed = store.list_sessions(key['project_key']).map { |s| s['session_id'] }
+        assert(!listed.include?(key['session_id']), 'session deleted via empty subpath must not be listed')
+      end
+
+      # 11. delete with subpath removes only that subkey.
+      store = fresh.call
+      [key, sub1, sub2].each { |k| store.append(k, [entry('n' => 1)]) }
+      store.delete(sub1)
+      assert(store.load(sub1).nil?, 'targeted subpath delete must remove that subkey')
+      assert((store.load(sub2) || []).length == 1, 'targeted subpath delete must spare other subkeys')
+      assert((store.load(key) || []).length == 1, 'targeted subpath delete must spare the main transcript')
+      return unless has_list_subkeys
+
+      assert_eq(store.list_subkeys(key), ['subagents/agent-2'], 'only the deleted subkey must be gone')
+    end
+
+    # -- Optional: list_subkeys --------------------------------------------
+
+    def check_list_subkeys(fresh)
+      # 12. list_subkeys returns subpaths (scoped to the session).
+      store = fresh.call
+      store.append(key, [entry('n' => 1)])
+      store.append(key.merge('subpath' => 'subagents/agent-1'), [entry('n' => 1)])
+      store.append(key.merge('subpath' => 'subagents/agent-2'), [entry('n' => 1)])
+      store.append({ 'project_key' => key['project_key'], 'session_id' => 'other-sess',
+                     'subpath' => 'subagents/agent-x' }, [entry('n' => 1)])
+      subkeys = store.list_subkeys(key)
+      assert_eq(subkeys.sort, ['subagents/agent-1', 'subagents/agent-2'], "list_subkeys must return this session's subpaths")
+      assert(!subkeys.include?('subagents/agent-x'), "list_subkeys must not leak another session's subkeys")
+
+      # 13. list_subkeys excludes the main transcript.
+      store = fresh.call
+      store.append(key, [entry('n' => 1)])
+      assert_eq(store.list_subkeys(key), [], 'list_subkeys must exclude the main transcript')
+      assert_eq(store.list_subkeys('project_key' => 'proj', 'session_id' => 'never-appended'), [],
+                'list_subkeys of an unknown session must be empty')
+    end
+
+    # -- helpers -----------------------------------------------------------
+
+    def key
+      { 'project_key' => 'proj', 'session_id' => 'sess' }
+    end
+
+    # Build a test entry satisfying SessionStoreEntry (type is required). The
+    # value of type is irrelevant to the contracts — entries are opaque blobs.
+    def entry(extra = {})
+      { 'type' => 'x' }.merge(extra)
+    end
+
+    def epoch_ms?(value)
+      value.is_a?(Numeric) && value.finite? && value > 1e12
+    end
+
+    # Fetch summaries, asserting on the RAW rows before collapsing into a hash:
+    # a store returning one row per append (every historical fold version)
+    # would otherwise pass — and then surface duplicate sessions from
+    # list_sessions_from_store.
+    def summaries_by_id(store, project, expected_ids, message)
+      rows = Array(store.list_session_summaries(project))
+      assert_eq(rows.map { |s| s['session_id'] }.sort, expected_ids.sort, message)
+      rows.to_h { |s| [s['session_id'], s] }
+    end
+
+    def optional?(store, method, skip_optional)
+      return false if skip_optional.include?(method)
+
+      SessionStore.implements?(store, method.to_sym)
+    end
+
+    def assert(condition, message)
+      raise ConformanceError, "SessionStore conformance failed: #{message}" unless condition
+    end
+
+    def assert_eq(actual, expected, message)
+      return if actual == expected
+
+      raise ConformanceError,
+            "SessionStore conformance failed: #{message}\n  expected: #{expected.inspect}\n  actual:   #{actual.inspect}"
+    end
+
+    private_class_method :check_append_and_load, :check_list_sessions, :check_list_session_summaries,
+                         :check_delete, :check_list_subkeys, :key, :entry, :epoch_ms?, :optional?,
+                         :summaries_by_id, :assert, :assert_eq
+  end
+end

data/lib/claude_agent_sdk/transcript_mirror_batcher.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'async'
+require 'async/semaphore'
+require_relative 'fiber_boundary'
+require_relative 'session_store'
+
+module ClaudeAgentSDK
+  # Batching layer between `transcript_mirror` stdout frames and a SessionStore.
+  #
+  # The CLI subprocess emits
+  # `{"type":"transcript_mirror","filePath":...,"entries":[...]}` frames
+  # interleaved with normal SDK messages. The Query read loop peels these off
+  # and hands them to #enqueue, which accumulates them and flushes to
+  # SessionStore#append either when a `result` message arrives (explicit
+  # #flush) or when the pending buffer exceeds size thresholds (eager
+  # background flush). This keeps adapter latency off the hot path during
+  # model streaming.
+  #
+  # Adapter failures are retried (MIRROR_APPEND_MAX_ATTEMPTS total) with short
+  # backoff; timeouts are not retried since the in-flight call may still land.
+  # Failures never raise — the local-disk transcript is already durable, so the
+  # session continues unaffected — and are reported via the +on_error+ callback
+  # (which surfaces them as a MirrorErrorMessage). Adapters should dedupe by
+  # entry["uuid"] when present, since a retried batch may overlap a prior write.
+  #
+  # The semaphore serializes appends, but a #send that exceeds send_timeout is
+  # abandoned (its worker thread keeps running) and the next drain proceeds, so
+  # two #append calls for the SAME key can briefly overlap. SessionStore#append
+  # must be thread-safe per key (see that method's contract).
+  class TranscriptMirrorBatcher
+    # Eager-flush thresholds (exposed for tests).
+    MAX_PENDING_ENTRIES = 500
+    MAX_PENDING_BYTES = 1 << 20 # 1 MiB
+    SEND_TIMEOUT_SECONDS = 60.0
+
+    # Bounded retry for transient adapter failures. The backoff list length is
+    # MIRROR_APPEND_MAX_ATTEMPTS - 1 (one delay between each pair of attempts).
+    MIRROR_APPEND_MAX_ATTEMPTS = 3
+    MIRROR_APPEND_BACKOFF_S = [0.2, 0.8].freeze
+
+    # @param store [SessionStore] the adapter to mirror into
+    # @param projects_dir [String] base dir for file_path -> SessionKey mapping
+    # @param on_error [#call] called as on_error.call(key, message) after a batch
+    #   exhausts retries; must not raise
+    def initialize(store:, projects_dir:, on_error:, send_timeout: SEND_TIMEOUT_SECONDS,
+                   max_pending_entries: MAX_PENDING_ENTRIES, max_pending_bytes: MAX_PENDING_BYTES)
+      @store = store
+      @projects_dir = projects_dir
+      @on_error = on_error
+      @send_timeout = send_timeout
+      @max_pending_entries = max_pending_entries
+      @max_pending_bytes = max_pending_bytes
+      @pending = []
+      @pending_entries = 0
+      @pending_bytes = 0
+      # Fiber-aware lock: the critical section blocks on SessionStore#append
+      # (a thread hop), so a Thread::Mutex would deadlock the reactor. The
+      # semaphore serializes drains so append ordering matches enqueue order.
+      @lock = Async::Semaphore.new(1)
+    end
+
+    # Buffer a frame; schedule an eager background flush if thresholds are
+    # exceeded. Synchronous and fire-and-forget.
+    #
+    # +entries+ are deep-stringified because the transport parses CLI output
+    # with symbolized keys, but SessionStore entries are opaque JSON blobs that
+    # must round-trip through string keys (Postgres JSONB / Redis) and feed
+    # fold_session_summary, which reads string keys.
+    def enqueue(file_path, entries)
+      entries = deep_stringify(Array(entries))
+      # An empty frame mirrors nothing (do_flush skips empty keys anyway), so
+      # drop it here: otherwise its 2-byte "[]" inflates @pending_bytes and, in
+      # eager mode (thresholds 0), schedules a no-op background drain per frame.
+      return if entries.empty?
+
+      # Approximate wire size — one stringify per frame (not per entry).
+      size = JSON.generate(entries).bytesize
+      @pending << { file_path: file_path, entries: entries }
+      @pending_entries += entries.length
+      @pending_bytes += size
+      return unless @pending_entries > @max_pending_entries || @pending_bytes > @max_pending_bytes
+
+      task = Async::Task.current?
+      # Fire-and-forget on the reactor; @lock in #drain serializes against any
+      # in-flight flush so append ordering holds. #drain never raises.
+      task ? task.async { drain } : drain
+    end
+
+    # Flush all pending entries, serialized after any in-flight eager flush.
+    def flush
+      drain
+    end
+
+    # Final flush before teardown. Never raises.
+    def close
+      flush
+    rescue StandardError => e
+      warn "Claude SDK: TranscriptMirrorBatcher close flush failed: #{e.message}"
+    end
+
+    private
+
+    # Detach the pending buffer, await any prior flush, then send. Detaching
+    # before acquiring the lock lets #enqueue keep accumulating into a fresh
+    # buffer while a prior flush is in flight. Never raises.
+    def drain
+      items = @pending
+      @pending = []
+      @pending_entries = 0
+      @pending_bytes = 0
+
+      errors = []
+      @lock.acquire do
+        # Emptiness is checked INSIDE the lock (matching the Python batcher):
+        # an empty #flush/#close still serializes behind any in-flight or
+        # queued drain, so they are true barriers — at result-yield and at
+        # teardown the store really is up to date, and Query#close can't stop
+        # the read task while a detached batch is still being appended.
+        next if items.empty?
+
+        do_flush(items, errors)
+      rescue StandardError => e
+        # do_flush already guards each append; this guards any remaining path
+        # so the "never raises" contract holds against future regressions.
+        warn "Claude SDK: TranscriptMirrorBatcher drain failed: #{e.message}"
+      end
+
+      # Report errors after releasing the lock so a slow on_error callback can't
+      # block subsequent drains (which only need the lock for append ordering).
+      errors.each do |key, message|
+        @on_error.call(key, message)
+      rescue StandardError => e
+        warn "Claude SDK: TranscriptMirrorBatcher on_error callback raised: #{e.message}"
+      end
+    end
+
+    def do_flush(items, errors)
+      # Coalesce by file_path: one append per unique file per flush instead of
+      # one per frame. First-seen file order preserved; entries keep enqueue order.
+      by_path = {}
+      items.each do |item|
+        (by_path[item[:file_path]] ||= []).concat(item[:entries])
+      end
+
+      by_path.each do |file_path, entries|
+        next if entries.empty? # avoid phantom keys in adapters that touch storage on append([])
+
+        key = SessionStores.file_path_to_session_key(file_path, @projects_dir)
+        if key.nil?
+          warn "Claude SDK: [SessionStore] dropping mirror frame: filePath #{file_path} is not under " \
+               "#{@projects_dir} -- subprocess CLAUDE_CONFIG_DIR likely differs from parent (custom env / container?)"
+          next
+        end
+
+        append_with_retry(file_path, key, entries, errors)
+      end
+    end
+
+    def append_with_retry(file_path, key, entries, errors)
+      last_err = nil
+      succeeded = false
+
+      MIRROR_APPEND_MAX_ATTEMPTS.times do |attempt|
+        sleep_backoff(MIRROR_APPEND_BACKOFF_S[attempt - 1]) if attempt.positive?
+        status, err = invoke_append(key, entries)
+        case status
+        when :ok
+          succeeded = true
+          break
+        when :timeout
+          # Don't retry on timeout: the in-flight call may still land, so a
+          # retry would launch a concurrent duplicate. Also bounds worst-case
+          # lock hold at ~send_timeout rather than ~3x.
+          last_err = err
+          break
+        else # :error — retryable
+          last_err = err
+        end
+      end
+
+      errors << [key, last_err.to_s] unless succeeded
+      warn "Claude SDK: TranscriptMirrorBatcher flush failed for #{file_path}: #{last_err}" unless succeeded
+    end
+
+    # Run SessionStore#append (user code) on a plain thread via FiberBoundary,
+    # bounded by send_timeout (enforced with or without an active reactor).
+    # Returns [:ok, nil] / [:timeout, err] / [:error, err]. On timeout the
+    # worker thread is left running (cancellation is best-effort; the in-flight
+    # call may still land) and not retried.
+    def invoke_append(key, entries)
+      FiberBoundary.invoke(timeout: @send_timeout) { @store.append(key, entries) }
+      [:ok, nil]
+    rescue FiberBoundary::JoinTimeout
+      [:timeout, "append timed out after #{@send_timeout}s"]
+    rescue StandardError, NotImplementedError => e
+      # NotImplementedError is a ScriptError, not a StandardError: the base
+      # SessionStore stubs raise it, and letting it escape here would kill the
+      # whole reactor instead of surfacing a MirrorErrorMessage.
+      [:error, e]
+    end
+
+    # Sleep that yields the reactor when one is active, else a plain sleep.
+    def sleep_backoff(seconds)
+      task = Async::Task.current?
+      task ? task.sleep(seconds) : sleep(seconds)
+    end
+
+    def deep_stringify(obj)
+      case obj
+      when Hash then obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = deep_stringify(v) }
+      when Array then obj.map { |elem| deep_stringify(elem) }
+      else obj
+      end
+    end
+  end
+end

data/lib/claude_agent_sdk/types.rb

@@ -290,6 +290,13 @@ module ClaudeAgentSDK
     attr_accessor :uuid, :session_id, :content
   end
 
+  # Emitted when a session_store mirror batch exhausts its retries and is
+  # dropped. The local-disk transcript is still durable; this is the consumer's
+  # only signal that the external store missed a batch (at-most-once delivery).
+  class MirrorErrorMessage < SystemMessage
+    attr_accessor :uuid, :session_id, :error, :key
+  end
+
   # Hook started system message
   class HookStartedMessage < SystemMessage
     attr_accessor :uuid, :session_id, :hook_id, :hook_name, :hook_event
@@ -1344,17 +1351,19 @@ module ClaudeAgentSDK
 
   # Sandbox network configuration
   class SandboxNetworkConfig < Type
-    attr_accessor :allowed_domains, :allow_managed_domains_only,
+    attr_accessor :allowed_domains, :denied_domains, :allow_managed_domains_only,
                   :allow_unix_sockets, :allow_all_unix_sockets, :allow_local_binding,
-                  :http_proxy_port, :socks_proxy_port
+                  :allow_mach_lookup, :http_proxy_port, :socks_proxy_port
 
     def to_h
       result = {}
       result[:allowedDomains] = @allowed_domains if @allowed_domains
+      result[:deniedDomains] = @denied_domains if @denied_domains
       result[:allowManagedDomainsOnly] = @allow_managed_domains_only unless @allow_managed_domains_only.nil?
       result[:allowUnixSockets] = @allow_unix_sockets unless @allow_unix_sockets.nil?
       result[:allowAllUnixSockets] = @allow_all_unix_sockets unless @allow_all_unix_sockets.nil?
       result[:allowLocalBinding] = @allow_local_binding unless @allow_local_binding.nil?
+      result[:allowMachLookup] = @allow_mach_lookup if @allow_mach_lookup
       result[:httpProxyPort] = @http_proxy_port if @http_proxy_port
       result[:socksProxyPort] = @socks_proxy_port if @socks_proxy_port
       result
@@ -1475,26 +1484,33 @@ module ClaudeAgentSDK
                   :output_format, :max_budget_usd, :max_thinking_tokens,
                   :fallback_model, :plugins, :debug_stderr,
                   :betas, :tools, :sandbox, :append_allowed_tools,
-                  :thinking, :effort, :observers, :task_budget
+                  :thinking, :effort, :observers, :task_budget,
+                  :session_store, :session_store_flush, :load_timeout_ms
     attr_reader :bare, :fork_session, :enable_file_checkpointing,
-                :include_partial_messages, :continue_conversation
+                :include_partial_messages, :continue_conversation,
+                :include_hook_events, :strict_mcp_config
 
     def initialize(attributes = {})
       self.fork_session = false
       self.continue_conversation = false
       self.include_partial_messages = false
       self.enable_file_checkpointing = false
+      self.include_hook_events = false
+      self.strict_mcp_config = false
 
       super(merge_with_defaults(attributes || {}))
 
       # Non-nil defaults for options that need them.
-      self.env              ||= {}
-      self.extra_args       ||= {}
-      self.mcp_servers      ||= {}
-      self.add_dirs         ||= []
-      self.observers        ||= []
-      self.allowed_tools    ||= []
-      self.disallowed_tools ||= []
+      self.env                 ||= {}
+      self.extra_args          ||= {}
+      self.mcp_servers         ||= {}
+      self.add_dirs            ||= []
+      self.observers           ||= []
+      self.allowed_tools       ||= []
+      self.disallowed_tools    ||= []
+      self.session_store_flush ||= 'batched'
+      # 0 is a valid (immediate) timeout, so only fill in the default for nil.
+      self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
     end
 
     def dup_with(**changes)
@@ -1543,6 +1559,22 @@ module ClaudeAgentSDK
       @continue_conversation = coerce_boolean(value)
     end
 
+    def include_hook_events?
+      !!include_hook_events
+    end
+
+    def include_hook_events=(value)
+      @include_hook_events = coerce_boolean(value)
+    end
+
+    def strict_mcp_config?
+      !!strict_mcp_config
+    end
+
+    def strict_mcp_config=(value)
+      @strict_mcp_config = coerce_boolean(value)
+    end
+
     private
 
     # Strict key validation: unlike other Type subclasses (which silently drop

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.16.9'
+  VERSION = '0.17.0'
 end