Skip to content

: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.

fix(signals): serve the stored personal ranking by default (#129374)

posthog[bot]508a241d4eba
diff --git a/products/signals/backend/personal_ranking/candidates.py b/products/signals/backend/personal_ranking/candidates.py
index 3798c006a5ed..64f047ce2d7b 100644
--- a/products/signals/backend/personal_ranking/candidates.py
+++ b/products/signals/backend/personal_ranking/candidates.py
@@ -183,13 +183,17 @@ def _pool_ids(
)
-def _pools(
- team: Team, user: User, config: PersonalRankingConfig, *, now: datetime.datetime
-) -> list[tuple[str, list[str]]]:
+def _open_team_reports(team: Team) -> QuerySet[SignalReport]:
# The gate-aware filter, because a `monitoring` report reads as resolved while the monitoring gate is off.
- team_reports = SignalReport.objects.filter(team_id=team.id).exclude(
+ return SignalReport.objects.filter(team_id=team.id).exclude(
report_status_filter(EXCLUDED_STATUSES, team_id=team.id)
)
+
+
+def _pools(
+ team: Team, user: User, config: PersonalRankingConfig, *, now: datetime.datetime
+) -> list[tuple[str, list[str]]]:
+ team_reports = _open_team_reports(team)
return [
(pool.name, _pool_ids(team, user, pool, config, team_reports=team_reports, now=now))
for pool in candidate_pools(config)
@@ -248,12 +252,22 @@ def gather_candidates(
def stored_candidates(team: Team, user: User, report_ids: Sequence[str]) -> list[Candidate]:
"""The current facts of the reports a stored list considered, with no pool query and no source read.
- A report that no longer exists drops out, and no new report joins. `pools` is empty, because only a build reads it.
+ A plain read serves this list without a pool query, so it applies the pool rules here. A report that closed or
+ stopped being this person's drops out, and no new report joins. `pools` is empty, because only a build reads it.
"""
+ ids = list(report_ids)
+ for_person = reports_for_person(team.id, user).filter(id__in=ids).values_list("id", flat=True)
+ claimed = (
+ _open_team_reports(team)
+ .filter(id__in=ids)
+ .filter(reports_claimed_for_user(team_id=team.id, user_id=user.id))
+ .values_list("id", flat=True)
+ )
+ still_theirs = {str(report_id) for report_id in (*for_person, *claimed)}
return _load_candidates(
team,
user,
- {report_id: [] for report_id in report_ids},
+ {report_id: [] for report_id in ids if report_id in still_theirs},
can_view_ranking=can_view_inbox_ranking(user, team),
with_sources=False,
)
diff --git a/products/signals/backend/personal_ranking/logic.py b/products/signals/backend/personal_ranking/logic.py
index 23105ce9776c..8deeb37c5e51 100644
--- a/products/signals/backend/personal_ranking/logic.py
+++ b/products/signals/backend/personal_ranking/logic.py
@@ -324,6 +324,41 @@ def latest_row(team: Team, user: User) -> PersonalInboxRanking | None:
return PersonalInboxRanking.objects.for_team(team.id).filter(user_id=user.id).order_by("-created_at", "-id").first()
+def ready_summary_version(team: Team, user: User) -> int | None:
+ summary = get_summary(team, user.id)
+ return summary.version if summary is not None and summary.status == ActivitySummaryStatus.READY else None
+
+
+def record_check(team: Team, row: PersonalInboxRanking, now: datetime.datetime) -> None:
+ """Record that the list still matches the current inputs, so it counts as fresh again."""
+ PersonalInboxRanking.objects.for_team(team.id).filter(id=row.id).update(checked_at=now)
+
+
+@frozen
+class InputCheck:
+ unchanged: bool
+ calls_model: bool
+
+
+def check_inputs(team: Team, user: User, config: PersonalRankingConfig, *, now: datetime.datetime) -> InputCheck:
+ """Compare the latest list with the current inputs. A list that still matches counts as fresh again."""
+ latest = latest_row(team, user)
+ candidates = gather_candidates(team, user, config, now=now, with_sources=False)
+ summary_version = ready_summary_version(team, user)
+ current_hash = input_hash(candidates, activity_summary_version=summary_version, focus=None)
+ if (
+ latest is not None
+ and latest.input_hash == current_hash
+ and latest.fallback_reason not in RETRYABLE_FALLBACK_REASONS
+ ):
+ record_check(team, latest, now)
+ return InputCheck(unchanged=True, calls_model=False)
+ return InputCheck(
+ unchanged=False,
+ calls_model=bool(candidates) and may_call_model(team, summary_ready=summary_version is not None),
+ )
+
+
def _client(
team: Team, user: User, now: datetime.datetime, config: PersonalRankingConfig, trigger: BuildTrigger
) -> OpenAI:
diff --git a/products/signals/backend/personal_ranking/serve.py b/products/signals/backend/personal_ranking/serve.py
index 76ea0557dc56..eb3633ec1cae 100644
--- a/products/signals/backend/personal_ranking/serve.py
+++ b/products/signals/backend/personal_ranking/serve.py
@@ -1,17 +1,21 @@
"""Serve one person's ranked inbox list to the `for_me` endpoint. A request never waits on the model.
-A stored list is reused while it was built or checked by the tick less than `freshness_minutes` ago and its input
-hash matches the current inputs. Otherwise, and for every `refresh` or `focus` request, the read queues one
-background build per person and serves the latest stored list as stale, or the candidates in inbox order when
-there is none. The focus is part of the hash, so an unfocused request never reuses a focused list. A build that
-stores a list for the current inputs while the read runs answers the read, also a `refresh` read, so the read
-queues no second build. A lock lets one build per person run at a time, and each queued build spends two
+By default the read serves the latest stored list. It reads only the reports that list considered, with a fixed
+number of queries, and never reads the candidate pools. `stale` is true when one of those reports changed since
+the build. When the list was built or checked longer ago than `freshness_minutes`, the read also queues one
+background build that compares the input hash first: a match records `checked_at` and calls no model, as the tick
+does. So a new report joins at the next tick or at that build.
+
+`max_age_minutes` makes the read stricter. When the list was built or checked longer ago than that, the read
+reads every candidate and compares the input hash. A match records `checked_at` and serves the list. A difference
+queues a build and serves the list as stale. A `refresh` or `focus` request, and the first read of a person with
+no stored list, also read every candidate and queue a build. The read serves the candidates in inbox order when
+there is no stored list. The focus is part of the hash, so an unfocused request never reuses a focused list. A
+build that stores a list for the current inputs while the read runs answers the read, also a `refresh` read, so
+the read queues no second build. A lock lets one build per person run at a time, and each queued build spends two
per-person token buckets. A build that may call the model also spends the shared daily limit of the region
-(`build_budget.py`). `wait_seconds` waits a bounded time for the queued build to store its list, counted from the
-start of the request.
-
-While the stored list is young enough, the read checks only the reports that list considered, with a fixed number
-of queries, and skips the candidate pool queries. A new report joins at the next build after the list ages out.
+(`build_budget.py`). `wait_seconds` waits a bounded time for a queued or running build to store or check its
+list, counted from the start of the request.
"""
import time
@@ -31,17 +35,19 @@ from posthog.exceptions_capture import capture_exception
from posthog.models import Team, User
from posthog.token_bucket import BucketDecision, BucketUnavailable, Budget, consume, refund
-from products.signals.backend.activity_summary.read import ActivitySummaryStatus, get_summary
from products.signals.backend.models import PersonalInboxRanking
from products.signals.backend.personal_ranking.build_budget import DAILY_BUILD_COST, spend_shared_build
from products.signals.backend.personal_ranking.candidates import Candidate, gather_candidates, stored_candidates
from products.signals.backend.personal_ranking.config import PersonalRankingConfig, read_config
from products.signals.backend.personal_ranking.logic import (
+ RETRYABLE_FALLBACK_REASONS,
input_hash,
latest_row,
may_call_model,
model_order_reason,
normalize_focus,
+ ready_summary_version,
+ record_check,
)
from products.signals.backend.personal_ranking.validation import model_order
from products.signals.backend.personal_ranking_tasks import (
@@ -121,6 +127,8 @@ class ServedRanking:
building: bool
fallback_reason: str | None
generated_at: datetime.datetime | None
+ # When a build or a hash check last confirmed the list against the full candidates.
+ checked_at: datetime.datetime | None
latency_ms: int | None
activity_summary_version: int | None
candidates_considered: int
@@ -138,6 +146,7 @@ UNAVAILABLE = ServedRanking(
building=False,
fallback_reason=None,
generated_at=None,
+ checked_at=None,
latency_ms=None,
activity_summary_version=None,
candidates_considered=0,
@@ -187,11 +196,12 @@ def _start_build(
*,
calls_model: bool,
seen: PersonalInboxRanking | None,
- current_hash: str,
+ current_hash: str | None,
+ check_first: bool = False,
) -> BuildStart | PersonalInboxRanking:
"""Queue one background build, unless one is already running for the person or the buckets refuse it.
- Returns a row instead when an unfocused request finds a row for the current inputs stored after `seen`.
+ Returns a row instead when an unfocused request finds a row stored after `seen`, for `current_hash` when set.
"""
lock_key = build_lock_key(team.id, user.id)
locked = False
@@ -206,7 +216,7 @@ def _start_build(
if _spend_build(team.id, user.id, config, calls_model=calls_model) is not None:
cache.delete(lock_key)
return "rate_limited"
- build_personal_inbox_ranking.delay(team.id, user.id, focus, limit)
+ build_personal_inbox_ranking.delay(team.id, user.id, focus, limit, check_first)
return "started"
except Exception as error:
# A broker or cache failure must not fail the read, which still has a list to serve.
@@ -218,10 +228,12 @@ def _start_build(
def _row_stored_since(
- team: Team, user: User, seen: PersonalInboxRanking | None, current_hash: str
+ team: Team, user: User, seen: PersonalInboxRanking | None, current_hash: str | None
) -> PersonalInboxRanking | None:
row = latest_row(team, user)
- if row is None or (seen is not None and row.id == seen.id) or row.input_hash != current_hash:
+ if row is None or (seen is not None and row.id == seen.id):
+ return None
+ if current_hash is not None and row.input_hash != current_hash:
return None
return row
@@ -229,9 +241,10 @@ def _row_stored_since(
def _wait_for_new_row(
team: Team, user: User, previous: PersonalInboxRanking | None, deadline: float
) -> PersonalInboxRanking | None:
+ """Wait for a new row, or for a hash check that records `checked_at` on `previous`."""
while True:
row = latest_row(team, user)
- if row is not None and (previous is None or row.id != previous.id):
+ if row is not None and (previous is None or row.id != previous.id or row.checked_at != previous.checked_at):
return row
if time.monotonic() >= deadline:
return None
@@ -242,11 +255,6 @@ def _elapsed_ms(since: float) -> int:
return round((time.monotonic() - since) * 1000)
-def ready_summary_version(team: Team, user: User) -> int | None:
- summary = get_summary(team, user.id)
- return summary.version if summary is not None and summary.status == ActivitySummaryStatus.READY else None
-
-
def _served_report(candidate: Candidate) -> ServedReport:
return ServedReport(
id=candidate.report_id,
@@ -304,6 +312,7 @@ def _serve_row(
building=building,
fallback_reason=row.fallback_reason,
generated_at=row.created_at,
+ checked_at=row.checked_at or row.created_at,
latency_ms=row.latency_ms,
activity_summary_version=row.activity_summary_version,
candidates_considered=len(row.candidate_ids or ()),
@@ -332,6 +341,7 @@ def _serve_inbox_order(candidates: Sequence[Candidate], *, limit: int, building:
building=building,
fallback_reason=reason,
generated_at=None,
+ checked_at=None,
latency_ms=None,
activity_summary_version=None,
candidates_considered=len(candidates),
@@ -361,6 +371,7 @@ def serve_personal_ranking(
refresh: bool = False,
focus: str | None = None,
wait_seconds: int = 0,
+ max_age_minutes: int | None = None,
config: PersonalRankingConfig | None = None,
) -> ServedRanking:
config = config or read_config()
@@ -370,25 +381,59 @@ def serve_personal_ranking(
focus = normalize_focus(focus, config.focus_max_chars)
wait_seconds = min(max(wait_seconds, 0), MAX_WAIT_SECONDS)
started = time.monotonic()
+ check_ms: int | None = None
gather_ms: int | None = None
wait_ms: int | None = None
def timed(served: ServedRanking) -> ServedRanking:
return dataclasses.replace(served, timings=ReadTimings(check_ms=check_ms, gather_ms=gather_ms, wait_ms=wait_ms))
+ def checked_within(row: PersonalInboxRanking, minutes: int) -> bool:
+ return (row.checked_at or row.created_at) >= now - datetime.timedelta(minutes=minutes)
+
def fresh(row: PersonalInboxRanking | None) -> bool:
- return row is not None and (row.checked_at or row.created_at) >= now - datetime.timedelta(
- minutes=config.freshness_minutes
- )
+ return row is not None and checked_within(row, config.freshness_minutes)
+
+ def serve_stored(row: PersonalInboxRanking, *, cached: bool) -> ServedRanking:
+ stored = stored_candidates(team, user, row.candidate_ids or ())
+ stale = input_hash(stored, activity_summary_version=summary_version, focus=None) != row.input_hash
+ return _serve_row(row, stored, limit=limit, cached=cached, stale=stale, building=False)
now = timezone.now()
started_with = latest_row(team, user)
summary_version = ready_summary_version(team, user)
- if started_with is not None and fresh(started_with) and not refresh and focus is None:
- stored = stored_candidates(team, user, started_with.candidate_ids or ())
- if input_hash(stored, activity_summary_version=summary_version, focus=None) == started_with.input_hash:
- check_ms = _elapsed_ms(started)
- return timed(_serve_row(started_with, stored, limit=limit, cached=True, stale=False, building=False))
+ if (
+ started_with is not None
+ and not refresh
+ and focus is None
+ and (max_age_minutes is None or checked_within(started_with, max_age_minutes))
+ ):
+ served = serve_stored(started_with, cached=True)
+ check_ms = _elapsed_ms(started)
+ if fresh(started_with):
+ return timed(served)
+ # The task gathers the candidates and compares the hash, so the read stays fast.
+ start = _start_build(
+ team,
+ user,
+ config,
+ None,
+ limit,
+ calls_model=False,
+ seen=started_with,
+ current_hash=None,
+ check_first=True,
+ )
+ if isinstance(start, PersonalInboxRanking):
+ return timed(serve_stored(start, cached=True))
+ building = start in ("started", "running")
+ if building and wait_seconds:
+ wait_started = time.monotonic()
+ built = _wait_for_new_row(team, user, started_with, started + wait_seconds)
+ wait_ms = _elapsed_ms(wait_started)
+ if built is not None:
+ return timed(serve_stored(built, cached=built.id == started_with.id))
+ return timed(dataclasses.replace(served, building=building))
check_ms = _elapsed_ms(started)
gather_started = time.monotonic()
@@ -396,11 +441,16 @@ def serve_personal_ranking(
current_hash = input_hash(candidates, activity_summary_version=summary_version, focus=focus)
# Read again, because a build can store a row while the candidates are gathered.
latest = latest_row(team, user)
- current = latest is not None and fresh(latest) and latest.input_hash == current_hash
+ retryable = latest is not None and latest.fallback_reason in RETRYABLE_FALLBACK_REASONS
+ # An old list that matches needs no build. A failed build can still succeed, so it gets a new one when old.
+ current = latest is not None and latest.input_hash == current_hash and (fresh(latest) or not retryable)
gather_ms = _elapsed_ms(gather_started)
# A row stored after this read started also answers a refresh.
stored_since_start = latest is not None and (started_with is None or latest.id != started_with.id)
if latest is not None and current and focus is None and (not refresh or stored_since_start):
+ if not retryable:
+ record_check(team, latest, now)
+ latest.checked_at = now
return timed(_serve_row(latest, candidates, limit=limit, cached=True, stale=False, building=False))
calls_model = bool(candidates) and may_call_model(team, summary_ready=summary_version is not None)
diff --git a/products/signals/backend/personal_ranking/tick.py b/products/signals/backend/personal_ranking/tick.py
index 8268114ec26a..3b53a9a95049 100644
--- a/products/signals/backend/personal_ranking/tick.py
+++ b/products/signals/backend/personal_ranking/tick.py
@@ -43,7 +43,6 @@ from products.signals.backend.personal_ranking.build_budget import (
spend_shared_build,
spend_tick_build,
)
-from products.signals.backend.personal_ranking.candidates import gather_candidates
from products.signals.backend.personal_ranking.config import (
PersonalRankingConfig,
PersonalRankingTickConfig,
@@ -54,13 +53,9 @@ from products.signals.backend.personal_ranking.logic import (
CHANGED_UNKNOWN,
INPUT_PARTS,
PIPELINE_DISTINCT_ID,
- RETRYABLE_FALLBACK_REASONS,
build_personal_ranking,
- input_hash,
- latest_row,
- may_call_model,
+ check_inputs,
)
-from products.signals.backend.personal_ranking.serve import ready_summary_version
from products.signals.backend.personal_ranking_tasks import BUILD_LOCK_TTL_SECONDS, build_lock_key
logger = structlog.get_logger(__name__)
@@ -357,21 +352,11 @@ def plan_tick(limit: int | None, now: datetime.datetime) -> PersonalRankingTickP
def _check_and_build(team: Team, user: User, config: PersonalRankingConfig) -> PersonalRankingPairResult:
- now = timezone.now()
- latest = latest_row(team, user)
- candidates = gather_candidates(team, user, config, now=now, with_sources=False)
- summary_version = ready_summary_version(team, user)
- current_hash = input_hash(candidates, activity_summary_version=summary_version, focus=None)
- if (
- latest is not None
- and latest.input_hash == current_hash
- and latest.fallback_reason not in RETRYABLE_FALLBACK_REASONS
- ):
+ check = check_inputs(team, user, config, now=timezone.now())
+ if check.unchanged:
# The list is still current, so the pair leaves the due set until `target_interval_minutes` passes again.
- PersonalInboxRanking.objects.for_team(team.id).filter(id=latest.id).update(checked_at=now)
return PersonalRankingPairResult(status="unchanged")
- calls_model = bool(candidates) and may_call_model(team, summary_ready=summary_version is not None)
- if calls_model:
+ if check.calls_model:
if not spend_tick_build(config):
return PersonalRankingPairResult(status="tick_limited")
if spend_shared_build(config) is not None:
diff --git a/products/signals/backend/personal_ranking_tasks.py b/products/signals/backend/personal_ranking_tasks.py
index bbc76d197da4..ec5e0475588c 100644
--- a/products/signals/backend/personal_ranking_tasks.py
+++ b/products/signals/backend/personal_ranking_tasks.py
@@ -1,11 +1,14 @@
from django.core.cache import cache
+from django.utils import timezone
from celery import shared_task
from posthog.models import Team, User
from posthog.models.scoping import with_team_scope
-from products.signals.backend.personal_ranking.logic import build_personal_ranking
+from products.signals.backend.personal_ranking.build_budget import spend_shared_build
+from products.signals.backend.personal_ranking.config import PersonalRankingConfig, read_config
+from products.signals.backend.personal_ranking.logic import build_personal_ranking, check_inputs
# Above the task's time_limit, so a live build never loses its lock. It also frees the lock of a worker that died.
BUILD_LOCK_TTL_SECONDS = 5 * 60
@@ -15,15 +18,33 @@ def build_lock_key(team_id: int, user_id: int) -> str:
return f"signals_personal_ranking_build/{team_id}/{user_id}"
+def _skip_build(team: Team, user: User, config: PersonalRankingConfig) -> bool:
+ """Compare the latest list with the current inputs, as the tick does. True when the build must not run."""
+ check = check_inputs(team, user, config, now=timezone.now())
+ if check.unchanged:
+ return True
+ # The read did not gather the candidates, so it could not know whether the build calls the model.
+ return check.calls_model and spend_shared_build(config) is not None
+
+
@shared_task(ignore_result=True, max_retries=0, soft_time_limit=3 * 60, time_limit=4 * 60)
@with_team_scope()
-def build_personal_inbox_ranking(team_id: int, user_id: int, focus: str | None, limit: int | None) -> None:
- """Build and store one person's ranked inbox list. The `for_me` read takes the lock before it queues this task."""
+def build_personal_inbox_ranking(
+ team_id: int, user_id: int, focus: str | None, limit: int | None, check_first: bool = False
+) -> None:
+ """Build and store one person's ranked inbox list. The `for_me` read takes the lock before it queues this task.
+
+ With `check_first`, a list that still matches the current inputs gets `checked_at` and no model call, and a
+ build that calls the model spends the shared daily limit first.
+ """
try:
- team = Team.objects.filter(id=team_id).first()
+ team = Team.objects.select_related("organization").filter(id=team_id).first()
user = User.objects.filter(id=user_id).first()
if team is None or user is None:
return
- build_personal_ranking(team, user, focus=focus, limit=limit)
+ config = read_config()
+ if check_first and _skip_build(team, user, config):
+ return
+ build_personal_ranking(team, user, focus=focus, limit=limit, config=config)
finally:
cache.delete(build_lock_key(team_id, user_id))
diff --git a/products/signals/backend/serializers.py b/products/signals/backend/serializers.py
index 9299c04b218d..2cccca1babc6 100644
--- a/products/signals/backend/serializers.py
+++ b/products/signals/backend/serializers.py
@@ -1550,6 +1550,16 @@ class PersonalRankingQuerySerializer(serializers.Serializer):
"the request started. Defaults to 0, which does not wait. A build usually takes 10 to 60 seconds."
),
)
+ max_age_minutes = serializers.IntegerField(
+ required=False,
+ min_value=0,
+ max_value=10080,
+ help_text=(
+ "The oldest `checked_at` you accept. When the stored list is older, the request reads every candidate "
+ "report, which can take some seconds, and starts a build if your inbox changed. Leave it out to get "
+ "the stored list quickly. A new report then joins the list at the next scheduled build."
+ ),
+ )
class PersonalRankingReportSerializer(serializers.Serializer):
@@ -1618,7 +1628,8 @@ class PersonalRankingSerializer(serializers.Serializer):
stale = serializers.BooleanField(
help_text=(
"True when the list does not match your current inbox or focus. When `building` is true, a newer "
- "list is on the way. Otherwise a build limit was reached, so try again later."
+ "list is on the way. Otherwise a report in the list changed since the build, and the next scheduled "
+ "build updates it. Pass `refresh` for a new list now."
)
)
building = serializers.BooleanField(
@@ -1640,6 +1651,13 @@ class PersonalRankingSerializer(serializers.Serializer):
),
)
generated_at = serializers.DateTimeField(allow_null=True, help_text="When the list was built.")
+ checked_at = serializers.DateTimeField(
+ allow_null=True,
+ help_text=(
+ "When a build or a check last compared the list with your full inbox. The list is current as at this "
+ "time. Null when no list is stored."
+ ),
+ )
latency_ms = serializers.IntegerField(
allow_null=True,
help_text="How long the model call of the build took, in ms. Null when there was no model call.",
diff --git a/products/signals/backend/test/test_personal_ranking.py b/products/signals/backend/test/test_personal_ranking.py
index 353a5f857fe8..f02f5e2bd5c4 100644
--- a/products/signals/backend/test/test_personal_ranking.py
+++ b/products/signals/backend/test/test_personal_ranking.py
@@ -1,6 +1,7 @@
import json
import datetime
import dataclasses
+from collections.abc import Callable
from io import StringIO
from types import SimpleNamespace
from typing import Any
@@ -969,26 +970,33 @@ class TestForMeEndpoint(APIBaseTest):
first.title = "First, edited"
first.save()
- assert self._state(self._get()) == (True, True, True)
+ self._claimed_report("Not in the stored list")
+ with (
+ patch.object(personal_ranking_serve, "gather_candidates") as gather,
+ self.assertNumQueries(30),
+ ):
+ body = self._get(max_age_minutes=60)
+ assert (self._state(body), self.queued, gather.call_count) == ((True, True, False), [], 0)
+ assert body["checked_at"] == body["generated_at"]
+ assert self._state(self._get(max_age_minutes=0)) == (True, True, True)
self._run_builds()
assert (self._state(self._get()), self._rows()) == ((True, False, False), 3)
second = self._claimed_report("Second")
body = self._get()
assert (self._state(body), self.queued) == ((True, False, False), [])
- assert [entry["report"]["id"] for entry in body["results"]] == [str(first.id)]
+ assert len(body["results"]) == 2
PersonalInboxRanking.objects.for_team(self.team.id).update(
created_at=F("created_at") - datetime.timedelta(days=2)
)
- assert self._state(self._get()) == (True, True, True)
+ assert self._state(self._get()) == (True, False, True)
self._run_builds()
body = self._get()
- assert {entry["report"]["id"] for entry in body["results"]} == {str(first.id), str(second.id)}
+ assert str(second.id) in {entry["report"]["id"] for entry in body["results"]}
assert self._state(self._get(focus="checkout")) == (True, True, True)
self._run_builds()
- assert (self._state(self._get()), self._rows()) == ((True, True, True), 5)
- self._run_builds()
+ assert (self._state(self._get()), self.queued, self._rows()) == ((True, True, False), [], 5)
self.delay.side_effect = build_personal_inbox_ranking
body = self._get(refresh="true", wait_seconds=5)
@@ -996,11 +1004,11 @@ class TestForMeEndpoint(APIBaseTest):
@parameterized.expand(
[
- ("during_gather", "gather_candidates", {}, False, False),
- ("before_lock", "may_call_model", {}, False, False),
+ ("during_gather", "gather_candidates", {"max_age_minutes": 0}, False, False),
+ ("before_lock", "may_call_model", {"max_age_minutes": 0}, False, False),
("refresh", "gather_candidates", {"refresh": "true"}, False, False),
("refresh_before_lock", "may_call_model", {"refresh": "true"}, False, False),
- ("inputs_changed", "gather_candidates", {}, True, True),
+ ("inputs_changed", "gather_candidates", {"max_age_minutes": 0}, True, True),
("focus", "gather_candidates", {"focus": "checkout"}, False, True),
]
)
@@ -1013,7 +1021,7 @@ class TestForMeEndpoint(APIBaseTest):
self._run_builds()
report.title = "First, edited"
report.save()
- self._get()
+ self._get(max_age_minutes=0)
real_step = getattr(personal_ranking_serve, step)
@@ -1033,6 +1041,28 @@ class TestForMeEndpoint(APIBaseTest):
# A read that queued no build spent no bucket, so the burst still has one build left.
assert self._get(refresh="true")["building"] is not builds
+ @parameterized.expand(
+ [
+ ("resolved", lambda report: SignalReport.objects.filter(id=report.id).update(status="resolved")),
+ ("suppressed", lambda report: SignalReport.objects.filter(id=report.id).update(status="suppressed")),
+ ("claim_released", lambda report: SignalReportAssignment.all_teams.filter(report=report).delete()),
+ ]
+ )
+ def test_a_plain_read_drops_a_report_that_is_no_longer_theirs(
+ self, _name: str, leave: Callable[[SignalReport], Any]
+ ) -> None:
+ kept = self._claimed_report("Kept")
+ left = self._claimed_report("Left")
+ self._get()
+ self._run_builds()
+ leave(left)
+
+ with patch.object(personal_ranking_serve, "gather_candidates") as gather:
+ body = self._get()
+
+ assert [entry["report"]["id"] for entry in body["results"]] == [str(kept.id)]
+ assert (body["stale"], gather.call_count) == (True, 0)
+
def test_throttled_build_serves_the_stored_list_or_the_inbox_order(self) -> None:
self.payload = {"build_burst": 1, "builds_per_hour": 1}
first = self._claimed_report("First")
@@ -1088,7 +1118,7 @@ class TestForMeEndpoint(APIBaseTest):
self._claimed_report(f"Claimed by {user.email}", user)
with patch(
- "products.signals.backend.personal_ranking.serve.get_summary",
+ "products.signals.backend.personal_ranking.logic.get_summary",
side_effect=lambda _team, user_id: summaries[user_id],
):
assert self._get()["building"] is True
@@ -1100,22 +1130,26 @@ class TestForMeEndpoint(APIBaseTest):
assert [args[1] for args in self.queued] == [self.user.id, third.id]
- def test_a_list_the_tick_checked_stays_fresh_past_its_build_time(self) -> None:
+ def test_an_old_list_is_served_at_once_and_checked_in_the_background(self) -> None:
+ self.organization.is_ai_data_processing_approved = True
+ self.organization.save()
self._claimed_report("First")
with time_machine.travel(timezone.now(), tick=False) as traveller:
self._get()
self._run_builds()
traveller.shift(datetime.timedelta(hours=2))
- assert self._get()["stale"] is True
- self._run_builds()
-
- traveller.shift(datetime.timedelta(hours=2))
- PersonalInboxRanking.objects.for_team(self.team.id).filter(user_id=self.user.id).update(
- checked_at=timezone.now()
+ with patch.object(personal_ranking_serve, "gather_candidates") as gather:
+ body = self._get()
+ assert (self._state(body), gather.call_count, [args[-1] for args in self.queued]) == (
+ (True, False, True),
+ 0,
+ [True],
)
+ self._run_builds()
body = self._get()
- assert (self._state(body), self.queued) == ((True, False, False), [])
+ assert (self._state(body), self.queued, self._rows()) == ((True, False, False), [], 1)
+ assert body["checked_at"] > body["generated_at"]
def test_another_user_never_reads_your_list(self) -> None:
self._get()
diff --git a/products/signals/backend/test/test_personal_ranking_tick.py b/products/signals/backend/test/test_personal_ranking_tick.py
index 1e8e2362fb5c..36a400327104 100644
--- a/products/signals/backend/test/test_personal_ranking_tick.py
+++ b/products/signals/backend/test/test_personal_ranking_tick.py
@@ -212,7 +212,6 @@ class TestTickPair(_TickTest):
for target, value in (
("products.signals.backend.personal_ranking.logic.build_openai_client", MagicMock(return_value=self.llm)),
("products.signals.backend.personal_ranking.logic.get_summary", MagicMock(return_value=summary)),
- ("products.signals.backend.personal_ranking.serve.get_summary", MagicMock(return_value=summary)),
("products.signals.backend.personal_ranking.logic.ph_scoped_capture", scoped_capture),
(
"products.signals.backend.personal_ranking.candidates.fetch_source_products_for_reports",
diff --git a/products/signals/backend/views.py b/products/signals/backend/views.py
index 6430c6a53f01..5f893b053dae 100644
--- a/products/signals/backend/views.py
+++ b/products/signals/backend/views.py
@@ -1814,11 +1814,12 @@ class SignalReportViewSet(
description=(
"Your open inbox reports, ranked for you by one language model call over your activity summary, the "
"reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. "
- "The request never waits on the model. A current stored list returns quickly. Otherwise the request "
- "reads every candidate report, which can take some seconds, starts a background build and returns the "
- "last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, "
- "and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list "
- "is about can read it."
+ "The request never waits on the model. By default it returns the last stored list quickly, and "
+ "`checked_at` says how current it is. Pass `max_age_minutes` to check an older list against every "
+ "candidate report, which can take some seconds. `refresh`, `focus` and your first request start a "
+ "background build and set `building: true`. With no stored list, the request returns your reports in "
+ "inbox order with `fallback_reason: building`. Pass `wait_seconds` to wait a short time for the new "
+ "list. Only the user the list is about can read it."
),
)
@action(detail=False, methods=["get"], url_path="for_me", required_scopes=["inbox:read"], pagination_class=None)
@@ -1841,6 +1842,7 @@ class SignalReportViewSet(
refresh=query["refresh"],
focus=query.get("focus"),
wait_seconds=query["wait_seconds"],
+ max_age_minutes=query.get("max_age_minutes"),
)
report_user_action(
user,
@@ -1856,6 +1858,7 @@ class SignalReportViewSet(
"refresh": query["refresh"],
"has_focus": bool(query.get("focus")),
"wait_seconds": query["wait_seconds"],
+ "max_age_minutes": query.get("max_age_minutes"),
"result_count": len(served.results),
"duration_ms": round((time.monotonic() - started) * 1000),
"check_ms": served.timings.check_ms,
diff --git a/products/signals/frontend/generated/api.schemas.ts b/products/signals/frontend/generated/api.schemas.ts
index d85b1dfb43d9..11f0c36cd07d 100644
--- a/products/signals/frontend/generated/api.schemas.ts
+++ b/products/signals/frontend/generated/api.schemas.ts
@@ -6586,7 +6586,7 @@ export interface PersonalRankingApi {
personalized: boolean
/** True when the list is a stored one. False when it is the inbox order fallback or the new list that `wait_seconds` waited for. */
cached: boolean
- /** True when the list does not match your current inbox or focus. When `building` is true, a newer list is on the way. Otherwise a build limit was reached, so try again later. */
+ /** True when the list does not match your current inbox or focus. When `building` is true, a newer list is on the way. Otherwise a report in the list changed since the build, and the next scheduled build updates it. Pass `refresh` for a new list now. */
stale: boolean
/** True when a new list is being built in the background. Call again in a few seconds, or pass `wait_seconds`, to get it. */
building: boolean
@@ -6600,6 +6600,11 @@ export interface PersonalRankingApi {
* @nullable
*/
generated_at: string | null
+ /**
+ * When a build or a check last compared the list with your full inbox. The list is current as at this time. Null when no list is stored.
+ * @nullable
+ */
+ checked_at: string | null
/**
* How long the model call of the build took, in ms. Null when there was no model call.
* @nullable
@@ -11417,6 +11422,12 @@ export type SignalsReportsForMeRetrieveParams = {
* @maximum 100
*/
limit?: number
+ /**
+ * The oldest `checked_at` you accept. When the stored list is older, the request reads every candidate report, which can take some seconds, and starts a build if your inbox changed. Leave it out to get the stored list quickly. A new report then joins the list at the next scheduled build.
+ * @minimum 0
+ * @maximum 10080
+ */
+ max_age_minutes?: number
/**
* Start a new build even when the stored one is current. The build runs in the background, so the response has `building: true`. Pass `wait_seconds` to wait for it.
*/
diff --git a/products/signals/frontend/generated/api.ts b/products/signals/frontend/generated/api.ts
index 0907e161937a..11169e49770d 100644
--- a/products/signals/frontend/generated/api.ts
+++ b/products/signals/frontend/generated/api.ts
@@ -1633,7 +1633,7 @@ export const getSignalsReportsForMeRetrieveUrl = (projectId: string, params?: Si
}
/**
- * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. A current stored list returns quickly. Otherwise the request reads every candidate report, which can take some seconds, starts a background build and returns the last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
+ * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. By default it returns the last stored list quickly, and `checked_at` says how current it is. Pass `max_age_minutes` to check an older list against every candidate report, which can take some seconds. `refresh`, `focus` and your first request start a background build and set `building: true`. With no stored list, the request returns your reports in inbox order with `fallback_reason: building`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
* @summary Get your personal ranked inbox
*/
export const signalsReportsForMeRetrieve = async (
diff --git a/products/signals/mcp/tools.yaml b/products/signals/mcp/tools.yaml
index e64ca3d76bb3..8493a4feeba5 100644
--- a/products/signals/mcp/tools.yaml
+++ b/products/signals/mcp/tools.yaml
@@ -486,16 +486,17 @@ tools:
the ranking model's scores. Use it for "what should I work on" and "my top N" questions in place of paging
inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a
compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal:
- only the user it describes can read it. The call never waits on the model. A current stored list comes back
- quickly, as is. Otherwise the call reads every candidate report, which can take some seconds, starts a
- background build and returns the last stored list with `stale: true`, or the reports in inbox order with
- `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and
- builds are rate limited. A report created after the stored list joins at the next build. When `building` is
- true, call again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to
- wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or
- the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit
- was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for
- now.
+ only the user it describes can read it. The call never waits on the model. By default the last stored list
+ comes back quickly, and `checked_at` says when it was last compared with the full inbox. A report created
+ after that time joins at the next scheduled build. Pass `max_age_minutes` when the list must be newer than
+ that: an older list is checked against every candidate report, which can take some seconds, and rebuilt if
+ the inbox changed. `refresh` and `focus` always start a build, and builds are rate limited. A user with no
+ stored list gets the reports in inbox order with `fallback_reason: building`. When `building` is true, call
+ again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to wait for the
+ new list in the same call. `personalized: false` means the user has no activity summary yet or the list is
+ in inbox order (see `fallback_reason`). `stale: true` without `building` means a report in the list changed
+ since the build; the next scheduled build updates it, or pass `refresh`. `status: unavailable` means
+ personal ranking is off for now.
feature_flag: personal-inbox-ranking
inbox-reports-leave-reviewers:
operation: signals_reports_reviewers_me_create
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 78631553bdd3..3887778f9474 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -8089,7 +8089,7 @@
}
},
"inbox-reports-for-me": {
- "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks only the reports tied to them (suggested reviewer, claimed, waiting on their input), using their activity summary and the ranking model's scores. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call never waits on the model. A current stored list comes back quickly, as is. Otherwise the call reads every candidate report, which can take some seconds, starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. A report created after the stored list joins at the next build. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
+ "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks only the reports tied to them (suggested reviewer, claimed, waiting on their input), using their activity summary and the ranking model's scores. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call never waits on the model. By default the last stored list comes back quickly, and `checked_at` says when it was last compared with the full inbox. A report created after that time joins at the next scheduled build. Pass `max_age_minutes` when the list must be newer than that: an older list is checked against every candidate report, which can take some seconds, and rebuilt if the inbox changed. `refresh` and `focus` always start a build, and builds are rate limited. A user with no stored list gets the reports in inbox order with `fallback_reason: building`. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means a report in the list changed since the build; the next scheduled build updates it, or pass `refresh`. `status: unavailable` means personal ranking is off for now.",
"category": "Signals",
"feature": "signals",
"summary": "Get your personal ranked inbox",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index b4fbcfea0c42..9d99975eb5fc 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -8321,7 +8321,7 @@
}
},
"inbox-reports-for-me": {
- "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks only the reports tied to them (suggested reviewer, claimed, waiting on their input), using their activity summary and the ranking model's scores. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call never waits on the model. A current stored list comes back quickly, as is. Otherwise the call reads every candidate report, which can take some seconds, starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. A report created after the stored list joins at the next build. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
+ "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks only the reports tied to them (suggested reviewer, claimed, waiting on their input), using their activity summary and the ranking model's scores. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call never waits on the model. By default the last stored list comes back quickly, and `checked_at` says when it was last compared with the full inbox. A report created after that time joins at the next scheduled build. Pass `max_age_minutes` when the list must be newer than that: an older list is checked against every candidate report, which can take some seconds, and rebuilt if the inbox changed. `refresh` and `focus` always start a build, and builds are rate limited. A user with no stored list gets the reports in inbox order with `fallback_reason: building`. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30, counted from the start of the call) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means a report in the list changed since the build; the next scheduled build updates it, or pass `refresh`. `status: unavailable` means personal ranking is off for now.",
"category": "Signals",
"feature": "signals",
"summary": "Get your personal ranked inbox",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 23eeac8450b8..ffb894b87c9e 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -89522,7 +89522,7 @@ export namespace Schemas {
personalized: boolean;
/** True when the list is a stored one. False when it is the inbox order fallback or the new list that `wait_seconds` waited for. */
cached: boolean;
- /** True when the list does not match your current inbox or focus. When `building` is true, a newer list is on the way. Otherwise a build limit was reached, so try again later. */
+ /** True when the list does not match your current inbox or focus. When `building` is true, a newer list is on the way. Otherwise a report in the list changed since the build, and the next scheduled build updates it. Pass `refresh` for a new list now. */
stale: boolean;
/** True when a new list is being built in the background. Call again in a few seconds, or pass `wait_seconds`, to get it. */
building: boolean;
@@ -89536,6 +89536,11 @@ export namespace Schemas {
* @nullable
*/
generated_at: string | null;
+ /**
+ * When a build or a check last compared the list with your full inbox. The list is current as at this time. Null when no list is stored.
+ * @nullable
+ */
+ checked_at: string | null;
/**
* How long the model call of the build took, in ms. Null when there was no model call.
* @nullable
@@ -132611,6 +132616,12 @@ export namespace Schemas {
* @maximum 100
*/
limit?: number;
+ /**
+ * The oldest `checked_at` you accept. When the stored list is older, the request reads every candidate report, which can take some seconds, and starts a build if your inbox changed. Leave it out to get the stored list quickly. A new report then joins the list at the next scheduled build.
+ * @minimum 0
+ * @maximum 10080
+ */
+ max_age_minutes?: number;
/**
* Start a new build even when the stored one is current. The build runs in the background, so the response has `building: true`. Pass `wait_seconds` to wait for it.
*/
diff --git a/services/mcp/src/generated/signals/api.ts b/services/mcp/src/generated/signals/api.ts
index bf6ccb095bad..29d990657be0 100644
--- a/services/mcp/src/generated/signals/api.ts
+++ b/services/mcp/src/generated/signals/api.ts
@@ -1763,7 +1763,7 @@ export const SignalsReportsBulkStateCreateBody = () => zod.object({
})
/**
- * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. A current stored list returns quickly. Otherwise the request reads every candidate report, which can take some seconds, starts a background build and returns the last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
+ * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. By default it returns the last stored list quickly, and `checked_at` says how current it is. Pass `max_age_minutes` to check an older list against every candidate report, which can take some seconds. `refresh`, `focus` and your first request start a background build and set `building: true`. With no stored list, the request returns your reports in inbox order with `fallback_reason: building`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
* @summary Get your personal ranked inbox
*/
export const SignalsReportsForMeRetrieveParams = () => zod.object({
@@ -1778,6 +1778,9 @@ export const signalsReportsForMeRetrieveQueryFocusMax = 2000
export const signalsReportsForMeRetrieveQueryLimitMax = 100
+export const signalsReportsForMeRetrieveQueryMaxAgeMinutesMin = 0
+export const signalsReportsForMeRetrieveQueryMaxAgeMinutesMax = 10080
+
export const signalsReportsForMeRetrieveQueryRefreshDefault = false
export const signalsReportsForMeRetrieveQueryWaitSecondsDefault = 0
export const signalsReportsForMeRetrieveQueryWaitSecondsMin = 0
@@ -1799,6 +1802,14 @@ export const SignalsReportsForMeRetrieveQueryParams = () => zod.object({
.describe(
'The most reports to return, best first. Defaults to 25. Values above the configured maximum (50) use the maximum.'
),
+ max_age_minutes: zod
+ .number()
+ .min(signalsReportsForMeRetrieveQueryMaxAgeMinutesMin)
+ .max(signalsReportsForMeRetrieveQueryMaxAgeMinutesMax)
+ .optional()
+ .describe(
+ 'The oldest `checked_at` you accept. When the stored list is older, the request reads every candidate report, which can take some seconds, and starts a build if your inbox changed. Leave it out to get the stored list quickly. A new report then joins the list at the next scheduled build.'
+ ),
refresh: zod
.boolean()
.default(signalsReportsForMeRetrieveQueryRefreshDefault)
diff --git a/services/mcp/src/tools/generated/signals.ts b/services/mcp/src/tools/generated/signals.ts
index 69b43259dcc8..774df394688a 100644
--- a/services/mcp/src/tools/generated/signals.ts
+++ b/services/mcp/src/tools/generated/signals.ts
@@ -749,6 +749,7 @@ const inboxReportsForMe = (): ToolBase<ReturnType<typeof InboxReportsForMeSchema
query: {
focus: params.focus,
limit: params.limit,
+ max_age_minutes: params.max_age_minutes,
refresh: params.refresh,
wait_seconds: params.wait_seconds,
},
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
index f7c518727fd4..e05d6fe6b529 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
@@ -12,6 +12,12 @@
"minimum": 1,
"type": "number"
},
+ "max_age_minutes": {
+ "description": "The oldest `checked_at` you accept. When the stored list is older, the request reads every candidate report, which can take some seconds, and starts a build if your inbox changed. Leave it out to get the stored list quickly. A new report then joins the list at the next scheduled build.",
+ "maximum": 10080,
+ "minimum": 0,
+ "type": "number"
+ },
"refresh": {
"default": false,
"description": "Start a new build even when the stored one is current. The build runs in the background, so the response has `building: true`. Pass `wait_seconds` to wait for it.",