From c6d36d83c527713f065e13f06d91bc6c613dde82 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Fri, 16 Oct 2026 00:04:36 +0000 Subject: [PATCH] feat(automations): actions that wait, carried out at their time timers.later(db, intent) keeps an intent with a delay or a when as the timer intent-. When its time comes, timers.risk_now works its risk out again from the automation as it is then (its policy and namespaces now, the stricter effect, the action's own check): a routine one runs through actions.perform as the automation, inside its run's cause and ledger scope; one that should ask becomes an approval (approvals.ask once it exists). The run hears of each step through automations.update_intent, and an intent whose automation was switched off, whose timer was cancelled or that Lens missed expires. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01KfD6cia42GiEZakbs74jxY --- docs/automations.md | 31 +++- fastapi_backend/app/domain/timers.py | 121 +++++++++++++- .../tests/domain/test_automation_nodes.py | 9 +- .../tests/domain/test_timer_intents.py | 152 ++++++++++++++++++ 4 files changed, 306 insertions(+), 7 deletions(-) create mode 100644 fastapi_backend/tests/domain/test_timer_intents.py diff --git a/docs/automations.md b/docs/automations.md index 24a3fd34a..dd48f9835 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -33,7 +33,7 @@ merged is called built. | A webhook address per automation trigger, and calls to it as `webhook.received` ([Webhook trigger](#webhook-trigger)) | built | | Timers that outlast a restart and fire once across the API and the worker (`app/domain/timers.py`, [Time](#time)) | built | | The timers behind schedule, `at` and `relative` triggers, the `clock.tick` kind and what's coming ([Time](#time)); automations set them once they are stored | built | -| Actions that wait (`delay`, `when`) ([Time](#time)) | planned | +| Actions that wait (`delay`, `when`): kept as timers, carried out at their time, asking first when they should then ([Time](#time)) | built | | The Timeline page with filters, grouping, review keys and new items, and Home's Latest card ([Timeline](timeline.md)) | built | | Storing and running automations, joins, approvals, variables, the studio | planned | @@ -422,7 +422,8 @@ Checked when it is saved, on every path (create, a new version, a body): with params that fit its schema, and each template in its params is valid. - **The leaf rule:** an action that reaches outside Lens or other people (effect `out`, worked out from its params) or that waits has nothing connected after it, as it can't pass anything on while it waits for a yes or its time. -- Waiting before an action (`delay`, `when`) is refused as coming soon until timers are built. +- Waiting before an action takes a `delay` (more than 0, like `30m`) or a `when` (a time, or a template giving one), + not both; it is kept as a timer ([Actions that wait](#actions-that-wait)). Its automation runs it: an event workflow isn't run on an asset, as a pipeline step or as a routine's action, and the canvas's list of workflows leaves it out (`GET /api/v1/workflows?scope=event` lists them). @@ -636,6 +637,30 @@ timers.clock_state(db, automation) # each schedule and at trigger: wai schedule with `GET /api/v1/routines/schedule`, which now reads weekdays, single days and days of the month in words too ("every weekday at 07:00", "at 09:00 on the 20th of every month"). +### Actions that wait + +Built as timers; the automation's run hands them over once automations are stored. An action node with a `delay` +(`2h`) or a `when` (a time, or a template giving one) makes an intent with that time and status `scheduled`, and +`timers.later(db, intent)` keeps it as the timer `intent-` (its run and node, like `intent-51-n7`), giving +back `{timer, at}` to keep with the intent. The run's page shows it as "scheduled for 18:22". + +When its time comes, its risk is worked out again (`timers.risk_now`) from the automation as it is then, not as it +was when the run made the intent: + +- `read` and `self` run on their own. +- `lens` runs on its own only if it did when the run made it (the event's own object) and its namespaces are still + the automation's. +- `out` runs on its own only while the person still has that node set to run on its own; otherwise it asks. +- The action's own check may only make it stricter. The effect is the stricter of the intent's and what its params + give now. + +A routine one is carried out through `actions.perform` as the automation (its person's permissions as they are then), +inside its run's cause (what it makes carries `lens.cause`, for the loop guard) and its ledger scope +(`automation:`, `automation_run:`). One that should ask becomes an approval (`approvals.ask`, once approvals +are built; until then it waits, saying why). The run hears of each step through `automations.update_intent`: done +with what it gave back, failed with why, waiting, or expired when the automation was switched off or removed first, +the timer was cancelled, or Lens was off past the catch-up window. + ## Refine later - More operators: `in`, `matches` (bounded regular expressions), `between`, times against now, `changed`. @@ -674,7 +699,7 @@ timers.clock_state(db, automation) # each schedule and at trigger: wai - Calling a web address: secrets in the address itself (a Slack or Discord webhook URL) sealed like headers; PATCH and DELETE (DELETE would count as deleting); OAuth sign-in for an API; form-encoded bodies; retries with backoff; networks allowed for automations apart from notifications. -- Time: calendar-aware schedules ("first workday of the month", holidays); sunrise and sunset triggers; an all-day +- Time: an action that waits shown in the person's time zone in `upcoming` (today UTC); calendar-aware schedules ("first workday of the month", holidays); sunrise and sunset triggers; an all-day event's date in the person's time zone rather than UTC; upcoming relative timers in the person's time zone; an event that's cancelled calling off its relative timers; the timeline's kind filter leaving out `clock.tick`, which is never stored; sub-second timers woken by `events.wake()` alone; telling the other process (the worker) at once when the diff --git a/fastapi_backend/app/domain/timers.py b/fastapi_backend/app/domain/timers.py index 5c060b6dd..aca3b0cdb 100644 --- a/fastapi_backend/app/domain/timers.py +++ b/fastapi_backend/app/domain/timers.py @@ -12,7 +12,8 @@ What sets them: `schedule_automation` (an automation's schedule and at triggers; they fire it with a `clock.tick` activity), `relative` (a relative trigger's time for one activity, moved when the activity's object moves), and -`upcoming` lists what an automation has waiting, in words. +`later` (an action that waits: carried out at its time, asking first when it should then). `upcoming` lists what an +automation has waiting, in words. While Lens was off: a timer due within automations.catch_up (1 hour by default) fires late, with `late: true` in its payload; an older one is missed (counted on its automation). A repeating one fires once, for its latest time in the @@ -23,6 +24,7 @@ from __future__ import annotations +import contextlib import datetime as dt import hashlib import json @@ -600,6 +602,114 @@ def relative(db, automation, alias, activity, field, offset="0s", now=None): return {"key": key, "at": _iso(when), "set": True, "note": None} +# ---------- actions that wait ---------- +PERFORM = "intent.perform" # carry out an intent whose time came (an action node with a delay or a when) +_STRICT = {e: n for n, e in enumerate(automation_spec.EFFECTS)} # read, self, lens, out: each reaches further + + +def later(db, intent, depth=1): + """Keep an intent that waits for its time (an action node with a `delay` or a `when`; M6 hands it here): a timer + at its `when`, `intent-`, that carries it out then, asking first when it should (`risk_now`). `depth` is + the run's (for the loop guard on what it causes). What to keep with the intent: {timer, at}.""" + i = automation_spec.check_intent(intent) + if not i["when"]: + raise ValueError(f"intent {i['key']} doesn't say when it runs (when)") + key = f"intent-{i['key']}" + payload = {"intent": {**i, "status": "scheduled"}, "depth": max(1, int(depth or 1))} + row = set(db, key, i["when"], PERFORM, payload, i["automation"]) + return {"timer": key, "at": row["at"]} + + +def _automation_now(db, aid): + """The automation as it is stored now ({enabled, policy, spaces}); None when it isn't (removed, or automations + aren't stored yet).""" + if aid is None: + return None + try: + return db.one("SELECT enabled, policy, spaces FROM $r", r=R("automation", int(aid))) + except Exception: # noqa: BLE001 - no automation table yet + return None + + +def risk_now(db, intent, automation=None): + """routine or ask, worked out again for an intent whose time came: from its effect (the stricter of the one it was + made with and what its params give now), the automation's policy now (an out action runs on its own only while + its node is set to), its namespaces now (a lens action stays routine only on the event's own object, in + namespaces the automation still has), and the action's own check, which may only be stricter. `automation` is the + stored automation ({policy, spaces}), or None when there is none to read: then an out action asks.""" + from . import actions + + spec = actions.get(intent["action"]) + effect = max(intent["effect"], actions.effect_of(spec, intent["params"]), key=lambda e: _STRICT.get(e, 3)) + policy = (automation or {}).get("policy") or {} + spaces = (automation or {}).get("spaces") + if effect in ("read", "self"): + risk = "routine" + elif effect == "lens": + still = spaces is None or {int(s) for s in intent["spaces"]} <= {int(s) for s in spaces} + risk = "routine" if intent["risk"] == "routine" and still else "ask" + else: + risk = "routine" if policy.get(intent["node"]) == "auto" else "ask" + if risk == "routine" and spec.risk is not None: + ctx = {"automation": {"id": intent["automation"], "spaces": intent["spaces"] if spaces is None else spaces}} + try: + risk = "routine" if spec.risk(intent["params"], {**ctx, "node": intent["node"]}) == "routine" else "ask" + except Exception: # noqa: BLE001 - when the action can't tell, it asks + risk = "ask" + return risk + + +def _intent_status(db, i, status, result=None): + """Say on the run what became of an intent (M6's automations.update_intent owns the run's intents).""" + update = _provided("automations", "update_intent") + if update is None or i.get("run") is None: + log.info("automation %s run %s: intent %s %s", i.get("automation"), i.get("run"), i.get("key"), status) + return + update(db, i["run"], i["key"], status, result) + + +def _intent_ended(db, payload, status, why): + i = payload.get("intent") + if isinstance(i, dict): + _intent_status(db, i, "expired", {"why": why}) + + +@handler(PERFORM, ended=_intent_ended) +def _perform(db, cfg, p): + from . import actions, activity # here: actions loads its action modules, which load routines, which load this + + i = automation_spec.check_intent(p["intent"]) + auto = _automation_now(db, i["automation"]) + if i["automation"] is not None and _provided("automations", "fire") is not None and (not auto or auto.get("enabled") is False): + _intent_status(db, i, "expired", {"why": "the automation was switched off or removed before its time"}) + return + try: + risk = risk_now(db, i, auto) + except KeyError: + _intent_status(db, i, "failed", {"error": f"there's no action {i['action']} any more"}) + raise ValueError(f"there's no action {i['action']} any more") from None + if risk == "ask": + ask = _provided("approvals", "ask") + approval = ask(db, cfg, {**i, "risk": "ask", "status": "waiting"}) if ask is not None else None + _intent_status(db, i, "waiting", store.clean({"approval": approval, "why": "waiting for your pick"})) + return + refs = [] + if i["automation"] is not None: + refs.append(f"automation:{i['automation']}") + if i["run"] is not None: + refs.append(f"automation_run:{i['run']}") + try: + with contextlib.ExitStack() as stack: + if i["automation"] is not None and i["run"] is not None: + stack.enter_context(events.caused_by({"automation": i["automation"], "run": i["run"], "depth": int(p.get("depth") or 1)})) + stack.enter_context(activity.scope(db, *refs, cfg=cfg)) + out = actions.perform(db, cfg, {**i, "risk": "routine", "status": "done"}, None) + except Exception as e: + _intent_status(db, i, "failed", {"error": f"{type(e).__name__}: {e}"[:500]}) + raise + _intent_status(db, i, "done", out) + + # ---------- what is coming ---------- def _describe(r, now): p = r.get("payload") or {} @@ -616,6 +726,15 @@ def _describe(r, now): name = (a.get("object") or {}).get("name") or a.get("summary") or a["id"] what = f"{_offset_words(p.get('offset') or '0s')} “{str(name)[:120]}” {(title or p['field']).lower()}" return f"{what[:1].upper()}{what[1:]}: on {local(r['at'], 'UTC', now)} (UTC)", True + if r["kind"] == PERFORM and isinstance(p.get("intent"), dict): + from . import actions + + i = p["intent"] + try: + what = actions.describe(i["action"], i.get("params") or {}) + except KeyError: + what = i["action"] + return f"{what}: on {local(r['at'], 'UTC', now)} (UTC)", bool(i.get("untrusted")) alias_text = f" of trigger {alias}" if alias else "" return f"{r['kind']}{alias_text}: on {local(r['at'], 'UTC', now)} (UTC)", False diff --git a/fastapi_backend/tests/domain/test_automation_nodes.py b/fastapi_backend/tests/domain/test_automation_nodes.py index ed08447b4..869620d39 100644 --- a/fastapi_backend/tests/domain/test_automation_nodes.py +++ b/fastapi_backend/tests/domain/test_automation_nodes.py @@ -85,7 +85,7 @@ def _problem(db, g): return str(e.value) -def test_event_workflows_are_checked_on_save(db, made): +def test_event_workflows_are_checked_on_save(db, made, monkeypatch): assert "needs an action node" in _problem(db, graph(node("p", "pick", path="event"), edges=[edge("in", "p")])) assert "choose an action" in _problem(db, graph(node("a", "action", action="nope"), edges=[edge("in", "a")])) assert "needs Line (text)" in _problem(db, graph(node("a", "action", action="log_line"), edges=[edge("in", "a")])) @@ -101,9 +101,12 @@ def test_event_workflows_are_checked_on_save(db, made): node("a", "action", action="tag", params={"object": "{{ event.object.id }}", "tags": "{{ event.tag }}"}), edges=[edge("in", "a")] ) assert workflows.validate_graph(db, ok, "event")["nodes"][1]["config"]["params"]["tags"] == "{{ event.tag }}" - # waiting before an action comes with the time module; until then it is refused, as are both kinds of wait + # waiting before an action comes with the time module (timers.later); without it, it is refused waits = graph(node("a", "action", action="log_line", params={"text": "x"}, delay="5m"), edges=[edge("in", "a")]) - assert "coming soon" in _problem(db, waits) + assert workflows.validate_graph(db, waits, "event")["nodes"][1]["config"]["delay"] == "5m" + with monkeypatch.context() as m: + m.setattr(automation_nodes, "_timers", lambda: None) + assert "coming soon" in _problem(db, waits) assert "not both" in _problem( db, graph( diff --git a/fastapi_backend/tests/domain/test_timer_intents.py b/fastapi_backend/tests/domain/test_timer_intents.py new file mode 100644 index 000000000..85f56402e --- /dev/null +++ b/fastapi_backend/tests/domain/test_timer_intents.py @@ -0,0 +1,152 @@ +"""Actions that wait: later() keeps an intent as a timer; when its time comes its risk is worked out again from the +automation as it is then, so a routine one runs (as the automation, inside its run's cause and ledger scope) and one +that should ask becomes an approval; switched off, cancelled or missed, it expires.""" + +from __future__ import annotations + +import datetime as dt + +import pytest + +from app.domain import actions, activity, events, store, timers +from app.domain.actions import ActionSpec + +UTC = dt.UTC +WHEN = "2026-10-16T18:22:00Z" +DUE = dt.datetime(2026, 10, 16, 18, 22, 3, tzinfo=UTC) + + +@pytest.fixture +def studio(monkeypatch): + """What M6 and M8 provide (update_intent, fire, approvals.ask), faked, and two actions: test_send (out) and + test_tag (lens), which record what they saw.""" + timers._idle["until"] = 0.0 + log = {"status": [], "asked": [], "done": []} + have = { + ("automations", "update_intent"): lambda db, run, key, status, result=None: log["status"].append((run, key, status, result)), + ("automations", "fire"): lambda *a, **k: None, + ("approvals", "ask"): lambda db, cfg, intent: log["asked"].append(intent) or 77, + } + monkeypatch.setattr(timers, "_provided", lambda module, fn: have.get((module, fn))) + + def did(db, cfg, intent, user, dry): + log["done"].append({"params": intent["params"], "cause": events.cause(), "refs": activity.current(), "user": user}) + if intent["params"].get("fail"): + raise ValueError("the far end said no") + return {"sent": True} + + params = {"type": "object", "properties": {"to": {"type": "string"}, "fail": {"type": "boolean"}}} + monkeypatch.setattr(actions, "_ACTIONS", dict(actions._ACTIONS)) + actions.register(ActionSpec(name="test_send", label="Send", group="Messages", params=params, perform=did, effect="out")) + actions.register( + ActionSpec( + name="test_tag", + label="Tag", + group="Lens", + params=params, + perform=did, + effect="lens", + risk=lambda p, ctx: "ask" if p.get("to") == "everyone" else "routine", + ) + ) + return have, log + + +def intent(action="test_send", node="n7", effect="out", risk="ask", **params): + return { + "key": f"51-{node}", + "action": action, + "params": params, + "effect": effect, + "risk": risk, + "untrusted": False, + "spaces": [3], + "run_as": 1, + "node": node, + "automation": 4, + "run": 51, + "when": WHEN, + "status": "scheduled", + } + + +def automation(db, enabled=True, policy=None, spaces=(3,)): + db.q("UPSERT $r CONTENT $d", r=store.R("automation", 4), d={"enabled": enabled, "policy": policy or {}, "spaces": list(spaces)}) + + +def test_later_keeps_an_intent_until_its_time(db, cfg, studio): + _, log = studio + automation(db) + got = timers.later(db, intent("log_line", effect="read", risk="routine", text="hi"), depth=2) + assert got == {"timer": "intent-51-n7", "at": "2026-10-16T18:22:00+00:00"} + [u] = timers.upcoming(db, 4, now=DUE - dt.timedelta(hours=1)) + assert u["description"] == "Write “hi” to the run log: on Fri 16 Oct at 18:22 (UTC)" and u["node"] == "n7" + assert timers.due(db, cfg, now=DUE - dt.timedelta(minutes=1)) == 0 and log["status"] == [] + assert timers.due(db, cfg, now=DUE) == 1 + assert log["status"] == [(51, "51-n7", "done", {"line": "hi", "level": "info"})] + with pytest.raises(ValueError, match="doesn't say when"): + timers.later(db, {**intent(), "when": None}) + with pytest.raises(ValueError, match="key"): + timers.later(db, {**intent(), "key": "no spaces allowed"}) + + +def test_a_routine_intent_runs_as_the_automation_in_its_run(db, cfg, studio): + _, log = studio + automation(db, policy={"n7": "auto"}) + timers.later(db, intent(to="gateway:family"), depth=2) + assert timers.due(db, cfg, now=DUE) == 1 + [done] = log["done"] + assert done["params"] == {"to": "gateway:family"} and done["user"] is None # actions.person: its run_as + assert done["cause"] == {"automation": 4, "run": 51, "depth": 2} # what it causes carries the run + assert done["refs"][:2] == ["automation:4", "automation_run:51"] # model calls land in the ledger for it + assert log["status"] == [(51, "51-n7", "done", {"sent": True})] and log["asked"] == [] + + +def test_one_that_should_ask_becomes_an_approval(db, cfg, studio): + have, log = studio + automation(db, policy={"n7": "ask"}) # auto when the run made it; the person has since set it back to ask + timers.later(db, intent(risk="routine", to="gateway:family")) + assert timers.due(db, cfg, now=DUE) == 1 + assert log["done"] == [] and log["asked"][0]["risk"] == "ask" and log["asked"][0]["status"] == "waiting" + assert log["status"] == [(51, "51-n7", "waiting", {"approval": 77, "why": "waiting for your pick"})] + # before approvals are built it stays waiting, saying so + del have[("approvals", "ask")] + timers.later(db, intent(node="n8", to="gateway:family")) + assert timers.due(db, cfg, now=DUE) == 1 + assert log["status"][-1] == (51, "51-n8", "waiting", {"why": "waiting for your pick"}) + + +def test_switched_off_cancelled_or_missed_it_expires(db, cfg, studio): + _, log = studio + automation(db, enabled=False, policy={"n7": "auto"}) + timers.later(db, intent()) + assert timers.due(db, cfg, now=DUE) == 1 and log["done"] == [] + assert log["status"][-1][2:] == ("expired", {"why": "the automation was switched off or removed before its time"}) + timers.later(db, intent(node="n8")) + assert timers.cancel_for(db, 4) == 1 + assert log["status"][-1] == (51, "51-n8", "expired", {"why": "the automation was switched off"}) + timers.later(db, intent(node="n9")) + assert timers.due(db, cfg, now=DUE + dt.timedelta(hours=3)) == 0 # Lens was off for three hours + assert log["status"][-1] == (51, "51-n9", "expired", {"why": "Lens was off when it was due"}) + + +def test_a_failure_is_said_on_the_run_and_the_timer(db, cfg, studio): + _, log = studio + automation(db, policy={"n7": "auto"}) + timers.later(db, intent(fail=True)) + assert timers.due(db, cfg, now=DUE) == 1 + assert log["status"][-1] == (51, "51-n7", "failed", {"error": "ValueError: the far end said no"}) + assert timers.get(db, "intent-51-n7")["status"] == "failed" + + +def test_risk_is_worked_out_again_from_the_automation_now(db, studio): + out = intent() + assert timers.risk_now(db, out, None) == "ask" # no automation to read: an out action asks + assert timers.risk_now(db, out, {"policy": {"n7": "auto"}, "spaces": [3]}) == "routine" + assert timers.risk_now(db, {**out, "effect": "read"}, None) == "ask" # its params still reach out + tag = intent("test_tag", effect="lens", risk="routine", to="me") + assert timers.risk_now(db, tag, {"spaces": [3, 5]}) == "routine" + assert timers.risk_now(db, tag, {"spaces": [5]}) == "ask" # its namespace isn't the automation's any more + assert timers.risk_now(db, {**tag, "risk": "ask"}, {"spaces": [3]}) == "ask" + assert timers.risk_now(db, {**tag, "params": {"to": "everyone"}}, None) == "ask" # the action's own check + assert timers.risk_now(db, intent("log_line", effect="read", risk="routine", text="x"), None) == "routine"