:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(replay-vision): let a scanner draft start from a recording filter the person chose (#124517)
Kim Svatos Duganf9aab879ea58
diff --git a/posthog/session_recordings/queries/session_recording_list_from_query.py b/posthog/session_recordings/queries/session_recording_list_from_query.pyindex 0259c6dbf6a9..d8ea65fa4d99 100644--- a/posthog/session_recordings/queries/session_recording_list_from_query.py+++ b/posthog/session_recordings/queries/session_recording_list_from_query.py@@ -170,9 +170,12 @@ class SessionRecordingListFromQuery(SessionRecordingsListingBaseQuery):# variant (as `any(exposure.variant)`): the experiment-exposure join then projects it.# The population is unchanged, so plain listings never need this.project_exposure_variant: bool = False,+ # For callers that read a short page as "no more matches", so a timeout must raise, not truncate.+ throw_on_timeout: bool = False,**_,):self._user = user+ self._throw_on_timeout = throw_on_timeoutself._project_exposure_variant = project_exposure_variant# Storage-level SAMPLE on any events subqueries; opt-in for estimates.self._events_sample_factor = events_sample_factor@@ -280,10 +283,9 @@ class SessionRecordingListFromQuery(SessionRecordingsListingBaseQuery):# every cause.settings_args["max_memory_usage"] = linkage.live_scan_max_memory_bytesin_session_narrowed = linkage is not None and linkage.in_session- if in_session_narrowed:- # Under a "break" timeout profile a timed-out evidence subquery would return a partial- # session set, silently listing fewer in-session recordings. A partial result is worse- # than an error here, so the execution-time kill must throw.+ if in_session_narrowed or self._throw_on_timeout:+ # Under a "break" timeout profile a timed-out query returns partial rows, which an in-session+ # listing or a `throw_on_timeout` caller would take as complete. So the execution-time kill throws.settings_args["timeout_overflow_mode"] = "throw"with tracer.start_as_current_span("SessionRecordingListFromQuery.paginate"):diff --git a/products/replay_vision/backend/api/scanners.py b/products/replay_vision/backend/api/scanners.pyindex e476adca6625..0f0a032f57bb 100644--- a/products/replay_vision/backend/api/scanners.py+++ b/products/replay_vision/backend/api/scanners.py@@ -62,6 +62,7 @@ from posthog.rate_limit import (ReplayVisionHighlightFeedSustainedRateThrottle,)+from products.access_control.backend.facade.user_access_control import UserAccessControlfrom products.access_control.backend.presentation.access_control import (AccessControlViewSetMixin,UserAccessControlSerializerMixin,@@ -158,11 +159,19 @@ from products.replay_vision.backend.scanner_dashboard import ()from products.replay_vision.backend.scanner_draft import (DraftError,+ UnknownExperimentVariantError,UnwatchableExperimentError,draft_scanner_from_goal,+ readable_entity_kinds,scopes_allow_read,)-from products.replay_vision.backend.scanner_query import ScannerQueryError, clean_scanner_query+from products.replay_vision.backend.scanner_query import (+ ScannerQueryError,+ chosen_scope,+ clean_scanner_query,+ query_references,+ unresolved_references,+)from products.replay_vision.backend.scanning import (MAX_SESSIONS_PER_SCAN,run_inline_scan,@@ -240,7 +249,11 @@ logger = structlog.get_logger(__name__)class RecordingsQueryField(serializers.JSONField):"""A scanner's recording filter, a `RecordingsQuery`. The rules in `scanner_query` decide what a- scanner may keep, so this only refuses a value that is not an object, before any of them reads it."""+ scanner may keep, so this only refuses a value that is not an object, before any of them reads it.++ The OpenAPI type stays open on purpose. The app types this with the query schema's own+ `RecordingsQuery`, which the generated duplicate does not accept.+ """def to_internal_value(self, data: Any) -> Any:value = super().to_internal_value(data)@@ -249,6 +262,38 @@ class RecordingsQueryField(serializers.JSONField):return value+def query_reference_error(+ query: dict[str, Any],+ *,+ team: Team,+ user_access_control: UserAccessControl,+ allowed_scopes: list[str] | None,+) -> str | None:+ """Why the actions and cohorts a recording filter names can't be used, or None when they can.++ Gated before anything resolves, so a caller without read access learns nothing about which ids+ exist. A reference the query builder cannot load would fail every estimate and every run, and+ the estimate cannot tell that apart from a timeout, so it is refused here too. Create, update,+ the estimate and the draft all run the filter, so all of them check it.+ """+ try:+ refs = query_references(query, team)+ except ScannerQueryError as error:+ return str(error)+ kinds = readable_entity_kinds(user_access_control, allowed_scopes)+ for kind, ids in (("action", refs.actions), ("cohort", refs.cohorts)):+ if ids and kind not in kinds:+ return f"This recording filter uses {kind}s, which your access doesn't cover."+ missing = unresolved_references(+ query,+ team,+ can_read_action=lambda action: bool(user_access_control.check_access_level_for_object(action, "viewer")),+ )+ if missing:+ return f"This recording filter uses {', '.join(missing)}, which this project doesn't have."+ return None++def _clean_query(value: dict[str, Any]) -> dict[str, Any]:try:return clean_scanner_query(value)@@ -983,7 +1028,16 @@ class ReplayScannerSerializer(TaggedItemSerializerMixin, UserAccessControlSerialdef validate_query(self, value: dict[str, Any]) -> dict[str, Any]:# Persist exactly what the user sent (validated), minus the date keys the schedule controls.- return _clean_query(value)+ query = _clean_query(value)+ request = self.context.get("request")+ if error := query_reference_error(+ query,+ team=self.context["get_team"](),+ user_access_control=cast(UserAccessControl, self.user_access_control),+ allowed_scopes=get_authenticator_scopes(request.successful_authenticator) if request else None,+ ):+ raise serializers.ValidationError(error)+ return querydef to_representation(self, instance: ReplayScanner) -> dict[str, Any]:data = super().to_representation(instance)@@ -1949,6 +2003,20 @@ class DraftScannerRequestSerializer(serializers.Serializer):"The draft is then an `experiment` scanner on it."),)+ query = RecordingsQueryField(+ required=False,+ help_text=(+ "A `RecordingsQuery` the person already chose, as the replay list holds it. The draft starts from "+ "it and never removes or widens it. When the goal asks for narrower recordings, the draft can AND "+ "its own page, event, action or cohort filters onto it. It keeps them only when the combined "+ "filter still matches recent recordings, returns them in `query_additions`, and sizes the "+ "sampling dials against the combined `query`. `experiment_exposure` becomes the scanner's "+ "experiment and variants, which the draft keeps as they are. `date_from`/`date_to` are dropped, "+ "because a scanner's schedule owns time. `comment_text`, `hide_viewed_recordings` and in-session "+ "exposure are refused, because a scanner cannot apply them. A query with no filters starts from "+ "every new recording. Omit to let the draft pick the sessions."+ ),+ )def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:has_budget = attrs.get("monthly_credit_budget") is not None@@ -1956,6 +2024,13 @@ class DraftScannerRequestSerializer(serializers.Serializer):raise ValidationError({"monthly_credit_budget": "Set either a monthly credit budget or free_only, but not both."})+ if "query" in attrs:+ try:+ scope = chosen_scope(attrs["query"], experiment_id=attrs.get("experiment_id"))+ except ScannerQueryError as error:+ raise ValidationError({error.field: str(error)})+ attrs["chosen_scope"] = scope+ attrs["experiment_id"] = scope.experiment_idreturn attrs@@ -1974,13 +2049,19 @@ class DraftScannerResponseSerializer(serializers.Serializer):allow_blank=True,help_text="Why the draft picked this scanner type and configuration, addressed to the user.",)- query = extend_schema_field(RecordingsQuery)( # type: ignore[arg-type, type-var]- serializers.JSONField(- allow_null=True,- help_text=(- "`RecordingsQuery` narrowing which sessions get scanned; null when the draft targets every session."- ),- )+ query = RecordingsQueryField(+ allow_null=True,+ help_text=(+ "`RecordingsQuery` narrowing which sessions get scanned; null when the draft targets every session."+ ),+ )+ query_additions = RecordingsQueryField(+ allow_null=True,+ help_text=(+ "When the request passed a `query`: the filters the draft ANDed onto it, which `query` already "+ "includes. Show them to the person as added by AI. Null when nothing was added or no `query` "+ "was passed."+ ),)sampling_mode = serializers.ChoiceField(choices=SamplingMode.choices,@@ -3111,6 +3192,8 @@ class ReplayScannerViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, vi):raise serializers.ValidationError({scope_field: "Experiment not found in this project."})+ if (query := body.validated_data.get("query")) is not None:+ self._check_query_references(query, get_authenticator_scopes(request.successful_authenticator))# validate_query already validated this; the empty-dict default needs `kind` to parse.query_dict: dict[str, Any] = dict(body.validated_data.get("query") or {})query_dict.setdefault("kind", "RecordingsQuery")@@ -3150,6 +3233,12 @@ class ReplayScannerViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, vi).data)+ def _check_query_references(self, query: dict[str, Any], allowed_scopes: list[str] | None) -> None:+ if error := query_reference_error(+ query, team=self.team, user_access_control=self.user_access_control, allowed_scopes=allowed_scopes+ ):+ raise ValidationError({"query": error})+@extend_schema(request=DraftScannerRequestSerializer,responses={@@ -3207,12 +3296,15 @@ class ReplayScannerViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, vi)else:monthly_credit_budget = body.validated_data["monthly_credit_budget"]+ scope = body.validated_data.get("chosen_scope")# The goal is customer text, so only its length goes into telemetry.draft_properties: dict[str, Any] = {"goal_length": len(goal),"team_id": self.team_id,"monthly_credit_budget": monthly_credit_budget,"free_only": free_only,+ "query_pinned": "query" in body.validated_data,+ "experiment_from_query": bool(scope and scope.experiment_from_query),}# Scoped tokens must not receive data their scopes exclude. Core memory is INTERNAL# (session-only), so any scoped token loses it; the goal-based entity grounding (surveys,@@ -3226,6 +3318,8 @@ class ReplayScannerViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viand is_experiment_accessible(self.user_access_control, self.team_id, experiment_id)):raise ValidationError({"experiment_id": "Experiment not found in this project."})+ if scope is not None:+ self._check_query_references(scope.query, allowed_scopes)try:drafted = draft_scanner_from_goal(@@ -3237,12 +3331,16 @@ class ReplayScannerViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, viinclude_business_context=include_business_context,allowed_scopes=allowed_scopes,experiment_id=experiment_id,+ experiment_variants=scope.experiment_variants if scope else None,free_only=free_only,+ chosen_query=scope.query if scope else None,)except UnwatchableExperimentError:raise ValidationError({"experiment_id": "Pick a running experiment that splits people, not groups, into variants."})+ except UnknownExperimentVariantError as error:+ raise ValidationError({"query": f"The experiment has no variant named {error.variant!r}."})except DraftError as e:# The 503 below is deliberately uniform, so the reason only survives here.logger.warning(@@ -3272,6 +3370,9 @@ class ReplayScannerViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, vi"scanner_type": drafted.scanner_type,# Whether the goal mapped to a real filter or fell back to no targeting."has_query": bool(drafted.query),+ "query_extended": bool(drafted.query_additions),+ # Why proposed narrowing was not kept, so a prompt that keeps proposing dead filters shows up.+ "narrowing_refusal": drafted.narrowing_refusal,"has_experiment_targeting": drafted.scanner_type == ScannerType.EXPERIMENT,"experiment_picked": experiment_id is not None,"sampling_mode": drafted.sampling_mode,@@ -3293,6 +3394,7 @@ class ReplayScannerViewSet(TeamAndOrgViewSetMixin, AccessControlViewSetMixin, vi"scanner_config": drafted.scanner_config,"rationale": drafted.rationale,"query": drafted.query,+ "query_additions": drafted.query_additions,"sampling_mode": drafted.sampling_mode,"sampling_rate": drafted.sampling_rate,"model": drafted.model,diff --git a/products/replay_vision/backend/queries/__init__.py b/products/replay_vision/backend/queries/__init__.pyindex d20adb51a546..0be2d0edceb1 100644--- a/products/replay_vision/backend/queries/__init__.py+++ b/products/replay_vision/backend/queries/__init__.py@@ -7,6 +7,7 @@ from products.replay_vision.backend.queries.scanner_volume_estimate import (SAVE_ESTIMATE_BUDGET,ScannerVolumeEstimate,estimate_scanner_session_volume,+ has_recent_matching_recording,is_experiment_linkage_unresolved,project_monthly_observations,refresh_scanner_estimate,@@ -21,6 +22,7 @@ __all__ = ["MIN_SAMPLING_RATE","ScannerVolumeEstimate","estimate_scanner_session_volume",+ "has_recent_matching_recording","is_experiment_linkage_unresolved","project_monthly_observations","refresh_scanner_estimate",diff --git a/products/replay_vision/backend/queries/scanner_volume_estimate.py b/products/replay_vision/backend/queries/scanner_volume_estimate.pyindex 8729d27f8d31..a22b42a317af 100644--- a/products/replay_vision/backend/queries/scanner_volume_estimate.py+++ b/products/replay_vision/backend/queries/scanner_volume_estimate.py@@ -1,3 +1,4 @@+import timeimport datetime as dtfrom dataclasses import dataclassfrom typing import Any@@ -96,6 +97,82 @@ class _EstimateQueryPlan:sampled: bool+# One exclusion query covers this many ids, which is also the sweep's chunk size.+_MATCH_CHECK_ROWS = 1_000+++class MatchCheckIncomplete(Exception):+ """The match check could not reach an answer: every fetched recording was excluded and more remain."""+++def has_recent_matching_recording(+ *,+ team: Team,+ query: RecordingsQuery,+ user: User | None,+ sampling_mode: SamplingMode | str = SamplingMode.COMPREHENSIVE,+ budget: EstimateBudget = PREVIEW_ESTIMATE_BUDGET,+) -> bool:+ """Whether the sweep would observe at least one recording that matches `query` in the estimate's window.++ The estimate is no answer to this: it drops negative filters, because they never sample and an+ over-count is the safe direction for a forecast. This runs the sweep's own selection instead: the+ recordings list without its in-query blocklists, the sweep's eligibility rules, then the negative+ filters against the fetched rows, the way `find_scanner_candidates` excludes.++ It reads one batch, because each further page would scan the whole window again. Raises+ `MatchCheckIncomplete` when the exclusions remove every fetched row and more remain, and lets a+ timeout or query failure raise, so the caller never reads "no match" from a check that did not+ finish. Both queries share one deadline from `budget`. `user` is the principal for the exposure+ access check and the exclusion reads.+ """+ deadline = time.monotonic() + budget.max_execution_seconds++ def seconds_left() -> int:+ remaining = int(deadline - time.monotonic())+ if remaining < 1:+ raise TimeoutError("The recent-recording match check ran out of time.")+ return remaining++ scan_window_days = budget.window_days(unsampled=query.operand == FilterLogicalOperator.OR_)+ windowed = query.model_copy(deep=True)+ windowed.date_from = (dt.datetime.now(dt.UTC) - dt.timedelta(days=scan_window_days)).isoformat()+ windowed.date_to = None+ windowed.limit = _MATCH_CHECK_ROWS+ windowed.offset = None+ windowed.after = None+ extra_having = eligibility_predicates()+ if (surfacing := surfacing_score_predicate(sampling_mode)) is not None:+ extra_having.append(surfacing)+ tag_queries(team_id=team.id, product=Product.REPLAY_VISION, feature=Feature.QUERY)+ listing = SessionRecordingListFromQuery(+ team=team,+ query=windowed,+ user=user,+ extra_having_predicates=extra_having,+ skip_negative_blocklists=True,+ max_execution_time=seconds_left(),+ throw_on_timeout=True,+ )+ page = listing.run()+ session_ids = [row["session_id"] for row in page.results]+ excluded: set[str] = set()+ for exclusion in listing.excluded_sessions_queries(session_ids) if session_ids else []:+ response = execute_hogql_query(+ query=exclusion,+ team=team,+ user=user,+ query_type="ScannerMatchCheckExcludedSessions",+ settings=HogQLGlobalSettings(max_execution_time=seconds_left(), timeout_overflow_mode="throw"),+ )+ excluded.update(row[0] for row in response.results or [])+ if any(session_id not in excluded for session_id in session_ids):+ return True+ if page.has_more_recording:+ raise MatchCheckIncomplete()+ return False++def estimate_scanner_session_volume(*,team: Team,diff --git a/products/replay_vision/backend/scanner_draft.py b/products/replay_vision/backend/scanner_draft.pyindex 08101eb52ab9..c4f6f8e72d31 100644--- a/products/replay_vision/backend/scanner_draft.py+++ b/products/replay_vision/backend/scanner_draft.py@@ -11,6 +11,7 @@ re-validates everything on save."""import re+import jsonimport timeimport uuidimport functools@@ -63,10 +64,12 @@ from products.replay_vision.backend.queries.scanner_candidate_query import MIN_Sfrom products.replay_vision.backend.queries.scanner_volume_estimate import (PREVIEW_ESTIMATE_BUDGET,estimate_scanner_session_volume,+ has_recent_matching_recording,project_monthly_observations,)from products.replay_vision.backend.queries.visited_paths import VisitedPath, fetch_visited_pathsfrom products.replay_vision.backend.scanner_config import scanner_config_error+from products.replay_vision.backend.scanner_query import NarrowingRefusal, combines_with_and, narrow_chosen_queryfrom products.replay_vision.backend.tags import slugify_tagfrom ee.hogai.utils.feature_flags import is_core_memory_disabled@@ -265,6 +268,14 @@ class UnwatchableExperimentError(Exception):group-aggregated, or without variants."""+class UnknownExperimentVariantError(Exception):+ """A variant the person picked is not one the experiment defines, so the exposure read would refuse it."""++ def __init__(self, variant: str) -> None:+ super().__init__(variant)+ self.variant = variant++@dataclass(frozen=True, kw_only=True)class ScannerDraft:"""A normalized draft ready to seed the creation wizard's form."""@@ -286,6 +297,8 @@ class ScannerDraft:model: str | None = Nonecredit_limit: int | None = Nonefree_only: bool = False+ query_additions: dict[str, Any] | None = None+ narrowing_refusal: str | None = None@dataclass(frozen=True, kw_only=True)@@ -787,6 +800,8 @@ def _build_user_content(cohorts: Sequence[_MatchedCohort] = (),experiments: Sequence[_MatchedExperiment] = (),pinned_experiment: _MatchedExperiment | None = None,+ pinned_variants: Sequence[str] | None = None,+ chosen_query: dict[str, Any] | None = None,business_context: str = "",company: str = "",) -> str:@@ -861,12 +876,40 @@ def _build_user_content(),))+ if chosen_query is not None:+ # The operand covers the whole query, so a filter that ORs its conditions has nothing to AND onto.+ narrowable = combines_with_and(chosen_query)+ lines.append(+ "\n"+ + as_untrusted_data(+ "chosen-recordings",+ [json.dumps(chosen_query, separators=(",", ":"), sort_keys=True)],+ source=(+ "the recording filter the user already chose, as a RecordingsQuery. The scanner starts "+ "from it and always keeps it; with no filters it starts from every new recording. "+ + (+ "When the goal asks for narrower recordings than this filter holds, such as one page, "+ "event, action or cohort, set the filter_ fields for that. Each one you set is ANDed "+ "with this filter, so it can only remove recordings, and it is kept only if the "+ "result still matches recent recordings. Do not repeat a condition this filter already "+ "has, keep filter_events_match at all, and leave the filter_ fields empty when this "+ "filter already fits the goal. The user also fixed which experiment, if any, the "+ "scanner watches, so leave filter_experiment and filter_experiment_variant empty"+ if narrowable+ else "It matches recordings that meet any one of its conditions, so nothing can be "+ "ANDed onto it: leave every filter_ field empty and write the scanner for these "+ "recordings"+ )+ ),+ )+ )if pinned_experiment is not None:+ picked = f"; watch only: {', '.join(pinned_variants)}" if pinned_variants else ""lines.append("\n"+ as_untrusted_data("chosen-experiment",- [f'"{pinned_experiment.name}" -> variants: {", ".join(pinned_experiment.variants)}'],+ [f'"{pinned_experiment.name}" -> variants: {", ".join(pinned_experiment.variants)}{picked}'],source=("the experiment the user picked for this scanner to watch. Copy its name into ""filter_experiment and draft an experiment scanner about it"@@ -975,6 +1018,28 @@ def scopes_allow_read(allowed_scopes: list[str] | None, resource: APIScopeObjectreturn "*" in allowed_scopes or f"{resource}:read" in allowed_scopes or f"{resource}:write" in allowed_scopes+def readable_entity_kinds(user_access_control: UserAccessControl, allowed_scopes: list[str] | None) -> set[str]:+ """The kinds of team entity the caller may read: by role for the access-controlled kinds, and by+ token scope for every kind, since a draft has no viewset to enforce `required_scopes`.++ A kind the caller holds specific access to counts, so callers that act on single objects still+ check each one.+ """++ def _readable(resource: APIScopeObject) -> bool:+ return user_access_control.check_access_level_for_resource(+ resource, required_level="viewer"+ ) or user_access_control.has_any_specific_access_for_resource(resource, required_level="viewer")++ acl_kinds: tuple[APIScopeObject, ...] = ("survey", "action", "experiment")+ kinds: set[str] = {kind for kind in acl_kinds if _readable(kind) and scopes_allow_read(allowed_scopes, kind)}+ # Cohorts are team-scoped only, not in ACCESS_CONTROL_RESOURCES, so they get no resource gate,+ # but a scoped token still must hold cohort:read to receive them.+ if scopes_allow_read(allowed_scopes, "cohort"):+ kinds.add("cohort")+ return kinds++def _goal_entity_matches(team: Team,goal: str,@@ -1008,17 +1073,7 @@ def _goal_entity_matches(if not terms:return _GoalEntityMatches(surveys=[], actions=[], cohorts=[], experiments=[])- def _readable(resource: APIScopeObject) -> bool:- return user_access_control.check_access_level_for_resource(- resource, required_level="viewer"- ) or user_access_control.has_any_specific_access_for_resource(resource, required_level="viewer")-- acl_kinds: tuple[APIScopeObject, ...] = ("survey", "action", "experiment")- kinds: set[str] = {kind for kind in acl_kinds if _readable(kind) and scopes_allow_read(allowed_scopes, kind)}- # Cohorts are team-scoped only, not in ACCESS_CONTROL_RESOURCES, so they get no resource gate,- # but a scoped token still must hold cohort:read to receive them.- if scopes_allow_read(allowed_scopes, "cohort"):- kinds.add("cohort")+ kinds = readable_entity_kinds(user_access_control, allowed_scopes)# `search_entities` builds its result by unioning one queryset per kind, then orders by the rank# those querysets annotate. With no kind it orders an empty base queryset by a column that was# never added, which raises.@@ -1383,8 +1438,13 @@ def _finalize(allowed_cohorts: Sequence[_MatchedCohort] = (),allowed_experiments: Sequence[_MatchedExperiment] = (),pinned_experiment: _MatchedExperiment | None = None,+ pinned_variants: Sequence[str] | None = None,) -> ScannerDraft:- """Normalize the model output; costing is applied by the caller."""+ """Normalize the model output; costing is applied by the caller.++ `pinned_variants` are the variants of `pinned_experiment` the user picked, or empty for every+ variant. When it is set, the model's variant is ignored.+ """name = parsed.name.strip()[:_MAX_NAME_LENGTH]if not name or not parsed.prompt.strip():raise DraftError("missing_name_or_prompt")@@ -1423,7 +1483,13 @@ def _finalize(if pinned_experiment is not Noneelse (parsed.filter_experiment, allowed_experiments))- targeting = _grounded_targeting(experiment_name, parsed.filter_experiment_variant, allowed=experiments)+ if pinned_experiment is not None and pinned_variants is not None:+ targeting: dict[str, Any] | None = {+ "experiment_id": pinned_experiment.experiment_id,+ "variants": list(pinned_variants) or None,+ }+ else:+ targeting = _grounded_targeting(experiment_name, parsed.filter_experiment_variant, allowed=experiments)scanner_type, scanner_config = _typed_config(parsed, targeting)# Dropping a dead event narrows only while another filter still holds the scan down. Alone it# inverts, leaving a query that matches every session rather than none, so the event goes back.@@ -1647,7 +1713,7 @@ def _typed_config(parsed: _LlmDraft, targeting: dict[str, Any] | None) -> tuple[scanner_config = {**summary,"experiment_id": targeting["experiment_id"],- "variants": [variant] if variant else None,+ "variants": targeting.get("variants") or ([variant] if variant else None),"balance_variants": True,}if error := scanner_config_error(ScannerType.EXPERIMENT, scanner_config):@@ -1709,11 +1775,20 @@ def draft_scanner_from_goal(include_business_context: bool = True,allowed_scopes: list[str] | None = None,experiment_id: int | None = None,+ experiment_variants: Sequence[str] | None = None,free_only: bool = False,+ chosen_query: dict[str, Any] | None = None,) -> ScannerDraft:"""Ground the goal in the team's real pages, draft the whole scanner in onemodel call, then solve the sampling dials from the stated monthly credit budget.+ `chosen_query` is a recording filter the user already chose, already cleaned by+ `clean_scanner_query`. The draft starts from it and never widens it: see `_settle_chosen_scope`.+ The user's experiment scope is fixed with it, so the model cannot add or change an experiment.++ `experiment_variants` are the variants of `experiment_id` the user picked. This raises+ UnknownExperimentVariantError for one the experiment does not define.+`free_only` drafts a scanner that runs only on the organization's free credits. The caller thenpasses those free credits as `monthly_credit_budget`, and the draft carries no credit limit.@@ -1742,6 +1817,12 @@ def draft_scanner_from_goal()if pinned_experiment is None:raise UnwatchableExperimentError()+ for variant in experiment_variants or ():+ if variant not in pinned_experiment.variants:+ raise UnknownExperimentVariantError(variant)+ # With a chosen filter the user fixed the experiment scope too, so every variant is theirs unless+ # they picked some. Without one, the model may still narrow the picked experiment to a variant.+ pinned_variants = tuple(experiment_variants or ()) if chosen_query is not None or experiment_variants else Nonecompany = (" / ".join(part for part in [team.organization.name, team.project.name if team.project else ""] if part)if include_business_context@@ -1817,8 +1898,10 @@ def draft_scanner_from_goal(surveys=matches.surveys,actions=matches.actions,cohorts=matches.cohorts,- experiments=[e for e in matches.experiments if e != pinned_experiment],+ experiments=[] if chosen_query is not None else [e for e in matches.experiments if e != pinned_experiment],pinned_experiment=pinned_experiment,+ pinned_variants=pinned_variants,+ chosen_query=chosen_query,business_context=_business_context(team, user) if include_business_context else "",company=company,)@@ -1837,8 +1920,9 @@ def draft_scanner_from_goal(allowed_surveys=matches.surveys,allowed_actions=matches.actions,allowed_cohorts=matches.cohorts,- allowed_experiments=matches.experiments,+ allowed_experiments=() if chosen_query is not None else matches.experiments,pinned_experiment=pinned_experiment,+ pinned_variants=pinned_variants,)# The cap is the stated budget, so a mis-estimate stops the scanner at the credits the user# agreed to rather than overspending. Kept even when costing fails, so the guardrail survives.@@ -1863,6 +1947,23 @@ def draft_scanner_from_goal(model_mode=draft.sampling_mode or SamplingMode.COMPREHENSIVE,)+ if chosen_query is not None:++ def has_match(query: dict[str, Any]) -> bool:+ # Targeted the way the estimate is, so both ask about the same population.+ return has_recent_matching_recording(+ team=team,+ user=user,+ query=apply_experiment_targeting(+ RecordingsQuery.model_validate(query), config_experiment_scope(draft.scanner_config)+ ),+ # The solver keeps either every recording or the model's mode, and the model's mode is+ # the narrower one, so a match there holds for whichever the solver picks.+ sampling_mode=draft.sampling_mode or SamplingMode.COMPREHENSIVE,+ )++ return _settle_chosen_scope(draft, chosen=chosen_query, solve=solve, has_match=has_match, team_id=team.id)+# Started next to the draft's own estimate, so a filter that matches nothing costs no second wait.fallback = _pages_only(draft.query)if fallback == draft.query:@@ -1876,17 +1977,89 @@ def draft_scanner_from_goal(return Nonerelaxed = _start_in_background(solve_fallback) if fallback is not None else None- try:- solution = solve(draft.query)- except Exception:- # A slow count must not throw away a good draft; the wizard falls back to its defaults.- logger.warning("replay_vision.scanner_draft.budget_solve_failed", team_id=team.id, exc_info=True)- return replace(draft, sampling_mode=None, sampling_rate=None, estimated_monthly_observations=None)+ solution = _solve_or_none(solve, draft.query, team_id=team.id)+ if solution is None:+ return _costed(draft, None)if solution.estimated_monthly_observations == 0 and fallback is not None and relaxed is not None:if (relaxed_solution := relaxed()) is not None:draft, solution = _fall_back_to_pages(team=team, draft=draft, solution=solution, fallback=fallback, relaxed=relaxed_solution)+ return _costed(draft, solution)+++# The model's rationale describes the narrower filter, so a dropped proposal needs a note or it misleads.+_NARROWING_REFUSAL_NOTES: dict[NarrowingRefusal, str] = {+ NarrowingRefusal.OR_OPERAND: (+ "Your filter matches recordings that meet any one of its conditions, so nothing could be added to it. "+ "This watches the recordings you picked."+ ),+ NarrowingRefusal.INVALID: (+ "The filters suggested for yours would make a filter a scanner can't save. This watches the "+ "recordings you picked."+ ),+ NarrowingRefusal.MATCHED_NOTHING: (+ "The filters suggested for yours matched no recent recordings. This watches the recordings you picked."+ ),+ NarrowingRefusal.UNVERIFIED: (+ "The filters suggested for yours could not be checked against recent recordings. This watches the "+ "recordings you picked."+ ),+}+++def _settle_chosen_scope(+ draft: ScannerDraft,+ *,+ chosen: dict[str, Any],+ solve: Callable[[dict[str, Any] | None], _BudgetSolution],+ has_match: Callable[[dict[str, Any]], bool],+ team_id: int,+) -> ScannerDraft:+ """The draft on the user's chosen filter, narrowed by the model's filters only where that is shown to work.++ The chosen filter is the user's, so it is kept whatever it matches. The model's filters are a+ proposal: they are kept only when the combined filter is one a scanner can save, and the+ recordings list finds a recent recording that matches it. That check applies negative filters,+ which the estimate skips, so it is the check, and the estimate only prices the filter that won.+ Every other outcome keeps the chosen filter, and the rationale says why whenever a proposal was+ dropped.+ """+ narrowing = narrow_chosen_query(chosen, draft.query)+ refusal = narrowing.refusal+ query, additions = chosen, None+ if narrowing.additions is not None:+ try:+ matched: bool | None = has_match(narrowing.query)+ except Exception:+ logger.warning("replay_vision.scanner_draft.narrowing_check_failed", team_id=team_id, exc_info=True)+ matched = None+ if matched:+ query, additions = narrowing.query, narrowing.additions+ else:+ refusal = NarrowingRefusal.MATCHED_NOTHING if matched is False else NarrowingRefusal.UNVERIFIED+ draft = replace(draft, query=query, query_additions=additions, narrowing_refusal=refusal.value if refusal else None)+ if refusal is not None:+ draft = replace(draft, rationale=_rationale_with_note(draft.rationale, _NARROWING_REFUSAL_NOTES[refusal]))+ return _costed(draft, _solve_or_none(solve, query, team_id=team_id))+++def _solve_or_none(+ solve: Callable[[dict[str, Any] | None], _BudgetSolution], query: dict[str, Any] | None, *, team_id: int+) -> _BudgetSolution | None:+ """The budget solution for `query`, or None when counting failed."""+ try:+ return solve(query)+ except Exception:+ # A slow count must not throw away a good draft; the wizard falls back to its defaults.+ logger.warning("replay_vision.scanner_draft.budget_solve_failed", team_id=team_id, exc_info=True)+ return None+++def _costed(draft: ScannerDraft, solution: _BudgetSolution | None) -> ScannerDraft:+ """The draft with its sampling dials solved, or left empty for the wizard's defaults when counting failed."""+ if solution is None:+ return replace(draft, sampling_mode=None, sampling_rate=None, estimated_monthly_observations=None)return replace(draft,sampling_mode=solution.sampling_mode,@@ -1958,12 +2131,16 @@ def _fallback_rationale(rationale: str, *, dropped_events: int, dropped_actions:The rationale still describes the filter the model picked, so leaving it alone would tell theuser this scanner watches something it no longer watches.-- Trims the model's own text rather than the note, so the note cannot be cut in half by the cap."""if dropped_events and dropped_actions:filters = "event and action filters"else:filters = "event filter" if dropped_events else "action filter"- note = f"The {filters} matched no recent recordings, so this scans the pages instead."+ return _rationale_with_note(+ rationale, f"The {filters} matched no recent recordings, so this scans the pages instead."+ )+++def _rationale_with_note(rationale: str, note: str) -> str:+ """Trims the model's own text rather than the note, so the note cannot be cut in half by the cap."""return f"{rationale[: _MAX_RATIONALE_LENGTH - len(note) - 1].strip()} {note}".strip()diff --git a/products/replay_vision/backend/scanner_query.py b/products/replay_vision/backend/scanner_query.pyindex b6845e033b56..efb013d0bde9 100644--- a/products/replay_vision/backend/scanner_query.py+++ b/products/replay_vision/backend/scanner_query.py@@ -2,25 +2,54 @@A scanner keeps less of a recording filter than the replay list does, and each difference failssilently: a dropped condition saves a scanner that watches more than the person chose, and a broken-one saves a scanner whose runs keep failing. Create, update and the estimate all accept a filter, so-they share these rules rather than each keeping a copy that can drift.+one saves a scanner whose runs keep failing. Create, update, the estimate and the draft all accept a+filter, so they share these rules rather than each keeping a copy that can drift."""import json+from collections.abc import Callable+from enum import StrEnumfrom typing import Any-from pydantic import ValidationError as PydanticValidationError+from pydantic import (+ BaseModel,+ ValidationError as PydanticValidationError,+)+from rest_framework.exceptions import ValidationError as DRFValidationError-from posthog.schema import RecordingsQuery+from posthog.schema import ActionsNode, FilterLogicalOperator, RecordingsQuery++from posthog.hogql import ast+from posthog.hogql.errors import BaseHogQLError+from posthog.hogql.parser import parse_expr+from posthog.hogql.visitor import TraversingVisitor++from posthog.dataclasses import frozen+from posthog.models.team import Team+from posthog.session_recordings.queries.sub_queries.events_subquery import ReplayFiltersEventsSubQuery++from products.actions.backend.models.action import Action+from products.cohorts.backend.models.cohort import Cohort# A scanner's schedule owns time, so a saved filter never carries a date range.DATE_FIELDS = ("date_from", "date_to")+# A query can carry the rows it last returned, which may hold person data, and are never part of a filter.+RESULT_FIELDS = ("response",)+# Only the replay list API applies these, so a scanner that kept them would watch more than the filter shows.+REPLAY_LIST_ONLY_FIELDS = ("comment_text", "hide_viewed_recordings")# Copied into every observation's snapshot, so the write boundary caps it.MAX_QUERY_BYTES = 50_000+_FILTER_LISTS = ("properties", "events", "actions")+class ScannerQueryError(ValueError):- """A recording filter a scanner cannot keep. The message is safe to show to the caller."""+ """A recording filter a scanner cannot keep. The message is safe to show to the caller, and+ `field` names the request field it belongs to."""++ def __init__(self, message: str, *, field: str = "query") -> None:+ super().__init__(message)+ self.field = fielddef _as_object(value: object) -> dict[str, Any]:@@ -36,8 +65,17 @@ def _parsed(value: dict[str, Any]) -> RecordingsQuery:raise ScannerQueryError("Recording filter is invalid.")+def combines_with_and(query: dict[str, Any] | None) -> bool:+ """Whether the query's conditions must all hold, so a condition ANDed onto it narrows it.++ Read from the parsed query the way the recordings query builder reads it: anything but `AND`,+ an explicit null included, joins the conditions with OR.+ """+ return query is None or _parsed(query).operand == FilterLogicalOperator.AND_++def clean_scanner_query(value: object) -> dict[str, Any]:- """The filter as a scanner stores it: a valid `RecordingsQuery` without the date range.+ """The filter as a scanner stores it: a valid `RecordingsQuery` without the date range or results.Raises `ScannerQueryError` for anything a saved scanner must not hold."""@@ -50,7 +88,247 @@ def clean_scanner_query(value: object) -> dict[str, Any]:raise ScannerQueryError("Recording filter can't set experiment exposure directly. Set experiment_targeting instead.")- cleaned = {key: item for key, item in value.items() if key not in DATE_FIELDS}+ cleaned = {key: item for key, item in value.items() if key not in DATE_FIELDS + RESULT_FIELDS}+ if fields := replay_list_only_fields(cleaned):+ raise ScannerQueryError(+ f"A scanner can't apply these recording filters: {', '.join(fields)}. Remove them and try again."+ )if len(json.dumps(cleaned, separators=(",", ":")).encode()) > MAX_QUERY_BYTES:raise ScannerQueryError(f"Recording filter is too large. Keep it under {MAX_QUERY_BYTES // 1000} KB.")return cleaned+++def replay_list_only_fields(query: dict[str, Any]) -> list[str]:+ """The fields set on `query` that only the replay list API resolves."""+ return [field for field in REPLAY_LIST_ONLY_FIELDS if query.get(field)]+++def unresolved_references(+ query: dict[str, Any], team: Team, *, can_read_action: Callable[[Action], bool] = lambda action: True+) -> list[str]:+ """The actions and cohorts `query` names that a scan cannot load, described for the caller.++ Resolved the way the recordings query builder resolves them, by project and with deleted cohorts+ excluded, so a filter this accepts always builds. Without the check, the estimate fails the same+ way a timeout does, and a broken filter saves into a scanner whose runs keep failing.++ An action `can_read_action` refuses reads as unresolved too, so the result never tells a caller+ that an id they cannot read exists.+ """+ refs = query_references(query, team)+ action_ids = {ref for ref in refs.actions if isinstance(ref, int)}+ cohort_ids = {ref for ref in refs.cohorts if isinstance(ref, int)}+ found_actions = {+ action.id+ for action in Action.objects.filter(pk__in=action_ids, team__project_id=team.project_id)+ if can_read_action(action)+ }+ found_cohorts = set(+ Cohort.objects.filter(pk__in=cohort_ids, team__project_id=team.project_id, deleted=False).values_list(+ "id", flat=True+ )+ )+ missing_actions = [ref for ref in refs.actions if ref not in found_actions]+ missing_cohorts = [ref for ref in refs.cohorts if ref not in found_cohorts]+ return [f"action {ref}" for ref in missing_actions] + [f"cohort {ref}" for ref in missing_cohorts]+++@frozen+class QueryReferences:+ """The ids a query names, in order and without repeats. A value that is not an integer id stays as+ it is, so it reads as unresolved."""++ actions: list[int | str]+ cohorts: list[int | str]+++class _HogQLReferences(TraversingVisitor):+ """The actions and cohorts a HogQL filter names, through `matchesAction(id)` and `IN COHORT id`.++ Refuses what it cannot read: a subquery or a HogQLX tag, which can select from cohort tables+ directly or expand into a query after this check, and a reference that is not a constant id. A+ name is refused too, since resolving it here would tell the caller which id it belongs to before+ any access check.+ """++ def __init__(self) -> None:+ super().__init__()+ self.actions: list[int] = []+ self.cohorts: list[int] = []++ @staticmethod+ def _id(arg: ast.Expr | None, kind: str) -> int:+ if isinstance(arg, ast.Constant) and isinstance(arg.value, int) and not isinstance(arg.value, bool):+ return arg.value+ raise ScannerQueryError(f"A HogQL expression in a scanner filter must name each {kind} by its numeric id.")++ def visit_call(self, node: ast.Call) -> None:+ if node.name == "matchesAction":+ self.actions.append(self._id(node.args[0] if node.args else None, "action"))+ super().visit_call(node)++ def visit_compare_operation(self, node: ast.CompareOperation) -> None:+ if node.op in (ast.CompareOperationOp.InCohort, ast.CompareOperationOp.NotInCohort):+ self.cohorts.append(self._id(node.right, "cohort"))+ super().visit_compare_operation(node)++ def visit_select_query(self, node: ast.SelectQuery) -> None:+ raise ScannerQueryError("A HogQL expression in a scanner filter can't use a subquery.")++ def visit_select_set_query(self, node: ast.SelectSetQuery) -> None:+ raise ScannerQueryError("A HogQL expression in a scanner filter can't use a subquery.")++ def visit_hogqlx_tag(self, node: ast.HogQLXTag) -> None:+ raise ScannerQueryError("A HogQL expression in a scanner filter can't use a HogQLX tag.")+++def query_references(query: dict[str, Any], team: Team) -> QueryReferences:+ """Every action and cohort id the query names, read from the filters the query builder runs.++ The builder reads typed filters, not the raw JSON: an untyped `{"value": 7}` is a cohort filter,+ an event entry of type `actions` is an action, and a property group nests its filters. A HogQL+ filter is parsed for the references in its expression. Reading the same typed filters means a+ reference cannot run without being found here.+ """+ parsed = _parsed(query)+ try:+ builder = ReplayFiltersEventsSubQuery(team, parsed)+ entities = [*builder.entities, *builder.negated_entities]+ except (DRFValidationError, TypeError, ValueError):+ # Entities are untyped in the query, so a malformed one only fails when it is built.+ raise ScannerQueryError("Recording filter is invalid.")+ actions: dict[int | str, None] = {}+ cohorts: dict[int | str, None] = {}++ def as_id(value: object) -> int | str:+ try:+ return int(value) # type: ignore[call-overload]+ except (TypeError, ValueError, OverflowError):+ return str(value)++ def visit(item: object) -> None:+ if isinstance(item, BaseModel):+ item = item.model_dump(exclude_none=True)+ if isinstance(item, list):+ for child in item:+ visit(child)+ return+ if not isinstance(item, dict):+ return+ if item.get("type") in ("cohort", "precalculated-cohort", "static-cohort"):+ cohorts[as_id(item.get("value"))] = None+ elif item.get("type") == "behavioral" and item.get("event_type") == "actions":+ actions[as_id(item.get("key"))] = None+ elif item.get("type") == "hogql":+ try:+ expression = parse_expr(str(item.get("key") or ""))+ # The parser raises Python's own errors too: SyntaxError for an empty expression,+ # RecursionError for one nested too deeply.+ except (BaseHogQLError, SyntaxError, RecursionError):+ raise ScannerQueryError("Recording filter has a HogQL expression that doesn't parse.")+ embedded = _HogQLReferences()+ embedded.visit(expression)+ actions.update(dict.fromkeys(embedded.actions))+ cohorts.update(dict.fromkeys(embedded.cohorts))+ # A property group holds its filters in `values`, and a filter can nest its own `properties`.+ visit(item.get("values"))+ visit(item.get("properties"))++ for entity in entities:+ if isinstance(entity, ActionsNode):+ actions[as_id(entity.id)] = None+ visit(entity.properties)+ visit(parsed.properties)+ visit(parsed.having_predicates)+ return QueryReferences(actions=list(actions), cohorts=list(cohorts))+++class NarrowingRefusal(StrEnum):+ """Why conditions proposed for a chosen filter were not added to it."""++ # The operand covers the whole query, so an OR on either side would widen the scan, not narrow it.+ OR_OPERAND = "or_operand"+ INVALID = "invalid"+ MATCHED_NOTHING = "matched_nothing"+ UNVERIFIED = "unverified"+++@frozen+class ChosenQueryNarrowing:+ """A chosen filter with proposed conditions ANDed onto it, or the reason they were not."""++ query: dict[str, Any]+ additions: dict[str, Any] | None+ refusal: NarrowingRefusal | None+++def narrow_chosen_query(chosen: dict[str, Any], proposed: dict[str, Any] | None) -> ChosenQueryNarrowing:+ """`chosen` with the conditions of `proposed` that it lacks ANDed onto it.++ The chosen filter is never removed or widened, so the scanner can only watch fewer recordings+ than the person picked. A condition `chosen` already holds is not added twice, and a proposal+ with nothing new is no proposal, so it is not refused either.+ """+ new = {+ key: [item for item in (proposed or {}).get(key) or [] if item not in (chosen.get(key) or [])]+ for key in _FILTER_LISTS+ }+ new = {key: items for key, items in new.items() if items}+ if not new:+ return ChosenQueryNarrowing(query=chosen, additions=None, refusal=None)+ if not combines_with_and(chosen) or not combines_with_and(proposed):+ return ChosenQueryNarrowing(query=chosen, additions=None, refusal=NarrowingRefusal.OR_OPERAND)+ combined = {**chosen, **{key: [*(chosen.get(key) or []), *items] for key, items in new.items()}}+ try:+ combined = clean_scanner_query(combined)+ except ScannerQueryError:+ return ChosenQueryNarrowing(query=chosen, additions=None, refusal=NarrowingRefusal.INVALID)+ return ChosenQueryNarrowing(query=combined, additions={"kind": "RecordingsQuery", **new}, refusal=None)+++@frozen+class ChosenScope:+ """The scope a draft starts from: the filter as a scanner keeps it, and the experiment it watches."""++ query: dict[str, Any]+ experiment_id: int | None+ # The variants the person picked, or None for every variant. Set only by exposure in the filter.+ experiment_variants: list[str] | None+ experiment_from_query: bool+++def chosen_scope(value: object, *, experiment_id: int | None) -> ChosenScope:+ """The scope of a filter the person chose, as the replay list holds it.++ The replay list scopes a filter to an experiment with exposure inside the query, which a saved+ scanner keeps as its experiment instead. The whole filter is parsed first, so the exposure is read+ only once it is known to be well formed. A filter the scanner could keep only in part is refused,+ because the draft would then watch more than the person chose.+ """+ value = _as_object(value)+ exposure = _parsed(value).experiment_exposure+ query = clean_scanner_query({key: item for key, item in value.items() if key != "experiment_exposure"})+ if exposure is None:+ return ChosenScope(+ query=query, experiment_id=experiment_id, experiment_variants=None, experiment_from_query=False+ )+ # The replay list's exposure resolver refuses these, so the scope would be one it cannot honor.+ if exposure.variant is not None and exposure.variants is not None:+ raise ScannerQueryError("The experiment exposure can set 'variant' or 'variants', not both.")+ if exposure.variants is not None and not exposure.variants:+ raise ScannerQueryError("The experiment exposure's 'variants' must name at least one variant.")+ if exposure.in_session:+ raise ScannerQueryError("A scanner can't keep the in-session exposure condition. Remove it and try again.")+ if experiment_id is not None and experiment_id != exposure.experiment_id:+ raise ScannerQueryError("This is not the experiment the recording filter is scoped to.", field="experiment_id")+ # By presence, as the replay list reads them, so an empty name is checked rather than read as every variant.+ requested = exposure.variants if exposure.variants is not None else None+ if requested is None and exposure.variant is not None:+ requested = [exposure.variant]+ variants = list(dict.fromkeys(requested)) if requested is not None else None+ return ChosenScope(+ query=query,+ experiment_id=exposure.experiment_id,+ experiment_variants=variants,+ experiment_from_query=True,+ )diff --git a/products/replay_vision/backend/tests/test_api.py b/products/replay_vision/backend/tests/test_api.pyindex b68f0a93155a..34723f0317fa 100644--- a/products/replay_vision/backend/tests/test_api.py+++ b/products/replay_vision/backend/tests/test_api.py@@ -35,6 +35,8 @@ from posthog.redis import get_clientfrom posthog.session_recordings.queries.test.session_replay_sql import produce_replay_summaryfrom products.access_control.backend.models.access_control import AccessControl+from products.actions.backend.models.action import Action+from products.cohorts.backend.models.cohort import Cohortfrom products.experiments.backend.models.experiment import Experimentfrom products.replay_vision.backend.api.scanners import HighlightFeedQuerySerializer, ReplayScannerSerializerfrom products.replay_vision.backend.api.trigger import WorkflowStartOutcome, start_apply_scanner_workflow@@ -755,7 +757,7 @@ class TestReplayScannerViewSet(_VisionAPITestCase):self.assertEqual(resp.status_code, 201, resp.json())self.assertEqual(resp.json()["query"], {"filter_test_accounts": True})- def test_create_strips_date_fields_from_query(self) -> None:+ def test_create_strips_date_and_result_fields_from_query(self) -> None:# The schedule controls time, not the user.resp = self.client.post(self.scanners_url,@@ -764,12 +766,18 @@ class TestReplayScannerViewSet(_VisionAPITestCase):"scanner_type": ScannerType.MONITOR,"scanner_config": {"prompt": "p"},"model": ScannerModel.GEMINI_3_8_FLASH,- "query": {"date_from": "-7d", "date_to": "-1d", "filter_test_accounts": True},+ "query": {+ "date_from": "-7d",+ "date_to": "-1d",+ "filter_test_accounts": True,+ "response": {"results": [], "has_next": False},+ },},format="json",)self.assertEqual(resp.status_code, 201, resp.json())body_query = resp.json()["query"]+ self.assertNotIn("response", body_query)self.assertNotIn("date_from", body_query)self.assertNotIn("date_to", body_query)self.assertEqual(body_query["filter_test_accounts"], True)@@ -791,6 +799,24 @@ class TestReplayScannerViewSet(_VisionAPITestCase):{"experiment_exposure": {"experiment_id": 1}},"Recording filter can't set experiment exposure directly. Set experiment_targeting instead.",),+ (+ "replay_list_only",+ {+ "kind": "RecordingsQuery",+ "comment_text": {+ "type": "recording",+ "key": "comment_text",+ "value": "refund",+ "operator": "icontains",+ },+ },+ "A scanner can't apply these recording filters: comment_text. Remove them and try again.",+ ),+ (+ "missing_action",+ {"kind": "RecordingsQuery", "actions": [{"id": 999999, "type": "actions"}]},+ "This recording filter uses action 999999, which this project doesn't have.",+ ),])def test_create_rejects_invalid_query(self, _name: str, query: object, detail: str) -> None:@@ -4207,12 +4233,76 @@ class TestReplayScannerEstimateAction(ClickhouseTestMixin, _VisionAPITestCase):("query_oversized", {"query": {"distinct_ids": ["x" * 1_000 for _ in range(100)]}}),("query_experiment_exposure", {"query": {"experiment_exposure": {"experiment_id": 1}}}),("query_not_an_object", {"query": ["kind", "RecordingsQuery"]}),+ ("query_missing_cohort", {"query": {"properties": [{"type": "cohort", "key": "id", "value": 999999}]}}),+ ("query_malformed_entity", {"query": {"events": [{"id": "$pageview", "properties": 1}]}}),])def test_estimate_rejects_invalid_input(self, _name: str, payload: dict[str, Any]) -> None:resp = self.client.post(self.estimate_url, data=payload, format="json")self.assertEqual(resp.status_code, 400)+ def test_an_action_the_caller_cannot_read_is_refused_inside_hogql(self) -> None:+ # The HogQL action resolver loads any action in the project, so the object-level check has to+ # reach the ids an expression names, or a member could count a restricted action's sessions.+ self.organization.available_product_features = [+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL}+ ]+ self.organization.save()+ action = Action.objects.create(team=self.team, name="Restricted", created_by=self.user)+ AccessControl.objects.create(team=self.team, resource="action", resource_id=str(action.id), access_level="none")+ member = User.objects.create_and_join(self.organization, "[email protected]", "testtest")+ self.client.force_login(member)+ query = {"kind": "RecordingsQuery", "properties": [{"type": "hogql", "key": f"matchesAction({action.id})"}]}++ resp = self.client.post(self.estimate_url, data={"query": query}, format="json")++ self.assertEqual(resp.status_code, 400, resp.json())+ self.assertEqual(+ resp.json()["detail"], f"This recording filter uses action {action.id}, which this project doesn't have."+ )++ @parameterized.expand(+ [+ ("estimate", "cohort", "This recording filter uses cohorts, which your access doesn't cover."),+ ("create", "cohort", "This recording filter uses cohorts, which your access doesn't cover."),+ ("estimate", "hogql", "This recording filter uses cohorts, which your access doesn't cover."),+ ]+ )+ def test_a_token_without_cohort_read_cannot_filter_by_cohort(self, endpoint: str, form: str, detail: str) -> None:+ cohort = Cohort.objects.create(team=self.team, name="Paying customers")+ key = generate_random_token_personal()+ PersonalAPIKey.objects.create(+ label="cohort-scope-test",+ user=self.user,+ secure_value=hash_key_value(key),+ scopes=["replay_scanner:write", "session_recording:read"],+ )+ cohort_filter = (+ {"type": "cohort", "key": "id", "value": cohort.id}+ if form == "cohort"+ else {"type": "hogql", "key": f"person_id IN COHORT {cohort.id}"}+ )+ query = {"kind": "RecordingsQuery", "properties": [cohort_filter]}+ url, data = (+ (self.estimate_url, {"query": query})+ if endpoint == "estimate"+ else (+ self.scanners_url,+ {+ "name": "cohort-scoped",+ "scanner_type": ScannerType.MONITOR,+ "scanner_config": {"prompt": "p"},+ "model": ScannerModel.GEMINI_3_8_FLASH,+ "query": query,+ },+ )+ )++ resp = self.client.post(url, data=data, format="json", HTTP_AUTHORIZATION=f"Bearer {key}")++ self.assertEqual(resp.status_code, 400, resp.json())+ self.assertEqual(resp.json()["detail"], detail)+def test_estimate_scopes_to_an_experiment_scanners_experiment(self) -> None:# An experiment scanner keeps its experiment in its config, so the estimate has to take that# shape, or an agent sizing one counts every session instead of the exposed ones.diff --git a/products/replay_vision/backend/tests/test_recent_matching_recording.py b/products/replay_vision/backend/tests/test_recent_matching_recording.pynew file mode 100644index 000000000000..1bf7f7249df1--- /dev/null+++ b/products/replay_vision/backend/tests/test_recent_matching_recording.py@@ -0,0 +1,97 @@+import time_machine+from posthog.test.base import APIBaseTest, ClickhouseTestMixin+from unittest.mock import patch++from django.utils.timezone import now++from dateutil.relativedelta import relativedelta+from parameterized import parameterized++from posthog.schema import RecordingsQuery++from posthog.clickhouse.client import sync_execute+from posthog.models.utils import uuid7+from posthog.session_recordings.queries.test.listing_recordings.test_utils import create_event+from posthog.session_recordings.queries.test.session_replay_sql import produce_replay_summary+from posthog.session_recordings.sql.session_replay_event_sql import TRUNCATE_SESSION_REPLAY_EVENTS_TABLE_SQL++from products.replay_vision.backend.queries.scanner_volume_estimate import (+ MatchCheckIncomplete,+ has_recent_matching_recording,+)+++@time_machine.travel("2026-10-01T12:00:00Z", tick=False)+class TestHasRecentMatchingRecording(ClickhouseTestMixin, APIBaseTest):+ def setUp(self) -> None:+ super().setUp()+ sync_execute(TRUNCATE_SESSION_REPLAY_EVENTS_TABLE_SQL())+ self._recording(hours_ago=1, pathname="/checkout")++ def _recording(self, *, hours_ago: int, pathname: str) -> None:+ started = now() - relativedelta(hours=hours_ago)+ distinct_id = str(uuid7())+ session_id = str(uuid7())+ produce_replay_summary(+ team_id=self.team.id,+ distinct_id=distinct_id,+ session_id=session_id,+ first_timestamp=started.isoformat(),+ last_timestamp=(started + relativedelta(minutes=2)).isoformat(),+ active_milliseconds=30_000,+ )+ create_event(+ team=self.team,+ distinct_id=distinct_id,+ timestamp=started,+ properties={"$session_id": session_id, "$window_id": "1", "$pathname": pathname},+ )++ @parameterized.expand(+ [+ ("positive", "icontains", True),+ # The estimate skips negative filters, so only an exact check sees that this excludes the session.+ ("negative", "not_icontains", False),+ ]+ )+ def test_applies_event_filters_the_way_the_recordings_list_does(self, _name, operator, expected):+ query = RecordingsQuery.model_validate(+ {+ "kind": "RecordingsQuery",+ "events": [+ {+ "id": "$pageview",+ "name": "$pageview",+ "type": "events",+ "properties": [+ {"key": "$pathname", "type": "event", "value": "checkout", "operator": operator}+ ],+ }+ ],+ }+ )++ assert has_recent_matching_recording(team=self.team, query=query, user=self.user) is expected++ _EXCLUDES_CHECKOUT = RecordingsQuery.model_validate(+ {+ "kind": "RecordingsQuery",+ "properties": [{"key": "$pathname", "type": "event", "value": "/checkout", "operator": "is_not"}],+ }+ )++ @parameterized.expand([("an older recording matches", "/pricing", True), ("no recording matches", None, False)])+ def test_applies_negative_filters_to_the_fetched_rows(self, _name, older_pathname, expected):+ if older_pathname:+ self._recording(hours_ago=2, pathname=older_pathname)++ assert has_recent_matching_recording(team=self.team, query=self._EXCLUDES_CHECKOUT, user=self.user) is expected++ def test_an_excluded_batch_with_more_rows_left_is_not_an_answer(self):+ self._recording(hours_ago=2, pathname="/pricing")++ with (+ patch("products.replay_vision.backend.queries.scanner_volume_estimate._MATCH_CHECK_ROWS", 1),+ self.assertRaises(MatchCheckIncomplete),+ ):+ has_recent_matching_recording(team=self.team, query=self._EXCLUDES_CHECKOUT, user=self.user)diff --git a/products/replay_vision/backend/tests/test_scanner_draft.py b/products/replay_vision/backend/tests/test_scanner_draft.pyindex fe461f4b6d4c..ffa6b835c8bc 100644--- a/products/replay_vision/backend/tests/test_scanner_draft.py+++ b/products/replay_vision/backend/tests/test_scanner_draft.py@@ -457,6 +457,7 @@ class TestDraftScannerEndpoint(_VisionAPITestCase):"estimate_scanner_session_volume",{"return_value": ScannerVolumeEstimate(matched_sessions=300, effective_window_days=30)},),+ ("has_recent_matching_recording", {"return_value": True}),]for target, kwargs in targets:patcher = patch(f"{_MODULE}.{target}", **kwargs)@@ -513,6 +514,7 @@ class TestDraftScannerEndpoint(_VisionAPITestCase):},"rationale": "A classifier fits because you want the mix of visit intents, not a single yes/no.","query": {"kind": "RecordingsQuery", "filter_test_accounts": True},+ "query_additions": None,"sampling_mode": "comprehensive","sampling_rate": 1.0,"model": "gemini-3-flash-preview",@@ -520,6 +522,168 @@ class TestDraftScannerEndpoint(_VisionAPITestCase):**expected_spend,}+ @patch(_GENERATE_PATH)+ def test_a_chosen_query_reaches_the_draft_without_its_date_range(self, mock_generate):+ mock_generate.return_value = _draft()+ chosen = {"kind": "RecordingsQuery", "filter_test_accounts": False}++ resp = self.client.post(+ self.draft_url,+ data={"goal": "find rage clicks", "free_only": True, "query": {**chosen, "date_from": "-7d"}},+ format="json",+ )++ assert resp.status_code == status.HTTP_200_OK, resp.json()+ assert resp.json()["query"] == chosen+ assert '"filter_test_accounts":false' in mock_generate.call_args.kwargs["user_content"]++ @parameterized.expand(+ [+ (+ "comment search",+ {+ "kind": "RecordingsQuery",+ "comment_text": {+ "type": "recording",+ "key": "comment_text",+ "value": "checkout",+ "operator": "icontains",+ },+ },+ {},+ "comment_text",+ ),+ (+ "hide viewed recordings",+ {"kind": "RecordingsQuery", "hide_viewed_recordings": "current-user"},+ {},+ "hide_viewed_recordings",+ ),+ (+ "in-session exposure",+ {"kind": "RecordingsQuery", "experiment_exposure": {"experiment_id": 1, "in_session": True}},+ {},+ "in-session",+ ),+ ("not an object", ["kind", "RecordingsQuery"], {}, "JSON object"),+ (+ "unloadable cohort",+ {+ "kind": "RecordingsQuery",+ "properties": [{"type": "cohort", "key": "id", "value": 999999, "operator": "in"}],+ },+ {},+ "cohort 999999",+ ),+ (+ "conflicting experiment",+ {"kind": "RecordingsQuery", "experiment_exposure": {"experiment_id": 1}},+ {"experiment_id": 2},+ "not the experiment",+ ),+ ("exposure without an experiment", {"kind": "RecordingsQuery", "experiment_exposure": {}}, {}, "invalid"),+ ("exposure that is not an object", {"kind": "RecordingsQuery", "experiment_exposure": "x"}, {}, "invalid"),+ (+ "exposure with an empty variant list",+ {"kind": "RecordingsQuery", "experiment_exposure": {"experiment_id": 1, "variants": []}},+ {},+ "at least one variant",+ ),+ (+ "exposure with both variant forms",+ {+ "kind": "RecordingsQuery",+ "experiment_exposure": {"experiment_id": 1, "variant": "test", "variants": ["control"]},+ },+ {},+ "not both",+ ),+ ]+ )+ @patch(_GENERATE_PATH)+ def test_a_chosen_query_the_scanner_cannot_keep_is_refused(self, _name, query, extra, named, mock_generate):+ resp = self.client.post(+ self.draft_url,+ data={"goal": "find rage clicks", "free_only": True, "query": query, **extra},+ format="json",+ )++ assert resp.status_code == status.HTTP_400_BAD_REQUEST, resp.json()+ assert named in str(resp.json())+ mock_generate.assert_not_called()++ @parameterized.expand(+ [+ ("action", {"actions": [{"id": 999999, "type": "actions"}]}),+ ("cohort", {"properties": [{"type": "cohort", "key": "id", "value": 999999, "operator": "in"}]}),+ ]+ )+ @patch(_GENERATE_PATH)+ def test_a_chosen_query_naming_entities_the_token_cannot_read_is_refused(self, kind, filters, mock_generate):+ # Refused before anything resolves, so a token without the scope learns nothing about which ids exist.+ key = self._personal_api_key(["replay_scanner:write", "session_recording:read"])++ resp = self.client.post(+ self.draft_url,+ data={"goal": "find rage clicks", "free_only": True, "query": {"kind": "RecordingsQuery", **filters}},+ format="json",+ HTTP_AUTHORIZATION=f"Bearer {key}",+ )++ assert resp.status_code == status.HTTP_400_BAD_REQUEST, resp.json()+ assert f"uses {kind}s" in str(resp.json())+ assert "999999" not in str(resp.json())+ mock_generate.assert_not_called()++ @patch(_GENERATE_PATH)+ def test_a_chosen_query_scoped_to_an_experiment_keeps_its_variant(self, mock_generate):+ experiment = _launched_experiment(self.team, self.user, "Billing upgrade prompt")+ mock_generate.return_value = _draft(+ filter_experiment="Billing upgrade prompt", filter_experiment_variant="test"+ )++ resp = self.client.post(+ self.draft_url,+ data={+ "goal": "find rage clicks",+ "free_only": True,+ "query": {+ "kind": "RecordingsQuery",+ "experiment_exposure": {"experiment_id": experiment.id, "variant": "control"},+ },+ },+ format="json",+ )++ assert resp.status_code == status.HTTP_200_OK, resp.json()+ assert resp.json()["scanner_type"] == "experiment"+ assert resp.json()["scanner_config"]["experiment_id"] == experiment.id+ assert resp.json()["scanner_config"]["variants"] == ["control"]+ assert "experiment_exposure" not in resp.json()["query"]++ # An empty name must be checked as a variant, or the scanner would widen to every variant.+ @parameterized.expand([("unknown name", "holdout"), ("empty name", "")])+ @patch(_GENERATE_PATH)+ def test_a_chosen_variant_the_experiment_lacks_is_refused(self, _name, variant, mock_generate):+ experiment = _launched_experiment(self.team, self.user, "Billing upgrade prompt")+ mock_generate.return_value = _draft(filter_experiment="Billing upgrade prompt")++ resp = self.client.post(+ self.draft_url,+ data={+ "goal": "find rage clicks",+ "free_only": True,+ "query": {+ "kind": "RecordingsQuery",+ "experiment_exposure": {"experiment_id": experiment.id, "variant": variant},+ },+ },+ format="json",+ )++ assert resp.status_code == status.HTTP_400_BAD_REQUEST, resp.json()+ assert resp.json()["detail"] == f"The experiment has no variant named {variant!r}."+@parameterized.expand([("free name kept", [], "User intent"),@@ -1632,7 +1796,9 @@ class TestDraftScannerFromGoal(_VisionAPITestCase):return estimate- def _drafted_with(self, generate, estimate, experiment_id=None):+ def _drafted_with(+ self, generate, estimate, experiment_id=None, chosen_query=None, experiment_variants=None, has_match=None+ ):with (patch(f"{_MODULE}.fetch_visited_paths", return_value=(VisitedPath(pathname="/billing", sessions=10),)),# Measure every candidate live, so these tests exercise the estimate-based fallback rather@@ -1643,6 +1809,7 @@ class TestDraftScannerFromGoal(_VisionAPITestCase):),patch(_GENERATE_PATH, return_value=generate),patch(f"{_MODULE}.estimate_scanner_session_volume", side_effect=estimate),+ patch(f"{_MODULE}.has_recent_matching_recording", side_effect=has_match or (lambda **kwargs: True)),):return draft_scanner_from_goal(team=self.team,@@ -1651,6 +1818,8 @@ class TestDraftScannerFromGoal(_VisionAPITestCase):monthly_credit_budget=10_000,user_access_control=_access_control(allow=True),experiment_id=experiment_id,+ experiment_variants=experiment_variants,+ chosen_query=chosen_query,)def test_an_event_filter_that_matches_nothing_falls_back_to_the_pages(self):@@ -1705,6 +1874,73 @@ class TestDraftScannerFromGoal(_VisionAPITestCase):assert [e["id"] for e in draft.query["events"]] == ["billing_limit_set"]assert draft.estimated_monthly_observations == 0+ _CHOSEN = {+ "kind": "RecordingsQuery",+ "properties": [{"type": "recording", "key": "visited_page", "value": "/billing", "operator": "icontains"}],+ }++ @parameterized.expand(+ [+ ("adds a narrowing filter", _CHOSEN, ["billing_limit_set"], True, True, None),+ ("drops additions that match nothing", _CHOSEN, ["billing_limit_set"], False, False, "matched_nothing"),+ ("drops additions it could not check", _CHOSEN, ["billing_limit_set"], None, False, "unverified"),+ (+ "drops additions to an OR filter",+ {**_CHOSEN, "operand": "OR"},+ ["billing_limit_set"],+ True,+ False,+ "or_operand",+ ),+ # The query builder reads a null operand as OR too.+ (+ "drops additions to a null-operand filter",+ {**_CHOSEN, "operand": None},+ ["billing_limit_set"],+ True,+ False,+ "or_operand",+ ),+ ("keeps a chosen filter with nothing proposed", _CHOSEN, [], True, False, None),+ ]+ )+ def test_a_chosen_query_is_the_starting_point(self, _name, chosen, drafted_events, matched, extended, refusal):+ EventDefinition.objects.create(team=self.team, name="billing_limit_set", last_seen_at=timezone.now())+ checked: list[str] = []+ estimated: list[RecordingsQuery] = []++ def has_match(*, team, user, query, sampling_mode):+ checked.append(sampling_mode)+ if matched is None:+ raise RuntimeError("clickhouse timeout")+ return matched++ def estimate(*, team, query, user, sampling_mode, budget):+ estimated.append(query)+ return ScannerVolumeEstimate(matched_sessions=300, effective_window_days=30)++ draft = self._drafted_with(+ _draft(filter_events=drafted_events, rationale="Watches billing sessions.", sampling_mode="focused"),+ estimate,+ chosen_query=chosen,+ has_match=has_match,+ )++ assert draft.narrowing_refusal == refusal+ if extended:+ assert draft.query is not None+ assert draft.query["properties"] == chosen["properties"]+ assert [e["id"] for e in draft.query["events"]] == ["billing_limit_set"]+ assert draft.query_additions is not None+ assert [e["id"] for e in draft.query_additions["events"]] == ["billing_limit_set"]+ else:+ assert draft.query == chosen+ assert draft.query_additions is None+ assert draft.rationale.endswith("This watches the recordings you picked.") == (refusal is not None)+ assert checked == (["focused"] if drafted_events and refusal != "or_operand" else [])+ assert len(estimated) == 1+ assert bool(estimated[0].events) == extended+def test_a_measured_dead_event_is_dropped_before_it_can_zero_the_scan(self):# billing_limit_set is a real definition, so grounding's definition-lookup fallback would# re-admit it even after it leaves the briefing. Measured at zero sessions it is dead, and one@@ -1857,11 +2093,14 @@ class TestDraftScannerFromGoal(_VisionAPITestCase):@parameterized.expand([- ("named_in_the_goal", {"filter_experiment": "Billing upgrade prompt"}, False),- ("picked_by_the_user", {}, True),+ ("named_in_the_goal", {"filter_experiment": "Billing upgrade prompt"}, False, None, ["test"]),+ ("picked_by_the_user", {}, True, None, ["test"]),+ ("scoped_by_the_chosen_filter", {}, True, ["control"], ["control"]),])- def test_the_watched_experiment_becomes_an_experiment_scanner_and_is_counted(self, _name, overrides, picked):+ def test_the_watched_experiment_becomes_an_experiment_scanner_and_is_counted(+ self, _name, overrides, picked, chosen_variants, expected_variants+ ):# The projection has to count that experiment's participants, not every session the pages# match, while the query the wizard saves stays the exposure-free blob the API accepts.experiment = _launched_experiment(self.team, self.user, "Billing upgrade prompt")@@ -1875,15 +2114,17 @@ class TestDraftScannerFromGoal(_VisionAPITestCase):_draft(filter_pages=["/billing"], filter_experiment_variant="test", **overrides),estimate,experiment_id=experiment.id if picked else None,+ experiment_variants=chosen_variants,+ chosen_query={"kind": "RecordingsQuery"} if chosen_variants else None,)assert draft.scanner_type == "experiment"assert draft.scanner_config["experiment_id"] == experiment.id- assert draft.scanner_config["variants"] == ["test"]+ assert draft.scanner_config["variants"] == expected_variantsassert draft.query is not None and "experiment_exposure" not in draft.queryassert counted[0].experiment_exposure is not Noneassert counted[0].experiment_exposure.experiment_id == experiment.id- assert counted[0].experiment_exposure.variants == ["test"]+ assert counted[0].experiment_exposure.variants == expected_variantsdef test_a_picked_experiment_that_never_launched_is_refused_before_the_model_runs(self):experiment = _launched_experiment(self.team, self.user, "Billing upgrade prompt", launched=False)diff --git a/products/replay_vision/backend/tests/test_scanner_query.py b/products/replay_vision/backend/tests/test_scanner_query.pynew file mode 100644index 000000000000..b64091cb8614--- /dev/null+++ b/products/replay_vision/backend/tests/test_scanner_query.py@@ -0,0 +1,158 @@+from typing import Any++from posthog.test.base import BaseTest++from parameterized import parameterized++from products.actions.backend.models.action import Action+from products.cohorts.backend.models.cohort import Cohort+from products.replay_vision.backend.scanner_query import (+ MAX_QUERY_BYTES,+ NarrowingRefusal,+ QueryReferences,+ ScannerQueryError,+ chosen_scope,+ narrow_chosen_query,+ query_references,+ unresolved_references,+)++_CHOSEN: dict[str, Any] = {+ "kind": "RecordingsQuery",+ "properties": [{"type": "recording", "key": "visited_page", "value": "/billing", "operator": "icontains"}],+}+_EVENT = {"id": "billing_limit_set", "name": "billing_limit_set", "type": "events", "order": 0}+++class TestNarrowChosenQuery:+ @parameterized.expand(+ [+ (+ "chosen OR",+ {**_CHOSEN, "operand": "OR"},+ {"kind": "RecordingsQuery", "events": [_EVENT]},+ NarrowingRefusal.OR_OPERAND,+ ),+ (+ "chosen null operand",+ {**_CHOSEN, "operand": None},+ {"kind": "RecordingsQuery", "events": [_EVENT]},+ NarrowingRefusal.OR_OPERAND,+ ),+ (+ "drafted OR",+ _CHOSEN,+ {"kind": "RecordingsQuery", "events": [_EVENT, {**_EVENT, "id": "plan_upgraded"}], "operand": "OR"},+ NarrowingRefusal.OR_OPERAND,+ ),+ (+ "too large to save",+ _CHOSEN,+ {+ "kind": "RecordingsQuery",+ "events": [{**_EVENT, "id": f"event_{i}_{'x' * 500}"} for i in range(MAX_QUERY_BYTES // 500)],+ },+ NarrowingRefusal.INVALID,+ ),+ ("repeat only", _CHOSEN, {"kind": "RecordingsQuery", "properties": _CHOSEN["properties"]}, None),+ ("nothing drafted", _CHOSEN, None, None),+ ]+ )+ def test_keeps_the_chosen_query_when_it_cannot_be_narrowed(self, _name, chosen, proposed, refusal):+ narrowing = narrow_chosen_query(chosen, proposed)++ assert (narrowing.query, narrowing.additions, narrowing.refusal) == (chosen, None, refusal)++ def test_ands_new_conditions_and_reports_only_those(self):+ proposed = {"kind": "RecordingsQuery", "properties": _CHOSEN["properties"], "events": [_EVENT]}++ narrowing = narrow_chosen_query(_CHOSEN, proposed)++ assert narrowing.query == {**_CHOSEN, "events": [_EVENT]}+ assert narrowing.additions == {"kind": "RecordingsQuery", "events": [_EVENT]}+ assert narrowing.refusal is None+++class TestChosenScope:+ @parameterized.expand(+ [+ ("every variant", {}, None),+ ("an empty variant name", {"variant": ""}, [""]),+ ("repeated variants", {"variants": ["test", "control", "test"]}, ["test", "control"]),+ ]+ )+ def test_reads_the_exposure_variants_the_way_the_replay_list_does(self, _name, variant_fields, expected):+ exposure = {"experiment_id": 1, **variant_fields}++ scope = chosen_scope({"kind": "RecordingsQuery", "experiment_exposure": exposure}, experiment_id=None)++ assert scope.experiment_variants == expected+++class TestUnresolvedReferences(BaseTest):+ def test_names_the_references_a_scan_cannot_load(self):+ live_action = Action.objects.create(team=self.team, name="Completed checkout")+ live_cohort = Cohort.objects.create(team=self.team, name="Paying customers")+ deleted_cohort = Cohort.objects.create(team=self.team, name="Old customers", deleted=True)+ query = {+ "kind": "RecordingsQuery",+ "actions": [{"id": live_action.id, "type": "actions"}, {"id": 999999, "type": "actions"}],+ "properties": [+ {"type": "cohort", "key": "id", "value": live_cohort.id, "operator": "in"},+ {"type": "cohort", "key": "id", "value": deleted_cohort.id, "operator": "in"},+ ],+ }++ assert unresolved_references(query, self.team) == ["action 999999", f"cohort {deleted_cohort.id}"]++ def test_finds_references_in_every_shape_the_query_builder_runs(self):+ # Each runs as an action or cohort filter, so a check that missed one would skip read access.+ query = {+ "kind": "RecordingsQuery",+ "events": [+ {"id": 901, "type": "actions"},+ {+ "id": "$pageview",+ "type": "events",+ "properties": {"type": "AND", "values": [{"type": "cohort", "key": "id", "value": 902}]},+ },+ ],+ "properties": [+ {"value": 903},+ {"type": "hogql", "key": "matchesAction(904) AND person_id NOT IN COHORT 905"},+ ],+ }++ assert query_references(query, self.team) == QueryReferences(actions=[901, 904], cohorts=[902, 903, 905])++ @parameterized.expand(+ [+ ("a non-numeric action id", {"actions": [{"id": float("inf")}]}, "invalid"),+ # Resolving a name here would tell the caller which id it has before any access check.+ (+ "an action named in HogQL",+ {"properties": [{"type": "hogql", "key": "matchesAction('Signed up')"}]},+ "numeric id",+ ),+ (+ "a cohort named in HogQL",+ {"properties": [{"type": "hogql", "key": "person_id IN COHORT 'Paying'"}]},+ "numeric id",+ ),+ # A subquery can select from the cohort tables directly, where no reference is visible.+ (+ "a HogQL subquery",+ {"properties": [{"type": "hogql", "key": "person_id IN (SELECT person_id FROM cohort_people)"}]},+ "subquery",+ ),+ (+ "a HogQLX tag",+ {"properties": [{"type": "hogql", "key": "properties.$session_id IN <ActorsQuery />"}]},+ "HogQLX tag",+ ),+ ("an empty HogQL expression", {"properties": [{"type": "hogql", "key": ""}]}, "doesn't parse"),+ ]+ )+ def test_refuses_references_it_cannot_read(self, _name, filters, reason):+ with self.assertRaisesRegex(ScannerQueryError, reason):+ query_references({"kind": "RecordingsQuery", **filters}, self.team)diff --git a/products/replay_vision/frontend/generated/api.schemas.ts b/products/replay_vision/frontend/generated/api.schemas.tsindex fdc84efffe18..577ee575c085 100644--- a/products/replay_vision/frontend/generated/api.schemas.ts+++ b/products/replay_vision/frontend/generated/api.schemas.ts@@ -2709,6 +2709,8 @@ export interface DraftScannerRequestApi {* @maximum 2147483647*/experiment_id?: number+ /** A `RecordingsQuery` the person already chose, as the replay list holds it. The draft starts from it and never removes or widens it. When the goal asks for narrower recordings, the draft can AND its own page, event, action or cohort filters onto it. It keeps them only when the combined filter still matches recent recordings, returns them in `query_additions`, and sizes the sampling dials against the combined `query`. `experiment_exposure` becomes the scanner's experiment and variants, which the draft keeps as they are. `date_from`/`date_to` are dropped, because a scanner's schedule owns time. `comment_text`, `hide_viewed_recordings` and in-session exposure are refused, because a scanner cannot apply them. A query with no filters starts from every new recording. Omit to let the draft pick the sessions. */+ query?: unknown}/**@@ -2733,6 +2735,8 @@ export interface DraftScannerResponseApi {rationale: string/** `RecordingsQuery` narrowing which sessions get scanned; null when the draft targets every session. */query: unknown+ /** When the request passed a `query`: the filters the draft ANDed onto it, which `query` already includes. Show them to the person as added by AI. Null when nothing was added or no `query` was passed. */+ query_additions: unknown/** The quality pre-filter the draft chose for the goal. Null when the costing estimate failed, in which case the wizard keeps its defaults.** * `focused` - Focuseddiff --git a/products/replay_vision/frontend/generated/api.zod.ts b/products/replay_vision/frontend/generated/api.zod.tsindex 66150f6cc273..44c724181a75 100644--- a/products/replay_vision/frontend/generated/api.zod.ts+++ b/products/replay_vision/frontend/generated/api.zod.ts@@ -1379,6 +1379,12 @@ export const VisionScannersDraftCreateBody = /* @__PURE__ */ zod.describe('A launched experiment the person picked for the scanner to watch. The draft is then an `experiment` scanner on it.'),+ query: zod+ .unknown()+ .optional()+ .describe(+ "A `RecordingsQuery` the person already chose, as the replay list holds it. The draft starts from it and never removes or widens it. When the goal asks for narrower recordings, the draft can AND its own page, event, action or cohort filters onto it. It keeps them only when the combined filter still matches recent recordings, returns them in `query_additions`, and sizes the sampling dials against the combined `query`. `experiment_exposure` becomes the scanner's experiment and variants, which the draft keeps as they are. `date_from`\/`date_to` are dropped, because a scanner's schedule owns time. `comment_text`, `hide_viewed_recordings` and in-session exposure are refused, because a scanner cannot apply them. A query with no filters starts from every new recording. Omit to let the draft pick the sessions."+ ),}).describe("Body of POST \/vision\/scanners\/draft\/ — the user's goal, stated in their own words.")diff --git a/products/replay_vision/frontend/replay_scanners/ReplayScannersScene.stories.tsx b/products/replay_vision/frontend/replay_scanners/ReplayScannersScene.stories.tsxindex 9357192a69d1..d59c8d6e18ae 100644--- a/products/replay_vision/frontend/replay_scanners/ReplayScannersScene.stories.tsx+++ b/products/replay_vision/frontend/replay_scanners/ReplayScannersScene.stories.tsx@@ -2012,6 +2012,7 @@ const goalDraft: DraftScannerResponseApi = {},],},+ query_additions: null,sampling_mode: 'comprehensive',sampling_rate: 0.25,model: 'gemini-3-flash-preview',diff --git a/products/replay_vision/mcp/tools.yaml b/products/replay_vision/mcp/tools.yamlindex 32be8a207ca9..4ff5a73368c3 100644--- a/products/replay_vision/mcp/tools.yaml+++ b/products/replay_vision/mcp/tools.yaml@@ -628,8 +628,10 @@ tools:addressed to the person, the chosen `model`, and the `free_only` and `credit_limit` to save. `sampling_mode`and `sampling_rate` are solved to fit the budget, and come back null only when the cost estimate failed. Adraft that watches an experiment comes back as an `experiment` scanner; pass `experiment_id` to draft one on- a launched experiment the person picked. Review the draft with the person, then pass it to- `vision-scanners-create`. The call is an inline LLM request and can take a while.+ a launched experiment the person picked. Pass `query` when the person already chose which recordings to+ watch: the draft starts from that filter and can only narrow it, and returns what it added in+ `query_additions`. Review the draft with the person, then pass it to `vision-scanners-create`. The call is+ an inline LLM request and can take a while.requires_ai_consent: truevision-scanners-duplicate:operation: vision_scanners_duplicate_creatediff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.jsonindex 35b0456d12f1..1771a935bc71 100644--- a/services/mcp/schema/generated-tool-definitions.json+++ b/services/mcp/schema/generated-tool-definitions.json@@ -15718,7 +15718,7 @@}},"vision-scanners-draft": {- "description": "Draft a full scanner configuration from a natural-language `goal` (e.g. \"find where users get stuck during onboarding\"). First ask the person how much it should use, and offer both choices: free, which sets `free_only: true` so the scanner runs only on the organization's free monthly credits, never adds to the bill and pauses when they run out; or a set `monthly_credit_budget` in credits a month (1 credit = $0.01), which becomes the scanner's `credit_limit`. Pass exactly one of the two, and never guess a budget. Check `vision-quota-get` first and skip the free choice when `credits_used` has reached `free_monthly_credits`. Nothing is saved. Returns `name`, `description`, `scanner_type`, `scanner_config`, `query`, a `rationale` addressed to the person, the chosen `model`, and the `free_only` and `credit_limit` to save. `sampling_mode` and `sampling_rate` are solved to fit the budget, and come back null only when the cost estimate failed. A draft that watches an experiment comes back as an `experiment` scanner; pass `experiment_id` to draft one on a launched experiment the person picked. Review the draft with the person, then pass it to `vision-scanners-create`. The call is an inline LLM request and can take a while.",+ "description": "Draft a full scanner configuration from a natural-language `goal` (e.g. \"find where users get stuck during onboarding\"). First ask the person how much it should use, and offer both choices: free, which sets `free_only: true` so the scanner runs only on the organization's free monthly credits, never adds to the bill and pauses when they run out; or a set `monthly_credit_budget` in credits a month (1 credit = $0.01), which becomes the scanner's `credit_limit`. Pass exactly one of the two, and never guess a budget. Check `vision-quota-get` first and skip the free choice when `credits_used` has reached `free_monthly_credits`. Nothing is saved. Returns `name`, `description`, `scanner_type`, `scanner_config`, `query`, a `rationale` addressed to the person, the chosen `model`, and the `free_only` and `credit_limit` to save. `sampling_mode` and `sampling_rate` are solved to fit the budget, and come back null only when the cost estimate failed. A draft that watches an experiment comes back as an `experiment` scanner; pass `experiment_id` to draft one on a launched experiment the person picked. Pass `query` when the person already chose which recordings to watch: the draft starts from that filter and can only narrow it, and returns what it added in `query_additions`. Review the draft with the person, then pass it to `vision-scanners-create`. The call is an inline LLM request and can take a while.","category": "Replay vision","feature": "replay_vision","summary": "Draft scanner from goal",diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.jsonindex 17b4ca74e7af..59b264156216 100644--- a/services/mcp/schema/tool-definitions-all.json+++ b/services/mcp/schema/tool-definitions-all.json@@ -16494,7 +16494,7 @@}},"vision-scanners-draft": {- "description": "Draft a full scanner configuration from a natural-language `goal` (e.g. \"find where users get stuck during onboarding\"). First ask the person how much it should use, and offer both choices: free, which sets `free_only: true` so the scanner runs only on the organization's free monthly credits, never adds to the bill and pauses when they run out; or a set `monthly_credit_budget` in credits a month (1 credit = $0.01), which becomes the scanner's `credit_limit`. Pass exactly one of the two, and never guess a budget. Check `vision-quota-get` first and skip the free choice when `credits_used` has reached `free_monthly_credits`. Nothing is saved. Returns `name`, `description`, `scanner_type`, `scanner_config`, `query`, a `rationale` addressed to the person, the chosen `model`, and the `free_only` and `credit_limit` to save. `sampling_mode` and `sampling_rate` are solved to fit the budget, and come back null only when the cost estimate failed. A draft that watches an experiment comes back as an `experiment` scanner; pass `experiment_id` to draft one on a launched experiment the person picked. Review the draft with the person, then pass it to `vision-scanners-create`. The call is an inline LLM request and can take a while.",+ "description": "Draft a full scanner configuration from a natural-language `goal` (e.g. \"find where users get stuck during onboarding\"). First ask the person how much it should use, and offer both choices: free, which sets `free_only: true` so the scanner runs only on the organization's free monthly credits, never adds to the bill and pauses when they run out; or a set `monthly_credit_budget` in credits a month (1 credit = $0.01), which becomes the scanner's `credit_limit`. Pass exactly one of the two, and never guess a budget. Check `vision-quota-get` first and skip the free choice when `credits_used` has reached `free_monthly_credits`. Nothing is saved. Returns `name`, `description`, `scanner_type`, `scanner_config`, `query`, a `rationale` addressed to the person, the chosen `model`, and the `free_only` and `credit_limit` to save. `sampling_mode` and `sampling_rate` are solved to fit the budget, and come back null only when the cost estimate failed. A draft that watches an experiment comes back as an `experiment` scanner; pass `experiment_id` to draft one on a launched experiment the person picked. Pass `query` when the person already chose which recordings to watch: the draft starts from that filter and can only narrow it, and returns what it added in `query_additions`. Review the draft with the person, then pass it to `vision-scanners-create`. The call is an inline LLM request and can take a while.","category": "Replay vision","feature": "replay_vision","summary": "Draft scanner from goal",diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex c09a61db6a6f..2901ef310e6a 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -40591,6 +40591,8 @@ export namespace Schemas {* @maximum 2147483647*/experiment_id?: number;+ /** A `RecordingsQuery` the person already chose, as the replay list holds it. The draft starts from it and never removes or widens it. When the goal asks for narrower recordings, the draft can AND its own page, event, action or cohort filters onto it. It keeps them only when the combined filter still matches recent recordings, returns them in `query_additions`, and sizes the sampling dials against the combined `query`. `experiment_exposure` becomes the scanner's experiment and variants, which the draft keeps as they are. `date_from`/`date_to` are dropped, because a scanner's schedule owns time. `comment_text`, `hide_viewed_recordings` and in-session exposure are refused, because a scanner cannot apply them. A query with no filters starts from every new recording. Omit to let the draft pick the sessions. */+ query?: unknown;}/**@@ -40629,6 +40631,8 @@ export namespace Schemas {rationale: string;/** `RecordingsQuery` narrowing which sessions get scanned; null when the draft targets every session. */query: unknown;+ /** When the request passed a `query`: the filters the draft ANDed onto it, which `query` already includes. Show them to the person as added by AI. Null when nothing was added or no `query` was passed. */+ query_additions: unknown;/** The quality pre-filter the draft chose for the goal. Null when the costing estimate failed, in which case the wizard keeps its defaults.** * `focused` - Focuseddiff --git a/services/mcp/src/generated/replay_vision/api.ts b/services/mcp/src/generated/replay_vision/api.tsindex dd589074e67a..191ad38cdc07 100644--- a/services/mcp/src/generated/replay_vision/api.ts+++ b/services/mcp/src/generated/replay_vision/api.ts@@ -2157,6 +2157,12 @@ export const VisionScannersDraftCreateBody = () => zod.describe('A launched experiment the person picked for the scanner to watch. The draft is then an `experiment` scanner on it.'),+ query: zod+ .unknown()+ .optional()+ .describe(+ "A `RecordingsQuery` the person already chose, as the replay list holds it. The draft starts from it and never removes or widens it. When the goal asks for narrower recordings, the draft can AND its own page, event, action or cohort filters onto it. It keeps them only when the combined filter still matches recent recordings, returns them in `query_additions`, and sizes the sampling dials against the combined `query`. `experiment_exposure` becomes the scanner's experiment and variants, which the draft keeps as they are. `date_from`\/`date_to` are dropped, because a scanner's schedule owns time. `comment_text`, `hide_viewed_recordings` and in-session exposure are refused, because a scanner cannot apply them. A query with no filters starts from every new recording. Omit to let the draft pick the sessions."+ ),}).describe("Body of POST \/vision\/scanners\/draft\/ — the user's goal, stated in their own words.")diff --git a/services/mcp/src/tools/generated/replay_vision.ts b/services/mcp/src/tools/generated/replay_vision.tsindex 062a28542da7..e5e148d72377 100644--- a/services/mcp/src/tools/generated/replay_vision.ts+++ b/services/mcp/src/tools/generated/replay_vision.ts@@ -1031,6 +1031,9 @@ const visionScannersDraft = (): ToolBase<if (params.experiment_id !== undefined) {body['experiment_id'] = params.experiment_id}+ if (params.query !== undefined) {+ body['query'] = params.query+ }const result = await context.api.request<Schemas.DraftScannerResponse>({method: 'POST',path: `/api/projects/${encodeURIComponent(String(projectId))}/vision/scanners/draft/`,diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-draft.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-draft.jsonindex d6a1216adbb7..83bdbe7a00a1 100644--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-draft.json+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/vision-scanners-draft.json@@ -23,6 +23,9 @@"maximum": 100000000,"minimum": 1,"type": "number"+ },+ "query": {+ "description": "A `RecordingsQuery` the person already chose, as the replay list holds it. The draft starts from it and never removes or widens it. When the goal asks for narrower recordings, the draft can AND its own page, event, action or cohort filters onto it. It keeps them only when the combined filter still matches recent recordings, returns them in `query_additions`, and sizes the sampling dials against the combined `query`. `experiment_exposure` becomes the scanner's experiment and variants, which the draft keeps as they are. `date_from`/`date_to` are dropped, because a scanner's schedule owns time. `comment_text`, `hide_viewed_recordings` and in-session exposure are refused, because a scanner cannot apply them. A query with no filters starts from every new recording. Omit to let the draft pick the sessions."}},"required": ["goal"],