parse-stack-next 5.5.4 → 5.5.6

data/lib/parse/agent/constraint_translator.rb

@@ -72,9 +72,9 @@ module Parse
       ].freeze
 
       # Operators whose value carries an inner sub-query of the shape
-      # +{className:, where:, key:}+. Each must be validated through
+      # `{className:, where:, key:}`. Each must be validated through
       # {Tools.assert_class_accessible!} so the LLM cannot reach into a
-      # hidden class via the sub-query, and the inner +where+ must be
+      # hidden class via the sub-query, and the inner `where` must be
       # recursively re-translated so blocked operators inside it are
       # also caught.
       CROSS_CLASS_OPERATORS = %w[
@@ -260,11 +260,11 @@ module Parse
       end
 
       # Translate the value of a cross-class operator
-      # (+$inQuery+/+$notInQuery+/+$select+/+$dontSelect+). The value
-      # carries an embedded +className+ that must be validated against
-      # the active accessibility policy, and an embedded +where+ that
+      # (`$inQuery`/`$notInQuery`/`$select`/`$dontSelect`). The value
+      # carries an embedded `className` that must be validated against
+      # the active accessibility policy, and an embedded `where` that
       # must be recursively translated so blocked operators (e.g.
-      # +$where+ nested inside) cannot smuggle through.
+      # `$where` nested inside) cannot smuggle through.
       def translate_cross_class_value(op, val, depth:, agent: nil)
         return val unless val.is_a?(Hash)
         val = val.transform_keys(&:to_s)
@@ -321,20 +321,20 @@ module Parse
         translate_value(val, depth: depth, agent: agent)
       end
 
-      # Validate the owning-object class named by a +$relatedTo+ constraint.
+      # Validate the owning-object class named by a `$relatedTo` constraint.
       #
-      # +$relatedTo+ has the shape +{ object: <Pointer>, key: <relation field> }+.
-      # Unlike +$inQuery+ / +$select+ it carries no +className+ / inner +where+,
+      # `$relatedTo` has the shape `{ object: <Pointer>, key: <relation field> }`.
+      # Unlike `$inQuery` / `$select` it carries no `className` / inner `where`,
       # so it is NOT a {CROSS_CLASS_OPERATORS} entry — but it DOES reach across
       # to a second class: the owning object whose relation is being read. Left
       # unvalidated, an agent narrowed to one class (or with a class globally
-      # +agent_hidden+) could still name a relation anchored on an off-allowlist
-      # class via the +object+ pointer. That is the SDK-surface analog of
-      # GHSA-wmwx-jr2p-4j4r, where Parse Server's own +$relatedTo+ bypassed the
+      # `agent_hidden`) could still name a relation anchored on an off-allowlist
+      # class via the `object` pointer. That is the SDK-surface analog of
+      # GHSA-wmwx-jr2p-4j4r, where Parse Server's own `$relatedTo` bypassed the
       # owning object's ACL. Run the owning class through the same accessibility
       # policy as every other cross-class hop, then translate the value normally.
       #
-      # Fails closed when the owning class cannot be resolved from +object+: an
+      # Fails closed when the owning class cannot be resolved from `object`: an
       # unresolvable pointer is exactly the shape that would otherwise slip the
       # check, so refuse the constraint rather than skip it.
       def translate_related_to_value(val, depth:, agent: nil)
@@ -351,10 +351,10 @@ module Parse
         translate_value(val, depth: depth, agent: agent)
       end
 
-      # Extract the Parse class name of a +$relatedTo+ constraint's owning
-      # object from its +object+ slot, which may be a Parse::Pointer, a Parse
-      # pointer/relation hash (+{__type:, className:, objectId:}+, string or
-      # symbol keys), or a storage-form string (+"ClassName$objectId"+).
+      # Extract the Parse class name of a `$relatedTo` constraint's owning
+      # object from its `object` slot, which may be a Parse::Pointer, a Parse
+      # pointer/relation hash (`{__type:, className:, objectId:}`, string or
+      # symbol keys), or a storage-form string (`"ClassName$objectId"`).
       # Returns nil when no class can be resolved so the caller can fail closed.
       def related_to_owning_class(val)
         return nil unless val.is_a?(Hash)
@@ -371,7 +371,7 @@ module Parse
       end
 
       # Hook into the agent-side accessibility check when the agent
-      # module is loaded; in pure-unit contexts where +Parse::Agent::Tools+
+      # module is loaded; in pure-unit contexts where `Parse::Agent::Tools`
       # has not been loaded, default to a no-op rather than raising —
       # the strict check is enforced wherever the agent dispatches.
       def assert_embedded_class_accessible!(op, class_name, agent: nil)

data/lib/parse/agent/errors.rb

@@ -121,22 +121,22 @@ module Parse
       end
     end
 
-    # Raised inside the +call_method+ tool when the resolved
-    # +ClassName.method_name+ is excluded by the agent instance's
-    # +methods:+ filter. The execute() rescue maps this to a
-    # +:tool_filtered+ error_code so consumers can distinguish "the
+    # Raised inside the `call_method` tool when the resolved
+    # `ClassName.method_name` is excluded by the agent instance's
+    # `methods:` filter. The execute() rescue maps this to a
+    # `:tool_filtered` error_code so consumers can distinguish "the
     # filter excluded this method" from "this method isn't declared
     # agent-callable" (a Parse::Error) or "the tier doesn't allow it"
-    # (a +:permission_denied+).
+    # (a `:permission_denied`).
     class MethodFiltered < AgentError; end
 
     # Raised at semantic-search dispatch time when at least one class in
-    # the model registry declares +agent_tenant_scope+ but the class
+    # the model registry declares `agent_tenant_scope` but the class
     # being searched does not. In a tenant-aware deployment an
     # un-scoped searchable surface would let an agent retrieve across
     # tenant boundaries, so the gate is a hard refusal, not a warning.
     # Enforced at dispatch (when all classes are loaded) rather than at
-    # +agent_searchable+ declaration time so class-load order can't
+    # `agent_searchable` declaration time so class-load order can't
     # produce a false negative.
     class MissingTenantScope < AgentError; end
 
@@ -145,5 +145,27 @@ module Parse
     # `:refuse`. A SecurityError subclass so it routes through execute's
     # security rescue and is never swallowed.
     class PromptInjectionDetected < SecurityError; end
+
+    # Raised by Parse::Agent::Tools.invoke when a tool name is recognized
+    # (advertised in a permission tier / passes the gates) but has no
+    # handler in this SDK version. The built-in raw-CRUD write/admin tools
+    # (`create_object`, `update_object`, `delete_object`, `create_class`,
+    # `delete_class`) are declared in the write/admin tiers but ship
+    # without an implementation — invoking one previously raised a bare
+    # `NoMethodError` that collapsed to an opaque "internal error" on the
+    # wire. This turns that into a clear, typed refusal so the caller
+    # learns the tool is not implemented rather than that the SDK broke.
+    class NotImplemented < AgentError
+      attr_reader :tool_name
+
+      def initialize(tool_name, message = nil)
+        @tool_name = tool_name.to_s
+        super(message || "Tool '#{@tool_name}' is recognized but not implemented in this " \
+                         "SDK version. The built-in raw create/update/delete tools are not " \
+                         "available; expose the operation as an application method via " \
+                         "`agent_method` + `call_method`, or register a handler with " \
+                         "`Parse::Agent::Tools.register`.")
+      end
+    end
   end
 end

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

@@ -450,15 +450,15 @@ module Parse
         #   preview-only execution. When false (default), passing dry_run: true in
         #   arguments is refused at dispatch time with :invalid_argument.
         # @param permitted_keys [Array<Symbol,String>, nil] when provided,
-        #   +call_method+ refuses any +arguments+ key not in this list.
+        #   `call_method` refuses any `arguments` key not in this list.
         #   Without this, an LLM (or a prompt-injection payload) can
-        #   pass arbitrary keys through a method that splats with +**+,
-        #   reaching protected columns like +_hashed_password+ or +ACL+.
-        #   Highly recommended on any +agent_write+/+agent_admin+ method
+        #   pass arbitrary keys through a method that splats with `**`,
+        #   reaching protected columns like `_hashed_password` or `ACL`.
+        #   Highly recommended on any `agent_write`/`agent_admin` method
         #   that takes a kwargs splat.
         # @param parameters [Hash, nil] when provided, a JSON Schema (as a
-        #   Ruby Hash) describing the +arguments+ object. Surfaced in
-        #   +tools/list+ so the LLM submits properly-shaped inputs and
+        #   Ruby Hash) describing the `arguments` object. Surfaced in
+        #   `tools/list` so the LLM submits properly-shaped inputs and
         #   stricter MCP clients can validate before dispatch.
         # @return [Hash] the method metadata
         def agent_method(method_name, description = nil, permission: :readonly,