From 7e3de8b38a65ffec683cfd4208899022ff6b6cc8 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 22:25:29 +0000 Subject: [PATCH 1/3] feat(automations): look back over the stream in an automation's If A seen lookback asks whether activities of some kinds happened in a window before now, with the same sender (or any path) as the activity that started the run and passing its own where, counted at least or at most n. Only an automation's If may hold one, in its namespaces and as its person may see them, reading at most 200 activities. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01AjJqXgjj1cNdKGRQbX5frb --- docs/automations.md | 22 +++ fastapi_backend/app/domain/automation_spec.py | 5 +- fastapi_backend/app/domain/match.py | 160 +++++++++++++++++- .../tests/domain/test_match_seen.py | 134 +++++++++++++++ 4 files changed, 311 insertions(+), 10 deletions(-) create mode 100644 fastapi_backend/tests/domain/test_match_seen.py diff --git a/docs/automations.md b/docs/automations.md index 59f0446e3..9fcf24855 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -11,6 +11,7 @@ merged is called built. | --- | --- | | Match trees: one condition language for triggers, an automation's If and workflow nodes | built | | Operators for times, lists, text patterns and changes (`in`, `matches`, `within`, `changed`...) | built | +| Looking back over the stream in an automation's If (`seen`) | built | | Activities, the kinds catalog, the event log, following the stream, timeline reads (`app/domain/events.py`) | built | | New assets as `asset.added` (the `recordings` source) | built | | New assets by kind: emails received, calendar events, files from storage, uploads, pages saved from the web, imports | built | @@ -381,6 +382,27 @@ its items does (as `contains` does), and `not_in` passes when none does. A value that the oldest go and are counted (`match.dropped(db, automation)`). A `last` value is kept 30 days after it was last seen; `match.tidy` drops expired rows once an hour, from the routine schedule. +#### Looking back + +Built (`match.seen`). An automation's If (and only its If, so testing a trigger's `where` on each new activity stays +cheap) can ask whether something happened before: a `seen` stands where a test would. + +```json +{"seen": {"kinds": ["email.received"], "within": "2d", "same": "object.from", + "where": {"path": "object.subject", "op": "matches", "value": "trip|outing"}, + "count": {"at_least": 1}}} +``` + +- It finds activities of `kinds` (and the kinds under them) published in the last `within` before now, passing its + own `where`, and, with `same`, holding the same value at that path as the activity that started the run (the run + context's `event`). That activity itself doesn't count. +- `count` is `{"at_least": n}` (1 when not given), `{"at_most": n}` or both, up to 100: `{"at_most": 0}` reads + "if nothing like it came", as in "if I haven't replied within 2 days". +- It reads at most 200 activities, of the automation's namespaces (`env["spaces"]`) and as the automation's person + (`env["account"]`) may see them; `env["db"]` and `env["cfg"]` give the database. Without a database it finds + nothing. Its `where` is tested with the same `env` (so its clock too) and can't test `changed`. +- In words: `at least one of “Email received” in the last 2 days, with the same sender`. + In a workflow, a condition, filter or switch case takes either one test, as before, or a tree in `match`; with a tree, `path` (when given) is the part of the value the tree tests. Graphs saved before keep running unchanged. diff --git a/fastapi_backend/app/domain/automation_spec.py b/fastapi_backend/app/domain/automation_spec.py index 94c4413ea..43d7aec5a 100644 --- a/fastapi_backend/app/domain/automation_spec.py +++ b/fastapi_backend/app/domain/automation_spec.py @@ -271,10 +271,11 @@ def check_join(j, aliases=None): # ---------- If, policy ---------- def check_if(tree): - """An automation's If, cleaned: a match tree over the run context, whose paths start with one of its keys.""" + """An automation's If, cleaned: a match tree over the run context, whose paths start with one of its keys. It + may look back over what happened (match.py, seen).""" if tree is None: return None - out = match.check(tree, "the If") + out = match.check(tree, "the If", lookback=True) keys = {c[0] for c in CONTEXT} for p in match.paths(out): if p.split(".")[0] not in keys: diff --git a/fastapi_backend/app/domain/match.py b/fastapi_backend/app/domain/match.py index 49a914e1b..d9fb3ecaf 100644 --- a/fastapi_backend/app/domain/match.py +++ b/fastapi_backend/app/domain/match.py @@ -87,13 +87,14 @@ def _num(v): # ---------- checking ---------- -def check(tree, what="the condition"): +def check(tree, what="the condition", lookback=False): """The tree, cleaned: ValueError naming the first problem, and where it is (`what`, then the path into the tree, - such as "the condition, all.1: ...").""" - return _check(tree, what, 0, [0], "") + such as "the condition, all.1: ..."). Only an automation's If may look back over the stream (`seen`, with + `lookback`), so that testing a trigger's where on each new activity stays cheap.""" + return _check(tree, what, 0, [0], "", lookback) -def _check(m, what, depth, count, at): +def _check(m, what, depth, count, at, lookback=False): where = f"{what}, {at}" if at else what if depth >= MAX_DEPTH: raise ValueError(f"{where}: conditions nest at most {MAX_DEPTH} deep") @@ -105,13 +106,25 @@ def _check(m, what, depth, count, at): raise ValueError(f"{where}: {groups[0]} stands alone, with nothing next to it") k = groups[0] if k == "not": - return {"not": _check(m["not"], what, depth + 1, count, f"{at}.not" if at else "not")} + return {"not": _check(m["not"], what, depth + 1, count, f"{at}.not" if at else "not", lookback)} items = m[k] if not isinstance(items, list): raise ValueError(f"{where}: {k} is a list of conditions") if k == "any" and not items: raise ValueError(f"{where}: any needs at least one condition") - return {k: [_check(x, what, depth + 1, count, f"{at}.{k}.{n}" if at else f"{k}.{n}") for n, x in enumerate(items)]} + return {k: [_check(x, what, depth + 1, count, f"{at}.{k}.{n}" if at else f"{k}.{n}", lookback) for n, x in enumerate(items)]} + if "seen" in m: + if len(m) != 1: + raise ValueError(f"{where}: seen stands alone, with nothing next to it") + if not lookback: + raise ValueError(f"{where}: only an automation's If looks back over what happened (seen)") + count[0] += 1 + if count[0] > MAX_LEAVES: + raise ValueError(f"{what} has at most {MAX_LEAVES} tests") + try: + return {"seen": check_seen(m["seen"])} + except ValueError as e: + raise ValueError(f"{where}: {e}") from None extra = sorted(set(m) - LEAF) if extra: raise ValueError(f"{where}: a test is {{path, op, value}}, not {extra[0]}") @@ -344,6 +357,8 @@ def _changed_value(v): # ---------- testing ---------- def test(tree, value, env=None): """Whether `value` passes the tree (checked with `check` first).""" + if "seen" in tree: + return seen(tree["seen"], value, env) if "all" in tree: return all(test(m, value, env) for m in tree["all"]) if "any" in tree: @@ -594,14 +609,139 @@ def tidy(db, cfg=None, now=None): return cut +# ---------- looking back over the stream ---------- +SEEN_KEYS = {"kinds", "within", "where", "same", "count"} +MAX_SEEN = 200 # activities a lookback reads at most +MAX_SEEN_COUNT = 100 +MAX_SEEN_KINDS = 10 + + +def check_seen(s): + """A lookback ({kinds, within, where, same, count}), cleaned: ValueError saying what is wrong with it.""" + from . import automation_spec, events + + if not isinstance(s, dict): + raise ValueError("seen is {kinds, within, where, same, count}") + extra = sorted(set(s) - SEEN_KEYS) + if extra: + raise ValueError(f"seen has no {extra[0]}; it takes {', '.join(sorted(SEEN_KEYS))}") + ks = s.get("kinds") + if not isinstance(ks, list) or not 1 <= len(ks) <= MAX_SEEN_KINDS or not all(isinstance(k, str) for k in ks): + raise ValueError(f"seen's kinds lists 1 to {MAX_SEEN_KINDS} kinds of activity, like email.received") + events.expand(ks) + within = s.get("within") + if within is None: + raise ValueError("seen says how far back it looks (within), like 2d") + automation_spec.check_duration(within, what="seen's within") + if automation_spec.check_duration(within) == 0: + raise ValueError("seen's within is more than 0") + out: dict = {"kinds": list(dict.fromkeys(ks)), "within": within.strip()} + if s.get("where") is not None: + out["where"] = check(s["where"], "seen's where") + if any(m["op"] == "changed" for m in leaves(out["where"])): + raise ValueError("seen's where can't test changed; test it in the If itself") + if s.get("same") is not None: + if not isinstance(s["same"], str) or not flow.PATH_RX.match(s["same"]): + raise ValueError("seen's same is a path in the activities, like object.from") + out["same"] = s["same"] + c = s.get("count") if s.get("count") is not None else {"at_least": 1} + if not isinstance(c, dict) or not c or set(c) - {"at_least", "at_most"}: + raise ValueError("seen's count is {at_least: n}, {at_most: n} or both") + for k, v in c.items(): + if not isinstance(v, int) or isinstance(v, bool) or not 0 <= v <= MAX_SEEN_COUNT: + raise ValueError(f"seen's count {k} is a whole number from 0 to {MAX_SEEN_COUNT}") + if "at_most" in c and c.get("at_least", 0) > c["at_most"]: + raise ValueError("seen's count at_least is at most its at_most") + if not c.get("at_least") and "at_most" not in c: + raise ValueError("seen's count needs at_least 1 or more, or an at_most") + out["count"] = dict(c) + return out + + +def found(s, value, env=None): + """The activities a (checked) lookback finds, newest first, leaving out the one being tested: of its kinds, + published in the last `within` before now, passing its `where`, with the same value at its `same` path as the + activity being tested (the run context's `event`, or the value itself), in the automation's namespaces, as the + automation's person may see them. `env` gives `db`, `cfg`, `spaces` (the automation's namespaces) and `account` + (its person), or a `viewer` (events.viewer). Without a database it finds nothing.""" + from . import automation_spec, events + + env = env or {} + db = env.get("db") + if db is None: + return [] + current = value.get("event") if isinstance(value, dict) and isinstance(value.get("event"), dict) else value + current = current if isinstance(current, dict) else {} + now = now_of(env) + since = now - dt.timedelta(seconds=automation_spec.check_duration(s["within"])) + flt: dict = {"kinds": s["kinds"], "since": since.isoformat(), "until": now.isoformat()} + if s.get("same"): + want = flow.dig(current, s["same"]) + if want is None: + return [] + flt["where"] = {"path": s["same"], "op": "equals", "value": want} + spaces = env.get("spaces") + if spaces is not None: + flt["spaces"] = list(spaces) + who = env.get("viewer") or events.viewer(env.get("account"), spaces or [], admin=False) + c = s["count"] + # with a where of its own (tested here, with env's clock), it reads as far as it may; else just enough to count + need = MAX_SEEN if s.get("where") else min(MAX_SEEN, (c["at_most"] + 1 if "at_most" in c else c["at_least"]) + 1) + items = events.page(db, env.get("cfg") or {}, who, flt=flt, limit=need)["items"] + return [a for a in items if a.get("id") != current.get("id") and (not s.get("where") or test(s["where"], a, env))] + + +def seen(s, value, env=None): + """Whether a (checked) lookback finds as many activities as its count asks (at least 1 when it doesn't say).""" + n, c = len(found(s, value, env)), s["count"] + return n >= c.get("at_least", 0) and ("at_most" not in c or n <= c["at_most"]) + + +def _kind_label(k): + from . import events + + try: + return f"“{events.kind_info(k)['label']}”" + except KeyError: + return k + + +def _seen_words(s, negated): + c = s["count"] + lo, hi = c.get("at_least", 0), c.get("at_most") + if hi is None: + n = ("none" if negated else "at least one") if lo == 1 else (f"fewer than {lo}" if negated else f"at least {lo}") + elif hi == 0: + n = "at least one" if negated else "none" + elif negated: + n = f"more than {hi}" if not lo else f"not {lo} to {hi}" + else: + n = f"at most {hi}" if not lo else f"{lo} to {hi}" + words = f"{n} of {_either([_kind_label(k) for k in s['kinds']])} in the last {duration_words(s['within'])}" + if s.get("same"): + words += f", with the same {_label(s['same'], s['kinds'][0])}" + if s.get("where"): + words += f", where {_describe(s['where'], s['kinds'][0], False)}" + return words + + # ---------- reading trees ---------- def leaves(tree): - """The tests in a tree, in order.""" + """The tests in a tree, in order (not the lookbacks: `lookbacks`).""" if "all" in tree or "any" in tree: return [x for m in tree.get("all", tree.get("any")) for x in leaves(m)] if "not" in tree: return leaves(tree["not"]) - return [tree] + return [] if "seen" in tree else [tree] + + +def lookbacks(tree): + """The seen lookbacks in a tree, in order.""" + if "all" in tree or "any" in tree: + return [x for m in tree.get("all", tree.get("any")) for x in lookbacks(m)] + if "not" in tree: + return lookbacks(tree["not"]) + return [tree["seen"]] if "seen" in tree else [] def paths(tree): @@ -697,7 +837,11 @@ def _describe(m, kind, top): return text if top or len(parts) == 1 else f"({text})" if "not" in m: inner = m["not"] + if "seen" in inner: + return _seen_words(inner["seen"], True) return _leaf(inner, kind, True) if "op" in inner else f"not ({_describe(inner, kind, True)})" + if "seen" in m: + return _seen_words(m["seen"], False) return _leaf(m, kind, False) diff --git a/fastapi_backend/tests/domain/test_match_seen.py b/fastapi_backend/tests/domain/test_match_seen.py new file mode 100644 index 000000000..f30dc67b4 --- /dev/null +++ b/fastapi_backend/tests/domain/test_match_seen.py @@ -0,0 +1,134 @@ +"""Looking back over the stream in an automation's If (docs/automations.md, Match trees: Looking back): `seen` finds +activities of some kinds in a window before now, with the same sender as the one being tested, in the automation's +namespaces only; it is refused anywhere but an If, and reads in words.""" + +from __future__ import annotations + +import pytest + +from app.domain import automation_spec, events, match + +NOW = "2026-10-15T16:00:00Z" + + +@pytest.fixture(autouse=True) +def kinds(): + before = dict(events._KINDS) + events.kind("test_mail.came", label="Mail came", source="log", as_type="Create", object_type="Note") + events.kind("test_mail.sent", label="Mail sent", source="log", as_type="Create", object_type="Note") + yield + events._KINDS.clear() + events._KINDS.update(before) + + +def mail(db, kind, sender, when, space=1, subject="Trip"): + obj = {"type": "Note", "name": subject, "from": [sender]} + return events.emit(db, kind, actor=events.LENS, obj=obj, space=space, summary=f"{sender}: {subject}", published=when) + + +def env(db, cfg, spaces=(1,), now=NOW): + return {"db": db, "cfg": cfg, "now": now, "spaces": list(spaces), "account": 1} + + +def look(**s): + return match.check_seen({"kinds": ["test_mail.came"], "within": "2d", **s}) + + +def test_seen_finds_what_happened_in_the_window(db, cfg): + mine = mail(db, "test_mail.came", "office@stmarys.org", "2026-10-15T15:00:00Z") + mail(db, "test_mail.came", "office@stmarys.org", "2026-10-14T09:00:00Z", subject="Outing") + mail(db, "test_mail.came", "office@stmarys.org", "2026-10-12T09:00:00Z") # before the window + mail(db, "test_mail.came", "club@example.com", "2026-10-15T10:00:00Z") + mail(db, "test_mail.came", "office@stmarys.org", "2026-10-15T11:00:00Z", space=2) # another namespace + mail(db, "test_mail.came", "office@stmarys.org", "2026-10-15T17:00:00Z") # after now + event = events.get(db, cfg, mine, events.viewer(1, None, admin=True)) + ctx = {"event": event} + e = env(db, cfg) + every = look(count={"at_least": 10}) # it reads just enough to count, so ask for more than there is to list them + assert [a["object"]["from"] for a in match.found(every, ctx, e)] == [["club@example.com"], ["office@stmarys.org"]] + assert len(match.found(look(), ctx, e)) == 1 + same = look(same="object.from", count={"at_least": 1}) + assert [a["object"]["name"] for a in match.found(same, ctx, e)] == ["Outing"] # not the one being tested + assert match.seen(same, ctx, e) + assert not match.seen(look(same="object.from", count={"at_least": 2}), ctx, e) + assert match.seen(look(same="object.from", count={"at_least": 2}), ctx, env(db, cfg, spaces=(1, 2))) + assert not match.seen(look(same="object.from", within="1h"), ctx, e) + where = { + "all": [{"path": "object.name", "op": "matches", "value": "trip|outing"}, {"path": "published", "op": "within", "value": "1d"}] + } + names = [a["summary"] for a in match.found(look(where=where), ctx, e)] + assert names == ["club@example.com: Trip"] # the outing is two days old, past a day of env's now + names = [a["summary"] for a in match.found(look(where=where), ctx, {**e, "now": "2026-10-15T08:00:00Z"})] + assert names == ["office@stmarys.org: Outing"] + assert match.found(look(same="object.to"), ctx, e) == [] # the activity has nothing there: nothing is the same + assert match.found(same, ctx, {**e, "db": None}) == [] + assert match.found(same, ctx, {**e, "spaces": []}) == [] + # "if I haven't replied within 2 days": none of the kind in the window + no_reply = look(count={"at_most": 0}) + assert not match.seen(no_reply, ctx, e) + assert match.seen(match.check_seen({"kinds": ["test_mail.sent"], "within": "2d", "count": {"at_most": 0}}), ctx, e) + mail(db, "test_mail.sent", "me@home", "2026-10-15T12:00:00Z") + assert not match.seen(match.check_seen({"kinds": ["test_mail.sent"], "within": "2d", "count": {"at_most": 0}}), ctx, e) + + +def test_an_if_looks_back_and_reads_the_context(db, cfg): + mine = mail(db, "test_mail.came", "office@stmarys.org", "2026-10-15T15:00:00Z") + mail(db, "test_mail.came", "office@stmarys.org", "2026-10-15T12:00:00Z") + tree = automation_spec.check_if( + { + "all": [ + {"path": "event.object.name", "op": "equals", "value": "Trip"}, + {"seen": {"kinds": ["test_mail.came"], "within": "1d", "same": "object.from"}}, + ] + } + ) + ctx = {"event": events.get(db, cfg, mine, events.viewer(1, None, admin=True))} + assert match.test(tree, ctx, env(db, cfg)) + assert not match.test(tree, ctx, env(db, cfg, now="2026-10-17T00:00:00Z")) + assert not match.test({"not": tree["all"][1]}, ctx, env(db, cfg)) + assert match.paths(tree) == ["event.object.name"] and match.lookbacks(tree) == [tree["all"][1]["seen"]] + + +def test_seen_is_only_for_an_automations_if(): + s = {"seen": {"kinds": ["test_mail.came"], "within": "1d"}} + with pytest.raises(ValueError, match="the condition: only an automation's If looks back"): + match.check(s) + with pytest.raises(ValueError, match="trigger mail's where, all.0: only an automation's If looks back"): + automation_spec.check_trigger({"as": "mail", "on": "event", "kinds": ["test_mail.came"], "where": {"all": [s]}}) + assert automation_spec.check_if({"any": [s]}) == { + "any": [{"seen": {"kinds": ["test_mail.came"], "within": "1d", "count": {"at_least": 1}}}] + } + bad = [ + ({"kinds": ["test_mail.came"]}, "seen says how far back it looks"), + ({"kinds": [], "within": "1d"}, "seen's kinds lists 1 to 10 kinds"), + ({"kinds": ["nope.never"], "within": "1d"}, "no kind nope.never"), + ({"kinds": ["test_mail.came"], "within": "-1d"}, "seen's within can't point back"), + ({"kinds": ["test_mail.came"], "within": "0s"}, "seen's within is more than 0"), + ({"kinds": ["test_mail.came"], "within": "1d", "same": "a b"}, "seen's same is a path"), + ({"kinds": ["test_mail.came"], "within": "1d", "count": {"at_least": 0}}, "needs at_least 1 or more"), + ({"kinds": ["test_mail.came"], "within": "1d", "count": {"at_least": 3, "at_most": 2}}, "at_least is at most its at_most"), + ({"kinds": ["test_mail.came"], "within": "1d", "count": {"exactly": 2}}, "seen's count is"), + ({"kinds": ["test_mail.came"], "within": "1d", "count": {"at_least": 101}}, "from 0 to 100"), + ({"kinds": ["test_mail.came"], "within": "1d", "where": {"path": "x", "op": "changed"}}, "can't test changed"), + ({"kinds": ["test_mail.came"], "within": "1d", "where": {"seen": {}}}, "seen's where: only an automation's If"), + ({"kinds": ["test_mail.came"], "within": "1d", "when": 1}, "seen has no when"), + ] + for spec, said in bad: + with pytest.raises(ValueError, match=said): + automation_spec.check_if({"seen": spec}) + with pytest.raises(ValueError, match="seen stands alone"): + automation_spec.check_if({"seen": {"kinds": ["test_mail.came"], "within": "1d"}, "path": "x"}) + + +def test_seen_reads_in_words(): + def words(**s): + return match.describe(automation_spec.check_if({"seen": {"kinds": ["test_mail.came"], "within": "2d", **s}})) + + assert words() == "at least one of “Mail came” in the last 2 days" + assert words(same="object.from", count={"at_least": 3}) == "at least 3 of “Mail came” in the last 2 days, with the same object.from" + assert words(count={"at_most": 0}, where={"path": "object.name", "op": "contains", "value": "trip"}) == ( + "none of “Mail came” in the last 2 days, where the name contains “trip”" + ) + assert words(count={"at_least": 1, "at_most": 4}) == "1 to 4 of “Mail came” in the last 2 days" + negated = automation_spec.check_if({"not": {"seen": {"kinds": ["test_mail.came", "test_mail.sent"], "within": "1h"}}}) + assert match.describe(negated) == "none of “Mail came” or “Mail sent” in the last 1 hour" From 8abcee4d3bab91ff95f7d583fbc67c5cfc2dbef6 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sat, 17 Oct 2026 02:43:55 +0000 Subject: [PATCH 2/3] feat(automations): look back and compare in running automations An automation's If and its graph's conditions are tested with the run's clock, time zone, one State for changed, and its namespaces and person for seen; a trigger's where compares changed with its last activity. automations.py looks up automation_nodes.provided when called, so importing workflows first no longer fails on a circular import. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01AjJqXgjj1cNdKGRQbX5frb --- CHANGELOG.md | 5 ++ README.md | 3 +- docs/automations.md | 12 ++- docs/requirements.md | 1 + fastapi_backend/app/domain/automations.py | 37 ++++++++- .../domain/test_automation_conditions.py | 83 +++++++++++++++++++ 6 files changed, 133 insertions(+), 8 deletions(-) create mode 100644 fastapi_backend/tests/domain/test_automation_conditions.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ee3f4298..be4c8e328 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version two, before or after a time or within a duration, falls on certain days or times of day, and whether a value changed since the last activity. Each value is checked when it's saved, and patterns that could tie up the worker are refused ([Operators](docs/automations.md#operators)). +- **Automations look back.** An automation's If can ask whether something like this happened before: activities of + some kinds within a time, from the same sender or about the same thing, at least or at most so many times, looked for + only in the automation's namespaces and only as its person may see them. `changed` in a trigger's where or an If + compares each activity with the last one, and trying an automation keeps nothing + ([Looking back](docs/automations.md#looking-back)). - **Specs from transcripts.** Turn a voice session or a meeting into a technical spec, saved as a note linked to it: the model writes the spec, then lists every named decision, every "no" and "not that, this", every constraint and every gap the speaker left to decide later, each with its quote and a link to the moment it was said; a quote the diff --git a/README.md b/README.md index 6f93f6e3d..8bbcc7c9f 100644 --- a/README.md +++ b/README.md @@ -148,7 +148,8 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p warnings) is kept as a stream of activities in W3C Activity Streams form, which agents read through the API, MCP and the assistant, and people review on the Timeline page (and Latest on Home), marking what they've seen. Automations act on that stream, on a schedule, at a time or when their own webhook is called: they test conditions (text, patterns, - numbers, lists, times, days and whether a value changed), then tell you in + numbers, lists, times, days, whether a value changed and whether something like it happened before in their + namespaces), then tell you in your own chat app, ask the model or the agent, use a tool, call a web address (its credentials kept sealed), run a workflow, pipeline or routine, or change assets and notes. A Classify node in a workflow sorts an asset into labels, content types or topics, acting only on a sure answer. Anything that reaches outside Lens or changes more than what diff --git a/docs/automations.md b/docs/automations.md index 9fcf24855..020868621 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -399,7 +399,7 @@ cheap) can ask whether something happened before: a `seen` stands where a test w - `count` is `{"at_least": n}` (1 when not given), `{"at_most": n}` or both, up to 100: `{"at_most": 0}` reads "if nothing like it came", as in "if I haven't replied within 2 days". - It reads at most 200 activities, of the automation's namespaces (`env["spaces"]`) and as the automation's person - (`env["account"]`) may see them; `env["db"]` and `env["cfg"]` give the database. Without a database it finds + (`env["viewer"]`, or `env["account"]`) may see them; `env["db"]` and `env["cfg"]` give the database. Without a database it finds nothing. Its `where` is tested with the same `env` (so its clock too) and can't test `changed`. - In words: `at least one of “Email received” in the last 2 days, with the same sender`. @@ -1094,7 +1094,8 @@ Each new activity is checked against each trigger that listens for its kind (a w - an automation made it, unless the trigger says `from_automations`; - it is the end of a chain of automations setting each other off as long as `automations.max_depth` (3); - it isn't in one of the automation's namespaces, or the automation's person may not see it; -- the trigger's `where` doesn't match it. +- the trigger's `where` doesn't match it (in the trigger's time zone; a `changed` in it compares with the last + activity the trigger saw). Then it is claimed (for the automation, trigger and activity together), so it runs each automation once, even with the API and a worker both following. **`automations.fire(db, cfg, automation_id, alias, activity, events=None, dry=False)`** @@ -1103,8 +1104,11 @@ joins); it gives the run's id, or none when nothing ran. A run goes: 1. **Its person**: if the person it acts for lost their account, their admin role (for one that works everywhere) or the right to edit one of its namespaces, the run fails saying so, and the automation is switched off. -2. **The If**, on the [run context](#run-context). When it is false the run stops there: it counts in - `counters.skipped`, uses up no limit and makes no run and no activity. +2. **The If**, on the [run context](#run-context), with the run's clock and time zone: a `seen` in it looks back in + the automation's namespaces as its person may see, and `changed` compares with what the automation saw last + ([Operators](#operators)). The If and the graph's condition, filter and switch nodes share one State a run, so a + node testing what the If tested agrees with it; a dry run keeps nothing. When it is false the run stops there: it + counts in `counters.skipped`, uses up no limit and makes no run and no activity. 3. **Limits**: the automation's `cooldown` (the wait between runs) and `max_per_hour`, then every automation's runs together this minute (`automations.max_runs_per_minute`, 60). Over one, nothing runs: it counts in `counters.limited` and says so in the stream (`automation.limited`) at most once an hour. diff --git a/docs/requirements.md b/docs/requirements.md index c38286a14..b737234a2 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -185,6 +185,7 @@ request, to another check that proves the same thing; loosening a requirement or | They test conditions, then tell you, ask the model or the agent, use a tool, call a web address with sealed credentials, run Lens work, or change assets and notes | [test_automation_runs.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_runs.py) `test_the_if_limits_and_dry_runs`; [test_actions_messages.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_messages.py) `test_notify_tells_me_in_my_chat_app`; [test_actions_ai.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_ai.py) `test_ask_model_answers_in_text_or_as_the_fields_a_schema_names`, `test_ask_agent_works_on_what_happened_and_saves_the_conversation`, `test_call_tool_reads_as_the_person_and_changes_only_by_asking_them`; [test_actions_web.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_web.py) `test_credentials_in_headers_are_sealed_to_the_automation_and_the_host_and_never_shown`; [test_actions_run.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_run.py) `test_run_workflow_queues_it_on_the_asset_as_the_automation`, `test_run_pipeline_processes_the_asset_again`; [test_actions_lens.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_actions_lens.py) `test_set_field_is_kept_in_the_assets_history_by_the_automation`, `test_write_note_writes_a_page_adds_to_a_things_page_or_notes_an_asset` | | What reaches outside Lens, or changes more than what set it off, asks first: on the Approvals page or with a yes in chat; agents decline but never approve | [test_automation_spec.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_spec.py) `test_risk_follows_the_effect`; [test_approvals.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_approvals.py) `test_approve_carries_the_action_out_and_the_run_records_it`, `test_agents_over_mcp_list_and_decline_but_never_approve`; [test_approvals_chat.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_approvals_chat.py) `test_a_yes_in_my_chat_decides_an_action_inside_lens`; [approvals-page.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/approvals-page.test.tsx) `groups what waits, puts the first in focus, and Enter approves it` | | Conditions test text, patterns, numbers, lists, times, days and whether a value changed, checked as they're saved and read in words | [test_match_ops.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_ops.py) `test_each_test_passes_what_it_should`, `test_checks_refuse_values_a_test_cant_use`, `test_a_pattern_reads_a_long_value_only_so_far_and_gives_up_when_slow`, `test_changed_compares_with_the_last_value_seen`, `test_the_added_tests_read_in_words` | +| Conditions look back over what happened in the automation's namespaces, as its person may see it, and compare each activity with the last one; a dry run keeps nothing | [test_match_seen.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_seen.py) `test_seen_finds_what_happened_in_the_window`, `test_an_if_looks_back_and_reads_the_context`, `test_seen_is_only_for_an_automations_if`; [test_automation_conditions.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_conditions.py) `test_the_if_looks_back_in_the_automations_namespaces`, `test_changed_in_a_where_compares_with_the_last_activity`, `test_the_if_and_a_condition_node_agree_and_dry_runs_keep_nothing` | | Each automation has limits and budgets | [test_automation_runs.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_runs.py) `test_the_if_limits_and_dry_runs`, `test_a_run_over_budget_is_held_for_the_persons_pick` | | Agents make, try and run automations over MCP and in the assistant, or draft one from a sentence | [test_automation_tools.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_tools.py) `test_agents_save_try_and_run_automations_over_mcp`, `test_the_assistant_saves_at_once_and_asks_to_switch_on_or_run`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_an_automation_is_drafted_from_a_sentence` | diff --git a/fastapi_backend/app/domain/automations.py b/fastapi_backend/app/domain/automations.py index 197d789a8..19440b89d 100644 --- a/fastapi_backend/app/domain/automations.py +++ b/fastapi_backend/app/domain/automations.py @@ -38,6 +38,7 @@ match, store, telemetry, + variables, workflows, ) from . import activity as activity_mod @@ -682,8 +683,9 @@ def run(db, cfg, aid, alias, activity, evs=None, dry=False, by=None, over_budget auto = {"id": row.get("id"), "name": row["name"], "version": version, "spaces": row.get("spaces")} trigger = {"as": trig["as"], "on": trig["on"], "timezone": trig.get("timezone")} ctx = automation_nodes.context(db, cfg, auto, {"id": run_id, "dry": dry}, trigger, activity, evs, person) + env = _env(db, cfg, row, trig["as"], ctx, account, dry) # the If first: a run it stops uses up no limit, holds no budget and makes no row - if row.get("condition") and not match.test(row["condition"], ctx): + if row.get("condition") and not match.test(row["condition"], ctx, env): if not dry: db.q("UPDATE $r SET counters.skipped += 1", r=R("automation", row["id"])) return {**out, "status": "skipped", "why": "its If was false"} @@ -739,7 +741,16 @@ def say(msg): ) who = f"automation:{row['id']}" if row.get("id") is not None else None r = flow.Run( - db, cfg, workflows.KITS["event"], ctx, say, dry=dry, user=who, origin={"automation": row.get("id"), "run": run_id}, intents=box + db, + cfg, + workflows.KITS["event"], + ctx, + say, + dry=dry, + user=who, + origin={"automation": row.get("id"), "run": run_id}, + intents=box, + env=env, ) run_refs = [x for x in (who, f"automation_run:{run_id}" if run_id else None) if x] error = None @@ -805,6 +816,21 @@ def say(msg): return got +def _env(db, cfg, row, alias, ctx, account, dry): + """What a run's If and its graph's conditions test with (match.test's env): the run's clock and time zone, one + State for `changed` (so the If and a node testing the same thing agree), and its namespaces and person for + looking back (`seen`).""" + return { + "db": db, + "cfg": cfg, + "now": ctx.get("now"), + "timezone": ctx.get("timezone"), + "spaces": row.get("spaces"), + "viewer": _viewer(db, account) if account else None, + "state": match.State(db, row.get("id"), alias, dry=dry or row.get("id") is None), + } + + def _failed(db, cfg, row, alias, activity, evs, by, now, why): """A run that can't happen because its person lost access: failed, saying why, and the automation switched off.""" run_id = db.next_id("automation_run") @@ -921,6 +947,11 @@ def _after(t, since): return False +def _where_env(db, a, t): + """What a trigger's where tests with: the trigger's time zone and its own State for `changed`.""" + return {"timezone": variables.timezone_of(a, t), "state": match.State(db, a["id"], t["as"])} + + def _route(db, cfg, a, t, act, who, sec): """One activity against one trigger: the guards, a claim so it's handled once, then on to its run (or a join, or a timer). How many runs it started.""" @@ -938,7 +969,7 @@ def _route(db, cfg, a, t, act, who, sec): return 0 if t["on"] == "webhook" and (act.get("object") or {}).get("hook") != t.get("hook"): return 0 - if t.get("where") and not match.test(t["where"], act): + if t.get("where") and not match.test(t["where"], act, _where_env(db, a, t)): return 0 if not events.claim(db, CONSUMER, f"{a['id']}|{t['as']}|{act['id']}"): return 0 diff --git a/fastapi_backend/tests/domain/test_automation_conditions.py b/fastapi_backend/tests/domain/test_automation_conditions.py new file mode 100644 index 000000000..7a7a26075 --- /dev/null +++ b/fastapi_backend/tests/domain/test_automation_conditions.py @@ -0,0 +1,83 @@ +"""Conditions in running automations (docs/automations.md, Running automations): an automation's If looks back over +the stream (`seen`) in its own namespaces, as its person may see; `changed` in a trigger's where compares each +activity with the last one; the If and a condition node testing the same thing agree within a run; a dry run keeps +nothing.""" + +from __future__ import annotations + +import pytest + +from app.domain import auth, automations, events, store +from tests.helpers import make_user + + +def node(nid, t, **config): + return {"id": nid, "type": t, "config": config} + + +SAY = { + "nodes": [node("i", "input"), node("a", "action", action="log_line", params={"text": "Mail from {{ event.object.from.0 }}"})], + "edges": [{"source": "i", "target": "a"}], +} +MAIL = [{"as": "mail", "on": "event", "kinds": ["test_mail.came"]}] + + +@pytest.fixture +def env(db, cfg): + before = dict(events._KINDS) + events.kind("test_mail.came", label="Mail came", source="log", as_type="Create", object_type="Note") + events._seen.clear() + events._claimed.clear() + pods, calls = store.ns_id(db, "pods"), store.ns_id(db, "calls") + make_user(db, "ed@x.io", "editor password 1", roles={"pods": "editor"}) + yield {"pods": pods, "calls": calls, "ed": {**auth.find_account(db, "ed@x.io"), "admin": False}} + events._KINDS.clear() + events._KINDS.update(before) + + +def mail(db, cfg, sender, space, name="Trip"): + aid = events.emit( + db, "test_mail.came", actor=events.LENS, obj={"type": "Note", "name": name, "from": [sender]}, space=space, summary=name + ) + return events.get(db, cfg, aid, events.viewer(1, None, admin=True)) + + +def make(db, cfg, who, **over): + return automations.create(db, cfg, {"name": "Mail", "triggers": MAIL, "graph": SAY, "spaces": [over.pop("space")], **over}, who)["id"] + + +def test_the_if_looks_back_in_the_automations_namespaces(db, cfg, env): + again = {"seen": {"kinds": ["test_mail.came"], "within": "1d", "same": "object.from"}} + aid = make(db, cfg, env["ed"], space=env["pods"], **{"if": again}) + assert automations.fire(db, cfg, aid, "mail", mail(db, cfg, "office@stmarys.org", env["pods"])) is None # the first one + mail(db, cfg, "club@example.com", env["calls"]) # a namespace the automation isn't in + assert automations.fire(db, cfg, aid, "mail", mail(db, cfg, "club@example.com", env["pods"])) is None + run = automations.fire(db, cfg, aid, "mail", mail(db, cfg, "office@stmarys.org", env["pods"])) + assert run and automations.get_run(db, run)["intents"][0]["result"]["line"] == "Mail from office@stmarys.org" + assert automations.get(db, aid)["counters"]["skipped"] == 2 + + +def test_changed_in_a_where_compares_with_the_last_activity(db, cfg, env): + where = {"path": "object.name", "op": "changed"} + aid = make(db, cfg, env["ed"], space=env["pods"], triggers=[{**MAIL[0], "where": where}]) + a = automations.get(db, aid) + who = automations._viewer(db, auth.get_account(db, env["ed"]["id"])) + sec = automations.section(cfg) + names = ["Open", "Open", "Closed", "Closed", "Open"] + got = [automations._route(db, cfg, a, a["triggers"][0], mail(db, cfg, "door", env["pods"], n), who, sec) for n in names] + assert got == [0, 0, 1, 0, 1] + + +def test_the_if_and_a_condition_node_agree_and_dry_runs_keep_nothing(db, cfg, env): + changed = {"path": "event.object.name", "op": "changed"} + graph = { + "nodes": [*SAY["nodes"][:1], node("c", "condition", match=changed), SAY["nodes"][1]], + "edges": [{"source": "i", "target": "c"}, {"source": "c", "target": "a", "port": "yes"}], + } + aid = make(db, cfg, env["ed"], space=env["pods"], graph=graph, **{"if": changed}) + assert automations.fire(db, cfg, aid, "mail", mail(db, cfg, "door", env["pods"], "Open")) is None # nothing to compare with + # a dry run of a new name passes, but keeps nothing: the next real run still compares with Open + assert automations.test(db, cfg, aid, activity=mail(db, cfg, "door", env["pods"], "Closed"))["status"] == "done" + run = automations.fire(db, cfg, aid, "mail", mail(db, cfg, "door", env["pods"], "Closed")) + assert run and automations.get_run(db, run)["trace"]["a"]["status"] == "done" # the node saw the If's change + assert automations.fire(db, cfg, aid, "mail", mail(db, cfg, "door", env["pods"], "Closed")) is None From ff713261ceb7fdad471609c9571ea50d09886cff Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 02:15:45 +0000 Subject: [PATCH 3/3] fix(store): run a query made inside another on the same thread Python can close an abandoned generator (a streamed chat answer whose reader navigated away) in the middle of any query, on whatever thread is running when the garbage collector fires. That generator's cleanup queries, and with the embedded engine's single connection held by the very thread it runs on, it waited for ever and took every other thread with it: the server froze until the process was killed (the Clicks check hitting this on main is how it was found; a py-spy dump shows the guard middleware's settings query holding the connection while the stream's `on.end()` waits in `_pool.get()`). The handle now records the connection a thread is inside a query on. A nested query on an embedded engine shares it: while Python runs, the outer query is between sends, so the inner one is safe on it. Against a server the inner query still takes another connection from the pool. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01AjJqXgjj1cNdKGRQbX5frb --- CHANGELOG.md | 4 +++ docs/database.md | 4 ++- fastapi_backend/app/domain/store.py | 20 ++++++++++- .../tests/domain/test_store_nested.py | 36 +++++++++++++++++++ 4 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 fastapi_backend/tests/domain/test_store_nested.py diff --git a/CHANGELOG.md b/CHANGELOG.md index be4c8e328..07f172b59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -84,6 +84,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version - **Agents follow news feeds.** `subscribe_feed` (MCP and the assistant, admins) follows a feed into a namespace in one step, checked before it's kept; `news_feeds` lists them and `unsubscribe_feed` stops one ([News feeds](docs/processing.md#news-feeds-rss-and-atom)). +- **Fixed: Lens could freeze after an answer.** When a browser left a streaming answer early, the cleanup of that + stream could wait for a database connection its own thread already held, and every request after it waited too. + A query made inside another on the same thread now runs on that connection + ([Concurrency](docs/database.md#concurrency)). ## 0.14.0 October 17, 2026 {id="0.14.0"} diff --git a/docs/database.md b/docs/database.md index de85f27c8..254bbfff4 100644 --- a/docs/database.md +++ b/docs/database.md @@ -163,7 +163,9 @@ are in `.upgrade-check/` (on GitHub, the run's `upgrade-check` artifact). ## Concurrency The handle (`store.DB`) is thread-safe. Against a server it keeps a small pool of connections; the embedded engine has -one connection that queries take turns on. SurrealDB transactions are optimistic: when two touch the same record at +one connection that queries take turns on. A query made on a thread that is already inside one (Python closing an +abandoned generator in the middle of a query, say) shares that thread's connection rather than waiting for it. +SurrealDB transactions are optimistic: when two touch the same record at once, one fails with a retryable write conflict. The handle retries those automatically, with jittered backoff, for single statements and for `run()` transactions (which roll back as a whole, so retrying is safe). diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index 6803f6e43..9b8419d2a 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -945,6 +945,7 @@ def __init__(self, cfg, pool_size=None): self._all = [] # one connection now, the rest of the pool as concurrent queries need them: each server sign-in costs time self._size, self._grow_lock = size, threading.Lock() + self._held = threading.local() # the connection this thread is inside a query on (conn) try: c = self._open() self._all.append(c) @@ -1011,17 +1012,34 @@ def closed(self): def conn(self): """A connection from the pool. A server connection that has dropped (the server restarted, or a keepalive ping went unanswered while the machine slept) is replaced: without that, every query sent on it fails until - the process restarts.""" + the process restarts. + + A query made on a thread that is already inside one (Python can close an abandoned generator, such as a + streamed response whose reader went away, in the middle of any query, and its cleanup may query) shares that + thread's connection when the engine is embedded: it has the one connection, and waiting for it would wait for + ever, with every other thread behind. While Python runs, the outer query is between sends, so the inner one + is safe on it. A server has a pool, so there the inner query takes another connection.""" + held = getattr(self, "_held", None) # a handle made without __init__ (tests) keeps no record of its thread + outer = getattr(held, "c", None) + if outer is not None and self.embedded: + yield outer + return c = self._take() + if held is not None: + held.c = c try: if _closed(c): c = self._replace(c) + if held is not None: + held.c = c yield c except Exception as e: if not self.embedded and _lost(e): c = self._replace(c) raise finally: + if held is not None: + held.c = outer self._pool.put(c) def _take(self): diff --git a/fastapi_backend/tests/domain/test_store_nested.py b/fastapi_backend/tests/domain/test_store_nested.py new file mode 100644 index 000000000..c1472a845 --- /dev/null +++ b/fastapi_backend/tests/domain/test_store_nested.py @@ -0,0 +1,36 @@ +"""The database handle's connections: a query made inside another on the same thread runs instead of waiting for ever. +Python can close an abandoned generator (a streamed response whose reader went away) in the middle of any query, and +when its cleanup queries, the embedded engine's one connection is held by that very thread.""" + +from __future__ import annotations + +import threading + + +def test_a_query_inside_another_on_the_same_thread_runs(db): + got = [] + + def nested(): + with db.conn(): # a query in flight on this thread holds the connection + got.append(db.values("RETURN 1")) # what a generator's cleanup, run by the garbage collector here, does + + t = threading.Thread(target=nested, daemon=True) + t.start() + t.join(10) + assert not t.is_alive(), "the inner query waited for the connection its own thread holds" + assert got == [[1]] + + +def test_the_connection_goes_back_to_the_pool_after_nested_queries(db): + with db.conn() as c: + assert db.values("RETURN 2") == [2] + with db.conn() as inner: + assert db.values("RETURN 3") == [3] + if db.embedded: + assert inner is c + # free again: another thread gets it at once + got = [] + t = threading.Thread(target=lambda: got.append(db.values("RETURN 4")), daemon=True) + t.start() + t.join(10) + assert got == [[4]]