parse-stack-next 5.5.5 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef7d7de047cc0a3b4a21f3b080745f36f67cd2a53a81787fe53fdbb68fc3ec41
-  data.tar.gz: 74af45b9e2f334ca13c99419fe71d1653b9a218dffcf2a02ff801088ab86850b
+  metadata.gz: d7ea05ce0688ca7c1df6a1077162478dfee52e33d9fac77c7480c5ca818c9eb8
+  data.tar.gz: 71e61f7e70da94793dae9d741a3e5d29ffc7f9cd45f2adee6c96cd98b5ac2d24
 SHA512:
-  metadata.gz: e31f81f269bf874438617b00a01f1fb095fc7853f544d0a38f02aff8f58e21b14e8561650e3d3fb29bad6ff6276722992451a4f78b640481de3e5ab421cd033a
-  data.tar.gz: 71063ac383cb393af56969a1b631885585f5863b764218d7bee65b79a34cc9b469a885e96cf5bac5239ec66c140602e2bbe8197a46fa90ff4568cb240571e80f
+  metadata.gz: c723fbb9589ce57c7651fab142bed386f3a2070d39fc20887fc40b50f676ccb0041e9b758611e8b75d0a9202095de318ce2bbae35e41015be519209d9d2628dd
+  data.tar.gz: dbbc09ee718630415da1ab329168fc1c10d5d9cf20ad09e4129b2518087231206ca84d7d5ecd5e1a27f66e2fb75d3704b856592fcd43c6d2f7711fa20c0dba1b

data/CHANGELOG.md

@@ -1,5 +1,343 @@
 ## parse-stack-next Changelog
 
+### 5.6.0
+
+#### Voyage embeddings reach the Atlas endpoint, video, and streamed media
+
+- **NEW**: The Voyage provider now targets MongoDB's Atlas Embedding and
+  Reranking API in addition to Voyage's own. The two serve the same models
+  over an identical wire contract but do not share credentials — an Atlas
+  model API key returns 403 from Voyage's host and vice versa. A key carrying
+  the Atlas prefix routes to `https://ai.mongodb.com/v1` automatically; pass
+  `endpoint: :atlas` or `:voyage` to be explicit, or a `base_url:` to override
+  both. A named endpoint that contradicts an explicit `base_url` is rejected
+  rather than silently reconciled, so a credential is never sent to a host the
+  caller did not intend. `#endpoint` and `#atlas?` report the resolved target.
+- **NEW**: Added `voyage-3.5`, `voyage-3.5-lite`, `voyage-code-2` (1536-dim),
+  and `voyage-multimodal-3.5`. Models the Atlas endpoint does not expose —
+  `voyage-3`, `voyage-3-lite`, `voyage-4-nano` — are refused at construction
+  when that endpoint is active, with an error naming a current replacement;
+  they remain valid against Voyage's own API.
+- **NEW**: `Parse::Embeddings::Voyage#embed_video` embeds video through
+  `voyage-multimodal-3.5`, the only model that accepts it. Text, image, and
+  video vectors share one space, so a stored text vector is comparable against
+  a video vector without re-embedding. `#modalities` reports `[:text, :image,
+  :video]` for that model and `[:text, :image]` for `voyage-multimodal-3`.
+- **NEW**: `Parse::Embeddings::MediaFile` wraps a local image or video and
+  streams it into the request body instead of buffering it. Serializing media
+  with `to_json` costs roughly 2.4x the file size resident — raw bytes, the
+  1.33x base64 copy, and the serialized document — which is enough to exhaust
+  a small dyno on a single moderate video. `MediaFile` reads only a 16-byte
+  header at construction; the payload is then base64-encoded into the socket
+  in fixed-size chunks by `Parse::Embeddings::StreamingBody`, so peak memory
+  is bounded by the chunk size regardless of file size and nothing spills to
+  disk. `Content-Length` is computed exactly so the request avoids chunked
+  transfer encoding, and the body replays byte-identically on retry. Passing a
+  URL instead keeps the SDK out of the transfer entirely.
+- **FIXED**: Corrected the model dimension table. The entire v4 family
+  defaults to 1024 — `voyage-4-large`'s 2048, `voyage-4-lite`'s 512, and
+  `voyage-4-nano`'s 256 were recorded as native widths when they are
+  Matryoshka options reached only by requesting them. Because the provider
+  validates the returned vector width against the declared one, both
+  `voyage-4-large` and `voyage-4-lite` raised
+  `Parse::Embeddings::InvalidResponseError` on every call. `voyage-4-nano` is
+  1024, and `voyage-finance-2` carries a 32,000-token context rather than
+  16,000.
+- **CHANGED**: The coarse "Matryoshka-capable models" gate is replaced by
+  per-model `MODEL_SUPPORTED_DIMENSIONS`. Any width on a model's ladder is now
+  accepted — including one wider than its default, which the old rule rejected
+  as "exceeds native" — and a width off the ladder is refused with the
+  supported set named. `output_dimension` is sent whenever the configured
+  width differs from the model's default, so `voyage-4-lite` at 512 and
+  `voyage-4-large` at 2048 both work.
+- **FIXED**: A caller-supplied URL can no longer capture a local file's bytes.
+  The streamed body previously marked each payload with a sentinel token and
+  located it by searching the serialized JSON, so a URL containing that token
+  matched first: the file's base64 was spliced into the URL slot and forwarded
+  to the provider as a URL to fetch, disclosing local file contents, while the
+  intended slot kept the literal token. Request bodies are now assembled
+  structurally — each fragment serialized independently and concatenated in
+  order — so payloads are placed by position and caller data is never
+  searched.
+- **FIXED**: Mixed `image_url` / `image_base64` batches no longer violate
+  Voyage's request contract, which requires a single representation per
+  request. A mixed batch is split into one request per representation and
+  reassembled into the caller's original order, preserving the 1:1 alignment
+  between inputs and returned vectors.
+- **FIXED**: Video validation no longer accepts containers the provider
+  rejects. MP4 is the only format Voyage supports, and WebM and QuickTime
+  payloads are refused by the API, so both are out of the default allowlist.
+  An `ftyp` box no longer implies MP4 on its own — QuickTime and the
+  audio-only profiles share the ISO base media container — so major brands are
+  matched explicitly and an unrecognized brand is refused rather than assumed.
+  Apple's audio-only `M4A` brand is excluded, closing a type confusion in
+  which an audio file passed as video.
+- **NEW**: `Parse::Embeddings.max_media_bytes` caps streamed media per file,
+  defaulting to the 20 MB Voyage documents. Streaming already prevents an
+  oversized file from exhausting memory, but the provider still rejects it, so
+  failing locally turns a wasted upload into an immediate error. The Voyage
+  adapter enforces the 20 MB ceiling independently, so raising the global knob
+  for another provider cannot push an oversized payload onto Voyage.
+
+#### Breaking
+
+- **BREAKING**: The Voyage provider's default model moves from `voyage-3` to
+  `voyage-3.5`. `voyage-3` is retired from the Atlas endpoint, so the old
+  default made an Atlas key fail at construction whenever no model was named.
+  Vectors from the two models are not comparable. **Migration:** code relying
+  on the default must pin `model: "voyage-3"` explicitly to keep existing
+  embeddings valid, or re-embed against the new default. A `:vector` property
+  that declares `model:` is unaffected — the new binding audit catches the
+  mismatch before any request rather than letting the two mix silently.
+
+#### Vector search no longer returns fewer results than requested
+
+- **FIXED**: `$vectorSearch` set its `limit` to `k`, but Atlas applies that
+  limit before the SDK's ACL `$match`, `protectedFields` redaction,
+  pointer-field filtering, and any caller-supplied `filter` — so a scoped
+  caller who could read 2 of the top 10 documents asked for 10 and received 2,
+  even when hundreds of readable matches existed further down the ranking.
+  The search now requests a wider internal candidate window, applies every
+  enforcement layer, and only then trims to `k`. The window is raised only
+  when something can actually drop rows, so a master-key call with no filter
+  keeps its previous one-for-one cost. A `candidate_limit:` option on
+  `VectorSearch.search` and `find_similar` tunes the window for principals
+  whose visibility is unusually narrow. This is a mitigation, not a guarantee:
+  a sufficiently selective ACL can still exhaust any finite window, which is
+  why the attrition counts below exist. HNSW width stays anchored to `k`, so
+  the wider window does not widen the ANN search.
+- **NEW**: `VectorSearch.search` emits a `parse.vector_search.search`
+  `ActiveSupport::Notifications` event carrying `candidate_limit`,
+  `num_candidates`, `post_filter_count`, `post_pointer_count`,
+  `returned_count`, `pointer_attrition`, and `underfilled`. The counts are
+  named for where they are measured — obtaining a true pre-`$match` count
+  would require a `$facet` — so an underfill is observable rather than silent.
+
+#### Vector properties are checked against the provider actually registered
+
+- **FIXED**: A `:vector` property's `model:` was recorded and never enforced.
+  Because models in the same family usually share a width (`voyage-3` and
+  `voyage-3.5` are both 1024), swapping the registered provider's model
+  silently mixed incomparable vectors into one index — no error, just
+  degraded recall, repairable only by re-embedding. `dimensions:` was
+  verified, but only against a vector the provider had already returned and
+  billed for. Both are now checked by `Parse::Embeddings::BindingAudit`
+  before any request is issued, on the managed-write path and the
+  query-embedding path alike. The audit runs ahead of the digest short-circuit
+  so an unchanged record still surfaces a drifted binding, and it fails closed:
+  a provider that cannot report `#model_name` or `#dimensions` is refused
+  rather than skipped, since a declaration that cannot be verified is not a
+  declaration that has been satisfied.
+- **NEW**: `Parse::Embeddings::BindingAudit.audit_all!` and
+  `.audit_all_or_raise!` check every declared binding at once, for a boot-time
+  or CI gate rather than waiting for the first save that happens to touch one.
+- **NEW**: `:vector` properties validate `similarity:` against the functions
+  Atlas accepts (`euclidean`, `cosine`, `dotProduct`) at declaration time
+  instead of surfacing a typo as an index error later.
+- **FIXED**: Hybrid search applies the same candidate window as the plain
+  vector search, so opting into hybrid no longer underfills where a straight
+  vector search would not. Each branch's limit is applied before ACL
+  enforcement and was narrower than the plain path's window.
+- **FIXED**: Hybrid search separates the rows each branch retains for fusion
+  from the rows Atlas considers before ACL. Conflating them meant the branch
+  limit was passed as the vector branch's `k` and then multiplied a second
+  time by the plain search's own window derivation — a hybrid `k: 10` asked
+  Atlas for 1,000 rows instead of the intended 100, an explicit
+  `candidate_limit: 250` became 2,500 on the client path while staying 250 on
+  the native path, and any `k` above 100 produced a branch `k` beyond
+  `VectorSearch::MAX_K` that failed outright. The fusion depth is now bounded
+  by `MAX_K` and the candidate window by Atlas's 10,000 ceiling, with both
+  paths using the same window. A `candidate_limit` outside that range is
+  refused rather than clamped, and `vector: { candidate_limit: }` is forwarded
+  through `hybrid_search`.
+- **FIXED**: The native `$rankFusion` pipeline trimmed to `k` in a `$limit`
+  stage that runs after its ACL `$match`, reintroducing the underfill the
+  candidate window exists to prevent. It now limits to the candidate window
+  and trims to `k` once enforcement has run.
+- **NEW**: A `parse.vector_search.hybrid` notification reports `method`,
+  `branch_depth`, `candidate_window`, `post_filter_count`, `returned_count`,
+  and `underfilled` for both fusion paths. `branch_depth` differs by method by
+  design: the client path enforces ACL inside each branch and can retain the
+  narrower fusion depth, while the native path enforces after `$rankFusion`
+  and must retain the full window. The value reported is the one that ran.
+- **NEW**: A `:vector` property wider than the Atlas vectorSearch index cap is
+  refused unless it declares `searchable: false`. `Parse::Vector` tolerates up
+  to 16384 dimensions while an Atlas index caps at 8192, so such a property
+  was previously declarable, storable, and permanently unsearchable, with the
+  failure appearing only at query time. The two limits remain distinct — they
+  govern storage and indexing respectively — but the combination now has to be
+  acknowledged.
+- **NEW**: `searchable: false` makes a `:vector` property genuinely
+  storage-only, whether it opted out to clear the index cap or by choice. It
+  is excluded from `find_similar` / `hybrid_search` field resolution, refused
+  with an explanation when named directly, and rejected by `agent_searchable`
+  at class load rather than at an agent's first query.
+
+#### Provider protocol
+
+- **NEW**: `Parse::Embeddings::Provider#embed_video` joins `#embed_image` in
+  the base protocol with the same `NotImplementedError` default, so video is a
+  declared capability rather than a Voyage-only method. `#supports_modality?`
+  answers the capability question without rescuing.
+- **NEW**: `rake test:contract` runs live, billable provider contract tests
+  that pin request routing, native dimensions, the Matryoshka ladder, accepted
+  media, size limits, model availability, and response shape. They skip unless
+  `VOYAGE_CONTRACT_KEY` is set and are excluded from both `rake test` and
+  `rake test:unit`, so no ordinary run becomes billable because a key happens
+  to be exported. Probes that assert a refusal issue raw requests rather than
+  going through the SDK — a local guard asserted against itself proves nothing
+  about the contract it encodes — and distinguish a genuine refusal from an
+  authentication, rate-limit, or 5xx failure so infrastructure trouble cannot
+  read as a contract verdict. Mocked tests assert what the SDK believes the
+  API does and therefore cannot detect provider drift: every dimension and
+  media-format correction in this release was invisible to a fully green
+  mocked suite.
+
+### Behavior Notes
+
+- Audio is not offered by any Voyage model, and neither PDF nor DOCX is
+  accepted as a content type. Render document pages to images and embed those;
+  the SDK does not perform that conversion.
+- Deterministic result fill under highly selective ACLs would require the
+  authorization predicate to run inside the Atlas prefilter rather than after
+  it. The post-search `$match` remains the enforcement boundary regardless.
+- `voyage-4-nano` is served by neither hosted endpoint — it is open-weight and
+  meant to be self-hosted. It is refused against Voyage's and Atlas's hosts
+  with a message pointing at a self-hosted `base_url:` or
+  `Parse::Embeddings::LocalHTTP`, and remains usable through either.
+
+### Code Example
+
+```ruby
+# Endpoint inferred from the key prefix — no base_url needed.
+provider = Parse::Embeddings::Voyage.new(
+  api_key: ENV.fetch("ATLAS_MODEL_API_KEY"),
+  model: "voyage-multimodal-3.5",
+)
+provider.endpoint    # => :atlas
+provider.modalities  # => [:text, :image, :video]
+
+# Local media streams into the request; the bytes are never held in memory.
+provider.embed_image([Parse::Embeddings::MediaFile.image("page.png")])
+provider.embed_video([Parse::Embeddings::MediaFile.video("demo.mp4")])
+
+# A URL keeps the SDK out of the transfer entirely — the provider fetches it.
+provider.embed_image(["https://cdn.example.com/page.png"])
+```
+
+### 5.5.6
+
+#### MCP clients now receive the SSE response instead of hanging
+
+- **FIXED**: The Streamable HTTP SSE transport framed its events with custom
+  event names — `event: progress` for `notifications/progress` and
+  `event: response` for the final JSON-RPC response. MCP defines a single SSE
+  event type for JSON-RPC traffic, and clients match only the default
+  `message` type, so every frame the SDK emitted was silently discarded: tool
+  progress never surfaced, and, critically, the terminating response never
+  arrived, leaving the client blocked until its own timeout on any streaming
+  `tools/call`. All frames on both the request-scoped POST stream and the
+  server-to-client GET notification stream now carry `event: message`, and
+  clients discriminate from the JSON-RPC envelope (`method` present for a
+  notification, `id` plus `result`/`error` for a response) as the protocol
+  intends. Deployments that worked around this with a middleware rewriting
+  the event name can drop it.
+
+### 5.5.5
+
+#### Agent `call_method` runs under the caller's scope, not the master key
+
+- **FIXED**: Instance `call_method` resolved its receiver with a bare
+  `klass.find` on the master-backed default client, so a scoped agent could
+  read — and through a write method, mutate — any object by id. The receiver
+  (both the real call and the dry-run existence check) is now fetched through
+  the requesting agent's scope: a session scope fetches with the session token
+  (Parse Server enforces ACL/CLP), an `acl_user` / `acl_role` scope routes
+  mongo-direct (ACL simulation), and a row the scope cannot read fails closed
+  to "not found". The method body runs inside the caller's session so its own
+  writes inherit the same principal, and an instance write/admin method under
+  an `acl_user` / `acl_role` scope — which has no session token to bind — is
+  refused rather than run with master authority.
+- **FIXED**: Aggregation pipelines now default-deny joins under an active
+  tenant scope. A `$lookup` / `$graphLookup` / `$unionWith` sub-pipeline runs
+  in the joined collection's context with no tenant predicate injected, so any
+  such join could surface rows from other tenants; all are refused while a
+  tenant scope is active. The `$unionWith` bare-string shorthand
+  (`{ "$unionWith" => "Class" }`) is now covered by that guard as well as the
+  class-allowlist, hidden/underscore, and CLP-`find` gates, which previously
+  inspected only the Hash form.
+- **IMPROVED**: Unimplemented agent tools now raise a typed
+  `Parse::Agent::NotImplemented` error, and tools without a handler are omitted
+  from tool listings.
+
+#### Blank or injected credentials no longer escalate to the master key
+
+- **FIXED**: An explicitly-supplied blank or whitespace `session_token:` no
+  longer falls through to the master key. It now fails closed to an anonymous
+  request (master suppressed, no session header) and does not fall back to a
+  bound or ambient token. `Parse.with_session` likewise rejects a blank token
+  at the source instead of storing a whitespace ambient that the request layer
+  would then drop.
+- **FIXED**: The control options `use_master_key` and `session` can no longer
+  be set from a string-keyed conditions hash — the "forward a request params
+  hash straight into `Query.new` / `where`" pattern. `{"use_master_key" =>
+  true}` from untrusted params was an ACL/CLP-bypass mass-assignment; these two
+  keys are now honored only when passed as symbols (code-authored), and a
+  string form is treated as an ordinary field constraint with a warning.
+
+#### Atlas Search and aggregation stay ACL-scoped
+
+- **FIXED**: Atlas Search keeps `$search` at pipeline stage 0 while running the
+  scoped ACL/CLP enforcement chain (ACL `$match` folded after `$search`,
+  protectedFields strip, pointerFields filter, and a protected-field `$expr`
+  oracle guard). Query-derived constraints on the builder-block, options, and
+  autocomplete paths are converted to MongoDB storage form before the
+  post-`$search` `$match`, so a pointer/date/objectId constraint targets the
+  correct storage column and no longer fails BSON serialization.
+- **FIXED**: `search_with_stage` rejects a non-`$search` stage and any
+  `returnStoredSource`, which could otherwise return only index-stored fields
+  (without `_rperm`), be read as public by the ACL match, and leak restricted
+  rows.
+- **FIXED**: A scoped `$geoNear` folds the ACL predicate into `$geoNear.query`
+  rather than prepending a `$match`, keeping `$geoNear` at stage 0 so the query
+  no longer fails under ACL scoping. The fold embeds a copy of the caller's
+  existing query so the caller's pipeline is not mutated.
+
+#### Outbound fetches and the shipped CLI are hardened
+
+- **FIXED**: `parse-console --url` now parses and scheme-validates its argument
+  (HTTP(S) only) before fetching, instead of passing it to `Kernel#open` —
+  closing a path where a `|command` argument would be executed as a subprocess.
+- **IMPROVED**: The Cohere reranker `base_url` is validated to reject
+  credentials embedded in the URL and plaintext HTTP to non-loopback hosts.
+- **IMPROVED**: Remote file/image fetches enforce a streaming size cap that
+  aborts mid-download; the per-call `max_bytes:` ceiling is validated as a
+  positive integer, so a zero, negative, or non-numeric value is refused up
+  front rather than silently rejecting every response.
+
+#### Redaction, locking, and API ergonomics
+
+- **IMPROVED**: Query-string credential redaction for logging and request
+  profiling is now a single shared implementation, so the two cannot drift. It
+  redacts the value of any credential-bearing parameter name (matched by a
+  generic rule with a safe-list, and aware of percent-encoded names) and uses
+  possessive-quantifier matching so it stays linear on pathological URLs.
+- **FIXED**: The in-process fallback mutex registry (used when no shared lock
+  store is configured) is bounded, and its eviction can no longer reclaim a
+  mutex a caller is about to lock — a pending-acquirer reservation prevents two
+  callers from getting distinct mutexes for the same key.
+- **IMPROVED**: `call_function` and `trigger_job` accept request options as
+  bare keyword arguments (for example `call_function("f", {}, session_token:
+  t)`), merged with the explicit `opts:` hash for back-compat.
+
+#### Packaging, CI, and docs
+
+- **CHANGED**: The shipped-gem file list was narrowed to an allowlist of the
+  library, binaries, docs, examples, and standard metadata.
+- **CHANGED**: The SHA-pinned `ruby/setup-ruby` GitHub action was bumped to
+  `v1.318.0` across the CI, docs, and release workflows.
+- **IMPROVED**: README, test-server, and guide updates, plus YARD styling.
+
 ### 5.5.4
 
 #### Dependency updates

data/lib/parse/agent/mcp_rack_app.rb

@@ -1183,10 +1183,21 @@ module Parse
       # Wire format for each SSE event (note: trailing blank line is required
       # by the SSE spec):
       #
-      #   event: progress\n
+      #   event: message\n
       #   data: <json>\n
       #   \n
       #
+      # EVERY frame — progress notifications, list-changed notifications,
+      # and the final JSON-RPC response alike — carries the event name
+      # `message`. MCP Streamable HTTP defines exactly one SSE event type
+      # for JSON-RPC traffic; clients discriminate by inspecting the
+      # envelope (`method` present => notification, `id` + `result`/`error`
+      # => response), NOT by the SSE event name. Earlier releases emitted
+      # `event: progress` and `event: response`, which real MCP clients
+      # silently discard — they match only the default `message` type — so
+      # the final response never arrived and the call appeared to hang.
+      # Do not reintroduce custom event names.
+      #
       # @api private
       class SSEBody
         # Sentinel pushed to the queue when the worker is done.
@@ -1546,6 +1557,9 @@ module Parse
         # The `total` field is omitted (rather than nil) so the wire
         # shape matches the spec's optional-field convention.
         #
+        # Emitted as `event: message` — see the SSEBody class docs. The
+        # payload's `method` is what marks it as progress.
+        #
         # @param elapsed [Float] seconds elapsed since the stream started.
         # @return [String] SSE event string (includes trailing blank line).
         def build_progress_event(elapsed)
@@ -1557,15 +1571,14 @@ module Parse
               "progress"      => elapsed,
             },
           })
-          "event: progress\ndata: #{data}\n\n"
+          "event: message\ndata: #{data}\n\n"
         end
 
         # Format a `notifications/tools/list_changed` or
         # `notifications/prompts/list_changed` SSE event. Both
         # notifications have no `params` — the wire shape is just the
-        # JSON-RPC envelope with `method` set. SSE event name is
-        # "message" since this is not a progress notification (the
-        # progress event name is reserved for progress notifications).
+        # JSON-RPC envelope with `method` set. Emitted as `event: message`,
+        # like every other frame on this stream.
         #
         # @param method [String] full MCP method string.
         # @return [String] SSE event string (includes trailing blank line).
@@ -1599,7 +1612,7 @@ module Parse
             "method"  => "notifications/progress",
             "params"  => params,
           })
-          "event: progress\ndata: #{data}\n\n"
+          "event: message\ndata: #{data}\n\n"
         end
 
         # Build the callback the dispatcher block passes into
@@ -1631,12 +1644,17 @@ module Parse
           end
         end
 
-        # Format the final `response` SSE event.
+        # Format the final JSON-RPC response SSE event.
+        #
+        # Emitted as `event: message` (NOT `event: response`) — an MCP
+        # client matching only the default `message` type would otherwise
+        # discard the response and block until its own timeout. The
+        # envelope's `id` + `result`/`error` is what marks it final.
         #
         # @param body [Hash] JSON-RPC response envelope.
         # @return [String] SSE event string (includes trailing blank line).
         def build_response_event(body)
-          "event: response\ndata: #{JSON.generate(body)}\n\n"
+          "event: message\ndata: #{JSON.generate(body)}\n\n"
         end
 
         # Build an internal-error JSON-RPC envelope (id may be nil at this layer).
@@ -1755,9 +1773,9 @@ module Parse
           end
         end
 
-        # SSE wire form for a server→client notification. Event name "message"
-        # (not "progress"/"response", which are reserved for the request-scoped
-        # SSE path).
+        # SSE wire form for a server→client notification. Event name
+        # "message" — the single event type MCP Streamable HTTP defines for
+        # JSON-RPC traffic, matching the request-scoped SSE path.
         def format_event(notification)
           "event: message\ndata: #{JSON.generate(notification)}\n\n"
         end

data/lib/parse/agent/metadata_dsl.rb

@@ -634,6 +634,16 @@ module Parse
                   "agent_searchable field: :#{field_sym} is not a declared :vector property " \
                   "on #{parse_class_name} (declared: #{vector_properties.keys.inspect})."
           end
+          # A storage-only property is not eligible for search, so the
+          # tool this registers could never run. Refuse at class load
+          # rather than at the first agent query.
+          if respond_to?(:vector_properties) &&
+             vector_properties.dig(field_sym, :searchable) == false
+            raise ArgumentError,
+                  "agent_searchable field: :#{field_sym} on #{parse_class_name} is declared " \
+                  "`searchable: false` (storage-only, not eligible for search) and cannot " \
+                  "back a search tool."
+          end
           filters = Array(filter_fields).map(&:to_sym)
           @agent_searchable_field = field_sym
           @agent_searchable_filter_fields = filters