claude-agent-sdk 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4e4fcd2fa1c18916f41409482c8edfe3367ea5b06db9a90b80ed168f339a45e
-  data.tar.gz: 3726daa4aa431b4dba5cd181433066bc8f541efbe13984799c8642bfc671e75e
+  metadata.gz: 760ec1fb0cf80f6e56d7b5d3adb20ca2956b209d0961020ae36fa52a13e28144
+  data.tar.gz: 6ba365de4438e4081f9bfa47afadc4859d9a001bb6238c0b66f00437cb032626
 SHA512:
-  metadata.gz: 00cb37c301d1c1eae778bd55b0d19330e21b6069a0943a6cd7a7931da4d32d8da847c8362f102d530aed8cdcf66f28eb9ca57ac248ed5ce2cbcd5609b3435ab0
-  data.tar.gz: 0bcabed11ba7e49c78ab383bf1186d39cd65873e1190f13a7cbfc102f1c2c7f0226fc8604818f3fc4cf3706760334abb5bc82a7c9ab6e6c9d1e178fd3a1c3002
+  metadata.gz: 672d6640b3bdefc6c5d9cf599c41b89b6259107f780981da382b18bfa56180788225d5e278ab9a7ef22e79a09a000b48147a1a285b74182b5f4254d8d8ec474e
+  data.tar.gz: 0b6eff840de87f744de373bea259fd89a36ca1af33fbc2c678ac84296115b9a5fad841941feabaeb8ebda9c8333d6f4d72a380379c09c410e6358c571af1b26b

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-07-31
+
+### Added
+- **Fiber-native SessionStore adapters** (#47 phase 3): an adapter whose IO is entirely Fiber-scheduler-aware can declare it by defining an optional `callback_scheduling` method returning `:inline`. Every timeout-bounded store call the SDK makes (mirror-batcher appends; resume-materialization loads **and** the listing methods `list_sessions` / `list_session_summaries` / `list_subkeys`) then runs in place on the reactor fiber under a **cooperative** timeout — interrupted at the next suspension point with `ensure` blocks running — instead of on a throwaway thread with a hard `Thread#join` bound. The outward exception contract is unchanged (`FiberBoundary::JoinTimeout`); undeclared adapters are byte-for-byte untouched, and outside a reactor the hard bound still applies even for declared adapters. Cancellation reaches only the adapter's own fiber (offloaded work may still land afterwards), so timed-out appends are not retried in either mode and may remain permanently half-applied in the store — the drop is surfaced (`MirrorErrorMessage`, `batches_dropped?`) and the local transcript remains the source of truth. Invalid or raising declarations fail fast (`ArgumentError` at construction; conformance contract 17). Apps can opt a third-party fiber-native adapter in via `def store.callback_scheduling = :inline`.
+
 ## [0.26.0] - 2026-07-31
 
 ### Added

data/README.md

@@ -68,7 +68,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.26.0'
+gem 'claude-agent-sdk', '~> 0.27.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/docs/rails.md

@@ -80,7 +80,7 @@ end
 
 Preconditions, spelled out: `:inline` is only correct when the process satisfies the same requirements as solid_queue's fiber workers — `isolation_level = :fiber`, Rails 7.2+ for AR, and no thread-keyed libraries used inside callbacks without a fiber-aware wrapper. The SDK warns once if it detects `:inline` under `isolation_level == :thread`. Everything else (Puma request threads, threaded Sidekiq/solid_queue workers) should stay on the default `callback_scheduling: :thread`.
 
-Note that `SessionStore` adapter calls (`#append` / `#load`) intentionally stay on threads even in `:inline` mode — their timeouts are hard bounds (`Thread#join`) so a wedged store adapter can never stall the reactor.
+Note that `SessionStore` adapter calls (`#append` / `#load`) stay on threads by default even in `:inline` mode — their timeouts are hard bounds (`Thread#join`) so a wedged store adapter can never stall the reactor. The exception is an adapter that declares itself fiber-native via an optional `callback_scheduling` method returning `:inline` (see "Fiber-native adapters" in [docs/sessions.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/sessions.md)); its calls then run on the reactor under a cooperative timeout.
 
 ## ActionCable Streaming
 

data/docs/sessions.md

@@ -154,7 +154,8 @@ during resume materialization, default `60_000`).
 > Python and TypeScript SDKs.
 >
 > The temp dir is deleted at disconnect — **unless the mirror dropped batches**
-> (adapter failures that exhausted retries, surfaced as `MirrorErrorMessage`):
+> (terminal append failures — timeouts immediately, other failures after up to
+> three attempts — surfaced as `MirrorErrorMessage`):
 > the store copy is then incomplete and the temp dir holds the only copy of the
 > dropped turns, so the SDK scrubs the credential copies, keeps the transcripts,
 > and warns with the preserved path so you can import them into the store.
@@ -175,6 +176,48 @@ Copy-in reference adapters for **S3, Redis, and Postgres** live in
 [`examples/session_stores/`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md), each with a
 production checklist.
 
+#### Fiber-native adapters
+
+By default the SDK runs every timeout-bounded adapter call (`#append` from the
+mirror batcher, `#load` and friends during resume materialization) on a
+throwaway thread with a hard `Thread#join` timeout, so a wedged adapter can
+never stall the reactor. An adapter whose IO is **entirely
+Fiber-scheduler-aware** (e.g. built on `async`-native clients) can opt out of
+the thread hop by declaring it:
+
+```ruby
+class MyAsyncStore
+  def callback_scheduling = :inline
+  # append/load ...
+end
+```
+
+Declaring `:inline` means the calls run in place on the reactor fiber under a
+**cooperative** timeout. Three consequences to understand before opting in:
+
+- The declaration covers **every method the SDK invokes on the adapter** —
+  `append`, `load`, `list_sessions`, `list_session_summaries`,
+  `list_subkeys` — not just append/load: resume materialization runs the
+  listing calls inline too. **All** blocking inside all of them must yield to
+  the scheduler. Scheduler-opaque blocking (CPU-bound work, GVL-holding C
+  extensions, native drivers the scheduler can't see) stalls every job on
+  that worker **and** the cooperative timeout cannot fire while it blocks.
+- Cancellation semantics change: a timed-out call is interrupted at its next
+  suspension point and its `ensure` blocks run, instead of being abandoned on
+  a thread. The cancellation reaches only the adapter's **own fiber** — work
+  the adapter offloaded (descendant tasks, an already-issued remote write)
+  may still land afterwards. Timed-out appends are therefore **not retried**
+  (same as thread mode; a retry would race that still-landing work), and the
+  interrupted append may remain permanently **half-applied** in the store.
+  The drop is surfaced like every dropped batch — `MirrorErrorMessage` on
+  the stream, `batches_dropped?` on the batcher — and the local transcript
+  remains the source of truth, so nothing is lost from the session itself.
+
+Anything other than `:thread`/`:inline` raises `ArgumentError` when the
+session is set up; without a reactor the hard thread-hop bound still applies
+even for declared adapters. To opt in a third-party fiber-native adapter you
+don't own: `def store.callback_scheduling = :inline` (singleton method).
+
 ### Store-backed helpers
 
 The browsing/mutation helpers above have store-backed counterparts that take a

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'async'
+
 module ClaudeAgentSDK
   # Internal. Consumers of the SDK should never need this directly.
   #
@@ -38,11 +40,19 @@ module ClaudeAgentSDK
   # it via a scoped, invalidatable fiber-storage entry instead — see
   # SCHEDULING_KEY / SchedulingScope below.
   #
-  # A `timeout:` always forces the thread hop regardless of scheduling —
-  # `Thread#join(timeout)` is a hard bound that can abandon a wedged call,
-  # which cooperative `with_timeout` cancellation cannot guarantee. The
-  # store-adapter call sites (TranscriptMirrorBatcher, SessionResume) rely
-  # on this to never stall the reactor on a wedged adapter.
+  # A `timeout:` forces the thread hop — `Thread#join(timeout)` is a hard
+  # bound that can abandon a wedged call, which cooperative `with_timeout`
+  # cancellation cannot guarantee — unless the caller passes
+  # `scheduling: :inline` inside a reactor, where the bound becomes a
+  # cooperative `with_timeout` cancellation instead (issue #47 phase 3:
+  # fiber-native SessionStore adapters that declare
+  # `callback_scheduling -> :inline`). The store-adapter call sites
+  # (TranscriptMirrorBatcher, SessionResume) default to the thread hop so
+  # an undeclared (possibly scheduler-opaque) adapter can never stall the
+  # reactor; a declared-inline adapter accepts that a scheduler-opaque
+  # blocking call would stall it AND escape the cooperative deadline.
+  # Outside a reactor the hard bound applies even to inline-declared
+  # adapters — the timeout guarantee is never lost.
   #
   # The thread hop severs `break`/`return`/`next` from the surrounding method,
   # so SDK loops yielding user callbacks must keep loop control outside the
@@ -65,8 +75,9 @@ module ClaudeAgentSDK
     class JoinTimeout < StandardError; end
 
     # Cancellation injected into INLINE user callbacks by timeout
-    # enforcement (hook timeouts under scheduling: :inline) — user code
-    # should let it propagate. Deliberately
+    # enforcement (hook timeouts under scheduling: :inline; store-adapter
+    # timeouts for adapters declaring callback_scheduling :inline) — user
+    # code should let it propagate. Deliberately
     # NOT a StandardError: the exception is raised inside user code at a
     # suspension point, and a callback's ordinary `rescue StandardError`
     # must not be able to swallow the cancellation and convert an expired
@@ -133,10 +144,16 @@ module ClaudeAgentSDK
     # Run the given block on a plain thread when a Fiber scheduler is active.
     # Returns the block's value. Exceptions propagate to the caller.
     #
-    # With +timeout+ (seconds) the thread hop happens unconditionally — even
-    # without a scheduler or with `scheduling: :inline` — so the bound is
-    # enforced in plain synchronous code too; JoinTimeout is raised when it
-    # expires.
+    # With +timeout+ (seconds) the thread hop happens regardless of a
+    # scheduler being active, so the bound is enforced in plain synchronous
+    # code too; JoinTimeout is raised when it expires. Exception: with
+    # `scheduling: :inline` INSIDE an Async task, the block instead runs in
+    # place under a cooperative `with_timeout` — the deadline is delivered
+    # as InlineCancellation at the block's next suspension point (its
+    # ensure blocks run; not swallowable by `rescue StandardError`) and
+    # surfaces as the same JoinTimeout, so callers need no changes. When
+    # inline is requested but no Async task is present, the hard
+    # thread-hop bound applies — the timeout guarantee is never lost.
     #
     # With `scheduling: :inline` (and no timeout) the block runs in place on
     # the current fiber, scheduler or not. The caller opts in via
@@ -165,6 +182,25 @@ module ClaudeAgentSDK
       body = wrapper && timeout.nil? ? -> { wrapper.call(block) } : block
       return body.call if timeout.nil? && (scheduling == :inline || !Fiber.scheduler)
 
+      # Cooperative timeout for inline-declared store adapters: in place on
+      # the reactor fiber, cancelled at the next suspension point. The
+      # wrapper stays ignored on timeout paths (store adapters are never
+      # wrapped), so `body` is the bare block here. The cancellation class
+      # is a fresh per-invocation subclass: rescuing the shared base would
+      # also catch an OUTER timeout's cancellation delivered while this
+      # call is suspended (nested with_timeout — e.g. a store call inside a
+      # timed inline hook), mis-attributing the outer deadline to this call
+      # and letting execution continue past it. An outer cancellation is a
+      # different subclass, so it propagates through untouched.
+      if timeout && scheduling == :inline && (task = Async::Task.current?)
+        cancellation = Class.new(InlineCancellation)
+        begin
+          return task.with_timeout(timeout, cancellation, &block)
+        rescue cancellation
+          raise JoinTimeout, "timed out after #{timeout}s"
+        end
+      end
+
       thread = Thread.new(&body)
       thread.report_on_exception = false
       return thread.value if timeout.nil?

data/lib/claude_agent_sdk/query.rb

@@ -270,8 +270,9 @@ module ClaudeAgentSDK
     end
 
     # Synthesize a `mirror_error` system message and put it on the SDK message
-    # stream so consumers learn a mirror batch was dropped after exhausting
-    # retries. Non-blocking: the message queue is unbounded, so unlike the
+    # stream so consumers learn a mirror batch was dropped (timeouts
+    # immediately, other failures after up to three attempts).
+    # Non-blocking: the message queue is unbounded, so unlike the
     # Python SDK there is no buffer-full drop path.
     def report_mirror_error(key, error)
       session_id = key && (key['session_id'] || key[:session_id])
@@ -634,13 +635,18 @@ module ClaudeAgentSDK
             # wrapper composes INSIDE with_timeout, and the cancellation
             # passes through it un-swallowed (InlineCancellation is not a
             # StandardError, so a wrapper's ordinary rescue can't eat it).
+            # Fresh per-invocation subclass: rescuing the shared base would
+            # also catch an OUTER timeout's cancellation (e.g. an inline
+            # store call nested inside this hook already uses its own), so
+            # each timeout scope must only consume its own deadline.
             begin
-              Async::Task.current.with_timeout(timeout, FiberBoundary::InlineCancellation) do
+              cancellation = Class.new(FiberBoundary::InlineCancellation)
+              Async::Task.current.with_timeout(timeout, cancellation) do
                 FiberBoundary.invoke(scheduling: :inline, wrapper: @callback_wrapper) do
                   callback.call(hook_input, request_data[:tool_use_id], context)
                 end
               end
-            rescue FiberBoundary::InlineCancellation
+            rescue cancellation
               raise Async::TimeoutError, 'execution expired'
             end
           else

data/lib/claude_agent_sdk/session_resume.rb

@@ -108,6 +108,10 @@ module ClaudeAgentSDK
       return nil if options.resume.nil? && !options.continue_conversation
 
       timeout_s = options.load_timeout_ms / 1000.0
+      # Probed ONCE at materialization entry (the resume path's construction
+      # point) so an invalid callback_scheduling declaration fails fast here,
+      # before any store IO or temp-dir work.
+      scheduling = SessionStores.store_callback_scheduling(store)
       project_key = Sessions.project_key_for_directory(options.cwd)
 
       resolved =
@@ -116,9 +120,9 @@ module ClaudeAgentSDK
           # prevent traversal and match every other resume path.
           return nil unless options.resume.match?(Sessions::UUID_RE)
 
-          load_candidate(store, project_key, options.resume, timeout_s)
+          load_candidate(store, project_key, options.resume, timeout_s, scheduling)
         else
-          resolve_continue_candidate(store, project_key, timeout_s)
+          resolve_continue_candidate(store, project_key, timeout_s, scheduling)
         end
       return nil if resolved.nil?
 
@@ -133,7 +137,7 @@ module ClaudeAgentSDK
         # so it can authenticate. Missing files are fine (API-key auth, etc.).
         copy_auth_files(tmp_base, options.env)
 
-        materialize_subkeys(store, project_dir, project_key, session_id, timeout_s) if SessionStore.implements?(store, :list_subkeys)
+        materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling) if SessionStore.implements?(store, :list_subkeys)
       rescue Exception # rubocop:disable Lint/RescueException
         # Any failure after mkdtemp leaves tmp_base (which may already hold a
         # .credentials.json copy) on disk with no path for the caller to clean
@@ -149,8 +153,8 @@ module ClaudeAgentSDK
     # -- Helpers --
 
     # Load entries for session_id; return [session_id, entries] or nil if empty.
-    def load_candidate(store, project_key, session_id, timeout_s)
-      entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}") do
+    def load_candidate(store, project_key, session_id, timeout_s, scheduling)
+      entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}", scheduling) do
         store.load('project_key' => project_key, 'session_id' => session_id)
       end
       return nil if entries.nil? || entries.empty?
@@ -162,13 +166,13 @@ module ClaudeAgentSDK
     # transcripts are mirrored as ordinary top-level keys and often have the
     # highest mtime, so walk newest->oldest and skip them so --continue resumes
     # the user's conversation, not a subagent's.
-    def resolve_continue_candidate(store, project_key, timeout_s)
-      sessions = with_timeout(timeout_s, 'SessionStore#list_sessions') do
+    def resolve_continue_candidate(store, project_key, timeout_s, scheduling)
+      sessions = with_timeout(timeout_s, 'SessionStore#list_sessions', scheduling) do
         store.list_sessions(project_key)
       end
       return nil if sessions.nil? || sessions.empty?
 
-      sidechain_flags = sidechain_flags_from_summaries(store, project_key, timeout_s)
+      sidechain_flags = sidechain_flags_from_summaries(store, project_key, timeout_s, scheduling)
 
       sessions.sort_by { |s| -sortable_mtime(s['mtime']) }.each do |cand|
         sid = cand['session_id']
@@ -178,7 +182,7 @@ module ClaudeAgentSDK
         # --continue O(sum of transcript sizes) instead of O(candidates).
         next if sidechain_flags&.fetch(sid, false)
 
-        loaded = load_candidate(store, project_key, sid, timeout_s)
+        loaded = load_candidate(store, project_key, sid, timeout_s, scheduling)
         next if loaded.nil?
 
         first = loaded[1][0]
@@ -194,10 +198,10 @@ module ClaudeAgentSDK
     # fails (callers then fall back to checking each full load). The per-load
     # isSidechain check above stays even on the summary path: a missing or
     # stale sidecar row costs one extra load, never a wrong resume.
-    def sidechain_flags_from_summaries(store, project_key, timeout_s)
+    def sidechain_flags_from_summaries(store, project_key, timeout_s, scheduling)
       return nil unless SessionStore.implements?(store, :list_session_summaries)
 
-      rows = with_timeout(timeout_s, 'SessionStore#list_session_summaries') do
+      rows = with_timeout(timeout_s, 'SessionStore#list_session_summaries', scheduling) do
         store.list_session_summaries(project_key)
       end
       Array(rows).each_with_object({}) do |row, acc|
@@ -227,13 +231,17 @@ module ClaudeAgentSDK
 
     # Run a store call (user code) on a plain thread bounded by timeout_s,
     # re-raising failures/timeouts as RuntimeError with context. The thread hop
-    # (FiberBoundary with a timeout always hops) both keeps the async scheduler
-    # out of the user's store code AND enforces load_timeout_ms unconditionally
-    # — including when materialization runs outside an Async reactor, where a
-    # direct call would let a hung adapter block connect forever. A timed-out
-    # worker is left running (not killed) since it may still complete.
-    def with_timeout(timeout_s, what, &block)
-      FiberBoundary.invoke(timeout: timeout_s, &block)
+    # (the default for FiberBoundary with a timeout) both keeps the async
+    # scheduler out of the user's store code AND enforces load_timeout_ms
+    # unconditionally — including when materialization runs outside an Async
+    # reactor, where a direct call would let a hung adapter block connect
+    # forever. A timed-out worker is left running (not killed) since it may
+    # still complete. An adapter declaring `callback_scheduling -> :inline`
+    # (probed once at materialization entry) instead runs in place under a
+    # cooperative timeout when a reactor is present — outside one, the hard
+    # thread-hop bound still applies.
+    def with_timeout(timeout_s, what, scheduling = :thread, &block)
+      FiberBoundary.invoke(timeout: timeout_s, scheduling: scheduling, &block)
     rescue FiberBoundary::JoinTimeout
       raise "#{what} timed out after #{(timeout_s * 1000).to_i}ms during resume materialization"
     rescue RuntimeError
@@ -363,9 +371,9 @@ module ClaudeAgentSDK
     end
 
     # Load and write all subagent transcripts/metadata under session_id.
-    def materialize_subkeys(store, project_dir, project_key, session_id, timeout_s)
+    def materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling)
       session_dir = File.join(project_dir, session_id)
-      subkeys = with_timeout(timeout_s, "SessionStore#list_subkeys for session #{session_id}") do
+      subkeys = with_timeout(timeout_s, "SessionStore#list_subkeys for session #{session_id}", scheduling) do
         store.list_subkeys('project_key' => project_key, 'session_id' => session_id)
       end
 
@@ -377,7 +385,7 @@ module ClaudeAgentSDK
           next
         end
 
-        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}") do
+        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}", scheduling) do
           store.load('project_key' => project_key, 'session_id' => session_id, 'subpath' => subpath)
         end
         next if sub_entries.nil? || sub_entries.empty?

data/lib/claude_agent_sdk/session_store.rb

@@ -32,6 +32,32 @@ module ClaudeAgentSDK
   #   - 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)
+  #
+  # FIBER-NATIVE ADAPTERS (issue #47 phase 3): an adapter whose IO is
+  # entirely Fiber-scheduler-aware may additionally define an optional
+  # `callback_scheduling` method returning `:inline` (`:thread` = default
+  # behavior). The SDK then runs the adapter's timeout-bounded calls in place
+  # on the reactor fiber under a cooperative timeout instead of on a
+  # throwaway thread with a hard `Thread#join` bound. The declaration covers
+  # EVERY method the SDK invokes on the adapter — append, load,
+  # list_sessions, list_session_summaries, list_subkeys — not just
+  # append/load: resume materialization inlines the listing calls too. Only
+  # the adapter author can make this call — declare :inline ONLY if every
+  # blocking operation in every method yields to the scheduler;
+  # scheduler-opaque blocking stalls every job on the worker AND escapes the
+  # cooperative deadline. A timed-out inline call is interrupted at its next
+  # suspension point (ensure blocks run) rather than abandoned. The
+  # cancellation reaches only the adapter's own fiber — work the adapter
+  # offloaded (descendant tasks, an already-issued remote write) may still
+  # land afterwards — so timed-out appends are NOT retried (same as thread
+  # 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
+  # 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`).
   class SessionStore
     # True if +store+ overrides +method+ rather than inheriting the base
     # implementation that raises NotImplementedError. Works for both subclasses
@@ -249,8 +275,31 @@ module ClaudeAgentSDK
 
   # Internal SessionStore support functions (path mapping, option validation).
   module SessionStores
+    STORE_CALLBACK_SCHEDULING_MODES = %i[thread inline].freeze
+
     module_function
 
+    # Where an adapter's timeout-bounded #append/#load calls run: :thread
+    # (default — hard-bounded thread hop) unless the adapter declares
+    # fiber-nativeness via an optional `callback_scheduling` method returning
+    # :inline (String form coerced, matching ClaudeAgentOptions). Probed
+    # respond_to?-style like the rest of the subsystem. Called once at
+    # construction time (batcher initialize, resume-materialization entry)
+    # so an invalid declaration fails fast there, not mid-session.
+    def store_callback_scheduling(store)
+      return :thread unless store.respond_to?(:callback_scheduling)
+
+      value = store.callback_scheduling
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless STORE_CALLBACK_SCHEDULING_MODES.include?(mode)
+        raise ArgumentError,
+              'session_store#callback_scheduling must return one of ' \
+              "#{STORE_CALLBACK_SCHEDULING_MODES.map(&:inspect).join(', ')} (got #{value.inspect})"
+      end
+
+      mode
+    end
+
     # Derive a SessionKey from an absolute transcript file path.
     #
     #   Main:     <projects_dir>/<project_key>/<session_id>.jsonl

data/lib/claude_agent_sdk/testing/session_store_conformance.rb

@@ -13,9 +13,11 @@ module ClaudeAgentSDK
 
     module_function
 
-    # Assert the 16 SessionStore behavioral contracts against an adapter.
+    # Assert the 17 SessionStore behavioral contracts against an adapter.
     #
     # Contracts 1-14 mirror the Python SDK's run_session_store_conformance.
+    # Contract 17 (Ruby extension) validates the optional
+    # `callback_scheduling` fiber-nativeness declaration (:thread/:inline).
     # Contract 16 (Ruby extension) locks one-row-per-session `list_sessions`
     # under multiple appends — the naive one-row-per-append implementation
     # passed every other contract and then showed N duplicate sessions in
@@ -62,6 +64,7 @@ module ClaudeAgentSDK
       has_delete = optional?(probe, 'delete', skip_optional)
       has_list_subkeys = optional?(probe, 'list_subkeys', skip_optional)
 
+      check_callback_scheduling_declaration(fresh)
       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
@@ -71,6 +74,30 @@ module ClaudeAgentSDK
       nil
     end
 
+    # -- Optional: callback_scheduling declaration ---------------------------
+
+    # 17. an adapter declaring the optional callback_scheduling method (issue
+    # #47 phase 3: fiber-native adapters) must return :thread or :inline —
+    # the SDK probes it at construction and raises ArgumentError otherwise,
+    # so a bad declaration would fail every session using the store. Runs
+    # first because the SDK probes before any store IO; skipped entirely for
+    # non-declaring adapters (the probe defaults to :thread).
+    def check_callback_scheduling_declaration(fresh)
+      store = fresh.call
+      return unless store.respond_to?(:callback_scheduling)
+
+      begin
+        SessionStores.store_callback_scheduling(store)
+      rescue ArgumentError => e
+        assert(false, "callback_scheduling declaration must be :thread or :inline (#{e.message})")
+      rescue StandardError, NotImplementedError => e
+        # A raising declaration is as fatal as a bad value — the SDK probes
+        # it at construction. Report through the harness's documented
+        # ConformanceError instead of leaking the raw exception.
+        assert(false, "callback_scheduling declaration raised #{e.class}: #{e.message}")
+      end
+    end
+
     # -- Required: append + load -------------------------------------------
 
     def check_append_and_load(fresh, has_list_sessions) # rubocop:disable Metrics/MethodLength
@@ -347,8 +374,9 @@ module ClaudeAgentSDK
             "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, :check_uuid_dedupe_contract, :key, :entry,
+    private_class_method :check_callback_scheduling_declaration, :check_append_and_load, :check_list_sessions,
+                         :check_list_session_summaries, :check_delete, :check_list_subkeys,
+                         :check_uuid_dedupe_contract, :key, :entry,
                          :epoch_ms?, :optional?, :summaries_by_id, :assert, :assert_eq
   end
 end

data/lib/claude_agent_sdk/transcript_mirror_batcher.rb

@@ -28,7 +28,14 @@ module ClaudeAgentSDK
   # 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).
+  # must be thread-safe per key (see that method's contract). For adapters
+  # declaring `callback_scheduling -> :inline` the timed-out call is instead
+  # cancelled cooperatively (interrupted at its next suspension point, ensure
+  # runs) — but only on the adapter's own fiber; work the adapter offloaded
+  # may still land, so timeouts are not retried in either mode and the
+  # cancelled append may remain permanently HALF-applied in the store. The
+  # drop is surfaced (MirrorErrorMessage, batches_dropped?); the local
+  # transcript remains the source of truth.
   class TranscriptMirrorBatcher
     # Eager-flush thresholds (exposed for tests).
     MAX_PENDING_ENTRIES = 500
@@ -50,6 +57,9 @@ module ClaudeAgentSDK
       @projects_dir = projects_dir
       @on_error = on_error
       @send_timeout = send_timeout
+      # Probed ONCE here so an invalid callback_scheduling declaration fails
+      # at construction, not mid-session inside a flush.
+      @store_scheduling = SessionStores.store_callback_scheduling(store)
       @max_pending_entries = max_pending_entries
       @max_pending_bytes = max_pending_bytes
       @pending = []
@@ -203,9 +213,18 @@ module ClaudeAgentSDK
           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.
+          # Don't retry on timeout — in EITHER mode. Thread mode: the
+          # abandoned in-flight call may still land, so a retry would launch
+          # a concurrent duplicate. Inline mode: cooperative cancellation
+          # interrupts only the adapter's own fiber — work the adapter
+          # itself offloaded (descendant tasks, an already-issued remote
+          # write) may still land after the cancellation, so a retry races
+          # it exactly like the thread case (adversarially demonstrated in
+          # review: a dedupe-conforming adapter still persisted duplicates).
+          # Uniform no-retry also bounds worst-case lock hold at
+          # ~send_timeout. The dropped batch is surfaced (MirrorErrorMessage,
+          # batches_dropped?) and the local transcript remains the source of
+          # truth.
           last_err = err
           break
         else # :error — retryable
@@ -222,11 +241,16 @@ module ClaudeAgentSDK
 
     # 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.
+    # Returns [:ok, nil] / [:timeout, err] / [:error, err]. On timeout in
+    # thread mode the worker thread is left running (cancellation is
+    # best-effort; the in-flight call may still land) and not retried. An
+    # adapter declaring `callback_scheduling -> :inline` instead runs in
+    # place on the reactor under a cooperative timeout (interrupted at its
+    # next suspension point, ensure blocks run) — same JoinTimeout contract
+    # and same no-retry semantics (see append_with_retry: offloaded work
+    # may outlive the cancellation).
     def invoke_append(key, entries)
-      FiberBoundary.invoke(timeout: @send_timeout) { @store.append(key, entries) }
+      FiberBoundary.invoke(timeout: @send_timeout, scheduling: @store_scheduling) { @store.append(key, entries) }
       [:ok, nil]
     rescue FiberBoundary::JoinTimeout
       [:timeout, "append timed out after #{@send_timeout}s"]

data/lib/claude_agent_sdk/types.rb

@@ -290,9 +290,11 @@ 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).
+  # Emitted when a session_store mirror batch fails terminally and is
+  # dropped — timeouts immediately (never retried), other failures after up
+  # to three attempts. 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

data/lib/claude_agent_sdk/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Community Contributors