parse-stack-next 4.5.0 → 5.0.1

data/examples/transaction_example.rb

@@ -14,22 +14,22 @@ Parse.setup(
 )
 
 # Define example models
-class Team < Parse::Object
+class Workspace < Parse::Object
   property :name
   property :owner, :pointer, class_name: 'User'
   property :member_count, :integer, default: 0
 end
 
-class Membership < Parse::Object
+class Subscription < Parse::Object
   property :user, :pointer, class_name: 'User'
-  property :team, :pointer, class_name: 'Team'
+  property :workspace, :pointer, class_name: 'Workspace'
   property :access_level, :string
   property :grant, :string
 end
 
 class Project < Parse::Object
   property :name
-  property :team, :pointer, class_name: 'Team'
+  property :workspace, :pointer, class_name: 'Workspace'
   property :owner, :pointer, class_name: 'User'
 end
 
@@ -39,16 +39,16 @@ def transfer_project_ownership_basic(project, new_owner)
     # Get old owner
     old_owner = project.owner
     
-    # Find or create new owner membership
-    new_owner_membership = Membership.first(
+    # Find or create new owner subscription
+    new_owner_membership = Subscription.first(
       project: project,
       user: new_owner
     )
     
     if new_owner_membership.nil?
-      new_owner_membership = Membership.new(
+      new_owner_membership = Subscription.new(
         project: project,
-        team: project.team,
+        workspace: project.workspace,
         user: new_owner,
         grant: 'project',
         access_level: 'owner'
@@ -59,9 +59,9 @@ def transfer_project_ownership_basic(project, new_owner)
       batch.add(new_owner_membership)
     end
     
-    # Demote old owner if they have a membership
+    # Demote old owner if they have a subscription
     if old_owner.present?
-      old_owner_membership = Membership.first(
+      old_owner_membership = Subscription.first(
         project: project,
         user: old_owner
       )
@@ -89,13 +89,13 @@ def transfer_project_ownership_auto(project, new_owner)
     old_owner = project.owner
     objects_to_save = []
     
-    # Find or create new owner membership
-    new_owner_membership = Membership.first(
+    # Find or create new owner subscription
+    new_owner_membership = Subscription.first(
       project: project,
       user: new_owner
-    ) || Membership.new(
+    ) || Subscription.new(
       project: project,
-      team: project.team,
+      workspace: project.workspace,
       user: new_owner,
       grant: 'project'
     )
@@ -105,7 +105,7 @@ def transfer_project_ownership_auto(project, new_owner)
     
     # Demote old owner
     if old_owner.present?
-      old_owner_membership = Membership.first(
+      old_owner_membership = Subscription.first(
         project: project,
         user: old_owner
       )
@@ -132,33 +132,33 @@ rescue Parse::Error => e
 end
 
 # Example 3: Complex transaction with validation
-def complex_team_operation(team, new_members, new_owner)
+def complex_team_operation(workspace, new_members, new_owner)
   Parse::Object.transaction(retries: 3) do |batch|
     # Validate new owner is in new members list
     unless new_members.include?(new_owner)
       raise Parse::Error, "New owner must be in members list"
     end
     
-    # Update team
-    team.owner = new_owner
-    team.member_count = new_members.count
-    batch.add(team)
+    # Update workspace
+    workspace.owner = new_owner
+    workspace.member_count = new_members.count
+    batch.add(workspace)
     
-    # Create memberships for all new members
+    # Create subscriptions for all new members
     new_members.each do |member|
-      membership = Membership.new(
-        team: team,
+      subscription = Subscription.new(
+        workspace: workspace,
         user: member,
-        grant: 'team',
+        grant: 'workspace',
         access_level: member == new_owner ? 'owner' : 'member'
       )
-      batch.add(membership)
+      batch.add(subscription)
     end
     
-    # Create a project for the team
+    # Create a project for the workspace
     project = Project.new(
-      name: "#{team.name} Project",
-      team: team,
+      name: "#{workspace.name} Project",
+      workspace: workspace,
       owner: new_owner
     )
     batch.add(project)

data/lib/parse/acl_scope.rb

@@ -63,7 +63,7 @@ module Parse
     #     `false` for backwards compatibility. Note: even with
     #     `strict_role: true`, rows with NO `_rperm` field still pass
     #     (Parse-Server treats absent `_rperm` as public-default); the
-    #     knob only suppresses the `"*"` membership in the `$in` set.
+    #     knob only suppresses the `"*"` subscription in the `$in` set.
     Resolution = Struct.new(:mode, :permission_strings, :user_id, :session, :strict_role, keyword_init: true) do
       def master?; mode == :master; end
       def session?; mode == :session; end
@@ -369,7 +369,7 @@ module Parse
 
       def rewrite_union_with(spec, acl_match, perms)
         # `$unionWith` accepts either a String (collection name only)
-        # or a Hash `{coll:, pipeline:}`. Capture the target from
+        # or a Hash `{coll:, pipeline:}`. Post the target from
         # either shape so the CLP gate fires before the String→Hash
         # upgrade — denying access to the joined class BEFORE we go
         # to the trouble of building out an upgraded sub-pipeline.

data/lib/parse/agent/mcp_rack_app.rb

@@ -188,6 +188,21 @@ module Parse
       #   CSRF and force a CORS preflight on browser `fetch()`, so this
       #   gate closes the browser-driven attack surface entirely. Pair
       #   with `allowed_origins` for defense in depth.
+      # @param health_path [String, nil] when set (e.g. `"/health"`),
+      #   `GET` requests to that exact path return `200 {"status":"ok"}`
+      #   without invoking the agent_factory, without authentication,
+      #   without rate-limiting, and without applying the
+      #   `allowed_origins` / `require_custom_header` CSRF gates.
+      #   Intended as a liveness probe for load balancers and
+      #   orchestrators (Kubernetes, ECS, Consul) that cannot present a
+      #   matching `Origin` or custom header. Because the probe sits
+      #   ahead of the pre-auth rate limiter, operators should
+      #   front-edge rate-limit the path at the LB/Nginx layer if
+      #   public-facing. The response intentionally contains no
+      #   version, build, or counter information — fingerprint-minimal
+      #   by design. `nil` (default) disables the endpoint entirely;
+      #   empty-string values are coerced to `nil`. Any non-GET method
+      #   on the path falls through to the standard 405 handler.
       # @raise [ArgumentError] if both or neither of agent_factory/block are given.
       def initialize(agent_factory: nil, max_body_size: DEFAULT_MAX_BODY_SIZE,
                      logger: nil, streaming: false,
@@ -195,7 +210,8 @@ module Parse
                      max_concurrent_dispatchers: nil,
                      pre_auth_rate_limiter: nil,
                      allowed_origins: nil,
-                     require_custom_header: nil, &block)
+                     require_custom_header: nil,
+                     health_path: nil, &block)
         if agent_factory && block
           raise ArgumentError, "Provide agent_factory: OR a block, not both"
         end
@@ -215,6 +231,7 @@ module Parse
         @pre_auth_rate_limiter      = pre_auth_rate_limiter
         @allowed_origins            = normalize_allowed_origins(allowed_origins)
         @required_custom_header     = normalize_required_custom_header(require_custom_header)
+        @health_path                = health_path.is_a?(String) && !health_path.empty? ? health_path : nil
         # Per-app registry of in-flight cancellable requests. Keyed by
         # [correlation_id, request_id]. A `notifications/cancelled` POST
         # whose `params.requestId` matches an entry trips the registered
@@ -267,6 +284,15 @@ module Parse
         #    underscored form collapses-and-overwrites the trusted slot.
         self.class.strip_underscore_smuggled_headers!(env)
 
+        # 0a. Liveness probe. When `health_path:` is configured, a GET to
+        #     that exact path returns `{"status":"ok"}` without auth,
+        #     rate-limiting, or factory invocation. Intentionally
+        #     fingerprint-minimal: no version, no build, no counter —
+        #     a load balancer needs "is it up?", not "what is it?".
+        if @health_path && env["PATH_INFO"] == @health_path && env["REQUEST_METHOD"] == "GET"
+          return [200, json_headers, ['{"status":"ok"}']]
+        end
+
         # 0b. NEW-MCP-6: pre-auth rate limit. Runs BEFORE the agent_factory
         #     so a malformed body / missing key / empty `{}` cannot force
         #     the operator-supplied factory to round-trip to Parse Server
@@ -282,6 +308,38 @@ module Parse
           end
         end
 
+        # 0c. DELETE /  — MCP 2025-06-18 Streamable HTTP session
+        #     termination. A client signals it is done with a session by
+        #     sending DELETE with the same `Mcp-Session-Id` header it
+        #     received from initialize. Per spec the server MAY support
+        #     this; if it doesn't, it MUST return 405. We support it.
+        #
+        #     Stateless-agent reality: the factory builds a fresh agent
+        #     per request, so there is no server-side session store to
+        #     evict. What DELETE meaningfully does is cancel any
+        #     in-flight requests still running under that correlation_id
+        #     so worker threads exit instead of completing wasted work.
+        #     The cancellation_registry returns 0 when nothing matches
+        #     (also the "unknown session" case) — we don't probe-leak by
+        #     differentiating known vs unknown ids in the response.
+        #
+        #     Sanitized through Parse::Agent#correlation_id= via a
+        #     throwaway agent so a malicious header value (CRLF, shell
+        #     metachars) is silently rejected rather than reaching the
+        #     registry as a key.
+        if env["REQUEST_METHOD"] == "DELETE"
+          sid = env["HTTP_MCP_SESSION_ID"].to_s
+          if sid.empty?
+            return [400, json_headers, [json_rpc_error(-32_600, "Missing Mcp-Session-Id")]]
+          end
+          clean_sid = sanitize_session_id(sid)
+          if clean_sid.nil?
+            return [400, json_headers, [json_rpc_error(-32_600, "Invalid Mcp-Session-Id")]]
+          end
+          @cancellation_registry.cancel_all_for(clean_sid, reason: :session_terminated)
+          return [204, json_headers, [""]]
+        end
+
         # 1. Method check — only POST is accepted.
         unless env["REQUEST_METHOD"] == "POST"
           return [405,
@@ -348,6 +406,32 @@ module Parse
           return [400, json_headers, [json_rpc_error(-32_600, "Invalid Request")]]
         end
 
+        # 4c. MCP-Protocol-Version header validation (MCP 2025-06-18
+        #     Streamable HTTP). The spec says:
+        #       - The client MUST send `MCP-Protocol-Version: <ver>`
+        #         on every request AFTER initialize.
+        #       - If absent on a non-initialize request, the server
+        #         SHOULD assume `2025-03-26` for backwards compatibility.
+        #       - If present but not a version the server supports,
+        #         the server MUST respond `400 Bad Request`.
+        #     Initialize requests are exempt — initialize IS the
+        #     negotiation, so the header is meaningless there.
+        #     Cancellation notifications are also exempt because they
+        #     may be sent by a client that has not (yet) completed
+        #     initialize against this transport instance (e.g. a
+        #     reconnecting client cancelling a pre-disconnect request).
+        unless body["method"] == "initialize" ||
+               body["method"] == "notifications/cancelled"
+          requested = env["HTTP_MCP_PROTOCOL_VERSION"]
+          if requested.is_a?(String) && !requested.empty? &&
+             !Parse::Agent::MCPDispatcher::SUPPORTED_PROTOCOL_VERSIONS.include?(requested)
+            return [400, json_headers,
+                    [json_rpc_error(-32_600,
+                                    "Unsupported MCP-Protocol-Version: #{requested}",
+                                    id: body["id"])]]
+          end
+        end
+
         # 5. Agent factory — auth gate. Rescue Unauthorized first, then catch-all
         #    for unexpected factory errors.
         begin
@@ -363,24 +447,42 @@ module Parse
           return [500, json_headers, [json_rpc_error(-32_603, "Internal error")]]
         end
 
-        # 5b. Thread the conversation correlation id through. Source:
-        #     X-MCP-Session-Id header. Only fills it when the factory
-        #     hasn't already assigned one — application code that needs to
-        #     override the client-supplied id (e.g., bind to an internal
-        #     session record) can do so in the factory and we don't
-        #     stomp on it. The Parse::Agent#correlation_id= setter
-        #     sanitizes the value; an invalid header is silently dropped.
+        # 5b. Thread the conversation correlation id through. Source
+        #     header: the MCP 2025-06-18 Streamable HTTP spec-canonical
+        #     `Mcp-Session-Id` (Rack env key `HTTP_MCP_SESSION_ID`).
+        #
+        #     Only fills it when the factory hasn't already assigned one
+        #     — application code that needs to override the
+        #     client-supplied id (e.g., bind to an internal session
+        #     record) can do so in the factory and we don't stomp on it.
+        #     The Parse::Agent#correlation_id= setter sanitizes the
+        #     value; an invalid header is silently dropped.
         if agent && agent.respond_to?(:correlation_id=) &&
            agent.correlation_id.nil? &&
-           (sid = env["HTTP_X_MCP_SESSION_ID"])
+           (sid = env["HTTP_MCP_SESSION_ID"])
           agent.correlation_id = sid
         end
 
+        # 5b-i. Server-assigned Mcp-Session-Id on initialize. Per MCP
+        #     2025-06-18 Streamable HTTP, the server SHOULD assign a
+        #     fresh session id during initialize when the client did not
+        #     supply one, and return it on the response so the client
+        #     can echo it on subsequent requests. Stateless-agent
+        #     reality: the SDK does not maintain a server-side session
+        #     store — the id is best-effort correlation only (used for
+        #     audit-log threading and cancellation routing). We do not
+        #     refuse subsequent requests carrying an "unknown" id.
+        if body.is_a?(Hash) && body["method"] == "initialize" &&
+           agent && agent.respond_to?(:correlation_id=) &&
+           agent.correlation_id.nil?
+          agent.correlation_id = SecureRandom.uuid
+        end
+
         # 5c. notifications/cancelled — special-cased BEFORE the dispatcher.
         #     A JSON-RPC notification has no `id`, expects no response
         #     body, and must trip the in-flight request whose
         #     `(correlation_id, request_id)` matches. We require the
-        #     cancelling request to carry the same X-MCP-Session-Id
+        #     cancelling request to carry the same Mcp-Session-Id
         #     (sanitized into agent.correlation_id above) as the original
         #     request — otherwise an attacker who guesses sequential
         #     JSON-RPC ids could cancel arbitrary in-flight requests.
@@ -422,14 +524,16 @@ module Parse
       # @return [Array] Rack triple with Array<String> body.
       def serve_json(body, agent)
         result = Parse::Agent::MCPDispatcher.call(body: body, agent: agent, logger: @logger)
+        headers = json_headers
+        merge_session_header!(headers, body, agent)
         # When the dispatcher returns body: nil (a JSON-RPC notification
         # like notifications/cancelled has no response), the Rack body
         # is an empty string — NOT the literal "null". The HTTP-level
         # success/empty-body shape is what the spec calls for and is
         # what every MCP client expects after sending a notification.
-        return [result[:status], json_headers, [""]] if result[:body].nil?
+        return [result[:status], headers, [""]] if result[:body].nil?
 
-        [result[:status], json_headers, [JSON.generate(result[:body])]]
+        [result[:status], headers, [JSON.generate(result[:body])]]
       end
 
       # Return a streaming Rack response that emits SSE progress events while
@@ -504,7 +608,9 @@ module Parse
           )
         end
 
-        [200, sse_headers, sse_body]
+        headers = sse_headers
+        merge_session_header!(headers, body, agent)
+        [200, headers, sse_body]
       end
 
       # ---------------------------------------------------------------------------
@@ -577,8 +683,16 @@ module Parse
         # @param dispatcher_blk [Proc] called with one argument (the
         #   {#progress_callback} Proc); must return the same
         #   `{ status:, body: }` hash that MCPDispatcher.call returns.
+        # @param heartbeat_waiter [Proc, nil] test hook. Called as
+        #   `waiter.call(dispatcher_thread, interval)` once per heartbeat
+        #   iteration; must block until either the dispatcher finishes or
+        #   `interval` elapses. Default delegates to
+        #   `dispatcher_thread.join(interval)`. Tests inject a queue-driven
+        #   waiter so heartbeat cadence is deterministic and not subject
+        #   to OS scheduler jitter.
         def initialize(progress_token, req_id, interval, logger,
-                       cancellation_token: nil, on_close: nil, &dispatcher_blk)
+                       cancellation_token: nil, on_close: nil,
+                       heartbeat_waiter: nil, &dispatcher_blk)
           @progress_token         = progress_token
           # Heartbeats use a dedicated server-generated progressToken so
           # the elapsed-seconds scale of heartbeats never appears on the
@@ -593,6 +707,9 @@ module Parse
           @dispatcher_blk         = dispatcher_blk
           @cancellation_token     = cancellation_token
           @on_close               = on_close
+          @heartbeat_waiter       = heartbeat_waiter ||
+                                    Thread.current[:parse_mcp_sse_heartbeat_waiter] ||
+                                    ->(t, i) { t.join(i) }
           @queue                  = Queue.new
           @worker                 = nil
           # Flipped to true by #each when the DONE sentinel is consumed.
@@ -778,7 +895,7 @@ module Parse
               end
 
               while dispatcher_thread.alive?
-                dispatcher_thread.join(@interval)
+                @heartbeat_waiter.call(dispatcher_thread, @interval)
                 # Skip the heartbeat when the tool has already reported
                 # work-unit progress on the same progressToken. Mixing
                 # elapsed-seconds heartbeats with work-unit values would
@@ -945,7 +1062,7 @@ module Parse
       # matching CancellationToken.
       #
       # Identity binding: cancellation requires the cancelling request's
-      # `X-MCP-Session-Id` (sanitized into `agent.correlation_id`) to
+      # `Mcp-Session-Id` (sanitized into `agent.correlation_id`) to
       # match the original request's. This prevents an attacker who
       # guesses sequential JSON-RPC request ids from cancelling other
       # clients' in-flight requests. A registration with a nil
@@ -1021,6 +1138,24 @@ module Parse
           true
         end
 
+        # Trip every token registered under the given correlation_id.
+        # Used by `DELETE /` session termination — when a client tears
+        # down its session, any in-flight requests still running under
+        # that correlation_id are cancelled so worker threads exit
+        # promptly instead of carrying a doomed result to completion.
+        #
+        # Silent no-op when no entries match (or correlation_id is
+        # blank). Returns the number of tokens tripped.
+        def cancel_all_for(correlation_id, reason: :session_terminated)
+          return 0 if correlation_id.nil? || correlation_id.to_s.empty?
+          tokens = @mutex.synchronize do
+            keys = @entries.keys.select { |(cid, _)| cid == correlation_id }
+            keys.map { |k| @entries.delete(k)[1] }
+          end
+          tokens.each { |t| t.cancel!(reason: reason) }
+          tokens.size
+        end
+
         # @return [Integer] number of currently-registered tokens. Used
         #   by tests and operator dashboards.
         def size
@@ -1046,6 +1181,39 @@ module Parse
         SSE_HEADERS.dup
       end
 
+      # Sanitize an `Mcp-Session-Id` header value with the same rules as
+      # {Parse::Agent#correlation_id=} (URL-safe ASCII, ≤128 chars).
+      # Returns the cleaned string, or nil if the input fails the regex.
+      # Used by the DELETE handler before passing the value to the
+      # cancellation registry; reproducing the regex here keeps the
+      # transport layer from instantiating a throwaway Parse::Agent just
+      # to borrow its setter.
+      # Same character set as {Parse::Agent::CORRELATION_ID_RE}, redeclared
+      # here so this file doesn't depend on agent.rb's load order.
+      SESSION_ID_RE = /\A[A-Za-z0-9._\-]+\z/.freeze
+
+      def sanitize_session_id(value)
+        return nil if value.nil?
+        s = value.to_s
+        return nil unless SESSION_ID_RE.match?(s)
+        s[0, 128]
+      end
+
+      # When the request being responded to is `initialize` and the agent
+      # carries a (server-assigned or factory-bound) correlation_id,
+      # advertise it as the spec-canonical `Mcp-Session-Id` response
+      # header so the client can echo it on subsequent requests. The
+      # header is emitted ONLY on the initialize response — non-init
+      # responses don't carry it, both to avoid leaking the id on every
+      # reply and because the client already knows it.
+      def merge_session_header!(headers, body, agent)
+        return unless body.is_a?(Hash) && body["method"] == "initialize"
+        return unless agent && agent.respond_to?(:correlation_id)
+        sid = agent.correlation_id
+        return if sid.nil? || sid.to_s.empty?
+        headers["Mcp-Session-Id"] = sid
+      end
+
       # ---------------------------------------------------------------------------
       # JSON-RPC envelope helpers
       # ---------------------------------------------------------------------------

data/lib/parse/agent/metadata_dsl.rb

@@ -8,10 +8,10 @@ module Parse
     # to the Parse Agent for LLM interaction.
     #
     # @example Define a model with agent metadata
-    #   class Team < Parse::Object
+    #   class Workspace < Parse::Object
     #     agent_description "A group of users contributing to a Project"
     #
-    #     property :name, :string, description: "The team's display name"
+    #     property :name, :string, description: "The workspace's display name"
     #     property :member_count, :integer, description: "Number of active members"
     #
     #     agent_method :active_projects, "Returns projects currently in progress"
@@ -190,7 +190,7 @@ module Parse
         # Called without arguments, returns the current allowlist.
         #
         # @example Limit agent visibility to analytics-relevant fields
-        #   class Team < Parse::Object
+        #   class Workspace < Parse::Object
         #     agent_fields :name, :status, :member_count, :owner
         #   end
         #
@@ -224,9 +224,9 @@ module Parse
         # allowlist is typically the full "what the agent may see" set;
         # the join-projection list is the narrower "what's interesting when
         # I'm a foreign key" set. Example: `_User` may surface 18 fields on
-        # a direct query, but when it's joined onto a `Membership` row the
+        # a direct query, but when it's joined onto a `Subscription` row the
         # agent usually only needs `firstName`, `lastName`, `email`,
-        # `internalTag` — not the `teams[]` pointer array or the
+        # `category` — not the `workspaces[]` pointer array or the
         # `iconImage` presigned URL.
         #
         # **Subset invariant**: when both `agent_fields` and
@@ -247,7 +247,7 @@ module Parse
         # pointer.
         #
         # @example
-        #   class Membership < Parse::Object
+        #   class Subscription < Parse::Object
         #     belongs_to :user
         #     property :title, :string
         #     property :active, :boolean
@@ -257,11 +257,11 @@ module Parse
         #   # In the _User reopen / customization:
         #   class Parse::User
         #     agent_fields :first_name, :last_name, :email, :icon_image,
-        #                  :source_image, :teams, :organizations, :last_active_at,
-        #                  :internal_tag
+        #                  :source_image, :workspaces, :tenants, :last_active_at,
+        #                  :category
         #     agent_large_fields :icon_image, :source_image
         #     agent_join_fields :first_name, :last_name, :email,
-        #                      :last_active_at, :internal_tag
+        #                      :last_active_at, :category
         #   end
         #
         # @param names [Array<Symbol, String>] field names to project on join
@@ -313,8 +313,8 @@ module Parse
         # Declare a canonical "valid state" filter for this class that the
         # agent's read tools (`query_class`, `count_objects`, `aggregate`)
         # apply BY DEFAULT to every call. Closes the silently-suspect-
-        # counts gap: when a class soft-deletes via `isRemoved`, hides
-        # rows via `on_timeline: false`, or has any other always-applied
+        # counts gap: when a class soft-deletes via `archived`, hides
+        # rows via `published: false`, or has any other always-applied
         # validity predicate, the canonical filter ensures an LLM that
         # drops to raw aggregate doesn't accidentally include the
         # excluded rows.
@@ -332,11 +332,11 @@ module Parse
         # caller can reproduce it manually.
         #
         # @example
-        #   class Capture < Parse::Object
-        #     property :isRemoved, :boolean
-        #     property :onTimeline, :boolean
-        #     agent_canonical_filter "isRemoved" => { "$ne" => true },
-        #                            "onTimeline" => true
+        #   class Post < Parse::Object
+        #     property :archived, :boolean
+        #     property :published, :boolean
+        #     agent_canonical_filter "archived" => { "$ne" => true },
+        #                            "published" => true
         #   end
         #
         # @param filter [Hash, nil] a where-style hash. Pass nil to

data/lib/parse/agent/pipeline_validator.rb

@@ -51,13 +51,22 @@ module Parse
       # Validate an aggregation pipeline for security issues.
       # Delegates to {Parse::PipelineSecurity.validate_pipeline!} and
       # translates its error into {PipelineSecurityError} for backwards
-      # compatibility.
+      # compatibility. Additionally refuses Atlas-stage-0-only operators
+      # (`$search`, `$searchMeta`, `$vectorSearch`, `$listSearchIndexes`)
+      # which are legal SDK-emitted stages but must NOT appear in a
+      # caller-supplied agent pipeline — the agent surface for those is
+      # the dedicated `atlas_search` / `semantic_search` tools, and the
+      # Agent's tenant-scope `$match` prepend would push them off
+      # stage 0 anyway. See
+      # {Parse::PipelineSecurity::STAGE0_ONLY_ATLAS_STAGES}.
       #
       # @param pipeline [Array<Hash>] the aggregation pipeline stages
       # @raise [PipelineSecurityError] if pipeline contains blocked or unknown stages
       # @return [true] if pipeline is valid
       def validate!(pipeline)
         Parse::PipelineSecurity.validate_pipeline!(pipeline)
+        refuse_stage0_only_atlas_stages!(pipeline)
+        true
       rescue Parse::PipelineSecurity::Error => e
         raise PipelineSecurityError.new(
           e.message,
@@ -67,6 +76,24 @@ module Parse
         )
       end
 
+      # @api private
+      def refuse_stage0_only_atlas_stages!(pipeline)
+        return unless pipeline.is_a?(Array)
+        pipeline.each do |stage|
+          next unless stage.is_a?(Hash)
+          stage.each_key do |k|
+            key = k.to_s
+            next unless Parse::PipelineSecurity::STAGE0_ONLY_ATLAS_STAGES.include?(key)
+            raise PipelineSecurityError.new(
+              "Stage #{key} is not allowed in caller-supplied agent pipelines. " \
+              "Use the dedicated atlas_search / semantic_search agent tool instead.",
+              stage: key,
+              reason: :stage0_only_atlas_stage,
+            )
+          end
+        end
+      end
+
       # Check if a pipeline is valid without raising.
       #
       # @param pipeline [Array<Hash>] the aggregation pipeline

data/lib/parse/agent/prompts.rb

@@ -106,7 +106,7 @@ module Parse
         },
         {
           "name" => "count_by",
-          "description" => "Count objects in a class grouped by a field (e.g. users by team, projects by status)",
+          "description" => "Count objects in a class grouped by a field (e.g. users by workspace, projects by status)",
           "arguments" => [
             { "name" => "class_name", "description" => "Parse class to count", "required" => true },
             { "name" => "group_by", "description" => "Field to group by", "required" => true },
@@ -122,12 +122,12 @@ module Parse
         },
         {
           "name" => "find_relationship",
-          "description" => "Find objects in one class related to a given object in another (e.g. members of a team)",
+          "description" => "Find objects in one class related to a given object in another (e.g. members of a workspace)",
           "arguments" => [
-            { "name" => "parent_class", "description" => "Class of the parent object (e.g. Team)", "required" => true },
+            { "name" => "parent_class", "description" => "Class of the parent object (e.g. Workspace)", "required" => true },
             { "name" => "parent_id", "description" => "objectId of the parent", "required" => true },
             { "name" => "child_class", "description" => "Class to query (e.g. _User)", "required" => true },
-            { "name" => "pointer_field", "description" => "Field on child_class that points to parent (e.g. team)", "required" => true },
+            { "name" => "pointer_field", "description" => "Field on child_class that points to parent (e.g. workspace)", "required" => true },
           ],
         },
         {
@@ -185,7 +185,7 @@ module Parse
             { "$limit" => 25 },
           ]
           "Count #{cn} objects grouped by #{gb}. Use aggregate with class_name=\"#{cn}\" and pipeline #{pipeline.to_json}. " \
-          "If #{gb} is a pointer field, Parse returns each `_id` as the literal string \"ClassName$objectId\" (e.g. \"Team$abc123\") — strip the \"ClassName$\" prefix to recover the objectId, then optionally call get_object on a few to label them. " \
+          "If #{gb} is a pointer field, Parse returns each `_id` as the literal string \"ClassName$objectId\" (e.g. \"Workspace$abc123\") — strip the \"ClassName$\" prefix to recover the objectId, then optionally call get_object on a few to label them. " \
           "Report the top groups, call out any null/missing values, and give the total."
         },