parse-stack-next 5.7.6 → 5.8.1

data/lib/parse/agent/constraint_translator.rb

@@ -138,6 +138,10 @@ module Parse
       # `^foo.*` is not).
       REDOS_NESTED_QUANTIFIER_RE = /\([^)]*[+*][^)]*\)[+*?]/.freeze
 
+      # Fiber-storage key holding the class whose field names are being
+      # resolved; see {#translate}.
+      CLASS_SCOPE_KEY = :parse_agent_constraint_class
+
       # Translate JSON constraints to Parse query format.
       # Validates all operators against the security whitelist.
       #
@@ -153,9 +157,38 @@ module Parse
       #   — continues to parse as a single positional Hash under Ruby 3+
       #   kwargs separation. Adding a kwarg would have turned the same call
       #   into "empty kwargs + missing positional arg."
-      def translate(constraints, agent = nil)
+      #
+      # @param class_name [String, nil] the class the constraints apply to.
+      #   When given, field keys are resolved the way the field-policy check
+      #   resolves them ({Parse::Agent::MetadataRegistry.wire_field_names}):
+      #   a declared `field:` name such as `PublicText` is kept exactly, so the
+      #   column that was checked is the column that is queried. Embedded
+      #   `$inQuery`/`$select` clauses resolve against their own className.
+      def translate(constraints, agent = nil, class_name = nil)
         return {} if constraints.nil? || constraints.empty?
+        previous = Fiber[CLASS_SCOPE_KEY]
+        Fiber[CLASS_SCOPE_KEY] = class_name&.to_s
+        begin
+          translate_in_scope(constraints, agent)
+        ensure
+          Fiber[CLASS_SCOPE_KEY] = previous
+        end
+      end
+
+      # Check if constraints are valid without raising.
+      #
+      # @param constraints [Hash] the query constraints
+      # @return [Boolean] true if valid, false otherwise
+      def valid?(constraints)
+        translate(constraints)
+        true
+      rescue ConstraintSecurityError, InvalidOperatorError
+        false
+      end
+
+      private
 
+      def translate_in_scope(constraints, agent)
         raise InvalidOperatorError.new(
           "Constraints must be a Hash, got #{constraints.class}",
           operator: nil,
@@ -178,19 +211,6 @@ module Parse
         end
       end
 
-      # Check if constraints are valid without raising.
-      #
-      # @param constraints [Hash] the query constraints
-      # @return [Boolean] true if valid, false otherwise
-      def valid?(constraints)
-        translate(constraints)
-        true
-      rescue ConstraintSecurityError, InvalidOperatorError
-        false
-      end
-
-      private
-
       # Translate a single value, handling nested operators
       #
       # @param value [Object] the value to translate
@@ -305,7 +325,7 @@ module Parse
         # disabling the per-agent class filter on every nested
         # cross-class hop. Keep this call POSITIONAL.
         if embedded_where.is_a?(Hash)
-          translated_where = translate(embedded_where, agent)
+          translated_where = translate(embedded_where, agent, embedded_class_name)
           new_val = val.dup
           if op == "$select" || op == "$dontSelect"
             query_part = new_val["query"].transform_keys(&:to_s)
@@ -542,6 +562,13 @@ module Parse
       def columnize(field)
         return field if field.start_with?("_") # Preserve special fields like _User
 
+        class_name = Fiber[CLASS_SCOPE_KEY]
+        if class_name && !class_name.empty? && defined?(Parse::Agent::MetadataRegistry)
+          root, rest = field.to_s.split(".", 2)
+          wire = Parse::Agent::MetadataRegistry.wire_field_names(class_name, [root]).first || root
+          return rest ? "#{wire}.#{rest}" : wire
+        end
+
         # Convert snake_case to camelCase
         field.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
              .sub(/^([A-Z])/) { ::Regexp.last_match(1).downcase }

data/lib/parse/agent/describe.rb

@@ -176,7 +176,8 @@ module Parse
           tenant_id: tenant_id,
           classes: filter_descriptor(@class_filter_only, @class_filter_except),
           tools: tools_descriptor,
-          methods: filter_descriptor(@method_filter_only, @method_filter_except, transform: ->(s) { s.to_s }),
+          methods: filter_descriptor(@method_filter_only, @method_filter_except, transform: ->(s) { s.to_s })
+            .merge(layers: method_filter_layers_descriptor),
           filters: per_agent_filters_summary,
           hidden_classes: Parse::Agent::MetadataRegistry.hidden_class_names,
           per_class: per_class_descriptor,
@@ -298,7 +299,9 @@ module Parse
       # the wire-format field name Array so the output reads identically to
       # the schema-enriched `get_schema` echo.
       def class_field_allowlist(class_name)
-        list = Parse::Agent::MetadataRegistry.field_allowlist(class_name)
+        # Effective allowlist for THIS agent: the class ceiling narrowed by
+        # its `fields:` policy.
+        list = Parse::Agent::FieldPolicy.with(self) { Parse::Agent::MetadataRegistry.field_allowlist(class_name) }
         list && list.any? ? list.dup : nil
       end
 
@@ -381,10 +384,15 @@ module Parse
         lines << "    except:    #{data[:tools][:except].inspect}" if data[:tools][:except]
         lines << "    effective: #{data[:tools][:effective].inspect}"
 
-        if data[:methods][:only] || data[:methods][:except]
+        inherited_layers = Array(data[:methods][:layers])[0...-1] if data[:methods][:only] || data[:methods][:except]
+        inherited_layers ||= Array(data[:methods][:layers])
+        if data[:methods][:only] || data[:methods][:except] || inherited_layers.any?
           lines << "  methods:"
           lines << "    only:    #{data[:methods][:only].inspect}" if data[:methods][:only]
           lines << "    except:  #{data[:methods][:except].inspect}" if data[:methods][:except]
+          inherited_layers.each do |layer|
+            lines << "    inherited: #{layer.compact.inspect}"
+          end
         end
 
         if data[:filters]

data/lib/parse/agent/field_names.rb

@@ -0,0 +1,53 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  class Agent
+    # Per-agent data-field naming mode for tool output.
+    #
+    # `Parse::Agent.new(field_names: :server)` asks for data fields in the
+    # exact names Parse returns or the model declares through its
+    # `field_map` (`createdAt`, `totalPlays`, `ExternalID`), with no
+    # snake_case conversion anywhere a tool would otherwise apply one.
+    # `:default` (or omitting the option) keeps every tool's existing output.
+    #
+    # Only data-field keys are affected. MCP protocol keys and SDK envelope
+    # keys (`chunks`, `documents`, `object_id`, `next_call`, ...) keep their
+    # contracts, and "server names" never means raw MongoDB storage columns
+    # (`_p_author`, `_rperm`, `_session_token`). Naming is presentation only:
+    # every access check (ACL/CLP, protectedFields, class and per-agent field
+    # policies) resolves against canonical field identities before output.
+    #
+    # Like {FieldPolicy}, the mode is scoped fiber-locally around each tool
+    # call by {Parse::Agent::Tools.invoke}, so concurrent agents with
+    # different modes never see each other's setting and nothing global is
+    # mutated.
+    module FieldNames
+      SCOPE_KEY = :parse_agent_field_names_scope
+
+      module_function
+
+      # Run the block with `agent`'s naming mode in effect.
+      def with(agent)
+        previous = Fiber[SCOPE_KEY]
+        Fiber[SCOPE_KEY] = agent
+        yield
+      ensure
+        Fiber[SCOPE_KEY] = previous
+      end
+
+      # @return [Symbol] `:server` or `:default` for the agent whose tool is
+      #   executing; `:default` outside a tool call.
+      def current_mode
+        agent = Fiber[SCOPE_KEY]
+        mode = agent.respond_to?(:field_names_mode) ? agent.field_names_mode : nil
+        mode || :default
+      end
+
+      # @return [Boolean] true when the executing agent asked for server names.
+      def server?
+        current_mode == :server
+      end
+    end
+  end
+end

data/lib/parse/agent/field_policy.rb

@@ -0,0 +1,74 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  class Agent
+    # Per-agent field narrowing.
+    #
+    # A class's `agent_fields` declaration is the CEILING: the most any agent
+    # may read. A `Parse::Agent.new(fields: { "Post" => [:title, :status] })`
+    # policy NARROWS that ceiling for one agent (one MCP deployment), so a
+    # user-facing assistant and an analytics endpoint in the same process can
+    # expose different subsets of the same model. A policy can never widen
+    # past the ceiling, and a sub-agent's policy intersects its parent's.
+    #
+    # The effective allowlist is resolved by
+    # {Parse::Agent::MetadataRegistry.field_allowlist}, which every
+    # enforcement point already calls (projection, `where:`/`keys:` checks,
+    # aggregation pipelines, Atlas Search fields, schema output, exports,
+    # `semantic_search` chunk text). This module supplies the narrowing for
+    # the agent whose tool is currently executing: {Parse::Agent::Tools.invoke}
+    # wraps every tool call in {.with}, so the policy applies without
+    # threading the agent through each helper.
+    #
+    # The scope lives in fiber storage (`Fiber[]`), which child fibers and
+    # threads inherit when they are created. Concurrent requests on
+    # different threads never see each other's policy, and work a custom
+    # tool hands to a thread or fiber it starts stays narrowed.
+    module FieldPolicy
+      SCOPE_KEY = :parse_agent_field_policy_scope
+
+      module_function
+
+      # Run the block with `agent`'s field narrowing in effect.
+      #
+      # @param agent [Parse::Agent, nil]
+      # @return the block's value
+      #
+      # Scopes nest: a tool that builds another agent and invokes it (even one
+      # constructed without `parent:`) runs under BOTH policies, so the inner
+      # call can only narrow further, never escape the outer agent's policy.
+      def with(agent)
+        previous = Fiber[SCOPE_KEY]
+        Fiber[SCOPE_KEY] = (previous || []) + [agent]
+        yield
+      ensure
+        Fiber[SCOPE_KEY] = previous
+      end
+
+      # @return [Parse::Agent, nil] the innermost agent whose tool is executing.
+      def current_agent
+        Fiber[SCOPE_KEY]&.last
+      end
+
+      # Wire-format field names the current agent narrows `class_name` to, or
+      # nil when the agent places no narrowing on that class (or no agent is
+      # in scope).
+      #
+      # @param class_name [String]
+      # @return [Array<String>, nil]
+      def narrowing_for(class_name)
+        stack = Fiber[SCOPE_KEY]
+        return nil if stack.nil? || stack.empty?
+        result = nil
+        stack.uniq.each do |agent|
+          next unless agent.respond_to?(:field_narrowing_for)
+          names = agent.field_narrowing_for(class_name)
+          next if names.nil?
+          result = result ? (result & names) : names
+        end
+        result
+      end
+    end
+  end
+end