From 7a8f92b2f7f84e79dea053fb18348de39d9b345b Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Thu, 15 Oct 2026 17:28:39 +0000 Subject: [PATCH] feat(automations): checks for automation shapes and an action registry Triggers, joins, an If, policy and intents checked with the first problem in words; the run context's keys; and the registry of actions with risk worked out from each action's effect, plus log_line. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01RFQUkVmALkdhRqXY1yFxW5 --- docs/automations.md | 87 ++++- fastapi_backend/app/domain/actions.py | 240 ++++++++++++ fastapi_backend/app/domain/automation_spec.py | 362 ++++++++++++++++++ .../tests/domain/test_automation_spec.py | 288 ++++++++++++++ 4 files changed, 976 insertions(+), 1 deletion(-) create mode 100644 fastapi_backend/app/domain/actions.py create mode 100644 fastapi_backend/app/domain/automation_spec.py create mode 100644 fastapi_backend/tests/domain/test_automation_spec.py diff --git a/docs/automations.md b/docs/automations.md index 999d25e67..6a89c52c7 100644 --- a/docs/automations.md +++ b/docs/automations.md @@ -14,7 +14,9 @@ merged is called built. | New assets as `asset.added` (the `recordings` source) | built | | More kinds: emails, files, calendar events, jobs, deletions, comments, notes, graph changes, sensors, chat | planned | | The timeline API, MCP and assistant tools | planned | -| Automations, triggers, joins, schedules, actions, approvals, variables, the timeline page, the studio | planned | +| The shapes of triggers, joins, an If, policy and intents, checked (`app/domain/automation_spec.py`) | built | +| The action registry with risk from each action's effect, and one action, `log_line` (`app/domain/actions.py`) | built | +| Storing and running automations, schedules and timers, joins, the real actions, approvals, variables, the timeline page, the studio | planned | ## Contract @@ -164,6 +166,89 @@ tree, `path` (when given) is the part of the value the tree tests. Graphs saved {"not": {"path": "attachments", "op": "gt", "value": 5}}]}}} ``` +### Automations: triggers and joins + +Built as shapes with checks (`app/domain/automation_spec.py`); storing and running automations is planned. Each check +gives a cleaned copy, or a ValueError naming the first problem. + +```json +{"name": "School emails", "enabled": true, "spaces": [3], "run_as": 1, + "triggers": [{"as": "mail", "on": "event", "kinds": ["email.received"], + "where": {"all": [{"path": "object.from.0", "op": "contains", "value": "@stmarys.org"}]}}, + {"as": "morning", "on": "schedule", "cron": "0 7 * * 1-5", "timezone": "Europe/London"}], + "join": {"mode": "any"}, + "if": {"all": [{"path": "events.mail.object.subject", "op": "contains", "value": "trip"}]}, + "workflow": 12, "policy": {"n7": "ask"}} +``` + +- `check_trigger(t)`, `check_triggers(list)`: one to ten triggers, each named once in `as` (lowercase letters, + digits and `_`). `on` is `event` (`kinds`, an optional `where` match tree, `from_automations`, false by default so + activities made by automations are left out), `schedule` (`cron`, five fields as routines take them, and + `timezone`), `at` (one moment, in `timezone`), `relative` (a time `field` of a matching activity plus an + `offset`, which may point back: `-30m`), `webhook` (`hook`, given when the automation is saved) or `manual`. +- `check_join(j, aliases)`: how the triggers make a run. `any` (the default): each on its own. `all`: every trigger + `within` a time, optionally on the same `key` path. `count`: `at_least` n of trigger `of` `within`. `absent`: + after trigger `after`, trigger `missing` not seen `within`. `batch`: collect what matches `within`, then one run. +- `check_duration(text, back=False)`: seconds in `30s`, `30m`, `2h` or `7d` (at most a year); a minus only where an + offset may point back. +- `check_if(tree)`: the If is a match tree over the run context, so its paths start with one of the context's keys. +- `check_policy(p, nodes, allow_auto=False)`: `{action node id: ask or auto}`. Only a person in a signed-in session + lets a node run on its own; everywhere else (agents, drafts, the workflow API) `auto` is refused. + +### Run context + +What an automation's If, its nodes and its templates see (`automation_spec.context_paths()` lists the keys, with +titles, for the variable picker): + +| Key | Holds | +| --- | --- | +| `event` | the activity that started the run (for a join, the last one) | +| `events` | each trigger's activity by its name, such as `events.mail` | +| `trigger` | the trigger that fired: `{as, on}` | +| `automation` | `{id, name, version, spaces}` | +| `run` | `{id, dry}` | +| `namespace` | `{id, name}` | +| `user` | who the automation acts for: `{id, name, email}` | +| `now`, `timezone` | when the run started (ISO 8601 in UTC) and the person's time zone | +| `vars` | the automation's and its namespace's saved variables | +| `steps` | what each node passed on so far, by node id, such as `steps.n3` | + +### Actions and intents + +Built: the registry (`app/domain/actions.py`). An action is registered with `actions.register(ActionSpec(name, +label, group, params, perform, required=(), effect="read", risk=None, output=None, describe=None, subject=None))`: +`params` is a JSON Schema of type object, `perform(db, cfg, intent, user, dry)` carries it out and gives a dict (with +`dry`, it says what it would do and changes nothing). `actions.catalog()` lists every action for the builder and +agents, `actions.get(name)` gives one, `actions.check_params(spec, params)` checks params and fills in defaults (a +string holding `{{ }}` stands for any type, since it is filled in when the action runs), and `actions.perform(db, +cfg, intent, user, dry=False)` checks an intent and carries it out. + +When an action node runs, it makes an **intent**, checked by `automation_spec.check_intent`: + +```json +{"key": "51-n7", "action": "notify", "params": {"to": "me", "text": "School trip on Friday"}, "effect": "self", + "risk": "routine", "untrusted": true, "spaces": [3], "run_as": 1, "node": "n7", "automation": 4, "run": 51, + "when": null, "status": "waiting"} +``` + +Its status is `waiting`, `scheduled`, `done`, `failed`, `declined` or `expired`. The action's effect decides the +risk (`actions.resolve_risk(spec, params, ctx, policy)`, where `policy` is the node's pick or the automation's whole +policy with the node in `ctx["node"]`): + +| Effect | Means | Risk | +| --- | --- | --- | +| `read` | looks things up, changes nothing (a tool asks for any change itself) | routine | +| `self` | tells or keeps something for the automation's own person only | routine | +| `lens` | changes something inside Lens | routine on the event's own object in the automation's namespaces, else ask | +| `out` | sends outside Lens, reaches other people, or deletes | ask, unless the person set the node to `auto` | + +An effect may be worked out from the params (`notify` to "me" is `self`, to a room is `out`); when it can't be +worked out, it counts as `out`. An action's own `risk` function may make it stricter, never looser. + +| Action | Does | Effect | Output | +| --- | --- | --- | --- | +| `log_line` | puts a line (`text`, `level` info or warning) in the run's log | read | `{line, level}` | + ## Refine later - More operators: `in`, `matches` (bounded regular expressions), `between`, times against now, `changed`. diff --git a/fastapi_backend/app/domain/actions.py b/fastapi_backend/app/domain/actions.py new file mode 100644 index 000000000..fc246864b --- /dev/null +++ b/fastapi_backend/app/domain/actions.py @@ -0,0 +1,240 @@ +"""What automations can do (docs/automations.md, Contract: Actions and intents): one catalog of actions, each +declaring its parameters, its output and its effect, which the canvas, the builder and agents all read. + +An action's effect says how far it reaches, and so whether it may run without asking (`resolve_risk`): + +- `read` looks things up and changes nothing (a tool's own rules ask for any change it makes): routine. +- `self` tells or keeps something for the automation's own person only: routine. +- `lens` changes something inside Lens: routine on the event's own object in the automation's namespaces, else ask. +- `out` sends outside Lens, reaches other people, or deletes: ask, unless the person set that node to run on its own. + +When an action node runs, it renders its params and makes an intent (automation_spec.check_intent); `perform` carries +an intent out, or with `dry` says what it would do and changes nothing. One action ships here, `log_line`; the real +ones come with the actions module. +""" + +from __future__ import annotations + +import logging +import re +from collections.abc import Callable +from dataclasses import dataclass + +from . import automation_spec as spec_ + +NAME_RX = re.compile(r"^[a-z][a-z0-9_]{0,40}$") +GROUPS = ("Messages", "Lens", "Assets", "Web", "AI", "Run") +TYPES = {"string": str, "integer": int, "number": (int, float), "boolean": bool, "array": list, "object": dict} +TEMPLATE = "{{" +log = logging.getLogger("lens.automations") + + +@dataclass(frozen=True) +class ActionSpec: + """One action. `params` is a JSON Schema (type object) for its parameters, `required` the ones it can't do + without. `effect` is one of read, self, lens, out, or fn(params) giving one (a templated param that decides the + reach counts as out). `risk`, fn(params, ctx) giving routine or ask, may only make it stricter. `subject`, + fn(params) giving the `lens:/` a lens action changes, is how a change to the event's own object is + told apart (default: the `object` param). `perform(db, cfg, intent, user, dry)` carries it out and gives a dict + (with `dry`, what it would do, changing nothing); `describe(params)` says it in words.""" + + name: str + label: str + group: str + params: dict + perform: Callable[..., dict] + required: tuple[str, ...] = () + effect: str | Callable[[dict], str] = "read" + risk: Callable[[dict, dict], str] | None = None + output: dict | None = None + describe: Callable[[dict], str] | None = None + subject: Callable[[dict], str | None] | None = None + description: str = "" + + def info(self): + return { + "name": self.name, + "label": self.label, + "group": self.group, + "description": self.description, + "params": self.params, + "required": list(self.required), + "effect": self.effect if isinstance(self.effect, str) else "depends", + "output": self.output, + } + + +_ACTIONS: dict[str, ActionSpec] = {} + + +def register(spec): + """Add an action to the catalog (registering a name again replaces it); the spec.""" + if not isinstance(spec, ActionSpec): + raise ValueError("an action is an ActionSpec") + if not NAME_RX.match(spec.name or ""): + raise ValueError(f"an action is named with lowercase letters, digits and _, not {spec.name}") + if not (spec.label or "").strip(): + raise ValueError(f"action {spec.name}: give it a label") + if spec.group not in GROUPS: + raise ValueError(f"action {spec.name}: its group is one of {', '.join(GROUPS)}") + if not isinstance(spec.params, dict) or spec.params.get("type") != "object": + raise ValueError(f"action {spec.name}: params is a JSON Schema of type object") + props = spec.params.get("properties") or {} + missing = [k for k in spec.required if k not in props] + if missing: + raise ValueError(f"action {spec.name}: required param {missing[0]} isn't in its params") + if isinstance(spec.effect, str) and spec.effect not in spec_.EFFECTS: + raise ValueError(f"action {spec.name}: its effect is one of {', '.join(spec_.EFFECTS)}, or a function giving one") + if not callable(spec.perform): + raise ValueError(f"action {spec.name}: perform is a function") + _ACTIONS[spec.name] = spec + return spec + + +def catalog(): + """Every action, for the canvas palette, the builder and agents.""" + return [s.info() for s in sorted(_ACTIONS.values(), key=lambda s: (GROUPS.index(s.group), s.label))] + + +def get(name): + """One action's spec; KeyError when there's none.""" + return _ACTIONS[name] + + +def _templated(v): + return isinstance(v, str) and TEMPLATE in v + + +def check_params(spec, params): + """An action's params, checked against its schema with defaults filled in: ValueError naming the first problem. + A string holding {{ }} stands for any type, since it is filled in when the action runs.""" + if params is None: + params = {} + if not isinstance(params, dict): + raise ValueError(f"{spec.name}: params are an object") + props = spec.params.get("properties") or {} + extra = sorted(set(params) - set(props)) + if extra and spec.params.get("additionalProperties") is not True: + raise ValueError(f"{spec.name} has no param {extra[0]}") + out = {} + for k, p in props.items(): + v = params.get(k, p.get("default")) + if v is None: + if k in spec.required: + raise ValueError(f"{spec.name} needs {p.get('title') or k} ({k})") + continue + if not _templated(v): + want = TYPES.get(p.get("type")) + if want and (not isinstance(v, want) or (isinstance(v, bool) and p.get("type") in ("integer", "number"))): + raise ValueError(f"{spec.name}: {k} is {'an' if p.get('type')[0] in 'aeiou' else 'a'} {p.get('type')}") + if "enum" in p and v not in p["enum"]: + raise ValueError(f"{spec.name}: {k} is one of {', '.join(map(str, p['enum']))}") + if isinstance(v, str) and p.get("maxLength") and len(v) > p["maxLength"]: + raise ValueError(f"{spec.name}: {k} is at most {p['maxLength']} characters") + out[k] = v + for k in extra: + out[k] = params[k] + return out + + +def effect_of(spec, params): + """The action's effect for these params; out (the strictest) when its function can't tell.""" + if isinstance(spec.effect, str): + return spec.effect + try: + e = spec.effect(params) + except Exception: # noqa: BLE001 - an effect that can't be worked out reaches as far as it could + return "out" + return e if e in spec_.EFFECTS else "out" + + +def _spaces(ctx): + a = (ctx or {}).get("automation") or {} + if a.get("spaces") is not None: + return set(a["spaces"]) + ns = (ctx or {}).get("namespace") or {} + return {ns["id"]} if ns.get("id") is not None else set() + + +def resolve_risk(spec, params, ctx, policy=None): + """routine or ask, from the effect table. `ctx` is the run context (`event`, and `automation.spaces` for the + automation's namespaces); `policy` is the node's pick (ask or auto), or the automation's whole policy with the node + in `ctx["node"]`. Only auto lets an out action run without asking; the action's own `risk` may only be stricter.""" + from . import events + + if isinstance(policy, dict): + policy = policy.get((ctx or {}).get("node")) + effect = effect_of(spec, params) + if effect in ("read", "self"): + risk = "routine" + elif effect == "lens": + event = (ctx or {}).get("event") or {} + own = ((event.get("object") or {}).get("id")) or None + subject = (spec.subject or (lambda p: p.get("object")))(params) + risk = "routine" if own and subject == own and set(events.spaces_of(event)) & _spaces(ctx) else "ask" + else: + risk = "routine" if policy == "auto" else "ask" + if risk == "routine" and spec.risk is not None: + try: + if spec.risk(params, ctx) != "routine": + risk = "ask" + except Exception: # noqa: BLE001 - when the action can't tell, it asks + risk = "ask" + return risk + + +def perform(db, cfg, intent, user, dry=False): + """Carry an intent out as `user` (the person the automation acts for), or with `dry` say what it would do and + change nothing; the action's output. ValueError for an intent or params that don't check.""" + i = spec_.check_intent(intent) + try: + spec = get(i["action"]) + except KeyError: + raise ValueError(f"no action {i['action']}") from None + i["params"] = check_params(spec, i["params"]) + out = spec.perform(db, cfg, i, user, bool(dry)) + if not isinstance(out, dict): + raise ValueError(f"{spec.name} gave {type(out).__name__}, not an object") + return out + + +def describe(name, params): + """What an action would do, in words.""" + spec = get(name) + if spec.describe: + try: + return spec.describe(params or {}) + except Exception: # noqa: BLE001 - fall back to its label + pass + return spec.label + + +# ---------- the reference action ---------- +def _log_line(db, cfg, intent, user, dry): + text = " ".join(str(intent["params"]["text"]).split())[:500] + if not dry: + level = logging.WARNING if intent["params"].get("level") == "warning" else logging.INFO + log.log(level, "automation %s run %s: %s", intent.get("automation"), intent.get("run"), text) + return {"line": text, "level": intent["params"].get("level", "info")} + + +register( + ActionSpec( + name="log_line", + label="Write to the run log", + group="Run", + description="Puts a line in the run's log; useful to see what a run saw, in tests and dry runs.", + params={ + "type": "object", + "properties": { + "text": {"type": "string", "title": "Line", "maxLength": 2000}, + "level": {"type": "string", "title": "Level", "enum": ["info", "warning"], "default": "info"}, + }, + }, + required=("text",), + effect="read", + output={"type": "object", "properties": {"line": {"type": "string"}, "level": {"type": "string"}}}, + perform=_log_line, + describe=lambda p: f"Write “{p.get('text', '')}” to the run log", + ) +) diff --git a/fastapi_backend/app/domain/automation_spec.py b/fastapi_backend/app/domain/automation_spec.py new file mode 100644 index 000000000..be4a96551 --- /dev/null +++ b/fastapi_backend/app/domain/automation_spec.py @@ -0,0 +1,362 @@ +"""The shapes automations are made of (docs/automations.md, Contract: Triggers, Joins, Policy, Intents, Run context), +with checks that give a ValueError naming the first problem, the way routines are checked. + +An automation watches triggers (`check_trigger`): activities from the stream (`event`), the clock (`schedule`, `at`, +`relative` to a time in an activity), its webhook, or a person asking (`manual`). Its join (`check_join`) says how +several triggers make one run. Its If is a match tree over the run context (`check_if`, `context_paths`). Its Then is +a workflow whose action nodes make intents (`check_intent`), each asked about first unless the person's policy for +that node (`check_policy`) says it may run on its own. Nothing is stored here: the automations module stores them. +""" + +from __future__ import annotations + +import datetime as dt +import re +from typing import Literal, NotRequired, TypedDict + +from . import events, match, schedule + +ALIAS_RX = re.compile(r"^[a-z][a-z0-9_]{0,39}$") +NODE_RX = re.compile(r"^[A-Za-z0-9_-]{1,40}$") # a workflow node's id, as flow.py has it +ACTION_RX = re.compile(r"^[a-z][a-z0-9_]{0,40}$") +KEY_RX = re.compile(r"^[A-Za-z0-9_.:|-]{1,200}$") +DURATION_RX = re.compile(r"^(-?)(\d{1,6})(s|m|h|d)$") +UNITS = {"s": 1, "m": 60, "h": 3600, "d": 86400} +MAX_DURATION = 366 * 86400 +MAX_TRIGGERS = 10 +ON = ("event", "schedule", "at", "relative", "webhook", "manual") +KEYS = { # what each kind of trigger takes, next to as and on + "event": {"kinds", "where", "from_automations"}, + "schedule": {"cron", "timezone"}, + "at": {"at", "timezone"}, + "relative": {"kinds", "where", "from_automations", "field", "offset"}, + "webhook": {"hook"}, + "manual": set(), +} +JOIN_MODES = ("any", "all", "count", "absent", "batch") +JOIN_KEYS = { + "any": set(), + "all": {"within", "key"}, + "count": {"of", "at_least", "within", "key"}, + "absent": {"after", "missing", "within", "key"}, + "batch": {"within", "of"}, +} +POLICY = ("ask", "auto") +EFFECTS = ("read", "self", "lens", "out") +RISKS = ("routine", "ask") +STATUSES = ("waiting", "scheduled", "done", "failed", "declined", "expired") +CONTEXT = ( # the run context's top-level keys (section Run context), in the order the variable picker lists them + ("event", "The event", "object", "the activity that started the run (for a join, the last one)"), + ("events", "Events by trigger", "object", "each trigger's activity by its name (as), such as events.mail"), + ("trigger", "Trigger", "object", "the trigger that fired: {as, on}"), + ("automation", "Automation", "object", "{id, name, version, spaces}"), + ("run", "Run", "object", "{id, dry}"), + ("namespace", "Namespace", "object", "{id, name}"), + ("user", "Person", "object", "who the automation acts for: {id, name, email}"), + ("now", "Now", "string", "when the run started, ISO 8601 in UTC"), + ("timezone", "Time zone", "string", "the person's time zone"), + ("vars", "Variables", "object", "the automation's and its namespace's saved variables"), + ("steps", "Steps", "object", "what each node passed on so far, by node id, such as steps.n3"), +) + + +# ---------- the shapes ---------- +Trigger = TypedDict( # the functional form, since "as" is a Python keyword + "Trigger", + { + "as": str, + "on": Literal["event", "schedule", "at", "relative", "webhook", "manual"], + "kinds": NotRequired[list[str]], + "where": NotRequired[dict], + "from_automations": NotRequired[bool], + "cron": NotRequired[str], + "timezone": NotRequired[str], + "at": NotRequired[str], + "field": NotRequired[str], + "offset": NotRequired[str], + "hook": NotRequired["int | None"], + }, +) + + +class Join(TypedDict): + mode: Literal["any", "all", "count", "absent", "batch"] + within: NotRequired[str] + key: NotRequired[str] + of: NotRequired[str] + at_least: NotRequired[int] + after: NotRequired[str] + missing: NotRequired[str] + + +class Intent(TypedDict): + key: str + action: str + params: dict + effect: Literal["read", "self", "lens", "out"] + risk: Literal["routine", "ask"] + untrusted: bool + spaces: list[int] + run_as: int | None + node: str + automation: int | None + run: int | None + when: str | None + status: Literal["waiting", "scheduled", "done", "failed", "declined", "expired"] + + +class RunContext(TypedDict): + event: dict + events: dict[str, dict] + trigger: dict + automation: dict + run: dict + namespace: dict | None + user: dict + now: str + timezone: str + vars: dict + steps: dict[str, object] + + +# ---------- durations ---------- +def check_duration(text, back=False, what="the duration"): + """Seconds in a duration like 30s, 30m, 2h or 7d (at most a year). A minus (-30m) only where an offset may point + back (`back`).""" + m = DURATION_RX.match(str(text).strip()) if isinstance(text, str) else None + if not m: + raise ValueError(f"{what} is a whole number and s, m, h or d, like 30m") + if m.group(1) and not back: + raise ValueError(f"{what} can't point back") + n = int(m.group(2)) * UNITS[m.group(3)] + if n > MAX_DURATION: + raise ValueError(f"{what} is at most 366d") + return -n if m.group(1) else n + + +# ---------- triggers ---------- +def _name(t, n): + return f"trigger {t.get('as')}" if isinstance(t.get("as"), str) and t.get("as") else f"trigger {n}" + + +def check_trigger(t, n=1): + """A trigger, cleaned (`n` is its place, for naming it in problems before it has a name).""" + if not isinstance(t, dict): + raise ValueError(f"trigger {n} is an object with on") + what = _name(t, n) + alias = t.get("as") + if not isinstance(alias, str) or not ALIAS_RX.match(alias): + raise ValueError(f"{what}: give it a name (as) of lowercase letters, digits and _, like mail") + on = t.get("on") + if on not in ON: + raise ValueError(f"{what}: on is one of {', '.join(ON)}") + extra = sorted(set(t) - KEYS[on] - {"as", "on"}) + if extra: + raise ValueError(f"{what}: a trigger on {on} has no {extra[0]}") + out: dict = {"as": alias, "on": on} + if on in ("event", "relative"): + ks = t.get("kinds") + if not isinstance(ks, list) or not ks or not all(isinstance(k, str) for k in ks): + raise ValueError(f"{what}: kinds lists the kinds of activity it starts on, like email.received") + try: + events.expand(ks) + except ValueError as e: + raise ValueError(f"{what}: {e}") from None + out["kinds"] = list(dict.fromkeys(ks)) + if t.get("where") is not None: + out["where"] = match.check(t["where"], f"{what}'s where") + if not isinstance(t.get("from_automations", False), bool): + raise ValueError(f"{what}: from_automations is true or false") + out["from_automations"] = bool(t.get("from_automations", False)) + if on in ("schedule", "at"): + out["timezone"] = t.get("timezone") or "UTC" + try: + schedule.zone(out["timezone"]) + except ValueError as e: + raise ValueError(f"{what}: {e}") from None + if on == "schedule": + cron = (t.get("cron") or "").strip() if isinstance(t.get("cron"), str) else "" + if not cron: + raise ValueError(f"{what}: give the schedule (cron), like 0 7 * * 1-5") + try: + schedule.check(cron, out["timezone"]) + except ValueError as e: + raise ValueError(f"{what}: {e}") from None + out["cron"] = cron + elif on == "at": + try: + when = dt.datetime.fromisoformat(str(t.get("at") or "").strip().replace("Z", "+00:00")) + except ValueError: + raise ValueError(f"{what}: at is a time like 2026-10-16T07:30 (in its time zone)") from None + out["at"] = when.isoformat(timespec="seconds") + elif on == "relative": + field = t.get("field") + if not isinstance(field, str) or not events.PATH_RX.match(field): + raise ValueError(f"{what}: field is the time in the activity it counts from, like object.startTime") + out["field"] = field + out["offset"] = t.get("offset") or "0s" + check_duration(out["offset"], back=True, what=f"{what}'s offset") + elif on == "webhook": + hook = t.get("hook") + if hook is not None and (not isinstance(hook, int) or isinstance(hook, bool)): + raise ValueError(f"{what}: hook is given when the automation is saved") + out["hook"] = hook + return out + + +def check_triggers(ts): + """An automation's triggers, cleaned: one to MAX_TRIGGERS, each named once.""" + if not isinstance(ts, list) or not ts: + raise ValueError("an automation has at least one trigger") + if len(ts) > MAX_TRIGGERS: + raise ValueError(f"an automation has at most {MAX_TRIGGERS} triggers") + out = [check_trigger(t, n) for n, t in enumerate(ts, 1)] + seen: set = set() + for t in out: + if t["as"] in seen: + raise ValueError(f"two triggers are named {t['as']}") + seen.add(t["as"]) + return out + + +# ---------- joins ---------- +def check_join(j, aliases=None): + """How the triggers make a run, cleaned (none: each on its own, mode any). `aliases` are the triggers' names, to + check the ones the join names.""" + if j is None or j == {}: + return {"mode": "any"} + if not isinstance(j, dict): + raise ValueError("the join is an object with a mode") + mode = j.get("mode", "any") + if mode not in JOIN_MODES: + raise ValueError(f"the join's mode is one of {', '.join(JOIN_MODES)}") + extra = sorted(set(j) - JOIN_KEYS[mode] - {"mode"}) + if extra: + raise ValueError(f"a join of mode {mode} has no {extra[0]}") + out: dict = {"mode": mode} + if mode == "any": + return out + out["within"] = j.get("within") + if out["within"] is None: + raise ValueError(f"a join of mode {mode} says how long it waits (within), like 2h") + if check_duration(out["within"], what="the join's within") == 0: + raise ValueError("the join's within is more than 0") + if j.get("key") is not None: + if not isinstance(j["key"], str) or not events.PATH_RX.match(j["key"]): + raise ValueError("the join's key is a path in the activities, like object.thread") + out["key"] = j["key"] + names = [k for k in ("of", "after", "missing") if k in JOIN_KEYS[mode]] + for k in names: + v = j.get(k) + if v is None and (k != "of" or mode == "count"): + raise ValueError(f"a join of mode {mode} names a trigger in {k}") + if v is None: + continue + if not isinstance(v, str) or not ALIAS_RX.match(v) or (aliases is not None and v not in aliases): + raise ValueError(f"the join's {k} is the name of one of the triggers") + out[k] = v + if mode == "count": + n = j.get("at_least") + if not isinstance(n, int) or isinstance(n, bool) or not 2 <= n <= 1000: + raise ValueError("a join of mode count says how many (at_least), 2 to 1000") + out["at_least"] = n + if mode == "absent" and out["after"] == out["missing"]: + raise ValueError("a join of mode absent waits after one trigger for another one (missing)") + if mode == "all" and aliases is not None and len(aliases) < 2: + raise ValueError("a join of mode all needs at least two triggers") + return out + + +# ---------- 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.""" + if tree is None: + return None + out = match.check(tree, "the If") + keys = {c[0] for c in CONTEXT} + for p in match.paths(out): + if p.split(".")[0] not in keys: + raise ValueError(f"the If tests {p or 'the whole context'}; paths start with {', '.join(sorted(keys))}") + return out + + +def check_policy(p, nodes=None, allow_auto=False): + """{action node id: ask or auto}, cleaned. Only a person in a signed-in session lets a node run on its own + (`allow_auto`); everywhere else auto is refused. `nodes` are the workflow's node ids, to check the ones named.""" + if p is None: + return {} + if not isinstance(p, dict): + raise ValueError("the policy is {node id: ask or auto}") + out = {} + for node, v in p.items(): + if not isinstance(node, str) or not NODE_RX.match(node) or (nodes is not None and node not in nodes): + raise ValueError(f"the policy names node {node}, which isn't in the workflow") + if v not in POLICY: + raise ValueError(f"node {node}'s policy is ask or auto") + if v == "auto" and not allow_auto: + raise ValueError(f"only you can let node {node} run without asking, from the automation's page") + out[node] = v + return out + + +# ---------- intents ---------- +def check_intent(i): + """An intent (what an action node means to do), cleaned. Its status defaults to waiting.""" + if not isinstance(i, dict): + raise ValueError("an intent is an object") + extra = sorted(set(i) - set(Intent.__annotations__)) + if extra: + raise ValueError(f"an intent has no {extra[0]}") + if not isinstance(i.get("key"), str) or not KEY_RX.match(i["key"]): + raise ValueError("an intent's key is its run and node, like 51-n7") + if not isinstance(i.get("action"), str) or not ACTION_RX.match(i["action"]): + raise ValueError("an intent names its action, like notify") + if not isinstance(i.get("params", {}), dict): + raise ValueError("an intent's params are an object") + if i.get("effect") not in EFFECTS: + raise ValueError(f"an intent's effect is one of {', '.join(EFFECTS)}") + if i.get("risk") not in RISKS: + raise ValueError(f"an intent's risk is {' or '.join(RISKS)}") + if not isinstance(i.get("untrusted", False), bool): + raise ValueError("an intent's untrusted is true or false") + spaces = i.get("spaces") or [] + if not isinstance(spaces, list) or not all(isinstance(s, int) and not isinstance(s, bool) for s in spaces): + raise ValueError("an intent's spaces are namespace ids") + for k in ("run_as", "automation", "run"): + v = i.get(k) + if v is not None and (not isinstance(v, int) or isinstance(v, bool)): + raise ValueError(f"an intent's {k} is an id, or null") + if not isinstance(i.get("node"), str) or not NODE_RX.match(i["node"]): + raise ValueError("an intent names the node that made it") + when = i.get("when") + if when is not None: + try: + if not isinstance(when, str): + raise ValueError + dt.datetime.fromisoformat(when.replace("Z", "+00:00")) + except ValueError: + raise ValueError("an intent's when is an ISO 8601 time, or null") from None + status = i.get("status", "waiting") + if status not in STATUSES: + raise ValueError(f"an intent's status is one of {', '.join(STATUSES)}") + return { + "key": i["key"], + "action": i["action"], + "params": dict(i.get("params") or {}), + "effect": i["effect"], + "risk": i["risk"], + "untrusted": bool(i.get("untrusted", False)), + "spaces": sorted(set(spaces)), + "run_as": i.get("run_as"), + "node": i["node"], + "automation": i.get("automation"), + "run": i.get("run"), + "when": when, + "status": status, + } + + +# ---------- the run context ---------- +def context_paths(): + """The run context's top-level keys, for the variable picker: [{path, title, type, description}].""" + return [{"path": p, "title": t, "type": ty, "description": d} for p, t, ty, d in CONTEXT] diff --git a/fastapi_backend/tests/domain/test_automation_spec.py b/fastapi_backend/tests/domain/test_automation_spec.py new file mode 100644 index 000000000..68c83db15 --- /dev/null +++ b/fastapi_backend/tests/domain/test_automation_spec.py @@ -0,0 +1,288 @@ +"""The shapes automations are made of (docs/automations.md, Contract): triggers, joins, the If, policy and intents +checked with the first problem in words; and the action registry with risk from each action's effect.""" + +from __future__ import annotations + +import logging + +import pytest + +from app.domain import actions, events +from app.domain import automation_spec as spec + +SCHOOL = {"all": [{"path": "object.name", "op": "contains", "value": "trip"}]} + + +def test_durations(): + assert [spec.check_duration(d) for d in ("30s", "30m", "2h", "7d", "0s")] == [30, 1800, 7200, 604800, 0] + assert spec.check_duration("-30m", back=True) == -1800 + for bad, said in [("30", "like 30m"), ("1.5h", "like 30m"), ("3w", "like 30m"), (30, "like 30m"), ("367d", "at most 366d")]: + with pytest.raises(ValueError, match=said): + spec.check_duration(bad) + with pytest.raises(ValueError, match="the offset can't point back"): + spec.check_duration("-5m", what="the offset") + + +def test_triggers(): + mail = spec.check_trigger({"as": "mail", "on": "event", "kinds": ["asset.added"], "where": SCHOOL}) + assert mail == {"as": "mail", "on": "event", "kinds": ["asset.added"], "where": SCHOOL, "from_automations": False} + assert ( + spec.check_trigger({"as": "morning", "on": "schedule", "cron": "0 7 * * 1-5", "timezone": "Europe/London"})["cron"] == "0 7 * * 1-5" + ) + assert spec.check_trigger({"as": "once", "on": "at", "at": "2026-10-16T07:30"}) == { + "as": "once", + "on": "at", + "timezone": "UTC", + "at": "2026-10-16T07:30:00", + } + soon = spec.check_trigger({"as": "soon", "on": "relative", "kinds": ["asset.added"], "field": "object.startTime", "offset": "-30m"}) + assert soon["offset"] == "-30m" and soon["field"] == "object.startTime" + assert spec.check_trigger({"as": "hook", "on": "webhook"}) == {"as": "hook", "on": "webhook", "hook": None} + assert spec.check_trigger({"as": "now", "on": "manual"}) == {"as": "now", "on": "manual"} + bad = [ + ("mail", "trigger 1 is an object"), + ({"on": "event"}, "trigger 1: give it a name"), + ({"as": "Mail", "on": "event"}, "give it a name"), + ({"as": "mail", "on": "email"}, "trigger mail: on is one of event, schedule"), + ({"as": "mail", "on": "event", "kinds": ["asset.added"], "cron": "* * * * *"}, "a trigger on event has no cron"), + ({"as": "mail", "on": "event"}, "kinds lists the kinds"), + ({"as": "mail", "on": "event", "kinds": ["email.nope"]}, "trigger mail: no kind email.nope"), + ({"as": "mail", "on": "event", "kinds": ["asset.added"], "where": {"any": []}}, "trigger mail's where: any needs"), + ({"as": "mail", "on": "event", "kinds": ["asset.added"], "from_automations": "yes"}, "from_automations is true or false"), + ({"as": "am", "on": "schedule"}, "give the schedule"), + ({"as": "am", "on": "schedule", "cron": "61 * * * *"}, "trigger am:"), + ({"as": "am", "on": "schedule", "cron": "0 7 * * *", "timezone": "Mars/Base"}, "unknown time zone"), + ({"as": "once", "on": "at", "at": "tomorrow"}, "at is a time like"), + ({"as": "soon", "on": "relative", "kinds": ["asset.added"]}, "field is the time in the activity"), + ( + {"as": "soon", "on": "relative", "kinds": ["asset.added"], "field": "object.startTime", "offset": "soon"}, + "trigger soon's offset is", + ), + ({"as": "hook", "on": "webhook", "hook": "abc"}, "hook is given when the automation is saved"), + ] + for t, said in bad: + with pytest.raises(ValueError, match=said): + spec.check_trigger(t) + both = spec.check_triggers([{"as": "a", "on": "manual"}, {"as": "b", "on": "manual"}]) + assert [t["as"] for t in both] == ["a", "b"] + for ts, said in [ + ([], "at least one trigger"), + ([{"as": "a", "on": "manual"}] * 2, "two triggers are named a"), + ([{"as": f"t{n}", "on": "manual"} for n in range(11)], "at most 10 triggers"), + ]: + with pytest.raises(ValueError, match=said): + spec.check_triggers(ts) + + +def test_joins(): + assert spec.check_join(None) == {"mode": "any"} and spec.check_join({"mode": "any"}) == {"mode": "any"} + names = ["mail", "reply"] + assert spec.check_join({"mode": "all", "within": "2h", "key": "object.thread"}, names) == { + "mode": "all", + "within": "2h", + "key": "object.thread", + } + assert spec.check_join({"mode": "count", "of": "mail", "at_least": 3, "within": "1h"}, names)["at_least"] == 3 + assert spec.check_join({"mode": "absent", "after": "mail", "missing": "reply", "within": "2d"}, names)["missing"] == "reply" + assert spec.check_join({"mode": "batch", "within": "15m"}, names) == {"mode": "batch", "within": "15m"} + bad = [ + ({"mode": "some"}, "the join's mode is one of any, all"), + ({"mode": "any", "within": "1h"}, "a join of mode any has no within"), + ({"mode": "all"}, "says how long it waits"), + ({"mode": "all", "within": "0s"}, "within is more than 0"), + ({"mode": "all", "within": "-1h"}, "can't point back"), + ({"mode": "all", "within": "1h", "key": "a b"}, "the join's key is a path"), + ({"mode": "count", "within": "1h", "at_least": 2}, "names a trigger in of"), + ({"mode": "count", "of": "nope", "within": "1h", "at_least": 2}, "the join's of is the name of one of the triggers"), + ({"mode": "count", "of": "mail", "within": "1h", "at_least": 1}, "how many \\(at_least\\), 2 to 1000"), + ({"mode": "absent", "after": "mail", "missing": "mail", "within": "1h"}, "waits after one trigger for another"), + ] + for j, said in bad: + with pytest.raises(ValueError, match=said): + spec.check_join(j, names) + with pytest.raises(ValueError, match="needs at least two triggers"): + spec.check_join({"mode": "all", "within": "1h"}, ["mail"]) + + +def test_if_policy_and_context(): + tree = { + "all": [ + {"path": "events.mail.object.name", "op": "contains", "value": "trip"}, + {"path": "steps.n3.ok", "op": "equals", "value": True}, + ] + } + assert spec.check_if(tree) == tree and spec.check_if(None) is None + with pytest.raises(ValueError, match="the If tests object.name; paths start with automation, event, events"): + spec.check_if({"all": [{"path": "object.name", "op": "exists"}]}) + with pytest.raises(ValueError, match="the If, any.0: the test is one of"): + spec.check_if({"any": [{"path": "event.kind", "op": "near"}]}) + assert spec.check_policy({"n7": "ask"}, ["n1", "n7"]) == {"n7": "ask"} and spec.check_policy(None) == {} + assert spec.check_policy({"n7": "auto"}, allow_auto=True) == {"n7": "auto"} + for p, said in [ + ({"n7": "auto"}, "only you can let node n7 run without asking"), + ({"n9": "ask"}, "names node n9"), + ({"n7": "always"}, "ask or auto"), + (["n7"], "the policy is"), + ]: + with pytest.raises(ValueError, match=said): + spec.check_policy(p, ["n7"]) + paths = spec.context_paths() + assert [p["path"] for p in paths] == [ + "event", + "events", + "trigger", + "automation", + "run", + "namespace", + "user", + "now", + "timezone", + "vars", + "steps", + ] + assert all(p["title"] and p["description"] for p in paths) + + +INTENT = { + "key": "51-n7", + "action": "log_line", + "params": {"text": "School trip on Friday"}, + "effect": "read", + "risk": "routine", + "untrusted": True, + "spaces": [3], + "run_as": 1, + "node": "n7", + "automation": 4, + "run": 51, + "when": None, +} + + +def test_intents(): + i = spec.check_intent(INTENT) + assert i["status"] == "waiting" and i == {**INTENT, "status": "waiting"} + assert spec.check_intent({**INTENT, "when": "2026-10-15T18:22:00Z", "status": "scheduled"})["when"] == "2026-10-15T18:22:00Z" + bad = [ + ({"colour": 1}, "an intent has no colour"), + ({"key": "51 n7"}, "an intent's key"), + ({"action": "Notify"}, "names its action"), + ({"params": []}, "params are an object"), + ({"effect": "far"}, "effect is one of read, self, lens, out"), + ({"risk": "maybe"}, "risk is routine or ask"), + ({"untrusted": "no"}, "untrusted is true or false"), + ({"spaces": ["family"]}, "spaces are namespace ids"), + ({"run": "51"}, "run is an id"), + ({"node": ""}, "names the node"), + ({"when": "later"}, "when is an ISO 8601 time"), + ({"status": "pending"}, "status is one of waiting"), + ] + for change, said in bad: + with pytest.raises(ValueError, match=said): + spec.check_intent({**INTENT, **change}) + + +# ---------- actions ---------- +@pytest.fixture +def registry(): + before = dict(actions._ACTIONS) + yield + actions._ACTIONS.clear() + actions._ACTIONS.update(before) + + +def fake(name, effect, **kw): + return actions.ActionSpec( + name=name, + label=name.title(), + group="Lens", + params={ + "type": "object", + "properties": {"object": {"type": "string"}, "to": {"type": "string"}, "n": {"type": "integer", "default": 2}}, + }, + effect=effect, + perform=lambda db, cfg, intent, user, dry: {"did": not dry, "params": intent["params"]}, + **kw, + ) + + +def test_the_catalog_and_params(registry): + actions.register(fake("tag_it", "lens")) + names = [a["name"] for a in actions.catalog()] + assert "log_line" in names and "tag_it" in names + info = next(a for a in actions.catalog() if a["name"] == "log_line") + assert info["effect"] == "read" and info["required"] == ["text"] and info["group"] == "Run" and info["output"] + assert actions.get("tag_it").label == "Tag_It" + with pytest.raises(KeyError): + actions.get("nope") + assert actions.check_params(actions.get("tag_it"), {"object": "lens:recording/7"}) == {"object": "lens:recording/7", "n": 2} + assert actions.check_params(actions.get("tag_it"), {"n": "{{ steps.n3.count }}"})["n"] == "{{ steps.n3.count }}" + for params, said in [ + ({"x": 1}, "tag_it has no param x"), + ({"n": "two"}, "n is an integer"), + ({"n": True}, "n is an integer"), + ([], "params are an object"), + ]: + with pytest.raises(ValueError, match=said): + actions.check_params(actions.get("tag_it"), params) + log = actions.get("log_line") + with pytest.raises(ValueError, match="log_line needs Line \\(text\\)"): + actions.check_params(log, {}) + with pytest.raises(ValueError, match="level is one of info, warning"): + actions.check_params(log, {"text": "x", "level": "loud"}) + bad = [ + (dict(name="Tag It"), "an action is named"), + (dict(group="Misc"), "its group is one of"), + (dict(params={"type": "array"}), "params is a JSON Schema of type object"), + (dict(required=("missing",)), "required param missing"), + (dict(effect="far"), "its effect is one of"), + ] + for change, said in bad: + base = {"name": "bad", "label": "Bad", "group": "Lens", "params": {"type": "object"}, "perform": lambda *a: {}, **change} + with pytest.raises(ValueError, match=said): + actions.register(actions.ActionSpec(**base)) + + +def test_risk_follows_the_effect(registry): + event = {"object": {"id": "lens:recording/7"}, "space": 3, "lens": {}} + ctx = {"event": event, "automation": {"id": 4, "spaces": [3]}, "node": "n7"} + read, own = actions.register(fake("look", "read")), actions.register(fake("mine", "self")) + lens, out = actions.register(fake("tag_it", "lens")), actions.register(fake("send", "out")) + assert actions.resolve_risk(read, {}, ctx) == "routine" and actions.resolve_risk(own, {}, ctx) == "routine" + assert actions.resolve_risk(lens, {"object": "lens:recording/7"}, ctx) == "routine" # the event's own object + assert actions.resolve_risk(lens, {"object": "lens:recording/8"}, ctx) == "ask" # something else + assert actions.resolve_risk(lens, {"object": "lens:recording/7"}, {**ctx, "automation": {"spaces": [5]}}) == "ask" # not its namespaces + assert actions.resolve_risk(lens, {}, ctx) == "ask" + assert actions.resolve_risk(out, {}, ctx) == "ask" and actions.resolve_risk(out, {}, ctx, "auto") == "routine" + assert actions.resolve_risk(out, {}, ctx, {"n7": "auto"}) == "routine" and actions.resolve_risk(out, {}, ctx, {"n8": "auto"}) == "ask" + # an effect worked out from the params: to me is self, to anyone else out; a template that decides the reach is out + tell = actions.register(fake("tell", lambda p: "self" if p.get("to") == "me" else "out")) + assert actions.resolve_risk(tell, {"to": "me"}, ctx) == "routine" and actions.resolve_risk(tell, {"to": "gateway:family"}, ctx) == "ask" + broken = actions.register(fake("broken", lambda p: 1 / 0)) + assert actions.effect_of(broken, {}) == "out" and actions.resolve_risk(broken, {}, ctx) == "ask" + # an action's own risk may make it stricter, never looser + careful = actions.register(fake("careful", "read", risk=lambda p, c: "ask" if p.get("n", 0) > 5 else "routine")) + assert actions.resolve_risk(careful, {"n": 9}, ctx) == "ask" and actions.resolve_risk(careful, {"n": 1}, ctx) == "routine" + loose = actions.register(fake("loose", "out", risk=lambda p, c: "routine")) + assert actions.resolve_risk(loose, {}, ctx) == "ask" + assert actions.describe("log_line", {"text": "hi"}) == "Write “hi” to the run log" and actions.describe("send", {}) == "Send" + + +def test_perform_carries_an_intent_out(registry, db, cfg, caplog): + with caplog.at_level(logging.INFO, logger="lens.automations"): + assert actions.perform(db, cfg, INTENT, {"id": 1}) == {"line": "School trip on Friday", "level": "info"} + assert "automation 4 run 51: School trip on Friday" in caplog.text + caplog.clear() + assert actions.perform(db, cfg, INTENT, {"id": 1}, dry=True)["line"] == "School trip on Friday" + assert caplog.text == "" # a dry run changes nothing + actions.register(fake("tag_it", "lens")) + got = actions.perform(db, cfg, {**INTENT, "action": "tag_it", "params": {"object": "lens:recording/7"}}, {"id": 1}, dry=True) + assert got == {"did": False, "params": {"object": "lens:recording/7", "n": 2}} + with pytest.raises(ValueError, match="no action nope"): + actions.perform(db, cfg, {**INTENT, "action": "nope"}, {"id": 1}) + with pytest.raises(ValueError, match="log_line needs"): + actions.perform(db, cfg, {**INTENT, "params": {}}, {"id": 1}) + actions.register(actions.ActionSpec(name="odd", label="Odd", group="Lens", params={"type": "object"}, perform=lambda *a: "done")) + with pytest.raises(ValueError, match="odd gave str, not an object"): + actions.perform(db, cfg, {**INTENT, "action": "odd", "params": {}}, {"id": 1}) + assert events.kind_info("asset.added") # the stream's catalog and the action catalog load together