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