parse-stack-next 5.2.1 → 5.4.0

data/Rakefile

@@ -35,6 +35,99 @@ def mcp_credentials_or_abort!
   [server_url, app_id, rest_api_key, master_key]
 end
 
+# Resolve the identity for `rake client:console`. Returns a session-token String,
+# or nil to mean "anonymous" (no token, no master). Order: PARSE_SESSION_TOKEN,
+# PARSE_CLIENT_ANONYMOUS=true, PARSE_LOGIN_USER (+PARSE_LOGIN_PASSWORD), else
+# prompt for login / token / anon. The login path uses the configured default
+# client (the master client set up just before this is called).
+def client_console_token!
+  token = ENV["PARSE_SESSION_TOKEN"].to_s.strip
+  return token unless token.empty?
+  return nil if ENV["PARSE_CLIENT_ANONYMOUS"].to_s == "true"
+
+  user = ENV["PARSE_LOGIN_USER"].to_s.strip
+  if user.empty?
+    print "Identity? [login/token/anon] (login): "
+    case $stdin.gets.to_s.strip.downcase
+    when "anon", "anonymous" then return nil
+    when "token"
+      print "Session token (r:...): "
+      t = $stdin.gets.to_s.strip
+      return t.empty? ? nil : t
+    else
+      print "Username (blank for anonymous): "
+      user = $stdin.gets.to_s.strip
+      return nil if user.empty?
+    end
+  end
+
+  pwd = ENV["PARSE_LOGIN_PASSWORD"].to_s
+  if pwd.empty?
+    begin
+      require "io/console"
+      print "Password for #{user}: "
+      pwd = $stdin.noecho(&:gets).to_s
+      puts
+    rescue LoadError, IOError, SystemCallError
+      # io/console missing, or stdin is not a TTY (piped input raises
+      # Errno::ENOTTY, a SystemCallError — not an IOError). Fall back to a
+      # plain read; warn that it will echo.
+      warn "[client:console] WARNING: cannot disable echo; password will be visible."
+      print "Password for #{user}: "
+      pwd = $stdin.gets.to_s
+    end
+  end
+  u = console_login_with_optional_mfa(user, pwd.chomp)
+  abort "[client:console] login failed for #{user.inspect}" if u.nil? || u.session_token.to_s.empty?
+  puts "Logged in as #{u.username} (#{u.id})."
+  u.session_token
+end
+
+# Log `user` in, transparently handling an MFA-enrolled account. If the server
+# reports that additional MFA auth is required, prompt for a TOTP / recovery
+# code (or read +PARSE_LOGIN_MFA+ for non-interactive use) and retry via
+# {Parse::User.login_with_mfa}. Returns a logged-in {Parse::User}, or nil when
+# the credentials themselves are rejected (so the caller's "login failed" abort
+# still fires for a bad password).
+def console_login_with_optional_mfa(user, pwd)
+  # Parse Server signals "this account needs an MFA token" two ways depending on
+  # the error code path: a returned error response ("Missing additional
+  # authData ...") or a raised Parse::Error for the OTHER_CAUSE (code <= 100)
+  # variant. Treat both as "prompt for MFA"; anything else is a real credential
+  # failure and must NOT trigger an MFA prompt.
+  mfa_indicator = /additional\s+authData|missing.*mfa|\bMFA\b/i
+  begin
+    response = Parse.client.login(user, pwd)
+    if response.success?
+      return Parse::User.with_authdata_trust { Parse::User.build(response.result) }
+    end
+    return nil unless response.error.to_s.match?(mfa_indicator)
+  rescue Parse::Error, Parse::Client::ResponseError => e
+    raise unless e.message.to_s.match?(mfa_indicator)
+  end
+
+  token = ENV["PARSE_LOGIN_MFA"].to_s.strip
+  if token.empty?
+    print "MFA token (authenticator code or recovery code): "
+    token = $stdin.gets.to_s.strip
+  end
+  abort "[client:console] MFA token required for #{user.inspect}" if token.empty?
+
+  # A wrong/expired token can surface either as Parse::MFA::VerificationError or,
+  # depending on the server error code path, as a generic Parse::Error (e.g.
+  # ServiceUnavailableError for the OTHER_CAUSE code) or a nil return. Since a
+  # token was supplied here, treat any failure as an MFA verification failure
+  # and abort cleanly rather than letting an unhandled exception escape.
+  result =
+    begin
+      Parse::User.login_with_mfa(user, pwd, token)
+    rescue Parse::MFA::VerificationError, Parse::Error => e
+      abort "[client:console] MFA verification failed for #{user.inspect}: #{e.message}"
+    end
+  abort "[client:console] MFA verification failed for #{user.inspect}" if result.nil?
+  result
+end
+
 # Default test task runs all tests with Docker enabled.
 #
 # `*disruptive*` tests are EXCLUDED here: they stop/restart the shared
@@ -48,55 +141,96 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
+# Shared runner for the file-per-process test tasks. Each test file runs in its
+# own Ruby process (isolation against the shared Parse Server); output streams
+# live, and — for trackability — a PASS/FAIL + duration line per file is printed
+# to STDOUT *and* appended to a progress log you can `tail -f` from another
+# shell while the run is in flight (works even when the run is backgrounded or
+# piped, where STDOUT would otherwise buffer until completion).
+#
+# Env knobs:
+#   TEST_PATTERN=<substr>       run only files whose path includes <substr>
+#                               (e.g. TEST_PATTERN=webhook)
+#   CONTINUE_ON_FAILURE=false   stop at the first failing file
+#                               (default: run them all, then list every failure)
+#
+# Exits non-zero if any file failed.
+def run_test_files!(label, files, log:)
+  $stdout.sync = true
+  require "fileutils"
+  if (pattern = ENV["TEST_PATTERN"].to_s).length.positive?
+    files = files.select { |f| f.include?(pattern) }
+    puts "TEST_PATTERN=#{pattern} -> #{files.length} matching file(s)"
+  end
+  continue = ENV.fetch("CONTINUE_ON_FAILURE", "true") != "false"
+  FileUtils.mkdir_p(File.dirname(log))
+  total = files.length
+  started = Time.now
+  results = []
+  File.write(log, "#{label}: #{total} files, started #{started}\n")
+  puts "\n>> #{label}: #{total} files (progress log: #{log})"
+
+  files.each_with_index do |file, i|
+    n = i + 1
+    puts "\n" + "=" * 80
+    puts "[#{n}/#{total}] #{file}"
+    puts "=" * 80
+    t0 = Time.now
+    # Always go through `bundle exec` so the locked gem versions win. With a
+    # bare `ruby`, RubyGems activates the newest installed minitest (6.0.x),
+    # which dropped the bundled `minitest/mock`; the standalone `minitest-mock`
+    # gem then can't co-activate and `test_helper.rb` fails to load every file.
+    ok = system("PARSE_TEST_USE_DOCKER=true bundle exec ruby -Ilib:test #{file}")
+    dt = Time.now - t0
+    results << [file, ok, dt]
+    summary = format("[%d/%d] %-4s %7.1fs  %s", n, total, ok ? "PASS" : "FAIL", dt, file)
+    puts summary
+    File.open(log, "a") { |f| f.puts summary }
+    if !ok && !continue
+      File.open(log, "a") { |f| f.puts "STOPPED at first failure (CONTINUE_ON_FAILURE=false)" }
+      break
+    end
+  end
+
+  elapsed = Time.now - started
+  passed = results.count { |_, ok, _| ok }
+  failed = results.reject { |_, ok, _| ok }
+  footer = format("%s: %d/%d passed in %.1fs (%.1f min)",
+                  label, passed, results.length, elapsed, elapsed / 60.0)
+  puts "\n" + "=" * 80
+  puts footer
+  unless failed.empty?
+    puts "Failed (#{failed.length}):"
+    failed.each { |f, _, d| puts format("  FAIL %7.1fs  %s", d, f) }
+  end
+  puts "=" * 80
+  File.open(log, "a") do |f|
+    f.puts footer
+    failed.each { |ff, _, d| f.puts format("  FAIL %7.1fs  %s", d, ff) }
+  end
+  exit(1) unless failed.empty?
+end
+
 # Integration tests require Docker
 namespace :test do
-  desc "Run all integration tests (requires Docker)"
+  desc "Run all integration tests (requires Docker). " \
+       "Knobs: TEST_PATTERN=<substr>, CONTINUE_ON_FAILURE=false."
   task :integration do
     # Disruptive tests (server stop/restart) are run separately via
     # `test:integration:disruptive` so they never interleave with — and
     # flake — the rest of the integration suite against the shared server.
-    integration_files = FileList["test/lib/**/*integration_test.rb"]
-                          .exclude("test/lib/**/*disruptive*")
-
-    puts "Running #{integration_files.length} integration test files..."
-    integration_files.each_with_index do |file, index|
-      puts "Running integration test #{index + 1}/#{integration_files.length}: #{file}"
-
-      # 10: docker integration test fails for cloud functions
-      skip_till = 0
-      if (index + 1) <= skip_till
-        puts "Skipping test #{index + 1} as per configuration\n"
-        next
-      end
-
-      puts "\n" + "="*80
-      puts "Running: #{file}"
-      puts "="*80
-      system("PARSE_TEST_USE_DOCKER=true ruby -Ilib:test #{file}") || exit(1)
-    end
-    puts "\n✅ All integration tests completed successfully!"
+    files = FileList["test/lib/**/*integration_test.rb"]
+              .exclude("test/lib/**/*disruptive*")
+    run_test_files!("Integration tests", files, log: "tmp/integration-progress.log")
   end
 
-  desc "Run unit tests only (no Docker required)"
+  desc "Run unit tests only (no Docker required). " \
+       "Knobs: TEST_PATTERN=<substr>, CONTINUE_ON_FAILURE=false."
   task :unit do
-    unit_files = FileList["test/lib/**/*_test.rb"]
-                   .exclude("test/lib/**/*integration_test.rb")
-                   .exclude("test/lib/**/*disruptive*")
-
-    puts "Running #{unit_files.length} unit test files (no Docker)..."
-    unit_files.each_with_index do |file, index|
-      puts "Running unit test #{index + 1}/#{unit_files.length}: #{file}"
-
-      # 73 is problematic Testing Contains and Nin with Parse Objects with contains and nin 
-      skip_till = 0
-      if (index + 1) <= skip_till
-        puts "Skipping test #{index + 1} as per configuration"
-        next
-      end
-
-      system("PARSE_TEST_USE_DOCKER=true ruby -Ilib:test #{file}") || exit(1)
-    end
-    puts "\n✅ All unit tests completed successfully!"
+    files = FileList["test/lib/**/*_test.rb"]
+              .exclude("test/lib/**/*integration_test.rb")
+              .exclude("test/lib/**/*disruptive*")
+    run_test_files!("Unit tests", files, log: "tmp/unit-progress.log")
   end
 
   namespace :integration do
@@ -118,7 +252,7 @@ namespace :test do
         puts "=" * 80
         # Each file runs in its own process so a server outage in one cannot
         # bleed into the next.
-        system("PARSE_TEST_USE_DOCKER=true ruby -Ilib:test #{file}") || begin
+        system("PARSE_TEST_USE_DOCKER=true bundle exec ruby -Ilib:test #{file}") || begin
           # A disruptive test may have left the server down on failure; bring
           # it back so a follow-up run / other tasks start from a clean state.
           system("docker start #{ENV["PSNEXT_PREFIX"] || "psnext-it"}-server", out: IO::NULL, err: IO::NULL)
@@ -602,6 +736,74 @@ namespace :mcp do
   end
 end
 
+# rake client:console — IRB whose DEFAULT client is a non-master client bound to
+# a user's session, so every model query runs as that user (ACL/CLP enforced).
+# Identity: PARSE_SESSION_TOKEN, or PARSE_LOGIN_USER/PARSE_LOGIN_PASSWORD, else
+# prompt. Connection env matches the other tasks; the master key is used only to
+# log in. Helpers in the REPL: client, whoami, as_master { … }.
+namespace :client do
+  desc "Interactive console authenticated as a Parse user (session token or login), not master"
+  task :console do
+    require "irb"
+    begin; require "dotenv/load"; rescue LoadError; end
+    $LOAD_PATH.unshift(File.expand_path("lib", __dir__))
+    require "parse-stack"
+
+    server_url, app_id, rest_api_key, master_key = mcp_credentials_or_abort!
+    Parse.setup(server_url: server_url, application_id: app_id, api_key: rest_api_key, master_key: master_key)
+    master_client = Parse.client
+    token = client_console_token! # String, or nil for anonymous
+
+    # Models memoize their resolved client at the class level (`@client ||=`),
+    # so swapping clients[:default] alone is NOT enough — every swap must also
+    # drop those cached ivars or already-touched classes keep the old client.
+    reset_client_caches = lambda do
+      next unless defined?(Parse::Object)
+      [Parse::Object, *Parse::Object.descendants, Parse::Query].each do |k|
+        k.remove_instance_variable(:@client) if k.instance_variable_defined?(:@client)
+      end
+    end
+
+    # Make a non-master client (session-bound, or anonymous) the default so
+    # every model query runs as the user.
+    user_client = token ? master_client.become(token) : master_client.anonymous
+    Parse::Client.clients[:default] = user_client
+    reset_client_caches.call
+
+    Object.send(:define_method, :client) { user_client }
+    # Redacted: GET /users/me returns a Parse::User carrying the live
+    # sessionToken, and Parse::Object has no redacted #inspect, so returning the
+    # raw object would print the token in the REPL. Hand back a safe summary.
+    Object.send(:define_method, :whoami) do
+      next "anonymous (no session)" unless token
+      r = user_client.current_user(token)
+      next "whoami failed: #{r.error}" unless r.success?
+      u = r.result
+      { "username" => u["username"], "objectId" => u["objectId"], "session_token" => "[FILTERED]" }
+    rescue StandardError => e
+      "whoami failed: #{e.message}"
+    end
+    # Escalate to the master key for the block, then restore the user client.
+    # Both swaps must reset the class client caches (see reset_client_caches),
+    # otherwise a class touched inside the block keeps master afterward, or a
+    # previously-touched class never escalates. Already-instantiated Parse::Query
+    # objects held in REPL locals keep their own client and are not reset.
+    Object.send(:define_method, :as_master) do |&blk|
+      Parse::Client.clients[:default] = master_client
+      reset_client_caches.call
+      blk.call
+    ensure
+      Parse::Client.clients[:default] = user_client
+      reset_client_caches.call
+    end
+
+    mode = token ? "a USER" : "ANONYMOUS"
+    puts "parse-stack-next client console — as #{mode} (no master key). Helpers: client, whoami, as_master { }."
+    ARGV.clear
+    IRB.start
+  end
+end
+
 desc "List undocumented methods"
 task "yard:stats" do
   exec "yard stats --list-undoc"

data/docs/atlas_vector_search_guide.md

@@ -372,6 +372,10 @@ embed-time chunking), use one of these patterns:
 
 ## Retrieval (RAG)
 
+> For an end-to-end runnable script — managed `embed`, `agent_searchable`,
+> `semantic_search`, and an OpenAI/Anthropic generation add-in — see
+> [`examples/rag_chatbot.rb`](../examples/rag_chatbot.rb).
+
 `Parse::Retrieval` (`Parse::RAG` is an alias) sits on top of
 `find_similar`. `Parse::Retrieval.retrieve` embeds a natural-language
 query, runs Atlas `$vectorSearch` through `find_similar` (so ACL/CLP are
@@ -395,8 +399,88 @@ chunks = Parse::Retrieval.retrieve(
 # => Array<Parse::Retrieval::Chunk> — { id, score, content, source, metadata }
 ```
 
-`rerank:` and `hybrid:` are reserved on the signature and raise
-`NotImplementedError` if supplied.
+`retrieve` also accepts `hybrid:` (fuse a lexical branch with the vector
+branch — see [Hybrid search](#hybrid-search-vector--lexical) below) and
+`rerank:` (reorder retrieved documents with a cross-encoder before
+chunking — see [Reranking](#reranking)). Both were reserved in earlier
+releases and now ship in 5.4.0.
+
+### Hybrid search (vector + lexical)
+
+`Class.hybrid_search` runs a lexical Atlas Search (`$search`) branch and a
+`$vectorSearch` branch as **two independent aggregations**, then fuses
+their ranked results with reciprocal-rank fusion (RRF). Two aggregations
+(not a single `$facet`) is mandatory: `$vectorSearch` is prohibited inside
+`$facet` / `$lookup` / `$unionWith` and must be stage 0 of its pipeline.
+Each branch enforces ACL/CLP/`protectedFields` independently before
+fusion (via `Parse::AtlasSearch.search` and `Parse::VectorSearch.search`),
+so the fused rows are already access-filtered — there is no separate
+hydration fetch.
+
+```ruby
+hits = Article.hybrid_search(
+  text:    "how do I reset my password",   # embedded for the vector branch;
+                                            # also the default lexical query
+  lexical: { index: "article_search", fields: %w[title body] },
+  vector:  { index: "article_embedding_idx", num_candidates: 200 },
+  k:       20,
+  fusion:  { k_constant: 60, weights: { lexical: 0.4, vector: 0.6 } },
+  session_token: user.session_token,        # ACL scope, applied to BOTH branches
+)
+# => Array<Parse::Object>; each carries #hybrid_score, #hybrid_ranks,
+#    and #vector_score / #search_score when that branch contributed.
+```
+
+**RRF math.** `fused_score(d) = Σ_b weight_b / (k_constant + rank_b(d))`,
+where `rank_b(d)` is the document's 1-based rank in branch `b`. A larger
+`k_constant` (default 60) flattens the contribution curve. `weights`
+defaults to 1.0 per branch. `Parse::VectorSearch::Hybrid.rrf` exposes the
+pure fusion if you want to fuse pre-fetched ranked lists yourself.
+
+**Native `$rankFusion` (Atlas 8.0+).**
+`Parse::VectorSearch::Hybrid.rank_fusion_supported?(collection)` detects
+the native server-side fusion stage via a cached behavioural probe (1-hour
+TTL — not version-string parsing). Native execution is **opt-in**
+(`fusion: { method: :rrf_native }`) and falls back to the client-side path
+when the cluster does not support it; the default `:rrf` always fuses
+client-side, which is the fully-enforced, deterministic path. `$rankFusion`
+is admitted to `PipelineSecurity::ALLOWED_STAGES` for the native path.
+
+`Parse::Retrieval.retrieve(hybrid: true, ...)` routes through
+`hybrid_search` and chunks the fused results; pass `hybrid: { lexical:,
+vector:, fusion: }` to configure the branches. Tenant scope is folded into
+**both** branches (the vector Atlas pre-filter and the lexical
+post-`$search` `$match`) so neither leaks cross-tenant document existence.
+
+### Reranking
+
+A reranker reorders retrieved documents by a cross-encoder relevance score
+**before** chunking. Pass any object answering
+`#rerank(query:, documents:, top_n:)` — typically a
+`Parse::Retrieval::Reranker::Base` subclass:
+
+```ruby
+reranker = Parse::Retrieval::Reranker::Cohere.new(
+  api_key: ENV.fetch("COHERE_API_KEY"), model: "rerank-v3.5",
+)
+chunks = Parse::Retrieval.retrieve(
+  query: "reset my password", klass: Article, k: 30,
+  rerank: reranker, rerank_top_n: 5,    # keep the 5 most relevant docs
+)
+# Reranked chunks' score is the cross-encoder relevance_score.
+```
+
+`Reranker::Fixture` is a deterministic, zero-network reranker (lexical
+token overlap) for tests. The `Reranker::Base` protocol validates inputs,
+bounds `top_n`, rejects out-of-range indices, and sorts descending —
+adapters implement only the network call (`#rerank_scores`).
+
+> **Spend cap.** The `semantic_search` agent tool charges the estimated
+> query-embedding tokens against the caller's tenant budget via
+> `Parse::Embeddings::SpendCap` (opt-in; `configure(limit_tokens:,
+> window:)`). A breach hard-refuses (surfaced to the agent as a
+> rate-limited tool error). Admin agents are exempt; direct
+> `find_similar` / `retrieve` callers are not metered.
 
 ### Chunkers
 

data/docs/client_sdk_guide.md

@@ -11,6 +11,11 @@ go over REST, and authorization is carried by the user's `sessionToken`.
 Every claim below is locked in by the integration tests under
 `test/lib/parse/client_*_integration_test.rb`.
 
+For a runnable starting point, see
+[`examples/basic_client.rb`](../examples/basic_client.rb) (a no-master client
+with a row-level ACL-enforcement demo) and its master-key counterpart
+[`examples/basic_server.rb`](../examples/basic_server.rb).
+
 ---
 
 ## Why a separate guide?
@@ -180,6 +185,39 @@ This duality is intentional. The high-level convenience method matches
 what mobile SDKs do; the raw client preserves the response so you can
 log or reroute.
 
+#### A user-scoped client straight from login
+
+`Parse::User#session_client` turns a logged-in user into a **non-master client
+with that user's token bound**, so you don't thread `session_token:` through
+every call. (`Parse.client.become(token)` builds the same thing from any token.)
+`Parse::User#with_session` runs a block as the user:
+
+```ruby
+client = Parse::User.login("ada", "p4ssw0rd!").session_client
+Parse::Query.new("Post", client: client).results     # runs as Ada
+
+# Or a block — every REST-routed op inside is authorized as Ada:
+Parse::User.login("ada", "p4ssw0rd!").with_session do
+  Post.query.count
+  Post.create(title: "Hello")
+end
+```
+
+`session_client` returns `nil` if the user has no session token (e.g. it was
+fetched/saved under the master key rather than logged in). The bound token is
+applied as the lowest-priority auth fallback, so an explicit per-call
+`session_token:`, a `Parse.with_session` block, or `use_master_key: true` all
+still take precedence.
+
+> **Scope boundary.** `with_session` (and `Parse.with_session`) authorize
+> **REST-routed** operations (`find` / `get` / `count` / `save`) as the user.
+> Mongo-direct queries (`results_direct`, `aggregate`, Atlas search) do **not**
+> pick up the ambient session — scope them explicitly with a per-query
+> `session_token:` or a scoped `Parse::Agent`. A no-master client like this one
+> has no mongo-direct path anyway. To run a query as a user *without* a token —
+> via the master key and SDK-side ACL simulation — use
+> `Parse::Query#scope_to_user(user)`.
+
 ### 2.3 Validate / refresh a session
 
 ```ruby

data/docs/mcp_guide.md

@@ -7,7 +7,7 @@ The Model Context Protocol (MCP) is a standardized JSON-RPC 2.0-based interface
 Three deployment modes are available:
 
 - **Standalone HTTP server (`MCPServer`)** — a WEBrick process for dedicated MCP deployments.
-- **Rack-mountable adapter (`MCPRackApp`)** — embeds inside an existing Sinatra or Rails application.
+- **Rack-mountable adapter (`MCPRackApp`)** — embeds inside an existing Sinatra or Rails application. This is the primary deployment for the MCP 2025-06-18 Streamable HTTP transport; enable it with `transport: :streamable_http` (see [Streamable HTTP transport](#streamable-http-transport-primary)).
 - **Direct in-process dispatcher (`MCPDispatcher`)** — a pure function for in-process usage, custom transports, and testing.
 
 ---
@@ -191,6 +191,42 @@ map("/mcp") { run mcp_app }
 map("/")    { run ->(env) { [200, {"Content-Type" => "text/plain"}, ["ok"]] } }
 ```
 
+#### Streamable HTTP transport (primary)
+
+The MCP 2025-06-18 **Streamable HTTP** transport is the recommended transport for `MCPRackApp`. It is a single connection model in which the client `POST`s JSON-RPC requests (receiving either a buffered JSON reply or, with `Accept: text/event-stream`, a streamed SSE reply) and holds open a long-lived `GET` request to receive server-initiated notifications. Session termination is signalled with `DELETE` carrying the `Mcp-Session-Id`.
+
+Enable the whole transport with one switch:
+
+```ruby
+mcp_app = Parse::Agent.rack_app(transport: :streamable_http) do |env|
+  # ... auth factory ...
+end
+```
+
+`transport: :streamable_http` is exactly equivalent to `streaming: true, notifications: true` — it turns on POST→SSE streaming and the server→client `GET /` notification stream together. Add `resource_subscriptions: true` alongside it to upgrade the server→client bus from the plain notification posture to the LiveQuery-backed resource-subscription posture:
+
+```ruby
+mcp_app = Parse::Agent.rack_app(
+  transport: :streamable_http,
+  resource_subscriptions: true,   # optional: bridge LiveQuery resource updates
+) do |env|
+  # ...
+end
+```
+
+`transport:` is a closed enum:
+
+| Value | Effect |
+|-------|--------|
+| `:streamable_http` | Full Streamable HTTP transport (`streaming: true` + `notifications: true`). |
+| `:legacy` / `nil` (default) | Historical behavior: buffered JSON responses, no server→client stream. The standalone SSE/JSON path below remains a supported fallback. |
+
+Passing `transport: :streamable_http` together with an explicit `streaming:` or `notifications:` raises `ArgumentError` (the switch already owns those toggles); any value other than the two above also raises. The default is unchanged, so an existing `Parse::Agent.rack_app { ... }` keeps its non-streaming JSON behavior until you opt in.
+
+**WEBrick cannot deliver Streamable HTTP.** The switch — like `streaming:` — has no effect under the WEBrick-backed standalone `MCPServer`, which buffers responses and cannot hold the `GET` stream open. Use Puma, Falcon, or Unicorn for a real Streamable HTTP deployment.
+
+The remaining subsections document the individual toggles `transport: :streamable_http` consolidates, for operators who need finer control or are reading older configurations.
+
 #### MCP progress notifications via SSE (opt-in)
 
 **WEBrick cannot stream.** The standalone `MCPServer` is WEBrick-based and buffers the full response before sending. Setting `streaming: true` on an `MCPRackApp` mounted under WEBrick silently degrades to a single buffered response with concatenated SSE events. SSE streaming requires a Rack server that supports streaming response bodies — **Puma, Falcon, or Unicorn**. Verify your deployment uses one of these before relying on `streaming: true`.
@@ -537,10 +573,29 @@ Parse Server version and its `masterKeyIps` configuration.)
   soft cap *equal to* `max_concurrent_dispatchers`. So the effective steady-state
   ceiling across both surfaces is up to **2× `max_concurrent_dispatchers`** (up
   to N request-scoped SSE dispatchers plus N listening streams). Size the value
-  with that 2× factor in mind (e.g. relative to your Puma `max_threads`). Leaving
-  it unset (the default `nil`) leaves both surfaces uncapped; the app logs a
+  with that 2× factor in mind (e.g. relative to your Puma `max_threads`).
+  `max_concurrent_dispatchers:` defaults to a finite **100**
+  (`Parse::Agent::MCPRackApp::DEFAULT_MAX_CONCURRENT_DISPATCHERS`), so a
+  streaming surface is bounded out of the box — once the cap is reached a new
+  SSE request or listening stream is refused with a `503` JSON-RPC `-32000`
+  ("server busy"). Pass an explicit positive integer to resize it, or
+  `max_concurrent_dispatchers: nil` to knowingly run uncapped (the app logs a
   one-time warning at construction when a streaming or subscription/notification
-  surface is enabled without a cap.
+  surface is enabled with `nil`). A non-positive or non-integer value raises
+  `ArgumentError`.
+- **Client disconnect mid-tool-call.** When a client drops the connection while
+  a tool is still running, the SSE worker is torn down and the dispatcher's
+  cancellation token is tripped, so a cooperative tool (one that checks
+  `agent.cancelled?` at a checkpoint) exits promptly. A tool blocked inside a
+  Mongo/REST roundtrip cannot observe the token, but its slot is reclaimed when
+  the per-tool `Timeout` or the clean MongoDB `socket_timeout` (10s) / REST
+  `timeout` (30s) deadline fires — through the driver's clean error path. The
+  orphaned dispatcher is **intentionally not force-killed**: a `Thread#kill`
+  would bypass the driver's connection-invalidation and could return a half-used
+  pooled connection to a later request. To observe how often disconnects abandon
+  in-flight work, watch the cumulative
+  `Parse::Agent::MCPRackApp.abandoned_dispatcher_count` or subscribe to the
+  `parse.agent.mcp_dispatcher_abandoned` `ActiveSupport::Notifications` event.
 
 ### Listening-stream ownership
 
@@ -3106,6 +3161,66 @@ Four different refusal reasons each produce a distinct `:error_code` and message
 
 **Resolution order at dispatch:** operator filter ▷ mutation gate ▷ mode ceiling ▷ in-tool class gate. Operator-filter precedence is deliberate — when a tool is excluded by both the operator's `tools: { except: [...] }` AND the mutation gate (or the mode ceiling), the operator-filter message wins so the operator looks at the right knob first. The mode-ceiling message names the tool, not the class — even when the request would have hit an `agent_hidden` class, the ceiling fires first for a refused tool, so the LLM does not learn anything about the class. For tools that pass the ceiling (e.g. `query_class`) the in-tool `assert_class_accessible!` runs next and the `agent_hidden` message echoes the class name supplied by the caller.
 
+### Client mode from a webhook — run a handler as the calling user (v5.3.0)
+
+Parse Server includes the caller's live session token (`user.sessionToken`) in
+every trigger webhook fired by a logged-in user (it is absent for a master-key
+request). `Parse::Webhooks::Payload` captures that token before scrubbing it out
+of `payload.user` / `payload.object` (so it never lands in `payload.as_json` or
+the request log) and exposes two opt-in, user-scoped handles — the webhook
+counterpart of constructing a client-mode agent by hand:
+
+```ruby
+Parse::Webhooks.route(:after_save, "Post") do
+  # self is the Parse::Webhooks::Payload.
+  next true unless session_token?            # master-key save → no caller token
+
+  # A client-mode Parse::Agent bound to the caller — ACL/CLP enforced, no
+  # master-key fallback. Same posture as Parse::Agent.new(session_token:, client: <no master_key>).
+  visible = user_agent.execute(:query_class, class_name: "Post", limit: 20)
+
+  # …or a raw user-scoped Parse::Client (token is BOUND, so plain REST calls
+  # are authorized as the user with no per-call session_token: needed):
+  mine = user_client.request(:get, "classes/Post").result
+  true
+end
+```
+
+| Payload handle | Returns | `nil` when |
+|----------------|---------|-----------|
+| `payload.session_token` | the caller's raw token (`String`) | master-key request (no user) |
+| `payload.user_agent(**opts)` | non-master `Parse::Agent` in **client mode**, token bound | no token |
+| `payload.user_client` | non-master `Parse::Client` with the token **bound** | no token |
+
+`user_client` binds the token via the new `Parse::Client.new(session_token:)`
+option, applied as the lowest-priority auth fallback on every request — an
+explicit per-call `session_token:`, a `Parse.with_session` block, or an explicit
+`use_master_key: true` all still take precedence. Everything the Client Mode
+ceiling above says about a hand-built client-mode agent applies verbatim to
+`payload.user_agent`: read tools only unless `allow_mutations: true`, and
+`acl_user:` / `acl_role:` are not available on a no-master client.
+
+The same user-scoped client is available client-side from a login
+(`Parse::User#session_client`, or `Parse.client.become(token)` from any token),
+and `Parse::User#with_session` / `Parse::Client#with_session` run a block as the
+user so ordinary model operations are implicitly scoped:
+
+```ruby
+client = Parse::User.login(username, password).session_client   # non-master, token bound
+Parse::Query.new("Post", client: client).results                # query as the user
+Parse::User.login(username, password).with_session { Post.query.count }
+```
+
+`with_session` (and `Parse.with_session`) authorize **REST-routed** operations
+(`find` / `get` / `count` / `save`) as the user. Mongo-direct queries
+(`results_direct`, `aggregate`, Atlas search) do NOT pick up the ambient
+session — they resolve auth from the query's own `session_token:` / `acl_user:`
+and otherwise run in **master** mode (a full master read, not anonymous), so
+scope them explicitly with a per-query `session_token:` or a scoped
+`Parse::Agent`. This is deliberate: mongo-direct scoping is always explicit in
+this SDK, so the ambient fiber state can never silently flip a mongo-direct
+query into user scope (or be mistaken for it).
+
 ---
 
 ## `agent_hidden` — Per-Class Agent-Surface Denial